/ Hex Artifact Content
Login

Artifact 35e253c3b408157a9edc3306d4f1b770af73a398:


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 53  #ifndef SQLITE_S
0790: 54 44 43 41 4c 4c 0a 23 20 64 65 66 69 6e 65 20  TDCALL.# define 
07a0: 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 0a 23  SQLITE_STDCALL.#
07b0: 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 54 68 65  endif../*.** The
07c0: 73 65 20 6e 6f 2d 6f 70 20 6d 61 63 72 6f 73 20  se no-op macros 
07d0: 61 72 65 20 75 73 65 64 20 69 6e 20 66 72 6f 6e  are used in fron
07e0: 74 20 6f 66 20 69 6e 74 65 72 66 61 63 65 73 20  t of interfaces 
07f0: 74 6f 20 6d 61 72 6b 20 74 68 6f 73 65 0a 2a 2a  to mark those.**
0800: 20 69 6e 74 65 72 66 61 63 65 73 20 61 73 20 65   interfaces as e
0810: 69 74 68 65 72 20 64 65 70 72 65 63 61 74 65 64  ither deprecated
0820: 20 6f 72 20 65 78 70 65 72 69 6d 65 6e 74 61 6c   or experimental
0830: 2e 20 20 4e 65 77 20 61 70 70 6c 69 63 61 74 69  .  New applicati
0840: 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 6f  ons.** should no
0850: 74 20 75 73 65 20 64 65 70 72 65 63 61 74 65 64  t use deprecated
0860: 20 69 6e 74 65 72 66 61 63 65 73 20 2d 20 74 68   interfaces - th
0870: 65 79 20 61 72 65 20 73 75 70 70 6f 72 74 65 64  ey are supported
0880: 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 0a 2a   for backwards.*
0890: 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20  * compatibility 
08a0: 6f 6e 6c 79 2e 20 20 41 70 70 6c 69 63 61 74 69  only.  Applicati
08b0: 6f 6e 20 77 72 69 74 65 72 73 20 73 68 6f 75 6c  on writers shoul
08c0: 64 20 62 65 20 61 77 61 72 65 20 74 68 61 74 0a  d be aware that.
08d0: 2a 2a 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20  ** experimental 
08e0: 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 73  interfaces are s
08f0: 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65  ubject to change
0900: 20 69 6e 20 70 6f 69 6e 74 20 72 65 6c 65 61 73   in point releas
0910: 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  es..**.** These 
0920: 6d 61 63 72 6f 73 20 75 73 65 64 20 74 6f 20 72  macros used to r
0930: 65 73 6f 6c 76 65 20 74 6f 20 76 61 72 69 6f 75  esolve to variou
0940: 73 20 6b 69 6e 64 73 20 6f 66 20 63 6f 6d 70 69  s kinds of compi
0950: 6c 65 72 20 6d 61 67 69 63 20 74 68 61 74 0a 2a  ler magic that.*
0960: 2a 20 77 6f 75 6c 64 20 67 65 6e 65 72 61 74 65  * would generate
0970: 20 77 61 72 6e 69 6e 67 20 6d 65 73 73 61 67 65   warning message
0980: 73 20 77 68 65 6e 20 74 68 65 79 20 77 65 72 65  s when they were
0990: 20 75 73 65 64 2e 20 20 42 75 74 20 74 68 61 74   used.  But that
09a0: 0a 2a 2a 20 63 6f 6d 70 69 6c 65 72 20 6d 61 67  .** compiler mag
09b0: 69 63 20 65 6e 64 65 64 20 75 70 20 67 65 6e 65  ic ended up gene
09c0: 72 61 74 69 6e 67 20 73 75 63 68 20 61 20 66 6c  rating such a fl
09d0: 75 72 72 79 20 6f 66 20 62 75 67 20 72 65 70 6f  urry of bug repo
09e0: 72 74 73 0a 2a 2a 20 74 68 61 74 20 77 65 20 68  rts.** that we h
09f0: 61 76 65 20 74 61 6b 65 6e 20 69 74 20 61 6c 6c  ave taken it all
0a00: 20 6f 75 74 20 61 6e 64 20 67 6f 6e 65 20 62 61   out and gone ba
0a10: 63 6b 20 74 6f 20 75 73 69 6e 67 20 73 69 6d 70  ck to using simp
0a20: 6c 65 0a 2a 2a 20 6e 6f 6f 70 20 6d 61 63 72 6f  le.** noop macro
0a30: 73 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  s..*/.#define SQ
0a40: 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 0a  LITE_DEPRECATED.
0a50: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45  #define SQLITE_E
0a60: 58 50 45 52 49 4d 45 4e 54 41 4c 0a 0a 2f 2a 0a  XPERIMENTAL../*.
0a70: 2a 2a 20 45 6e 73 75 72 65 20 74 68 65 73 65 20  ** Ensure these 
0a80: 73 79 6d 62 6f 6c 73 20 77 65 72 65 20 6e 6f 74  symbols were not
0a90: 20 64 65 66 69 6e 65 64 20 62 79 20 73 6f 6d 65   defined by some
0aa0: 20 70 72 65 76 69 6f 75 73 20 68 65 61 64 65 72   previous header
0ab0: 20 66 69 6c 65 2e 0a 2a 2f 0a 23 69 66 64 65 66   file..*/.#ifdef
0ac0: 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 0a   SQLITE_VERSION.
0ad0: 23 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 56  # undef SQLITE_V
0ae0: 45 52 53 49 4f 4e 0a 23 65 6e 64 69 66 0a 23 69  ERSION.#endif.#i
0af0: 66 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53  fdef SQLITE_VERS
0b00: 49 4f 4e 5f 4e 55 4d 42 45 52 0a 23 20 75 6e 64  ION_NUMBER.# und
0b10: 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f  ef SQLITE_VERSIO
0b20: 4e 5f 4e 55 4d 42 45 52 0a 23 65 6e 64 69 66 0a  N_NUMBER.#endif.
0b30: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
0b40: 20 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 4c 69   Compile-Time Li
0b50: 62 72 61 72 79 20 56 65 72 73 69 6f 6e 20 4e 75  brary Version Nu
0b60: 6d 62 65 72 73 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  mbers.**.** ^(Th
0b70: 65 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f  e [SQLITE_VERSIO
0b80: 4e 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f  N] C preprocesso
0b90: 72 20 6d 61 63 72 6f 20 69 6e 20 74 68 65 20 73  r macro in the s
0ba0: 71 6c 69 74 65 33 2e 68 20 68 65 61 64 65 72 0a  qlite3.h header.
0bb0: 2a 2a 20 65 76 61 6c 75 61 74 65 73 20 74 6f 20  ** evaluates to 
0bc0: 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c  a string literal
0bd0: 20 74 68 61 74 20 69 73 20 74 68 65 20 53 51 4c   that is the SQL
0be0: 69 74 65 20 76 65 72 73 69 6f 6e 20 69 6e 20 74  ite version in t
0bf0: 68 65 0a 2a 2a 20 66 6f 72 6d 61 74 20 22 58 2e  he.** format "X.
0c00: 59 2e 5a 22 20 77 68 65 72 65 20 58 20 69 73 20  Y.Z" where X is 
0c10: 74 68 65 20 6d 61 6a 6f 72 20 76 65 72 73 69 6f  the major versio
0c20: 6e 20 6e 75 6d 62 65 72 20 28 61 6c 77 61 79 73  n number (always
0c30: 20 33 20 66 6f 72 0a 2a 2a 20 53 51 4c 69 74 65   3 for.** SQLite
0c40: 33 29 20 61 6e 64 20 59 20 69 73 20 74 68 65 20  3) and Y is the 
0c50: 6d 69 6e 6f 72 20 76 65 72 73 69 6f 6e 20 6e 75  minor version nu
0c60: 6d 62 65 72 20 61 6e 64 20 5a 20 69 73 20 74 68  mber and Z is th
0c70: 65 20 72 65 6c 65 61 73 65 20 6e 75 6d 62 65 72  e release number
0c80: 2e 29 5e 0a 2a 2a 20 5e 28 54 68 65 20 5b 53 51  .)^.** ^(The [SQ
0c90: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d  LITE_VERSION_NUM
0ca0: 42 45 52 5d 20 43 20 70 72 65 70 72 6f 63 65 73  BER] C preproces
0cb0: 73 6f 72 20 6d 61 63 72 6f 20 72 65 73 6f 6c 76  sor macro resolv
0cc0: 65 73 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72  es to an integer
0cd0: 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 76 61 6c  .** with the val
0ce0: 75 65 20 28 58 2a 31 30 30 30 30 30 30 20 2b 20  ue (X*1000000 + 
0cf0: 59 2a 31 30 30 30 20 2b 20 5a 29 20 77 68 65 72  Y*1000 + Z) wher
0d00: 65 20 58 2c 20 59 2c 20 61 6e 64 20 5a 20 61 72  e X, Y, and Z ar
0d10: 65 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 6e 75  e the same.** nu
0d20: 6d 62 65 72 73 20 75 73 65 64 20 69 6e 20 5b 53  mbers used in [S
0d30: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 2e 29  QLITE_VERSION].)
0d40: 5e 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f  ^.** The SQLITE_
0d50: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 66  VERSION_NUMBER f
0d60: 6f 72 20 61 6e 79 20 67 69 76 65 6e 20 72 65 6c  or any given rel
0d70: 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 20 77  ease of SQLite w
0d80: 69 6c 6c 20 61 6c 73 6f 0a 2a 2a 20 62 65 20 6c  ill also.** be l
0d90: 61 72 67 65 72 20 74 68 61 6e 20 74 68 65 20 72  arger than the r
0da0: 65 6c 65 61 73 65 20 66 72 6f 6d 20 77 68 69 63  elease from whic
0db0: 68 20 69 74 20 69 73 20 64 65 72 69 76 65 64 2e  h it is derived.
0dc0: 20 20 45 69 74 68 65 72 20 59 20 77 69 6c 6c 0a    Either Y will.
0dd0: 2a 2a 20 62 65 20 68 65 6c 64 20 63 6f 6e 73 74  ** be held const
0de0: 61 6e 74 20 61 6e 64 20 5a 20 77 69 6c 6c 20 62  ant and Z will b
0df0: 65 20 69 6e 63 72 65 6d 65 6e 74 65 64 20 6f 72  e incremented or
0e00: 20 65 6c 73 65 20 59 20 77 69 6c 6c 20 62 65 20   else Y will be 
0e10: 69 6e 63 72 65 6d 65 6e 74 65 64 0a 2a 2a 20 61  incremented.** a
0e20: 6e 64 20 5a 20 77 69 6c 6c 20 62 65 20 72 65 73  nd Z will be res
0e30: 65 74 20 74 6f 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a  et to zero..**.*
0e40: 2a 20 53 69 6e 63 65 20 76 65 72 73 69 6f 6e 20  * Since version 
0e50: 33 2e 36 2e 31 38 2c 20 53 51 4c 69 74 65 20 73  3.6.18, SQLite s
0e60: 6f 75 72 63 65 20 63 6f 64 65 20 68 61 73 20 62  ource code has b
0e70: 65 65 6e 20 73 74 6f 72 65 64 20 69 6e 20 74 68  een stored in th
0e80: 65 0a 2a 2a 20 3c 61 20 68 72 65 66 3d 22 68 74  e.** <a href="ht
0e90: 74 70 3a 2f 2f 77 77 77 2e 66 6f 73 73 69 6c 2d  tp://www.fossil-
0ea0: 73 63 6d 2e 6f 72 67 2f 22 3e 46 6f 73 73 69 6c  scm.org/">Fossil
0eb0: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d   configuration m
0ec0: 61 6e 61 67 65 6d 65 6e 74 0a 2a 2a 20 73 79 73  anagement.** sys
0ed0: 74 65 6d 3c 2f 61 3e 2e 20 20 5e 54 68 65 20 53  tem</a>.  ^The S
0ee0: 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 20  QLITE_SOURCE_ID 
0ef0: 6d 61 63 72 6f 20 65 76 61 6c 75 61 74 65 73 20  macro evaluates 
0f00: 74 6f 0a 2a 2a 20 61 20 73 74 72 69 6e 67 20 77  to.** a string w
0f10: 68 69 63 68 20 69 64 65 6e 74 69 66 69 65 73 20  hich identifies 
0f20: 61 20 70 61 72 74 69 63 75 6c 61 72 20 63 68 65  a particular che
0f30: 63 6b 2d 69 6e 20 6f 66 20 53 51 4c 69 74 65 0a  ck-in of SQLite.
0f40: 2a 2a 20 77 69 74 68 69 6e 20 69 74 73 20 63 6f  ** within its co
0f50: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61 6e 61  nfiguration mana
0f60: 67 65 6d 65 6e 74 20 73 79 73 74 65 6d 2e 20 20  gement system.  
0f70: 5e 54 68 65 20 53 51 4c 49 54 45 5f 53 4f 55 52  ^The SQLITE_SOUR
0f80: 43 45 5f 49 44 0a 2a 2a 20 73 74 72 69 6e 67 20  CE_ID.** string 
0f90: 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 64 61 74  contains the dat
0fa0: 65 20 61 6e 64 20 74 69 6d 65 20 6f 66 20 74 68  e and time of th
0fb0: 65 20 63 68 65 63 6b 2d 69 6e 20 28 55 54 43 29  e check-in (UTC)
0fc0: 20 61 6e 64 20 61 6e 20 53 48 41 31 0a 2a 2a 20   and an SHA1.** 
0fd0: 68 61 73 68 20 6f 66 20 74 68 65 20 65 6e 74 69  hash of the enti
0fe0: 72 65 20 73 6f 75 72 63 65 20 74 72 65 65 2e 0a  re source tree..
0ff0: 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
1000: 5b 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73  [sqlite3_libvers
1010: 69 6f 6e 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  ion()],.** [sqli
1020: 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e  te3_libversion_n
1030: 75 6d 62 65 72 28 29 5d 2c 20 5b 73 71 6c 69 74  umber()], [sqlit
1040: 65 33 5f 73 6f 75 72 63 65 69 64 28 29 5d 2c 0a  e3_sourceid()],.
1050: 2a 2a 20 5b 73 71 6c 69 74 65 5f 76 65 72 73 69  ** [sqlite_versi
1060: 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  on()] and [sqlit
1070: 65 5f 73 6f 75 72 63 65 5f 69 64 28 29 5d 2e 0a  e_source_id()]..
1080: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1090: 45 5f 56 45 52 53 49 4f 4e 20 20 20 20 20 20 20  E_VERSION       
10a0: 20 22 2d 2d 56 45 52 53 2d 2d 22 0a 23 64 65 66   "--VERS--".#def
10b0: 69 6e 65 20 53 51 4c 49 54 45 5f 56 45 52 53 49  ine SQLITE_VERSI
10c0: 4f 4e 5f 4e 55 4d 42 45 52 20 2d 2d 56 45 52 53  ON_NUMBER --VERS
10d0: 49 4f 4e 2d 4e 55 4d 42 45 52 2d 2d 0a 23 64 65  ION-NUMBER--.#de
10e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 4f 55 52  fine SQLITE_SOUR
10f0: 43 45 5f 49 44 20 20 20 20 20 20 22 2d 2d 53 4f  CE_ID      "--SO
1100: 55 52 43 45 2d 49 44 2d 2d 22 0a 0a 2f 2a 0a 2a  URCE-ID--"../*.*
1110: 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d  * CAPI3REF: Run-
1120: 54 69 6d 65 20 4c 69 62 72 61 72 79 20 56 65 72  Time Library Ver
1130: 73 69 6f 6e 20 4e 75 6d 62 65 72 73 0a 2a 2a 20  sion Numbers.** 
1140: 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65  KEYWORDS: sqlite
1150: 33 5f 76 65 72 73 69 6f 6e 2c 20 73 71 6c 69 74  3_version, sqlit
1160: 65 33 5f 73 6f 75 72 63 65 69 64 0a 2a 2a 0a 2a  e3_sourceid.**.*
1170: 2a 20 54 68 65 73 65 20 69 6e 74 65 72 66 61 63  * These interfac
1180: 65 73 20 70 72 6f 76 69 64 65 20 74 68 65 20 73  es provide the s
1190: 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  ame information 
11a0: 61 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 56  as the [SQLITE_V
11b0: 45 52 53 49 4f 4e 5d 2c 0a 2a 2a 20 5b 53 51 4c  ERSION],.** [SQL
11c0: 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42  ITE_VERSION_NUMB
11d0: 45 52 5d 2c 20 61 6e 64 20 5b 53 51 4c 49 54 45  ER], and [SQLITE
11e0: 5f 53 4f 55 52 43 45 5f 49 44 5d 20 43 20 70 72  _SOURCE_ID] C pr
11f0: 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f  eprocessor macro
1200: 73 0a 2a 2a 20 62 75 74 20 61 72 65 20 61 73 73  s.** but are ass
1210: 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65  ociated with the
1220: 20 6c 69 62 72 61 72 79 20 69 6e 73 74 65 61 64   library instead
1230: 20 6f 66 20 74 68 65 20 68 65 61 64 65 72 20 66   of the header f
1240: 69 6c 65 2e 20 20 5e 28 43 61 75 74 69 6f 75 73  ile.  ^(Cautious
1250: 0a 2a 2a 20 70 72 6f 67 72 61 6d 6d 65 72 73 20  .** programmers 
1260: 6d 69 67 68 74 20 69 6e 63 6c 75 64 65 20 61 73  might include as
1270: 73 65 72 74 28 29 20 73 74 61 74 65 6d 65 6e 74  sert() statement
1280: 73 20 69 6e 20 74 68 65 69 72 20 61 70 70 6c 69  s in their appli
1290: 63 61 74 69 6f 6e 20 74 6f 0a 2a 2a 20 76 65 72  cation to.** ver
12a0: 69 66 79 20 74 68 61 74 20 76 61 6c 75 65 73 20  ify that values 
12b0: 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 73  returned by thes
12c0: 65 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61 74  e interfaces mat
12d0: 63 68 20 74 68 65 20 6d 61 63 72 6f 73 20 69 6e  ch the macros in
12e0: 0a 2a 2a 20 74 68 65 20 68 65 61 64 65 72 2c 20  .** the header, 
12f0: 61 6e 64 20 74 68 75 73 20 65 6e 73 75 72 65 20  and thus ensure 
1300: 74 68 61 74 20 74 68 65 20 61 70 70 6c 69 63 61  that the applica
1310: 74 69 6f 6e 20 69 73 0a 2a 2a 20 63 6f 6d 70 69  tion is.** compi
1320: 6c 65 64 20 77 69 74 68 20 6d 61 74 63 68 69 6e  led with matchin
1330: 67 20 6c 69 62 72 61 72 79 20 61 6e 64 20 68 65  g library and he
1340: 61 64 65 72 20 66 69 6c 65 73 2e 0a 2a 2a 0a 2a  ader files..**.*
1350: 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
1360: 72 65 3e 0a 2a 2a 20 61 73 73 65 72 74 28 20 73  re>.** assert( s
1370: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f  qlite3_libversio
1380: 6e 5f 6e 75 6d 62 65 72 28 29 3d 3d 53 51 4c 49  n_number()==SQLI
1390: 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45  TE_VERSION_NUMBE
13a0: 52 20 29 3b 0a 2a 2a 20 61 73 73 65 72 74 28 20  R );.** assert( 
13b0: 73 74 72 63 6d 70 28 73 71 6c 69 74 65 33 5f 73  strcmp(sqlite3_s
13c0: 6f 75 72 63 65 69 64 28 29 2c 53 51 4c 49 54 45  ourceid(),SQLITE
13d0: 5f 53 4f 55 52 43 45 5f 49 44 29 3d 3d 30 20 29  _SOURCE_ID)==0 )
13e0: 3b 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 74 72  ;.** assert( str
13f0: 63 6d 70 28 73 71 6c 69 74 65 33 5f 6c 69 62 76  cmp(sqlite3_libv
1400: 65 72 73 69 6f 6e 28 29 2c 53 51 4c 49 54 45 5f  ersion(),SQLITE_
1410: 56 45 52 53 49 4f 4e 29 3d 3d 30 20 29 3b 0a 2a  VERSION)==0 );.*
1420: 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
1430: 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54  uote>)^.**.** ^T
1440: 68 65 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69  he sqlite3_versi
1450: 6f 6e 5b 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73  on[] string cons
1460: 74 61 6e 74 20 63 6f 6e 74 61 69 6e 73 20 74 68  tant contains th
1470: 65 20 74 65 78 74 20 6f 66 20 5b 53 51 4c 49 54  e text of [SQLIT
1480: 45 5f 56 45 52 53 49 4f 4e 5d 0a 2a 2a 20 6d 61  E_VERSION].** ma
1490: 63 72 6f 2e 20 20 5e 54 68 65 20 73 71 6c 69 74  cro.  ^The sqlit
14a0: 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 20  e3_libversion() 
14b0: 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
14c0: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
14d0: 65 0a 2a 2a 20 74 6f 20 74 68 65 20 73 71 6c 69  e.** to the sqli
14e0: 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74  te3_version[] st
14f0: 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 2e 20 20  ring constant.  
1500: 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 69 62 76  The sqlite3_libv
1510: 65 72 73 69 6f 6e 28 29 0a 2a 2a 20 66 75 6e 63  ersion().** func
1520: 74 69 6f 6e 20 69 73 20 70 72 6f 76 69 64 65 64  tion is provided
1530: 20 66 6f 72 20 75 73 65 20 69 6e 20 44 4c 4c 73   for use in DLLs
1540: 20 73 69 6e 63 65 20 44 4c 4c 20 75 73 65 72 73   since DLL users
1550: 20 75 73 75 61 6c 6c 79 20 64 6f 20 6e 6f 74 20   usually do not 
1560: 68 61 76 65 0a 2a 2a 20 64 69 72 65 63 74 20 61  have.** direct a
1570: 63 63 65 73 73 20 74 6f 20 73 74 72 69 6e 67 20  ccess to string 
1580: 63 6f 6e 73 74 61 6e 74 73 20 77 69 74 68 69 6e  constants within
1590: 20 74 68 65 20 44 4c 4c 2e 20 20 5e 54 68 65 0a   the DLL.  ^The.
15a0: 2a 2a 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65  ** sqlite3_libve
15b0: 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 20 66  rsion_number() f
15c0: 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
15d0: 61 6e 20 69 6e 74 65 67 65 72 20 65 71 75 61 6c  an integer equal
15e0: 20 74 6f 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 56   to.** [SQLITE_V
15f0: 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2e 20  ERSION_NUMBER]. 
1600: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6f   ^The sqlite3_so
1610: 75 72 63 65 69 64 28 29 20 66 75 6e 63 74 69 6f  urceid() functio
1620: 6e 20 72 65 74 75 72 6e 73 20 0a 2a 2a 20 61 20  n returns .** a 
1630: 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 73 74 72  pointer to a str
1640: 69 6e 67 20 63 6f 6e 73 74 61 6e 74 20 77 68 6f  ing constant who
1650: 73 65 20 76 61 6c 75 65 20 69 73 20 74 68 65 20  se value is the 
1660: 73 61 6d 65 20 61 73 20 74 68 65 20 0a 2a 2a 20  same as the .** 
1670: 5b 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49  [SQLITE_SOURCE_I
1680: 44 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f  D] C preprocesso
1690: 72 20 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53  r macro..**.** S
16a0: 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
16b0: 5f 76 65 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20  _version()] and 
16c0: 5b 73 71 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69  [sqlite_source_i
16d0: 64 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  d()]..*/.SQLITE_
16e0: 45 58 54 45 52 4e 20 63 6f 6e 73 74 20 63 68 61  EXTERN const cha
16f0: 72 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f  r sqlite3_versio
1700: 6e 5b 5d 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20  n[];.const char 
1710: 2a 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73  *sqlite3_libvers
1720: 69 6f 6e 28 76 6f 69 64 29 3b 0a 63 6f 6e 73 74  ion(void);.const
1730: 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73   char *sqlite3_s
1740: 6f 75 72 63 65 69 64 28 76 6f 69 64 29 3b 0a 69  ourceid(void);.i
1750: 6e 74 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65  nt sqlite3_libve
1760: 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 76 6f 69  rsion_number(voi
1770: 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  d);../*.** CAPI3
1780: 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69  REF: Run-Time Li
1790: 62 72 61 72 79 20 43 6f 6d 70 69 6c 61 74 69 6f  brary Compilatio
17a0: 6e 20 4f 70 74 69 6f 6e 73 20 44 69 61 67 6e 6f  n Options Diagno
17b0: 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  stics.**.** ^The
17c0: 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65   sqlite3_compile
17d0: 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29 20 66 75  option_used() fu
17e0: 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 30  nction returns 0
17f0: 20 6f 72 20 31 20 0a 2a 2a 20 69 6e 64 69 63 61   or 1 .** indica
1800: 74 69 6e 67 20 77 68 65 74 68 65 72 20 74 68 65  ting whether the
1810: 20 73 70 65 63 69 66 69 65 64 20 6f 70 74 69 6f   specified optio
1820: 6e 20 77 61 73 20 64 65 66 69 6e 65 64 20 61 74  n was defined at
1830: 20 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20 74 69 6d   .** compile tim
1840: 65 2e 20 20 5e 54 68 65 20 53 51 4c 49 54 45 5f  e.  ^The SQLITE_
1850: 20 70 72 65 66 69 78 20 6d 61 79 20 62 65 20 6f   prefix may be o
1860: 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20  mitted from the 
1870: 0a 2a 2a 20 6f 70 74 69 6f 6e 20 6e 61 6d 65 20  .** option name 
1880: 70 61 73 73 65 64 20 74 6f 20 73 71 6c 69 74 65  passed to sqlite
1890: 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f  3_compileoption_
18a0: 75 73 65 64 28 29 2e 20 20 0a 2a 2a 0a 2a 2a 20  used().  .**.** 
18b0: 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d  ^The sqlite3_com
18c0: 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29  pileoption_get()
18d0: 20 66 75 6e 63 74 69 6f 6e 20 61 6c 6c 6f 77 73   function allows
18e0: 20 69 74 65 72 61 74 69 6e 67 0a 2a 2a 20 6f 76   iterating.** ov
18f0: 65 72 20 74 68 65 20 6c 69 73 74 20 6f 66 20 6f  er the list of o
1900: 70 74 69 6f 6e 73 20 74 68 61 74 20 77 65 72 65  ptions that were
1910: 20 64 65 66 69 6e 65 64 20 61 74 20 63 6f 6d 70   defined at comp
1920: 69 6c 65 20 74 69 6d 65 20 62 79 0a 2a 2a 20 72  ile time by.** r
1930: 65 74 75 72 6e 69 6e 67 20 74 68 65 20 4e 2d 74  eturning the N-t
1940: 68 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 20 6f  h compile time o
1950: 70 74 69 6f 6e 20 73 74 72 69 6e 67 2e 20 20 5e  ption string.  ^
1960: 49 66 20 4e 20 69 73 20 6f 75 74 20 6f 66 20 72  If N is out of r
1970: 61 6e 67 65 2c 0a 2a 2a 20 73 71 6c 69 74 65 33  ange,.** sqlite3
1980: 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67  _compileoption_g
1990: 65 74 28 29 20 72 65 74 75 72 6e 73 20 61 20 4e  et() returns a N
19a0: 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54  ULL pointer.  ^T
19b0: 68 65 20 53 51 4c 49 54 45 5f 20 0a 2a 2a 20 70  he SQLITE_ .** p
19c0: 72 65 66 69 78 20 69 73 20 6f 6d 69 74 74 65 64  refix is omitted
19d0: 20 66 72 6f 6d 20 61 6e 79 20 73 74 72 69 6e 67   from any string
19e0: 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 0a 2a  s returned by .*
19f0: 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c  * sqlite3_compil
1a00: 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 2e 0a 2a  eoption_get()..*
1a10: 2a 0a 2a 2a 20 5e 53 75 70 70 6f 72 74 20 66 6f  *.** ^Support fo
1a20: 72 20 74 68 65 20 64 69 61 67 6e 6f 73 74 69 63  r the diagnostic
1a30: 20 66 75 6e 63 74 69 6f 6e 73 20 73 71 6c 69 74   functions sqlit
1a40: 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e  e3_compileoption
1a50: 5f 75 73 65 64 28 29 0a 2a 2a 20 61 6e 64 20 73  _used().** and s
1a60: 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70  qlite3_compileop
1a70: 74 69 6f 6e 5f 67 65 74 28 29 20 6d 61 79 20 62  tion_get() may b
1a80: 65 20 6f 6d 69 74 74 65 64 20 62 79 20 73 70 65  e omitted by spe
1a90: 63 69 66 79 69 6e 67 20 74 68 65 20 0a 2a 2a 20  cifying the .** 
1aa0: 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d  [SQLITE_OMIT_COM
1ab0: 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49 41 47 53  PILEOPTION_DIAGS
1ac0: 5d 20 6f 70 74 69 6f 6e 20 61 74 20 63 6f 6d 70  ] option at comp
1ad0: 69 6c 65 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20  ile time..**.** 
1ae0: 53 65 65 20 61 6c 73 6f 3a 20 53 51 4c 20 66 75  See also: SQL fu
1af0: 6e 63 74 69 6f 6e 73 20 5b 73 71 6c 69 74 65 5f  nctions [sqlite_
1b00: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73  compileoption_us
1b10: 65 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71  ed()] and.** [sq
1b20: 6c 69 74 65 5f 63 6f 6d 70 69 6c 65 6f 70 74 69  lite_compileopti
1b30: 6f 6e 5f 67 65 74 28 29 5d 20 61 6e 64 20 74 68  on_get()] and th
1b40: 65 20 5b 63 6f 6d 70 69 6c 65 5f 6f 70 74 69 6f  e [compile_optio
1b50: 6e 73 20 70 72 61 67 6d 61 5d 2e 0a 2a 2f 0a 23  ns pragma]..*/.#
1b60: 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d  ifndef SQLITE_OM
1b70: 49 54 5f 43 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e  IT_COMPILEOPTION
1b80: 5f 44 49 41 47 53 0a 69 6e 74 20 73 71 6c 69 74  _DIAGS.int sqlit
1b90: 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e  e3_compileoption
1ba0: 5f 75 73 65 64 28 63 6f 6e 73 74 20 63 68 61 72  _used(const char
1bb0: 20 2a 7a 4f 70 74 4e 61 6d 65 29 3b 0a 63 6f 6e   *zOptName);.con
1bc0: 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
1bd0: 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67  _compileoption_g
1be0: 65 74 28 69 6e 74 20 4e 29 3b 0a 23 65 6e 64 69  et(int N);.#endi
1bf0: 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  f../*.** CAPI3RE
1c00: 46 3a 20 54 65 73 74 20 54 6f 20 53 65 65 20 49  F: Test To See I
1c10: 66 20 54 68 65 20 4c 69 62 72 61 72 79 20 49 73  f The Library Is
1c20: 20 54 68 72 65 61 64 73 61 66 65 0a 2a 2a 0a 2a   Threadsafe.**.*
1c30: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 74  * ^The sqlite3_t
1c40: 68 72 65 61 64 73 61 66 65 28 29 20 66 75 6e 63  hreadsafe() func
1c50: 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 7a 65 72  tion returns zer
1c60: 6f 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66  o if and only if
1c70: 0a 2a 2a 20 53 51 4c 69 74 65 20 77 61 73 20 63  .** SQLite was c
1c80: 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 6d 75 74  ompiled with mut
1c90: 65 78 69 6e 67 20 63 6f 64 65 20 6f 6d 69 74 74  exing code omitt
1ca0: 65 64 20 64 75 65 20 74 6f 20 74 68 65 0a 2a 2a  ed due to the.**
1cb0: 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53   [SQLITE_THREADS
1cc0: 41 46 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  AFE] compile-tim
1cd0: 65 20 6f 70 74 69 6f 6e 20 62 65 69 6e 67 20 73  e option being s
1ce0: 65 74 20 74 6f 20 30 2e 0a 2a 2a 0a 2a 2a 20 53  et to 0..**.** S
1cf0: 51 4c 69 74 65 20 63 61 6e 20 62 65 20 63 6f 6d  QLite can be com
1d00: 70 69 6c 65 64 20 77 69 74 68 20 6f 72 20 77 69  piled with or wi
1d10: 74 68 6f 75 74 20 6d 75 74 65 78 65 73 2e 20 20  thout mutexes.  
1d20: 57 68 65 6e 0a 2a 2a 20 74 68 65 20 5b 53 51 4c  When.** the [SQL
1d30: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20  ITE_THREADSAFE] 
1d40: 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
1d50: 61 63 72 6f 20 69 73 20 31 20 6f 72 20 32 2c 20  acro is 1 or 2, 
1d60: 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72 65 20 65  mutexes.** are e
1d70: 6e 61 62 6c 65 64 20 61 6e 64 20 53 51 4c 69 74  nabled and SQLit
1d80: 65 20 69 73 20 74 68 72 65 61 64 73 61 66 65 2e  e is threadsafe.
1d90: 20 20 57 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 53    When the.** [S
1da0: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
1db0: 5d 20 6d 61 63 72 6f 20 69 73 20 30 2c 20 0a 2a  ] macro is 0, .*
1dc0: 2a 20 74 68 65 20 6d 75 74 65 78 65 73 20 61 72  * the mutexes ar
1dd0: 65 20 6f 6d 69 74 74 65 64 2e 20 20 57 69 74 68  e omitted.  With
1de0: 6f 75 74 20 74 68 65 20 6d 75 74 65 78 65 73 2c  out the mutexes,
1df0: 20 69 74 20 69 73 20 6e 6f 74 20 73 61 66 65 0a   it is not safe.
1e00: 2a 2a 20 74 6f 20 75 73 65 20 53 51 4c 69 74 65  ** to use SQLite
1e10: 20 63 6f 6e 63 75 72 72 65 6e 74 6c 79 20 66 72   concurrently fr
1e20: 6f 6d 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65  om more than one
1e30: 20 74 68 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 45   thread..**.** E
1e40: 6e 61 62 6c 69 6e 67 20 6d 75 74 65 78 65 73 20  nabling mutexes 
1e50: 69 6e 63 75 72 73 20 61 20 6d 65 61 73 75 72 61  incurs a measura
1e60: 62 6c 65 20 70 65 72 66 6f 72 6d 61 6e 63 65 20  ble performance 
1e70: 70 65 6e 61 6c 74 79 2e 0a 2a 2a 20 53 6f 20 69  penalty..** So i
1e80: 66 20 73 70 65 65 64 20 69 73 20 6f 66 20 75 74  f speed is of ut
1e90: 6d 6f 73 74 20 69 6d 70 6f 72 74 61 6e 63 65 2c  most importance,
1ea0: 20 69 74 20 6d 61 6b 65 73 20 73 65 6e 73 65 20   it makes sense 
1eb0: 74 6f 20 64 69 73 61 62 6c 65 0a 2a 2a 20 74 68  to disable.** th
1ec0: 65 20 6d 75 74 65 78 65 73 2e 20 20 42 75 74 20  e mutexes.  But 
1ed0: 66 6f 72 20 6d 61 78 69 6d 75 6d 20 73 61 66 65  for maximum safe
1ee0: 74 79 2c 20 6d 75 74 65 78 65 73 20 73 68 6f 75  ty, mutexes shou
1ef0: 6c 64 20 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a  ld be enabled..*
1f00: 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 62  * ^The default b
1f10: 65 68 61 76 69 6f 72 20 69 73 20 66 6f 72 20 6d  ehavior is for m
1f20: 75 74 65 78 65 73 20 74 6f 20 62 65 20 65 6e 61  utexes to be ena
1f30: 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  bled..**.** This
1f40: 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62   interface can b
1f50: 65 20 75 73 65 64 20 62 79 20 61 6e 20 61 70 70  e used by an app
1f60: 6c 69 63 61 74 69 6f 6e 20 74 6f 20 6d 61 6b 65  lication to make
1f70: 20 73 75 72 65 20 74 68 61 74 20 74 68 65 0a 2a   sure that the.*
1f80: 2a 20 76 65 72 73 69 6f 6e 20 6f 66 20 53 51 4c  * version of SQL
1f90: 69 74 65 20 74 68 61 74 20 69 74 20 69 73 20 6c  ite that it is l
1fa0: 69 6e 6b 69 6e 67 20 61 67 61 69 6e 73 74 20 77  inking against w
1fb0: 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  as compiled with
1fc0: 0a 2a 2a 20 74 68 65 20 64 65 73 69 72 65 64 20  .** the desired 
1fd0: 73 65 74 74 69 6e 67 20 6f 66 20 74 68 65 20 5b  setting of the [
1fe0: 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
1ff0: 45 5d 20 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20  E] macro..**.** 
2000: 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 6f  This interface o
2010: 6e 6c 79 20 72 65 70 6f 72 74 73 20 6f 6e 20 74  nly reports on t
2020: 68 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  he compile-time 
2030: 6d 75 74 65 78 20 73 65 74 74 69 6e 67 0a 2a 2a  mutex setting.**
2040: 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   of the [SQLITE_
2050: 54 48 52 45 41 44 53 41 46 45 5d 20 66 6c 61 67  THREADSAFE] flag
2060: 2e 20 20 49 66 20 53 51 4c 69 74 65 20 69 73 20  .  If SQLite is 
2070: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
2080: 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41   SQLITE_THREADSA
2090: 46 45 3d 31 20 6f 72 20 3d 32 20 74 68 65 6e 20  FE=1 or =2 then 
20a0: 6d 75 74 65 78 65 73 20 61 72 65 20 65 6e 61 62  mutexes are enab
20b0: 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 20 62  led by default b
20c0: 75 74 0a 2a 2a 20 63 61 6e 20 62 65 20 66 75 6c  ut.** can be ful
20d0: 6c 79 20 6f 72 20 70 61 72 74 69 61 6c 6c 79 20  ly or partially 
20e0: 64 69 73 61 62 6c 65 64 20 75 73 69 6e 67 20 61  disabled using a
20f0: 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
2100: 33 5f 63 6f 6e 66 69 67 28 29 5d 0a 2a 2a 20 77  3_config()].** w
2110: 69 74 68 20 74 68 65 20 76 65 72 62 73 20 5b 53  ith the verbs [S
2120: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e  QLITE_CONFIG_SIN
2130: 47 4c 45 54 48 52 45 41 44 5d 2c 20 5b 53 51 4c  GLETHREAD], [SQL
2140: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49  ITE_CONFIG_MULTI
2150: 54 48 52 45 41 44 5d 2c 0a 2a 2a 20 6f 72 20 5b  THREAD],.** or [
2160: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45  SQLITE_CONFIG_SE
2170: 52 49 41 4c 49 5a 45 44 5d 2e 20 20 5e 28 54 68  RIALIZED].  ^(Th
2180: 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f  e return value o
2190: 66 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33  f the.** sqlite3
21a0: 5f 74 68 72 65 61 64 73 61 66 65 28 29 20 66 75  _threadsafe() fu
21b0: 6e 63 74 69 6f 6e 20 73 68 6f 77 73 20 6f 6e 6c  nction shows onl
21c0: 79 20 74 68 65 20 63 6f 6d 70 69 6c 65 2d 74 69  y the compile-ti
21d0: 6d 65 20 73 65 74 74 69 6e 67 20 6f 66 0a 2a 2a  me setting of.**
21e0: 20 74 68 72 65 61 64 20 73 61 66 65 74 79 2c 20   thread safety, 
21f0: 6e 6f 74 20 61 6e 79 20 72 75 6e 2d 74 69 6d 65  not any run-time
2200: 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 61 74   changes to that
2210: 20 73 65 74 74 69 6e 67 20 6d 61 64 65 20 62 79   setting made by
2220: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66  .** sqlite3_conf
2230: 69 67 28 29 2e 20 49 6e 20 6f 74 68 65 72 20 77  ig(). In other w
2240: 6f 72 64 73 2c 20 74 68 65 20 72 65 74 75 72 6e  ords, the return
2250: 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69   value from sqli
2260: 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 29  te3_threadsafe()
2270: 0a 2a 2a 20 69 73 20 75 6e 63 68 61 6e 67 65 64  .** is unchanged
2280: 20 62 79 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c   by calls to sql
2290: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 2e 29 5e  ite3_config().)^
22a0: 0a 2a 2a 0a 2a 2a 20 53 65 65 20 74 68 65 20 5b  .**.** See the [
22b0: 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
22c0: 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f  documentation fo
22d0: 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66  r additional inf
22e0: 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 69 6e 74  ormation..*/.int
22f0: 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73   sqlite3_threads
2300: 61 66 65 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a  afe(void);../*.*
2310: 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61 74 61  * CAPI3REF: Data
2320: 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20  base Connection 
2330: 48 61 6e 64 6c 65 0a 2a 2a 20 4b 45 59 57 4f 52  Handle.** KEYWOR
2340: 44 53 3a 20 7b 64 61 74 61 62 61 73 65 20 63 6f  DS: {database co
2350: 6e 6e 65 63 74 69 6f 6e 7d 20 7b 64 61 74 61 62  nnection} {datab
2360: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 7d  ase connections}
2370: 0a 2a 2a 0a 2a 2a 20 45 61 63 68 20 6f 70 65 6e  .**.** Each open
2380: 20 53 51 4c 69 74 65 20 64 61 74 61 62 61 73 65   SQLite database
2390: 20 69 73 20 72 65 70 72 65 73 65 6e 74 65 64 20   is represented 
23a0: 62 79 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  by a pointer to 
23b0: 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 0a 2a  an instance of.*
23c0: 2a 20 74 68 65 20 6f 70 61 71 75 65 20 73 74 72  * the opaque str
23d0: 75 63 74 75 72 65 20 6e 61 6d 65 64 20 22 73 71  ucture named "sq
23e0: 6c 69 74 65 33 22 2e 20 20 49 74 20 69 73 20 75  lite3".  It is u
23f0: 73 65 66 75 6c 20 74 6f 20 74 68 69 6e 6b 20 6f  seful to think o
2400: 66 20 61 6e 20 73 71 6c 69 74 65 33 0a 2a 2a 20  f an sqlite3.** 
2410: 70 6f 69 6e 74 65 72 20 61 73 20 61 6e 20 6f 62  pointer as an ob
2420: 6a 65 63 74 2e 20 20 54 68 65 20 5b 73 71 6c 69  ject.  The [sqli
2430: 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71  te3_open()], [sq
2440: 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c  lite3_open16()],
2450: 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
2460: 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65  _open_v2()] inte
2470: 72 66 61 63 65 73 20 61 72 65 20 69 74 73 20 63  rfaces are its c
2480: 6f 6e 73 74 72 75 63 74 6f 72 73 2c 20 61 6e 64  onstructors, and
2490: 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28   [sqlite3_close(
24a0: 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74  )].** and [sqlit
24b0: 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 5d 20 61  e3_close_v2()] a
24c0: 72 65 20 69 74 73 20 64 65 73 74 72 75 63 74 6f  re its destructo
24d0: 72 73 2e 20 20 54 68 65 72 65 20 61 72 65 20 6d  rs.  There are m
24e0: 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 69 6e 74  any other.** int
24f0: 65 72 66 61 63 65 73 20 28 73 75 63 68 20 61 73  erfaces (such as
2500: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
2510: 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c  pare_v2()], [sql
2520: 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
2530: 74 69 6f 6e 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20  tion()], and.** 
2540: 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69  [sqlite3_busy_ti
2550: 6d 65 6f 75 74 28 29 5d 20 74 6f 20 6e 61 6d 65  meout()] to name
2560: 20 62 75 74 20 74 68 72 65 65 29 20 74 68 61 74   but three) that
2570: 20 61 72 65 20 6d 65 74 68 6f 64 73 20 6f 6e 20   are methods on 
2580: 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 20 6f 62  an.** sqlite3 ob
2590: 6a 65 63 74 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  ject..*/.typedef
25a0: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 20   struct sqlite3 
25b0: 73 71 6c 69 74 65 33 3b 0a 0a 2f 2a 0a 2a 2a 20  sqlite3;../*.** 
25c0: 43 41 50 49 33 52 45 46 3a 20 36 34 2d 42 69 74  CAPI3REF: 64-Bit
25d0: 20 49 6e 74 65 67 65 72 20 54 79 70 65 73 0a 2a   Integer Types.*
25e0: 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c 69  * KEYWORDS: sqli
25f0: 74 65 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 5f  te_int64 sqlite_
2600: 75 69 6e 74 36 34 0a 2a 2a 0a 2a 2a 20 42 65 63  uint64.**.** Bec
2610: 61 75 73 65 20 74 68 65 72 65 20 69 73 20 6e 6f  ause there is no
2620: 20 63 72 6f 73 73 2d 70 6c 61 74 66 6f 72 6d 20   cross-platform 
2630: 77 61 79 20 74 6f 20 73 70 65 63 69 66 79 20 36  way to specify 6
2640: 34 2d 62 69 74 20 69 6e 74 65 67 65 72 20 74 79  4-bit integer ty
2650: 70 65 73 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e  pes.** SQLite in
2660: 63 6c 75 64 65 73 20 74 79 70 65 64 65 66 73 20  cludes typedefs 
2670: 66 6f 72 20 36 34 2d 62 69 74 20 73 69 67 6e 65  for 64-bit signe
2680: 64 20 61 6e 64 20 75 6e 73 69 67 6e 65 64 20 69  d and unsigned i
2690: 6e 74 65 67 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54  ntegers..**.** T
26a0: 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  he sqlite3_int64
26b0: 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 75 69 6e   and sqlite3_uin
26c0: 74 36 34 20 61 72 65 20 74 68 65 20 70 72 65 66  t64 are the pref
26d0: 65 72 72 65 64 20 74 79 70 65 20 64 65 66 69 6e  erred type defin
26e0: 69 74 69 6f 6e 73 2e 0a 2a 2a 20 54 68 65 20 73  itions..** The s
26f0: 71 6c 69 74 65 5f 69 6e 74 36 34 20 61 6e 64 20  qlite_int64 and 
2700: 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 20 74 79  sqlite_uint64 ty
2710: 70 65 73 20 61 72 65 20 73 75 70 70 6f 72 74 65  pes are supporte
2720: 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 0a  d for backwards.
2730: 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ** compatibility
2740: 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68   only..**.** ^Th
2750: 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  e sqlite3_int64 
2760: 61 6e 64 20 73 71 6c 69 74 65 5f 69 6e 74 36 34  and sqlite_int64
2770: 20 74 79 70 65 73 20 63 61 6e 20 73 74 6f 72 65   types can store
2780: 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 0a   integer values.
2790: 2a 2a 20 62 65 74 77 65 65 6e 20 2d 39 32 32 33  ** between -9223
27a0: 33 37 32 30 33 36 38 35 34 37 37 35 38 30 38 20  372036854775808 
27b0: 61 6e 64 20 2b 39 32 32 33 33 37 32 30 33 36 38  and +92233720368
27c0: 35 34 37 37 35 38 30 37 20 69 6e 63 6c 75 73 69  54775807 inclusi
27d0: 76 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c  ve.  ^The.** sql
27e0: 69 74 65 33 5f 75 69 6e 74 36 34 20 61 6e 64 20  ite3_uint64 and 
27f0: 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 20 74 79  sqlite_uint64 ty
2800: 70 65 73 20 63 61 6e 20 73 74 6f 72 65 20 69 6e  pes can store in
2810: 74 65 67 65 72 20 76 61 6c 75 65 73 20 0a 2a 2a  teger values .**
2820: 20 62 65 74 77 65 65 6e 20 30 20 61 6e 64 20 2b   between 0 and +
2830: 31 38 34 34 36 37 34 34 30 37 33 37 30 39 35 35  1844674407370955
2840: 31 36 31 35 20 69 6e 63 6c 75 73 69 76 65 2e 0a  1615 inclusive..
2850: 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45  */.#ifdef SQLITE
2860: 5f 49 4e 54 36 34 5f 54 59 50 45 0a 20 20 74 79  _INT64_TYPE.  ty
2870: 70 65 64 65 66 20 53 51 4c 49 54 45 5f 49 4e 54  pedef SQLITE_INT
2880: 36 34 5f 54 59 50 45 20 73 71 6c 69 74 65 5f 69  64_TYPE sqlite_i
2890: 6e 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20  nt64;.  typedef 
28a0: 75 6e 73 69 67 6e 65 64 20 53 51 4c 49 54 45 5f  unsigned SQLITE_
28b0: 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69 74  INT64_TYPE sqlit
28c0: 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c 69 66 20  e_uint64;.#elif 
28d0: 64 65 66 69 6e 65 64 28 5f 4d 53 43 5f 56 45 52  defined(_MSC_VER
28e0: 29 20 7c 7c 20 64 65 66 69 6e 65 64 28 5f 5f 42  ) || defined(__B
28f0: 4f 52 4c 41 4e 44 43 5f 5f 29 0a 20 20 74 79 70  ORLANDC__).  typ
2900: 65 64 65 66 20 5f 5f 69 6e 74 36 34 20 73 71 6c  edef __int64 sql
2910: 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70  ite_int64;.  typ
2920: 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20 5f 5f  edef unsigned __
2930: 69 6e 74 36 34 20 73 71 6c 69 74 65 5f 75 69 6e  int64 sqlite_uin
2940: 74 36 34 3b 0a 23 65 6c 73 65 0a 20 20 74 79 70  t64;.#else.  typ
2950: 65 64 65 66 20 6c 6f 6e 67 20 6c 6f 6e 67 20 69  edef long long i
2960: 6e 74 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b  nt sqlite_int64;
2970: 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73 69 67  .  typedef unsig
2980: 6e 65 64 20 6c 6f 6e 67 20 6c 6f 6e 67 20 69 6e  ned long long in
2990: 74 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b  t sqlite_uint64;
29a0: 0a 23 65 6e 64 69 66 0a 74 79 70 65 64 65 66 20  .#endif.typedef 
29b0: 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 73 71 6c  sqlite_int64 sql
29c0: 69 74 65 33 5f 69 6e 74 36 34 3b 0a 74 79 70 65  ite3_int64;.type
29d0: 64 65 66 20 73 71 6c 69 74 65 5f 75 69 6e 74 36  def sqlite_uint6
29e0: 34 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34  4 sqlite3_uint64
29f0: 3b 0a 0a 2f 2a 0a 2a 2a 20 49 66 20 63 6f 6d 70  ;../*.** If comp
2a00: 69 6c 69 6e 67 20 66 6f 72 20 61 20 70 72 6f 63  iling for a proc
2a10: 65 73 73 6f 72 20 74 68 61 74 20 6c 61 63 6b 73  essor that lacks
2a20: 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20   floating point 
2a30: 73 75 70 70 6f 72 74 2c 0a 2a 2a 20 73 75 62 73  support,.** subs
2a40: 74 69 74 75 74 65 20 69 6e 74 65 67 65 72 20 66  titute integer f
2a50: 6f 72 20 66 6c 6f 61 74 69 6e 67 2d 70 6f 69 6e  or floating-poin
2a60: 74 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c  t..*/.#ifdef SQL
2a70: 49 54 45 5f 4f 4d 49 54 5f 46 4c 4f 41 54 49 4e  ITE_OMIT_FLOATIN
2a80: 47 5f 50 4f 49 4e 54 0a 23 20 64 65 66 69 6e 65  G_POINT.# define
2a90: 20 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f   double sqlite3_
2aa0: 69 6e 74 36 34 0a 23 65 6e 64 69 66 0a 0a 2f 2a  int64.#endif../*
2ab0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6c  .** CAPI3REF: Cl
2ac0: 6f 73 69 6e 67 20 41 20 44 61 74 61 62 61 73 65  osing A Database
2ad0: 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 44   Connection.** D
2ae0: 45 53 54 52 55 43 54 4f 52 3a 20 73 71 6c 69 74  ESTRUCTOR: sqlit
2af0: 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  e3.**.** ^The sq
2b00: 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 61 6e  lite3_close() an
2b10: 64 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f  d sqlite3_close_
2b20: 76 32 28 29 20 72 6f 75 74 69 6e 65 73 20 61 72  v2() routines ar
2b30: 65 20 64 65 73 74 72 75 63 74 6f 72 73 0a 2a 2a  e destructors.**
2b40: 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65   for the [sqlite
2b50: 33 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e 43  3] object..** ^C
2b60: 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
2b70: 63 6c 6f 73 65 28 29 20 61 6e 64 20 73 71 6c 69  close() and sqli
2b80: 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 72  te3_close_v2() r
2b90: 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b  eturn [SQLITE_OK
2ba0: 5d 20 69 66 0a 2a 2a 20 74 68 65 20 5b 73 71 6c  ] if.** the [sql
2bb0: 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 20  ite3] object is 
2bc0: 73 75 63 63 65 73 73 66 75 6c 6c 79 20 64 65 73  successfully des
2bd0: 74 72 6f 79 65 64 20 61 6e 64 20 61 6c 6c 20 61  troyed and all a
2be0: 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20 72 65 73  ssociated.** res
2bf0: 6f 75 72 63 65 73 20 61 72 65 20 64 65 61 6c 6c  ources are deall
2c00: 6f 63 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49  ocated..**.** ^I
2c10: 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  f the database c
2c20: 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 61 73 73  onnection is ass
2c30: 6f 63 69 61 74 65 64 20 77 69 74 68 20 75 6e 66  ociated with unf
2c40: 69 6e 61 6c 69 7a 65 64 20 70 72 65 70 61 72 65  inalized prepare
2c50: 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73 20  d.** statements 
2c60: 6f 72 20 75 6e 66 69 6e 69 73 68 65 64 20 73 71  or unfinished sq
2c70: 6c 69 74 65 33 5f 62 61 63 6b 75 70 20 6f 62 6a  lite3_backup obj
2c80: 65 63 74 73 20 74 68 65 6e 20 73 71 6c 69 74 65  ects then sqlite
2c90: 33 5f 63 6c 6f 73 65 28 29 0a 2a 2a 20 77 69 6c  3_close().** wil
2ca0: 6c 20 6c 65 61 76 65 20 74 68 65 20 64 61 74 61  l leave the data
2cb0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
2cc0: 6f 70 65 6e 20 61 6e 64 20 72 65 74 75 72 6e 20  open and return 
2cd0: 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 0a 2a  [SQLITE_BUSY]..*
2ce0: 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6c  * ^If sqlite3_cl
2cf0: 6f 73 65 5f 76 32 28 29 20 69 73 20 63 61 6c 6c  ose_v2() is call
2d00: 65 64 20 77 69 74 68 20 75 6e 66 69 6e 61 6c 69  ed with unfinali
2d10: 7a 65 64 20 70 72 65 70 61 72 65 64 20 73 74 61  zed prepared sta
2d20: 74 65 6d 65 6e 74 73 0a 2a 2a 20 61 6e 64 2f 6f  tements.** and/o
2d30: 72 20 75 6e 66 69 6e 69 73 68 65 64 20 73 71 6c  r unfinished sql
2d40: 69 74 65 33 5f 62 61 63 6b 75 70 73 2c 20 74 68  ite3_backups, th
2d50: 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
2d60: 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 65 63 6f 6d  connection becom
2d70: 65 73 0a 2a 2a 20 61 6e 20 75 6e 75 73 61 62 6c  es.** an unusabl
2d80: 65 20 22 7a 6f 6d 62 69 65 22 20 77 68 69 63 68  e "zombie" which
2d90: 20 77 69 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61   will automatica
2da0: 6c 6c 79 20 62 65 20 64 65 61 6c 6c 6f 63 61 74  lly be deallocat
2db0: 65 64 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20 6c  ed when the.** l
2dc0: 61 73 74 20 70 72 65 70 61 72 65 64 20 73 74 61  ast prepared sta
2dd0: 74 65 6d 65 6e 74 20 69 73 20 66 69 6e 61 6c 69  tement is finali
2de0: 7a 65 64 20 6f 72 20 74 68 65 20 6c 61 73 74 20  zed or the last 
2df0: 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 20 69  sqlite3_backup i
2e00: 73 0a 2a 2a 20 66 69 6e 69 73 68 65 64 2e 20 20  s.** finished.  
2e10: 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73  The sqlite3_clos
2e20: 65 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65  e_v2() interface
2e30: 20 69 73 20 69 6e 74 65 6e 64 65 64 20 66 6f 72   is intended for
2e40: 20 75 73 65 20 77 69 74 68 0a 2a 2a 20 68 6f 73   use with.** hos
2e50: 74 20 6c 61 6e 67 75 61 67 65 73 20 74 68 61 74  t languages that
2e60: 20 61 72 65 20 67 61 72 62 61 67 65 20 63 6f 6c   are garbage col
2e70: 6c 65 63 74 65 64 2c 20 61 6e 64 20 77 68 65 72  lected, and wher
2e80: 65 20 74 68 65 20 6f 72 64 65 72 20 69 6e 20 77  e the order in w
2e90: 68 69 63 68 0a 2a 2a 20 64 65 73 74 72 75 63 74  hich.** destruct
2ea0: 6f 72 73 20 61 72 65 20 63 61 6c 6c 65 64 20 69  ors are called i
2eb0: 73 20 61 72 62 69 74 72 61 72 79 2e 0a 2a 2a 0a  s arbitrary..**.
2ec0: 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20  ** Applications 
2ed0: 73 68 6f 75 6c 64 20 5b 73 71 6c 69 74 65 33 5f  should [sqlite3_
2ee0: 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c  finalize | final
2ef0: 69 7a 65 5d 20 61 6c 6c 20 5b 70 72 65 70 61 72  ize] all [prepar
2f00: 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2c 0a  ed statements],.
2f10: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  ** [sqlite3_blob
2f20: 5f 63 6c 6f 73 65 20 7c 20 63 6c 6f 73 65 5d 20  _close | close] 
2f30: 61 6c 6c 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65  all [BLOB handle
2f40: 73 5d 2c 20 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c  s], and .** [sql
2f50: 69 74 65 33 5f 62 61 63 6b 75 70 5f 66 69 6e 69  ite3_backup_fini
2f60: 73 68 20 7c 20 66 69 6e 69 73 68 5d 20 61 6c 6c  sh | finish] all
2f70: 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70   [sqlite3_backup
2f80: 5d 20 6f 62 6a 65 63 74 73 20 61 73 73 6f 63 69  ] objects associ
2f90: 61 74 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65  ated.** with the
2fa0: 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63   [sqlite3] objec
2fb0: 74 20 70 72 69 6f 72 20 74 6f 20 61 74 74 65 6d  t prior to attem
2fc0: 70 74 69 6e 67 20 74 6f 20 63 6c 6f 73 65 20 74  pting to close t
2fd0: 68 65 20 6f 62 6a 65 63 74 2e 20 20 5e 49 66 0a  he object.  ^If.
2fe0: 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  ** sqlite3_close
2ff0: 5f 76 32 28 29 20 69 73 20 63 61 6c 6c 65 64 20  _v2() is called 
3000: 6f 6e 20 61 20 5b 64 61 74 61 62 61 73 65 20 63  on a [database c
3010: 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74 20  onnection] that 
3020: 73 74 69 6c 6c 20 68 61 73 0a 2a 2a 20 6f 75 74  still has.** out
3030: 73 74 61 6e 64 69 6e 67 20 5b 70 72 65 70 61 72  standing [prepar
3040: 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2c 20  ed statements], 
3050: 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 20  [BLOB handles], 
3060: 61 6e 64 2f 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  and/or.** [sqlit
3070: 65 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a 65 63  e3_backup] objec
3080: 74 73 20 74 68 65 6e 20 69 74 20 72 65 74 75 72  ts then it retur
3090: 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 61  ns [SQLITE_OK] a
30a0: 6e 64 20 74 68 65 20 64 65 61 6c 6c 6f 63 61 74  nd the deallocat
30b0: 69 6f 6e 0a 2a 2a 20 6f 66 20 72 65 73 6f 75 72  ion.** of resour
30c0: 63 65 73 20 69 73 20 64 65 66 65 72 72 65 64 20  ces is deferred 
30d0: 75 6e 74 69 6c 20 61 6c 6c 20 5b 70 72 65 70 61  until all [prepa
30e0: 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2c  red statements],
30f0: 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 2c   [BLOB handles],
3100: 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  .** and [sqlite3
3110: 5f 62 61 63 6b 75 70 5d 20 6f 62 6a 65 63 74 73  _backup] objects
3120: 20 61 72 65 20 61 6c 73 6f 20 64 65 73 74 72 6f   are also destro
3130: 79 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61  yed..**.** ^If a
3140: 6e 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65  n [sqlite3] obje
3150: 63 74 20 69 73 20 64 65 73 74 72 6f 79 65 64 20  ct is destroyed 
3160: 77 68 69 6c 65 20 61 20 74 72 61 6e 73 61 63 74  while a transact
3170: 69 6f 6e 20 69 73 20 6f 70 65 6e 2c 0a 2a 2a 20  ion is open,.** 
3180: 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  the transaction 
3190: 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  is automatically
31a0: 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a   rolled back..**
31b0: 0a 2a 2a 20 54 68 65 20 43 20 70 61 72 61 6d 65  .** The C parame
31c0: 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ter to [sqlite3_
31d0: 63 6c 6f 73 65 28 43 29 5d 20 61 6e 64 20 5b 73  close(C)] and [s
31e0: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28  qlite3_close_v2(
31f0: 43 29 5d 0a 2a 2a 20 6d 75 73 74 20 62 65 20 65  C)].** must be e
3200: 69 74 68 65 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20  ither a NULL.** 
3210: 70 6f 69 6e 74 65 72 20 6f 72 20 61 6e 20 5b 73  pointer or an [s
3220: 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 70  qlite3] object p
3230: 6f 69 6e 74 65 72 20 6f 62 74 61 69 6e 65 64 0a  ointer obtained.
3240: 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ** from [sqlite3
3250: 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74  _open()], [sqlit
3260: 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 6f 72  e3_open16()], or
3270: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  .** [sqlite3_ope
3280: 6e 5f 76 32 28 29 5d 2c 20 61 6e 64 20 6e 6f 74  n_v2()], and not
3290: 20 70 72 65 76 69 6f 75 73 6c 79 20 63 6c 6f 73   previously clos
32a0: 65 64 2e 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20  ed..** ^Calling 
32b0: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 20  sqlite3_close() 
32c0: 6f 72 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  or sqlite3_close
32d0: 5f 76 32 28 29 20 77 69 74 68 20 61 20 4e 55 4c  _v2() with a NUL
32e0: 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 61 72 67  L pointer.** arg
32f0: 75 6d 65 6e 74 20 69 73 20 61 20 68 61 72 6d 6c  ument is a harml
3300: 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2f 0a 69 6e  ess no-op..*/.in
3310: 74 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28  t sqlite3_close(
3320: 73 71 6c 69 74 65 33 2a 29 3b 0a 69 6e 74 20 73  sqlite3*);.int s
3330: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28  qlite3_close_v2(
3340: 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a  sqlite3*);../*.*
3350: 2a 20 54 68 65 20 74 79 70 65 20 66 6f 72 20 61  * The type for a
3360: 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
3370: 6f 6e 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20 6c  on..** This is l
3380: 65 67 61 63 79 20 61 6e 64 20 64 65 70 72 65 63  egacy and deprec
3390: 61 74 65 64 2e 20 20 49 74 20 69 73 20 69 6e 63  ated.  It is inc
33a0: 6c 75 64 65 64 20 66 6f 72 20 68 69 73 74 6f 72  luded for histor
33b0: 69 63 61 6c 0a 2a 2a 20 63 6f 6d 70 61 74 69 62  ical.** compatib
33c0: 69 6c 69 74 79 20 61 6e 64 20 69 73 20 6e 6f 74  ility and is not
33d0: 20 64 6f 63 75 6d 65 6e 74 65 64 2e 0a 2a 2f 0a   documented..*/.
33e0: 74 79 70 65 64 65 66 20 69 6e 74 20 28 2a 73 71  typedef int (*sq
33f0: 6c 69 74 65 33 5f 63 61 6c 6c 62 61 63 6b 29 28  lite3_callback)(
3400: 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a  void*,int,char**
3410: 2c 20 63 68 61 72 2a 2a 29 3b 0a 0a 2f 2a 0a 2a  , char**);../*.*
3420: 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 6e 65 2d  * CAPI3REF: One-
3430: 53 74 65 70 20 51 75 65 72 79 20 45 78 65 63 75  Step Query Execu
3440: 74 69 6f 6e 20 49 6e 74 65 72 66 61 63 65 0a 2a  tion Interface.*
3450: 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
3460: 33 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  3.**.** The sqli
3470: 74 65 33 5f 65 78 65 63 28 29 20 69 6e 74 65 72  te3_exec() inter
3480: 66 61 63 65 20 69 73 20 61 20 63 6f 6e 76 65 6e  face is a conven
3490: 69 65 6e 63 65 20 77 72 61 70 70 65 72 20 61 72  ience wrapper ar
34a0: 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ound.** [sqlite3
34b0: 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20  _prepare_v2()], 
34c0: 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
34d0: 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 66  , and [sqlite3_f
34e0: 69 6e 61 6c 69 7a 65 28 29 5d 2c 0a 2a 2a 20 74  inalize()],.** t
34f0: 68 61 74 20 61 6c 6c 6f 77 73 20 61 6e 20 61 70  hat allows an ap
3500: 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 72 75 6e  plication to run
3510: 20 6d 75 6c 74 69 70 6c 65 20 73 74 61 74 65 6d   multiple statem
3520: 65 6e 74 73 20 6f 66 20 53 51 4c 0a 2a 2a 20 77  ents of SQL.** w
3530: 69 74 68 6f 75 74 20 68 61 76 69 6e 67 20 74 6f  ithout having to
3540: 20 75 73 65 20 61 20 6c 6f 74 20 6f 66 20 43 20   use a lot of C 
3550: 63 6f 64 65 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68  code. .**.** ^Th
3560: 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  e sqlite3_exec()
3570: 20 69 6e 74 65 72 66 61 63 65 20 72 75 6e 73 20   interface runs 
3580: 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 55 54 46  zero or more UTF
3590: 2d 38 20 65 6e 63 6f 64 65 64 2c 0a 2a 2a 20 73  -8 encoded,.** s
35a0: 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74  emicolon-separat
35b0: 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  e SQL statements
35c0: 20 70 61 73 73 65 64 20 69 6e 74 6f 20 69 74 73   passed into its
35d0: 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2c 0a 2a   2nd argument,.*
35e0: 2a 20 69 6e 20 74 68 65 20 63 6f 6e 74 65 78 74  * in the context
35f0: 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 73   of the [databas
3600: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 61  e connection] pa
3610: 73 73 65 64 20 69 6e 20 61 73 20 69 74 73 20 31  ssed in as its 1
3620: 73 74 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 2e 20  st.** argument. 
3630: 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63   ^If the callbac
3640: 6b 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 68  k function of th
3650: 65 20 33 72 64 20 61 72 67 75 6d 65 6e 74 20 74  e 3rd argument t
3660: 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65  o.** sqlite3_exe
3670: 63 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c  c() is not NULL,
3680: 20 74 68 65 6e 20 69 74 20 69 73 20 69 6e 76 6f   then it is invo
3690: 6b 65 64 20 66 6f 72 20 65 61 63 68 20 72 65 73  ked for each res
36a0: 75 6c 74 20 72 6f 77 0a 2a 2a 20 63 6f 6d 69 6e  ult row.** comin
36b0: 67 20 6f 75 74 20 6f 66 20 74 68 65 20 65 76 61  g out of the eva
36c0: 6c 75 61 74 65 64 20 53 51 4c 20 73 74 61 74 65  luated SQL state
36d0: 6d 65 6e 74 73 2e 20 20 5e 54 68 65 20 34 74 68  ments.  ^The 4th
36e0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20   argument to.** 
36f0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69  sqlite3_exec() i
3700: 73 20 72 65 6c 61 79 65 64 20 74 68 72 6f 75 67  s relayed throug
3710: 68 20 74 6f 20 74 68 65 20 31 73 74 20 61 72 67  h to the 1st arg
3720: 75 6d 65 6e 74 20 6f 66 20 65 61 63 68 0a 2a 2a  ument of each.**
3730: 20 63 61 6c 6c 62 61 63 6b 20 69 6e 76 6f 63 61   callback invoca
3740: 74 69 6f 6e 2e 20 20 5e 49 66 20 74 68 65 20 63  tion.  ^If the c
3750: 61 6c 6c 62 61 63 6b 20 70 6f 69 6e 74 65 72 20  allback pointer 
3760: 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  to sqlite3_exec(
3770: 29 0a 2a 2a 20 69 73 20 4e 55 4c 4c 2c 20 74 68  ).** is NULL, th
3780: 65 6e 20 6e 6f 20 63 61 6c 6c 62 61 63 6b 20 69  en no callback i
3790: 73 20 65 76 65 72 20 69 6e 76 6f 6b 65 64 20 61  s ever invoked a
37a0: 6e 64 20 72 65 73 75 6c 74 20 72 6f 77 73 20 61  nd result rows a
37b0: 72 65 0a 2a 2a 20 69 67 6e 6f 72 65 64 2e 0a 2a  re.** ignored..*
37c0: 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 65 72 72 6f  *.** ^If an erro
37d0: 72 20 6f 63 63 75 72 73 20 77 68 69 6c 65 20 65  r occurs while e
37e0: 76 61 6c 75 61 74 69 6e 67 20 74 68 65 20 53 51  valuating the SQ
37f0: 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 70 61 73  L statements pas
3800: 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69  sed into.** sqli
3810: 74 65 33 5f 65 78 65 63 28 29 2c 20 74 68 65 6e  te3_exec(), then
3820: 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 74 68   execution of th
3830: 65 20 63 75 72 72 65 6e 74 20 73 74 61 74 65 6d  e current statem
3840: 65 6e 74 20 73 74 6f 70 73 20 61 6e 64 0a 2a 2a  ent stops and.**
3850: 20 73 75 62 73 65 71 75 65 6e 74 20 73 74 61 74   subsequent stat
3860: 65 6d 65 6e 74 73 20 61 72 65 20 73 6b 69 70 70  ements are skipp
3870: 65 64 2e 20 20 5e 49 66 20 74 68 65 20 35 74 68  ed.  ^If the 5th
3880: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
3890: 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20  lite3_exec().** 
38a0: 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e  is not NULL then
38b0: 20 61 6e 79 20 65 72 72 6f 72 20 6d 65 73 73 61   any error messa
38c0: 67 65 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e  ge is written in
38d0: 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e  to memory obtain
38e0: 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69  ed.** from [sqli
38f0: 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e  te3_malloc()] an
3900: 64 20 70 61 73 73 65 64 20 62 61 63 6b 20 74 68  d passed back th
3910: 72 6f 75 67 68 20 74 68 65 20 35 74 68 20 70 61  rough the 5th pa
3920: 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 54 6f 20 61  rameter..** To a
3930: 76 6f 69 64 20 6d 65 6d 6f 72 79 20 6c 65 61 6b  void memory leak
3940: 73 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  s, the applicati
3950: 6f 6e 20 73 68 6f 75 6c 64 20 69 6e 76 6f 6b 65  on should invoke
3960: 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
3970: 5d 0a 2a 2a 20 6f 6e 20 65 72 72 6f 72 20 6d 65  ].** on error me
3980: 73 73 61 67 65 20 73 74 72 69 6e 67 73 20 72 65  ssage strings re
3990: 74 75 72 6e 65 64 20 74 68 72 6f 75 67 68 20 74  turned through t
39a0: 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72  he 5th parameter
39b0: 20 6f 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65   of.** sqlite3_e
39c0: 78 65 63 28 29 20 61 66 74 65 72 20 74 68 65 20  xec() after the 
39d0: 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74  error message st
39e0: 72 69 6e 67 20 69 73 20 6e 6f 20 6c 6f 6e 67 65  ring is no longe
39f0: 72 20 6e 65 65 64 65 64 2e 0a 2a 2a 20 5e 49 66  r needed..** ^If
3a00: 20 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74   the 5th paramet
3a10: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78  er to sqlite3_ex
3a20: 65 63 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  ec() is not NULL
3a30: 20 61 6e 64 20 6e 6f 20 65 72 72 6f 72 73 0a 2a   and no errors.*
3a40: 2a 20 6f 63 63 75 72 2c 20 74 68 65 6e 20 73 71  * occur, then sq
3a50: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 73 65 74  lite3_exec() set
3a60: 73 20 74 68 65 20 70 6f 69 6e 74 65 72 20 69 6e  s the pointer in
3a70: 20 69 74 73 20 35 74 68 20 70 61 72 61 6d 65 74   its 5th paramet
3a80: 65 72 20 74 6f 0a 2a 2a 20 4e 55 4c 4c 20 62 65  er to.** NULL be
3a90: 66 6f 72 65 20 72 65 74 75 72 6e 69 6e 67 2e 0a  fore returning..
3aa0: 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 73 71 6c  **.** ^If an sql
3ab0: 69 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c  ite3_exec() call
3ac0: 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e  back returns non
3ad0: 2d 7a 65 72 6f 2c 20 74 68 65 20 73 71 6c 69 74  -zero, the sqlit
3ae0: 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 72 6f 75  e3_exec().** rou
3af0: 74 69 6e 65 20 72 65 74 75 72 6e 73 20 53 51 4c  tine returns SQL
3b00: 49 54 45 5f 41 42 4f 52 54 20 77 69 74 68 6f 75  ITE_ABORT withou
3b10: 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 63  t invoking the c
3b20: 61 6c 6c 62 61 63 6b 20 61 67 61 69 6e 20 61 6e  allback again an
3b30: 64 0a 2a 2a 20 77 69 74 68 6f 75 74 20 72 75 6e  d.** without run
3b40: 6e 69 6e 67 20 61 6e 79 20 73 75 62 73 65 71 75  ning any subsequ
3b50: 65 6e 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ent SQL statemen
3b60: 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 32  ts..**.** ^The 2
3b70: 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  nd argument to t
3b80: 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  he sqlite3_exec(
3b90: 29 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  ) callback funct
3ba0: 69 6f 6e 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75  ion is the.** nu
3bb0: 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20  mber of columns 
3bc0: 69 6e 20 74 68 65 20 72 65 73 75 6c 74 2e 20 20  in the result.  
3bd0: 5e 54 68 65 20 33 72 64 20 61 72 67 75 6d 65 6e  ^The 3rd argumen
3be0: 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  t to the sqlite3
3bf0: 5f 65 78 65 63 28 29 0a 2a 2a 20 63 61 6c 6c 62  _exec().** callb
3c00: 61 63 6b 20 69 73 20 61 6e 20 61 72 72 61 79 20  ack is an array 
3c10: 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73  of pointers to s
3c20: 74 72 69 6e 67 73 20 6f 62 74 61 69 6e 65 64 20  trings obtained 
3c30: 61 73 20 69 66 20 66 72 6f 6d 0a 2a 2a 20 5b 73  as if from.** [s
3c40: 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
3c50: 78 74 28 29 5d 2c 20 6f 6e 65 20 66 6f 72 20 65  xt()], one for e
3c60: 61 63 68 20 63 6f 6c 75 6d 6e 2e 20 20 5e 49 66  ach column.  ^If
3c70: 20 61 6e 20 65 6c 65 6d 65 6e 74 20 6f 66 20 61   an element of a
3c80: 0a 2a 2a 20 72 65 73 75 6c 74 20 72 6f 77 20 69  .** result row i
3c90: 73 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65 20  s NULL then the 
3ca0: 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 73 74  corresponding st
3cb0: 72 69 6e 67 20 70 6f 69 6e 74 65 72 20 66 6f 72  ring pointer for
3cc0: 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   the.** sqlite3_
3cd0: 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20  exec() callback 
3ce0: 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
3cf0: 72 2e 20 20 5e 54 68 65 20 34 74 68 20 61 72 67  r.  ^The 4th arg
3d00: 75 6d 65 6e 74 20 74 6f 20 74 68 65 0a 2a 2a 20  ument to the.** 
3d10: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63  sqlite3_exec() c
3d20: 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 61 72  allback is an ar
3d30: 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20  ray of pointers 
3d40: 74 6f 20 73 74 72 69 6e 67 73 20 77 68 65 72 65  to strings where
3d50: 20 65 61 63 68 0a 2a 2a 20 65 6e 74 72 79 20 72   each.** entry r
3d60: 65 70 72 65 73 65 6e 74 73 20 74 68 65 20 6e 61  epresents the na
3d70: 6d 65 20 6f 66 20 63 6f 72 72 65 73 70 6f 6e 64  me of correspond
3d80: 69 6e 67 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  ing result colum
3d90: 6e 20 61 73 20 6f 62 74 61 69 6e 65 64 0a 2a 2a  n as obtained.**
3da0: 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63   from [sqlite3_c
3db0: 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 5d 2e 0a 2a  olumn_name()]..*
3dc0: 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 32 6e 64  *.** ^If the 2nd
3dd0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
3de0: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20  lite3_exec() is 
3df0: 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20  a NULL pointer, 
3e00: 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20  a pointer.** to 
3e10: 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c  an empty string,
3e20: 20 6f 72 20 61 20 70 6f 69 6e 74 65 72 20 74 68   or a pointer th
3e30: 61 74 20 63 6f 6e 74 61 69 6e 73 20 6f 6e 6c 79  at contains only
3e40: 20 77 68 69 74 65 73 70 61 63 65 20 61 6e 64 2f   whitespace and/
3e50: 6f 72 20 0a 2a 2a 20 53 51 4c 20 63 6f 6d 6d 65  or .** SQL comme
3e60: 6e 74 73 2c 20 74 68 65 6e 20 6e 6f 20 53 51 4c  nts, then no SQL
3e70: 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20   statements are 
3e80: 65 76 61 6c 75 61 74 65 64 20 61 6e 64 20 74 68  evaluated and th
3e90: 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 69 73  e database.** is
3ea0: 20 6e 6f 74 20 63 68 61 6e 67 65 64 2e 0a 2a 2a   not changed..**
3eb0: 0a 2a 2a 20 52 65 73 74 72 69 63 74 69 6f 6e 73  .** Restrictions
3ec0: 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
3ed0: 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c 69 63 61  <li> The applica
3ee0: 74 69 6f 6e 20 6d 75 73 74 20 65 6e 73 75 72 65  tion must ensure
3ef0: 20 74 68 61 74 20 74 68 65 20 31 73 74 20 70 61   that the 1st pa
3f00: 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
3f10: 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 20 20 20  e3_exec().**    
3f20: 20 20 69 73 20 61 20 76 61 6c 69 64 20 61 6e 64    is a valid and
3f30: 20 6f 70 65 6e 20 5b 64 61 74 61 62 61 73 65 20   open [database 
3f40: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20  connection]..** 
3f50: 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c 69 63 61  <li> The applica
3f60: 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 63 6c  tion must not cl
3f70: 6f 73 65 20 74 68 65 20 5b 64 61 74 61 62 61 73  ose the [databas
3f80: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70  e connection] sp
3f90: 65 63 69 66 69 65 64 20 62 79 0a 2a 2a 20 20 20  ecified by.**   
3fa0: 20 20 20 74 68 65 20 31 73 74 20 70 61 72 61 6d     the 1st param
3fb0: 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
3fc0: 65 78 65 63 28 29 20 77 68 69 6c 65 20 73 71 6c  exec() while sql
3fd0: 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 72  ite3_exec() is r
3fe0: 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 6c 69 3e 20  unning..** <li> 
3ff0: 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
4000: 6d 75 73 74 20 6e 6f 74 20 6d 6f 64 69 66 79 20  must not modify 
4010: 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
4020: 74 20 74 65 78 74 20 70 61 73 73 65 64 20 69 6e  t text passed in
4030: 74 6f 0a 2a 2a 20 20 20 20 20 20 74 68 65 20 32  to.**      the 2
4040: 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20  nd parameter of 
4050: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 77  sqlite3_exec() w
4060: 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 65 78 65  hile sqlite3_exe
4070: 63 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a  c() is running..
4080: 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 69 6e 74 20  ** </ul>.*/.int 
4090: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 0a 20 20  sqlite3_exec(.  
40a0: 73 71 6c 69 74 65 33 2a 2c 20 20 20 20 20 20 20  sqlite3*,       
40b0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
40c0: 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 6e             /* An
40d0: 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 20 2a   open database *
40e0: 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
40f0: 73 71 6c 2c 20 20 20 20 20 20 20 20 20 20 20 20  sql,            
4100: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
4110: 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 76 61 6c  * SQL to be eval
4120: 75 61 74 65 64 20 2a 2f 0a 20 20 69 6e 74 20 28  uated */.  int (
4130: 2a 63 61 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a  *callback)(void*
4140: 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 63 68 61 72  ,int,char**,char
4150: 2a 2a 29 2c 20 20 2f 2a 20 43 61 6c 6c 62 61 63  **),  /* Callbac
4160: 6b 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20  k function */.  
4170: 76 6f 69 64 20 2a 2c 20 20 20 20 20 20 20 20 20  void *,         
4180: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4190: 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 31 73             /* 1s
41a0: 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 63 61  t argument to ca
41b0: 6c 6c 62 61 63 6b 20 2a 2f 0a 20 20 63 68 61 72  llback */.  char
41c0: 20 2a 2a 65 72 72 6d 73 67 20 20 20 20 20 20 20   **errmsg       
41d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
41e0: 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 20         /* Error 
41f0: 6d 73 67 20 77 72 69 74 74 65 6e 20 68 65 72 65  msg written here
4200: 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.);../*.** CA
4210: 50 49 33 52 45 46 3a 20 52 65 73 75 6c 74 20 43  PI3REF: Result C
4220: 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  odes.** KEYWORDS
4230: 3a 20 7b 72 65 73 75 6c 74 20 63 6f 64 65 20 64  : {result code d
4240: 65 66 69 6e 69 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a  efinitions}.**.*
4250: 2a 20 4d 61 6e 79 20 53 51 4c 69 74 65 20 66 75  * Many SQLite fu
4260: 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 61  nctions return a
4270: 6e 20 69 6e 74 65 67 65 72 20 72 65 73 75 6c 74  n integer result
4280: 20 63 6f 64 65 20 66 72 6f 6d 20 74 68 65 20 73   code from the s
4290: 65 74 20 73 68 6f 77 6e 0a 2a 2a 20 68 65 72 65  et shown.** here
42a0: 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 69 6e 64   in order to ind
42b0: 69 63 61 74 65 20 73 75 63 63 65 73 73 20 6f 72  icate success or
42c0: 20 66 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a 20   failure..**.** 
42d0: 4e 65 77 20 65 72 72 6f 72 20 63 6f 64 65 73 20  New error codes 
42e0: 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20  may be added in 
42f0: 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20  future versions 
4300: 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a  of SQLite..**.**
4310: 20 53 65 65 20 61 6c 73 6f 3a 20 5b 65 78 74 65   See also: [exte
4320: 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
4330: 20 64 65 66 69 6e 69 74 69 6f 6e 73 5d 0a 2a 2f   definitions].*/
4340: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4350: 4f 4b 20 20 20 20 20 20 20 20 20 20 20 30 20 20  OK           0  
4360: 20 2f 2a 20 53 75 63 63 65 73 73 66 75 6c 20 72   /* Successful r
4370: 65 73 75 6c 74 20 2a 2f 0a 2f 2a 20 62 65 67 69  esult */./* begi
4380: 6e 6e 69 6e 67 2d 6f 66 2d 65 72 72 6f 72 2d 63  nning-of-error-c
4390: 6f 64 65 73 20 2a 2f 0a 23 64 65 66 69 6e 65 20  odes */.#define 
43a0: 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 20 20 20  SQLITE_ERROR    
43b0: 20 20 20 20 31 20 20 20 2f 2a 20 53 51 4c 20 65      1   /* SQL e
43c0: 72 72 6f 72 20 6f 72 20 6d 69 73 73 69 6e 67 20  rror or missing 
43d0: 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 65 66  database */.#def
43e0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 52  ine SQLITE_INTER
43f0: 4e 41 4c 20 20 20 20 20 32 20 20 20 2f 2a 20 49  NAL     2   /* I
4400: 6e 74 65 72 6e 61 6c 20 6c 6f 67 69 63 20 65 72  nternal logic er
4410: 72 6f 72 20 69 6e 20 53 51 4c 69 74 65 20 2a 2f  ror in SQLite */
4420: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4430: 50 45 52 4d 20 20 20 20 20 20 20 20 20 33 20 20  PERM         3  
4440: 20 2f 2a 20 41 63 63 65 73 73 20 70 65 72 6d 69   /* Access permi
4450: 73 73 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f 0a  ssion denied */.
4460: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
4470: 42 4f 52 54 20 20 20 20 20 20 20 20 34 20 20 20  BORT        4   
4480: 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 72 6f 75 74  /* Callback rout
4490: 69 6e 65 20 72 65 71 75 65 73 74 65 64 20 61 6e  ine requested an
44a0: 20 61 62 6f 72 74 20 2a 2f 0a 23 64 65 66 69 6e   abort */.#defin
44b0: 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20 20 20  e SQLITE_BUSY   
44c0: 20 20 20 20 20 20 35 20 20 20 2f 2a 20 54 68 65        5   /* The
44d0: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 69   database file i
44e0: 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66  s locked */.#def
44f0: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45  ine SQLITE_LOCKE
4500: 44 20 20 20 20 20 20 20 36 20 20 20 2f 2a 20 41  D       6   /* A
4510: 20 74 61 62 6c 65 20 69 6e 20 74 68 65 20 64 61   table in the da
4520: 74 61 62 61 73 65 20 69 73 20 6c 6f 63 6b 65 64  tabase is locked
4530: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4540: 54 45 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20  TE_NOMEM        
4550: 37 20 20 20 2f 2a 20 41 20 6d 61 6c 6c 6f 63 28  7   /* A malloc(
4560: 29 20 66 61 69 6c 65 64 20 2a 2f 0a 23 64 65 66  ) failed */.#def
4570: 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f  ine SQLITE_READO
4580: 4e 4c 59 20 20 20 20 20 38 20 20 20 2f 2a 20 41  NLY     8   /* A
4590: 74 74 65 6d 70 74 20 74 6f 20 77 72 69 74 65 20  ttempt to write 
45a0: 61 20 72 65 61 64 6f 6e 6c 79 20 64 61 74 61 62  a readonly datab
45b0: 61 73 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ase */.#define S
45c0: 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 20  QLITE_INTERRUPT 
45d0: 20 20 20 39 20 20 20 2f 2a 20 4f 70 65 72 61 74     9   /* Operat
45e0: 69 6f 6e 20 74 65 72 6d 69 6e 61 74 65 64 20 62  ion terminated b
45f0: 79 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  y sqlite3_interr
4600: 75 70 74 28 29 2a 2f 0a 23 64 65 66 69 6e 65 20  upt()*/.#define 
4610: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 20 20 20  SQLITE_IOERR    
4620: 20 20 20 31 30 20 20 20 2f 2a 20 53 6f 6d 65 20     10   /* Some 
4630: 6b 69 6e 64 20 6f 66 20 64 69 73 6b 20 49 2f 4f  kind of disk I/O
4640: 20 65 72 72 6f 72 20 6f 63 63 75 72 72 65 64 20   error occurred 
4650: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4660: 45 5f 43 4f 52 52 55 50 54 20 20 20 20 20 31 31  E_CORRUPT     11
4670: 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61     /* The databa
4680: 73 65 20 64 69 73 6b 20 69 6d 61 67 65 20 69 73  se disk image is
4690: 20 6d 61 6c 66 6f 72 6d 65 64 20 2a 2f 0a 23 64   malformed */.#d
46a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54  efine SQLITE_NOT
46b0: 46 4f 55 4e 44 20 20 20 20 31 32 20 20 20 2f 2a  FOUND    12   /*
46c0: 20 55 6e 6b 6e 6f 77 6e 20 6f 70 63 6f 64 65 20   Unknown opcode 
46d0: 69 6e 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f  in sqlite3_file_
46e0: 63 6f 6e 74 72 6f 6c 28 29 20 2a 2f 0a 23 64 65  control() */.#de
46f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 4c 4c  fine SQLITE_FULL
4700: 20 20 20 20 20 20 20 20 31 33 20 20 20 2f 2a 20          13   /* 
4710: 49 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c 65 64  Insertion failed
4720: 20 62 65 63 61 75 73 65 20 64 61 74 61 62 61 73   because databas
4730: 65 20 69 73 20 66 75 6c 6c 20 2a 2f 0a 23 64 65  e is full */.#de
4740: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54  fine SQLITE_CANT
4750: 4f 50 45 4e 20 20 20 20 31 34 20 20 20 2f 2a 20  OPEN    14   /* 
4760: 55 6e 61 62 6c 65 20 74 6f 20 6f 70 65 6e 20 74  Unable to open t
4770: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
4780: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4790: 54 45 5f 50 52 4f 54 4f 43 4f 4c 20 20 20 20 31  TE_PROTOCOL    1
47a0: 35 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20  5   /* Database 
47b0: 6c 6f 63 6b 20 70 72 6f 74 6f 63 6f 6c 20 65 72  lock protocol er
47c0: 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ror */.#define S
47d0: 51 4c 49 54 45 5f 45 4d 50 54 59 20 20 20 20 20  QLITE_EMPTY     
47e0: 20 20 31 36 20 20 20 2f 2a 20 44 61 74 61 62 61    16   /* Databa
47f0: 73 65 20 69 73 20 65 6d 70 74 79 20 2a 2f 0a 23  se is empty */.#
4800: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 43  define SQLITE_SC
4810: 48 45 4d 41 20 20 20 20 20 20 31 37 20 20 20 2f  HEMA      17   /
4820: 2a 20 54 68 65 20 64 61 74 61 62 61 73 65 20 73  * The database s
4830: 63 68 65 6d 61 20 63 68 61 6e 67 65 64 20 2a 2f  chema changed */
4840: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4850: 54 4f 4f 42 49 47 20 20 20 20 20 20 31 38 20 20  TOOBIG      18  
4860: 20 2f 2a 20 53 74 72 69 6e 67 20 6f 72 20 42 4c   /* String or BL
4870: 4f 42 20 65 78 63 65 65 64 73 20 73 69 7a 65 20  OB exceeds size 
4880: 6c 69 6d 69 74 20 2a 2f 0a 23 64 65 66 69 6e 65  limit */.#define
4890: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
48a0: 4e 54 20 20 31 39 20 20 20 2f 2a 20 41 62 6f 72  NT  19   /* Abor
48b0: 74 20 64 75 65 20 74 6f 20 63 6f 6e 73 74 72 61  t due to constra
48c0: 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 2a 2f  int violation */
48d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
48e0: 4d 49 53 4d 41 54 43 48 20 20 20 20 32 30 20 20  MISMATCH    20  
48f0: 20 2f 2a 20 44 61 74 61 20 74 79 70 65 20 6d 69   /* Data type mi
4900: 73 6d 61 74 63 68 20 2a 2f 0a 23 64 65 66 69 6e  smatch */.#defin
4910: 65 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 20  e SQLITE_MISUSE 
4920: 20 20 20 20 20 32 31 20 20 20 2f 2a 20 4c 69 62       21   /* Lib
4930: 72 61 72 79 20 75 73 65 64 20 69 6e 63 6f 72 72  rary used incorr
4940: 65 63 74 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65  ectly */.#define
4950: 20 53 51 4c 49 54 45 5f 4e 4f 4c 46 53 20 20 20   SQLITE_NOLFS   
4960: 20 20 20 20 32 32 20 20 20 2f 2a 20 55 73 65 73      22   /* Uses
4970: 20 4f 53 20 66 65 61 74 75 72 65 73 20 6e 6f 74   OS features not
4980: 20 73 75 70 70 6f 72 74 65 64 20 6f 6e 20 68 6f   supported on ho
4990: 73 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  st */.#define SQ
49a0: 4c 49 54 45 5f 41 55 54 48 20 20 20 20 20 20 20  LITE_AUTH       
49b0: 20 32 33 20 20 20 2f 2a 20 41 75 74 68 6f 72 69   23   /* Authori
49c0: 7a 61 74 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f  zation denied */
49d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
49e0: 46 4f 52 4d 41 54 20 20 20 20 20 20 32 34 20 20  FORMAT      24  
49f0: 20 2f 2a 20 41 75 78 69 6c 69 61 72 79 20 64 61   /* Auxiliary da
4a00: 74 61 62 61 73 65 20 66 6f 72 6d 61 74 20 65 72  tabase format er
4a10: 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ror */.#define S
4a20: 51 4c 49 54 45 5f 52 41 4e 47 45 20 20 20 20 20  QLITE_RANGE     
4a30: 20 20 32 35 20 20 20 2f 2a 20 32 6e 64 20 70 61    25   /* 2nd pa
4a40: 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
4a50: 65 33 5f 62 69 6e 64 20 6f 75 74 20 6f 66 20 72  e3_bind out of r
4a60: 61 6e 67 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ange */.#define 
4a70: 53 51 4c 49 54 45 5f 4e 4f 54 41 44 42 20 20 20  SQLITE_NOTADB   
4a80: 20 20 20 32 36 20 20 20 2f 2a 20 46 69 6c 65 20     26   /* File 
4a90: 6f 70 65 6e 65 64 20 74 68 61 74 20 69 73 20 6e  opened that is n
4aa0: 6f 74 20 61 20 64 61 74 61 62 61 73 65 20 66 69  ot a database fi
4ab0: 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  le */.#define SQ
4ac0: 4c 49 54 45 5f 4e 4f 54 49 43 45 20 20 20 20 20  LITE_NOTICE     
4ad0: 20 32 37 20 20 20 2f 2a 20 4e 6f 74 69 66 69 63   27   /* Notific
4ae0: 61 74 69 6f 6e 73 20 66 72 6f 6d 20 73 71 6c 69  ations from sqli
4af0: 74 65 33 5f 6c 6f 67 28 29 20 2a 2f 0a 23 64 65  te3_log() */.#de
4b00: 66 69 6e 65 20 53 51 4c 49 54 45 5f 57 41 52 4e  fine SQLITE_WARN
4b10: 49 4e 47 20 20 20 20 20 32 38 20 20 20 2f 2a 20  ING     28   /* 
4b20: 57 61 72 6e 69 6e 67 73 20 66 72 6f 6d 20 73 71  Warnings from sq
4b30: 6c 69 74 65 33 5f 6c 6f 67 28 29 20 2a 2f 0a 23  lite3_log() */.#
4b40: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 4f  define SQLITE_RO
4b50: 57 20 20 20 20 20 20 20 20 20 31 30 30 20 20 2f  W         100  /
4b60: 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  * sqlite3_step()
4b70: 20 68 61 73 20 61 6e 6f 74 68 65 72 20 72 6f 77   has another row
4b80: 20 72 65 61 64 79 20 2a 2f 0a 23 64 65 66 69 6e   ready */.#defin
4b90: 65 20 53 51 4c 49 54 45 5f 44 4f 4e 45 20 20 20  e SQLITE_DONE   
4ba0: 20 20 20 20 20 31 30 31 20 20 2f 2a 20 73 71 6c       101  /* sql
4bb0: 69 74 65 33 5f 73 74 65 70 28 29 20 68 61 73 20  ite3_step() has 
4bc0: 66 69 6e 69 73 68 65 64 20 65 78 65 63 75 74 69  finished executi
4bd0: 6e 67 20 2a 2f 0a 2f 2a 20 65 6e 64 2d 6f 66 2d  ng */./* end-of-
4be0: 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 0a  error-codes */..
4bf0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
4c00: 45 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20  Extended Result 
4c10: 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44  Codes.** KEYWORD
4c20: 53 3a 20 7b 65 78 74 65 6e 64 65 64 20 72 65 73  S: {extended res
4c30: 75 6c 74 20 63 6f 64 65 20 64 65 66 69 6e 69 74  ult code definit
4c40: 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20 69  ions}.**.** In i
4c50: 74 73 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69  ts default confi
4c60: 67 75 72 61 74 69 6f 6e 2c 20 53 51 4c 69 74 65  guration, SQLite
4c70: 20 41 50 49 20 72 6f 75 74 69 6e 65 73 20 72 65   API routines re
4c80: 74 75 72 6e 20 6f 6e 65 20 6f 66 20 33 30 20 69  turn one of 30 i
4c90: 6e 74 65 67 65 72 0a 2a 2a 20 5b 72 65 73 75 6c  nteger.** [resul
4ca0: 74 20 63 6f 64 65 73 5d 2e 20 20 48 6f 77 65 76  t codes].  Howev
4cb0: 65 72 2c 20 65 78 70 65 72 69 65 6e 63 65 20 68  er, experience h
4cc0: 61 73 20 73 68 6f 77 6e 20 74 68 61 74 20 6d 61  as shown that ma
4cd0: 6e 79 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20 72  ny of.** these r
4ce0: 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 20  esult codes are 
4cf0: 74 6f 6f 20 63 6f 61 72 73 65 2d 67 72 61 69 6e  too coarse-grain
4d00: 65 64 2e 20 20 54 68 65 79 20 64 6f 20 6e 6f 74  ed.  They do not
4d10: 20 70 72 6f 76 69 64 65 20 61 73 0a 2a 2a 20 6d   provide as.** m
4d20: 75 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  uch information 
4d30: 61 62 6f 75 74 20 70 72 6f 62 6c 65 6d 73 20 61  about problems a
4d40: 73 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69  s programmers mi
4d50: 67 68 74 20 6c 69 6b 65 2e 20 20 49 6e 20 61 6e  ght like.  In an
4d60: 20 65 66 66 6f 72 74 20 74 6f 0a 2a 2a 20 61 64   effort to.** ad
4d70: 64 72 65 73 73 20 74 68 69 73 2c 20 6e 65 77 65  dress this, newe
4d80: 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  r versions of SQ
4d90: 4c 69 74 65 20 28 76 65 72 73 69 6f 6e 20 33 2e  Lite (version 3.
4da0: 33 2e 38 20 61 6e 64 20 6c 61 74 65 72 29 20 69  3.8 and later) i
4db0: 6e 63 6c 75 64 65 0a 2a 2a 20 73 75 70 70 6f 72  nclude.** suppor
4dc0: 74 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  t for additional
4dd0: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 74 68   result codes th
4de0: 61 74 20 70 72 6f 76 69 64 65 20 6d 6f 72 65 20  at provide more 
4df0: 64 65 74 61 69 6c 65 64 20 69 6e 66 6f 72 6d 61  detailed informa
4e00: 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20 65 72  tion.** about er
4e10: 72 6f 72 73 2e 20 54 68 65 73 65 20 5b 65 78 74  rors. These [ext
4e20: 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
4e30: 65 73 5d 20 61 72 65 20 65 6e 61 62 6c 65 64 20  es] are enabled 
4e40: 6f 72 20 64 69 73 61 62 6c 65 64 0a 2a 2a 20 6f  or disabled.** o
4e50: 6e 20 61 20 70 65 72 20 64 61 74 61 62 61 73 65  n a per database
4e60: 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73 69   connection basi
4e70: 73 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b  s using the.** [
4e80: 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64  sqlite3_extended
4e90: 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29 5d  _result_codes()]
4ea0: 20 41 50 49 2e 20 20 4f 72 2c 20 74 68 65 20 65   API.  Or, the e
4eb0: 78 74 65 6e 64 65 64 20 63 6f 64 65 20 66 6f 72  xtended code for
4ec0: 0a 2a 2a 20 74 68 65 20 6d 6f 73 74 20 72 65 63  .** the most rec
4ed0: 65 6e 74 20 65 72 72 6f 72 20 63 61 6e 20 62 65  ent error can be
4ee0: 20 6f 62 74 61 69 6e 65 64 20 75 73 69 6e 67 0a   obtained using.
4ef0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 74 65  ** [sqlite3_exte
4f00: 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 29 5d 2e  nded_errcode()].
4f10: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
4f20: 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 20 20  TE_IOERR_READ   
4f30: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4f40: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 3c 3c 38  TE_IOERR | (1<<8
4f50: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
4f60: 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45  E_IOERR_SHORT_RE
4f70: 41 44 20 20 20 20 20 20 20 20 28 53 51 4c 49 54  AD        (SQLIT
4f80: 45 5f 49 4f 45 52 52 20 7c 20 28 32 3c 3c 38 29  E_IOERR | (2<<8)
4f90: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
4fa0: 5f 49 4f 45 52 52 5f 57 52 49 54 45 20 20 20 20  _IOERR_WRITE    
4fb0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
4fc0: 5f 49 4f 45 52 52 20 7c 20 28 33 3c 3c 38 29 29  _IOERR | (3<<8))
4fd0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4fe0: 49 4f 45 52 52 5f 46 53 59 4e 43 20 20 20 20 20  IOERR_FSYNC     
4ff0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5000: 49 4f 45 52 52 20 7c 20 28 34 3c 3c 38 29 29 0a  IOERR | (4<<8)).
5010: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
5020: 4f 45 52 52 5f 44 49 52 5f 46 53 59 4e 43 20 20  OERR_DIR_FSYNC  
5030: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
5040: 4f 45 52 52 20 7c 20 28 35 3c 3c 38 29 29 0a 23  OERR | (5<<8)).#
5050: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5060: 45 52 52 5f 54 52 55 4e 43 41 54 45 20 20 20 20  ERR_TRUNCATE    
5070: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5080: 45 52 52 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64  ERR | (6<<8)).#d
5090: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
50a0: 52 52 5f 46 53 54 41 54 20 20 20 20 20 20 20 20  RR_FSTAT        
50b0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
50c0: 52 52 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64 65  RR | (7<<8)).#de
50d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
50e0: 52 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20 20  R_UNLOCK        
50f0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
5100: 52 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65 66  R | (8<<8)).#def
5110: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5120: 5f 52 44 4c 4f 43 4b 20 20 20 20 20 20 20 20 20  _RDLOCK         
5130: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5140: 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65 66 69   | (9<<8)).#defi
5150: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5160: 44 45 4c 45 54 45 20 20 20 20 20 20 20 20 20 20  DELETE          
5170: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5180: 7c 20 28 31 30 3c 3c 38 29 29 0a 23 64 65 66 69  | (10<<8)).#defi
5190: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
51a0: 42 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 20 20  BLOCKED         
51b0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
51c0: 7c 20 28 31 31 3c 3c 38 29 29 0a 23 64 65 66 69  | (11<<8)).#defi
51d0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
51e0: 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 20 20 20  NOMEM           
51f0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5200: 7c 20 28 31 32 3c 3c 38 29 29 0a 23 64 65 66 69  | (12<<8)).#defi
5210: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5220: 41 43 43 45 53 53 20 20 20 20 20 20 20 20 20 20  ACCESS          
5230: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5240: 7c 20 28 31 33 3c 3c 38 29 29 0a 23 64 65 66 69  | (13<<8)).#defi
5250: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5260: 43 48 45 43 4b 52 45 53 45 52 56 45 44 4c 4f 43  CHECKRESERVEDLOC
5270: 4b 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20  K (SQLITE_IOERR 
5280: 7c 20 28 31 34 3c 3c 38 29 29 0a 23 64 65 66 69  | (14<<8)).#defi
5290: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
52a0: 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20 20  LOCK            
52b0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
52c0: 7c 20 28 31 35 3c 3c 38 29 29 0a 23 64 65 66 69  | (15<<8)).#defi
52d0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
52e0: 43 4c 4f 53 45 20 20 20 20 20 20 20 20 20 20 20  CLOSE           
52f0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5300: 7c 20 28 31 36 3c 3c 38 29 29 0a 23 64 65 66 69  | (16<<8)).#defi
5310: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5320: 44 49 52 5f 43 4c 4f 53 45 20 20 20 20 20 20 20  DIR_CLOSE       
5330: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5340: 7c 20 28 31 37 3c 3c 38 29 29 0a 23 64 65 66 69  | (17<<8)).#defi
5350: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5360: 53 48 4d 4f 50 45 4e 20 20 20 20 20 20 20 20 20  SHMOPEN         
5370: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5380: 7c 20 28 31 38 3c 3c 38 29 29 0a 23 64 65 66 69  | (18<<8)).#defi
5390: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
53a0: 53 48 4d 53 49 5a 45 20 20 20 20 20 20 20 20 20  SHMSIZE         
53b0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
53c0: 7c 20 28 31 39 3c 3c 38 29 29 0a 23 64 65 66 69  | (19<<8)).#defi
53d0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
53e0: 53 48 4d 4c 4f 43 4b 20 20 20 20 20 20 20 20 20  SHMLOCK         
53f0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5400: 7c 20 28 32 30 3c 3c 38 29 29 0a 23 64 65 66 69  | (20<<8)).#defi
5410: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5420: 53 48 4d 4d 41 50 20 20 20 20 20 20 20 20 20 20  SHMMAP          
5430: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5440: 7c 20 28 32 31 3c 3c 38 29 29 0a 23 64 65 66 69  | (21<<8)).#defi
5450: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5460: 53 45 45 4b 20 20 20 20 20 20 20 20 20 20 20 20  SEEK            
5470: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5480: 7c 20 28 32 32 3c 3c 38 29 29 0a 23 64 65 66 69  | (22<<8)).#defi
5490: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
54a0: 44 45 4c 45 54 45 5f 4e 4f 45 4e 54 20 20 20 20  DELETE_NOENT    
54b0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
54c0: 7c 20 28 32 33 3c 3c 38 29 29 0a 23 64 65 66 69  | (23<<8)).#defi
54d0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
54e0: 4d 4d 41 50 20 20 20 20 20 20 20 20 20 20 20 20  MMAP            
54f0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5500: 7c 20 28 32 34 3c 3c 38 29 29 0a 23 64 65 66 69  | (24<<8)).#defi
5510: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5520: 47 45 54 54 45 4d 50 50 41 54 48 20 20 20 20 20  GETTEMPPATH     
5530: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5540: 7c 20 28 32 35 3c 3c 38 29 29 0a 23 64 65 66 69  | (25<<8)).#defi
5550: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5560: 43 4f 4e 56 50 41 54 48 20 20 20 20 20 20 20 20  CONVPATH        
5570: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5580: 7c 20 28 32 36 3c 3c 38 29 29 0a 23 64 65 66 69  | (26<<8)).#defi
5590: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
55a0: 56 4e 4f 44 45 20 20 20 20 20 20 20 20 20 20 20  VNODE           
55b0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
55c0: 7c 20 28 32 37 3c 3c 38 29 29 0a 23 64 65 66 69  | (27<<8)).#defi
55d0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
55e0: 41 55 54 48 20 20 20 20 20 20 20 20 20 20 20 20  AUTH            
55f0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5600: 7c 20 28 32 38 3c 3c 38 29 29 0a 23 64 65 66 69  | (28<<8)).#defi
5610: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44  ne SQLITE_LOCKED
5620: 5f 53 48 41 52 45 44 43 41 43 48 45 20 20 20 20  _SHAREDCACHE    
5630: 20 20 28 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44    (SQLITE_LOCKED
5640: 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64 65 66   |  (1<<8)).#def
5650: 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59 5f  ine SQLITE_BUSY_
5660: 52 45 43 4f 56 45 52 59 20 20 20 20 20 20 20 20  RECOVERY        
5670: 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53 59 20     (SQLITE_BUSY 
5680: 20 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64 65    |  (1<<8)).#de
5690: 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59  fine SQLITE_BUSY
56a0: 5f 53 4e 41 50 53 48 4f 54 20 20 20 20 20 20 20  _SNAPSHOT       
56b0: 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53 59      (SQLITE_BUSY
56c0: 20 20 20 7c 20 20 28 32 3c 3c 38 29 29 0a 23 64     |  (2<<8)).#d
56d0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e  efine SQLITE_CAN
56e0: 54 4f 50 45 4e 5f 4e 4f 54 45 4d 50 44 49 52 20  TOPEN_NOTEMPDIR 
56f0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41 4e       (SQLITE_CAN
5700: 54 4f 50 45 4e 20 7c 20 28 31 3c 3c 38 29 29 0a  TOPEN | (1<<8)).
5710: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
5720: 41 4e 54 4f 50 45 4e 5f 49 53 44 49 52 20 20 20  ANTOPEN_ISDIR   
5730: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43         (SQLITE_C
5740: 41 4e 54 4f 50 45 4e 20 7c 20 28 32 3c 3c 38 29  ANTOPEN | (2<<8)
5750: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5760: 5f 43 41 4e 54 4f 50 45 4e 5f 46 55 4c 4c 50 41  _CANTOPEN_FULLPA
5770: 54 48 20 20 20 20 20 20 20 28 53 51 4c 49 54 45  TH       (SQLITE
5780: 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 33 3c 3c  _CANTOPEN | (3<<
5790: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
57a0: 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 43 4f 4e 56  TE_CANTOPEN_CONV
57b0: 50 41 54 48 20 20 20 20 20 20 20 28 53 51 4c 49  PATH       (SQLI
57c0: 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 34  TE_CANTOPEN | (4
57d0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
57e0: 4c 49 54 45 5f 43 4f 52 52 55 50 54 5f 56 54 41  LITE_CORRUPT_VTA
57f0: 42 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51  B            (SQ
5800: 4c 49 54 45 5f 43 4f 52 52 55 50 54 20 7c 20 28  LITE_CORRUPT | (
5810: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  1<<8)).#define S
5820: 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 52  QLITE_READONLY_R
5830: 45 43 4f 56 45 52 59 20 20 20 20 20 20 20 28 53  ECOVERY       (S
5840: 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c  QLITE_READONLY |
5850: 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (1<<8)).#define
5860: 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59   SQLITE_READONLY
5870: 5f 43 41 4e 54 4c 4f 43 4b 20 20 20 20 20 20 20  _CANTLOCK       
5880: 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59  (SQLITE_READONLY
5890: 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69   | (2<<8)).#defi
58a0: 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e  ne SQLITE_READON
58b0: 4c 59 5f 52 4f 4c 4c 42 41 43 4b 20 20 20 20 20  LY_ROLLBACK     
58c0: 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e    (SQLITE_READON
58d0: 4c 59 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65  LY | (3<<8)).#de
58e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44  fine SQLITE_READ
58f0: 4f 4e 4c 59 5f 44 42 4d 4f 56 45 44 20 20 20 20  ONLY_DBMOVED    
5900: 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44      (SQLITE_READ
5910: 4f 4e 4c 59 20 7c 20 28 34 3c 3c 38 29 29 0a 23  ONLY | (4<<8)).#
5920: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 42  define SQLITE_AB
5930: 4f 52 54 5f 52 4f 4c 4c 42 41 43 4b 20 20 20 20  ORT_ROLLBACK    
5940: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 41 42        (SQLITE_AB
5950: 4f 52 54 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64  ORT | (2<<8)).#d
5960: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
5970: 53 54 52 41 49 4e 54 5f 43 48 45 43 4b 20 20 20  STRAINT_CHECK   
5980: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e       (SQLITE_CON
5990: 53 54 52 41 49 4e 54 20 7c 20 28 31 3c 3c 38 29  STRAINT | (1<<8)
59a0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
59b0: 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 43 4f 4d 4d  _CONSTRAINT_COMM
59c0: 49 54 48 4f 4f 4b 20 20 20 28 53 51 4c 49 54 45  ITHOOK   (SQLITE
59d0: 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 32  _CONSTRAINT | (2
59e0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
59f0: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f  LITE_CONSTRAINT_
5a00: 46 4f 52 45 49 47 4e 4b 45 59 20 20 20 28 53 51  FOREIGNKEY   (SQ
5a10: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20  LITE_CONSTRAINT 
5a20: 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (3<<8)).#defin
5a30: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41  e SQLITE_CONSTRA
5a40: 49 4e 54 5f 46 55 4e 43 54 49 4f 4e 20 20 20 20  INT_FUNCTION    
5a50: 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41   (SQLITE_CONSTRA
5a60: 49 4e 54 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64  INT | (4<<8)).#d
5a70: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
5a80: 53 54 52 41 49 4e 54 5f 4e 4f 54 4e 55 4c 4c 20  STRAINT_NOTNULL 
5a90: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e       (SQLITE_CON
5aa0: 53 54 52 41 49 4e 54 20 7c 20 28 35 3c 3c 38 29  STRAINT | (5<<8)
5ab0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5ac0: 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 50 52 49 4d  _CONSTRAINT_PRIM
5ad0: 41 52 59 4b 45 59 20 20 20 28 53 51 4c 49 54 45  ARYKEY   (SQLITE
5ae0: 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 36  _CONSTRAINT | (6
5af0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5b00: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f  LITE_CONSTRAINT_
5b10: 54 52 49 47 47 45 52 20 20 20 20 20 20 28 53 51  TRIGGER      (SQ
5b20: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20  LITE_CONSTRAINT 
5b30: 7c 20 28 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (7<<8)).#defin
5b40: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41  e SQLITE_CONSTRA
5b50: 49 4e 54 5f 55 4e 49 51 55 45 20 20 20 20 20 20  INT_UNIQUE      
5b60: 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41   (SQLITE_CONSTRA
5b70: 49 4e 54 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64  INT | (8<<8)).#d
5b80: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
5b90: 53 54 52 41 49 4e 54 5f 56 54 41 42 20 20 20 20  STRAINT_VTAB    
5ba0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e       (SQLITE_CON
5bb0: 53 54 52 41 49 4e 54 20 7c 20 28 39 3c 3c 38 29  STRAINT | (9<<8)
5bc0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5bd0: 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 52 4f 57 49  _CONSTRAINT_ROWI
5be0: 44 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45  D        (SQLITE
5bf0: 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 28 31 30  _CONSTRAINT |(10
5c00: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5c10: 4c 49 54 45 5f 4e 4f 54 49 43 45 5f 52 45 43 4f  LITE_NOTICE_RECO
5c20: 56 45 52 5f 57 41 4c 20 20 20 20 20 20 28 53 51  VER_WAL      (SQ
5c30: 4c 49 54 45 5f 4e 4f 54 49 43 45 20 7c 20 28 31  LITE_NOTICE | (1
5c40: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5c50: 4c 49 54 45 5f 4e 4f 54 49 43 45 5f 52 45 43 4f  LITE_NOTICE_RECO
5c60: 56 45 52 5f 52 4f 4c 4c 42 41 43 4b 20 28 53 51  VER_ROLLBACK (SQ
5c70: 4c 49 54 45 5f 4e 4f 54 49 43 45 20 7c 20 28 32  LITE_NOTICE | (2
5c80: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5c90: 4c 49 54 45 5f 57 41 52 4e 49 4e 47 5f 41 55 54  LITE_WARNING_AUT
5ca0: 4f 49 4e 44 45 58 20 20 20 20 20 20 20 28 53 51  OINDEX       (SQ
5cb0: 4c 49 54 45 5f 57 41 52 4e 49 4e 47 20 7c 20 28  LITE_WARNING | (
5cc0: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  1<<8)).#define S
5cd0: 51 4c 49 54 45 5f 41 55 54 48 5f 55 53 45 52 20  QLITE_AUTH_USER 
5ce0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53                (S
5cf0: 51 4c 49 54 45 5f 41 55 54 48 20 7c 20 28 31 3c  QLITE_AUTH | (1<
5d00: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5d10: 49 54 45 5f 4f 4b 5f 4c 4f 41 44 5f 50 45 52 4d  ITE_OK_LOAD_PERM
5d20: 41 4e 45 4e 54 4c 59 20 20 20 20 20 28 53 51 4c  ANENTLY     (SQL
5d30: 49 54 45 5f 4f 4b 20 7c 20 28 31 3c 3c 38 29 29  ITE_OK | (1<<8))
5d40: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
5d50: 3a 20 46 6c 61 67 73 20 46 6f 72 20 46 69 6c 65  : Flags For File
5d60: 20 4f 70 65 6e 20 4f 70 65 72 61 74 69 6f 6e 73   Open Operations
5d70: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 62 69 74  .**.** These bit
5d80: 20 76 61 6c 75 65 73 20 61 72 65 20 69 6e 74 65   values are inte
5d90: 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e 20  nded for use in 
5da0: 74 68 65 0a 2a 2a 20 33 72 64 20 70 61 72 61 6d  the.** 3rd param
5db0: 65 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c  eter to the [sql
5dc0: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20  ite3_open_v2()] 
5dd0: 69 6e 74 65 72 66 61 63 65 20 61 6e 64 0a 2a 2a  interface and.**
5de0: 20 69 6e 20 74 68 65 20 34 74 68 20 70 61 72 61   in the 4th para
5df0: 6d 65 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71  meter to the [sq
5e00: 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d  lite3_vfs.xOpen]
5e10: 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 23 64 65 66   method..*/.#def
5e20: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
5e30: 52 45 41 44 4f 4e 4c 59 20 20 20 20 20 20 20 20  READONLY        
5e40: 20 30 78 30 30 30 30 30 30 30 31 20 20 2f 2a 20   0x00000001  /* 
5e50: 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  Ok for sqlite3_o
5e60: 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66  pen_v2() */.#def
5e70: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
5e80: 52 45 41 44 57 52 49 54 45 20 20 20 20 20 20 20  READWRITE       
5e90: 20 30 78 30 30 30 30 30 30 30 32 20 20 2f 2a 20   0x00000002  /* 
5ea0: 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  Ok for sqlite3_o
5eb0: 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66  pen_v2() */.#def
5ec0: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
5ed0: 43 52 45 41 54 45 20 20 20 20 20 20 20 20 20 20  CREATE          
5ee0: 20 30 78 30 30 30 30 30 30 30 34 20 20 2f 2a 20   0x00000004  /* 
5ef0: 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  Ok for sqlite3_o
5f00: 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66  pen_v2() */.#def
5f10: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
5f20: 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 20 20 20  DELETEONCLOSE   
5f30: 20 30 78 30 30 30 30 30 30 30 38 20 20 2f 2a 20   0x00000008  /* 
5f40: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  VFS only */.#def
5f50: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
5f60: 45 58 43 4c 55 53 49 56 45 20 20 20 20 20 20 20  EXCLUSIVE       
5f70: 20 30 78 30 30 30 30 30 30 31 30 20 20 2f 2a 20   0x00000010  /* 
5f80: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  VFS only */.#def
5f90: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
5fa0: 41 55 54 4f 50 52 4f 58 59 20 20 20 20 20 20 20  AUTOPROXY       
5fb0: 20 30 78 30 30 30 30 30 30 32 30 20 20 2f 2a 20   0x00000020  /* 
5fc0: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  VFS only */.#def
5fd0: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
5fe0: 55 52 49 20 20 20 20 20 20 20 20 20 20 20 20 20  URI             
5ff0: 20 30 78 30 30 30 30 30 30 34 30 20 20 2f 2a 20   0x00000040  /* 
6000: 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  Ok for sqlite3_o
6010: 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66  pen_v2() */.#def
6020: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
6030: 4d 45 4d 4f 52 59 20 20 20 20 20 20 20 20 20 20  MEMORY          
6040: 20 30 78 30 30 30 30 30 30 38 30 20 20 2f 2a 20   0x00000080  /* 
6050: 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  Ok for sqlite3_o
6060: 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66  pen_v2() */.#def
6070: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
6080: 4d 41 49 4e 5f 44 42 20 20 20 20 20 20 20 20 20  MAIN_DB         
6090: 20 30 78 30 30 30 30 30 31 30 30 20 20 2f 2a 20   0x00000100  /* 
60a0: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  VFS only */.#def
60b0: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
60c0: 54 45 4d 50 5f 44 42 20 20 20 20 20 20 20 20 20  TEMP_DB         
60d0: 20 30 78 30 30 30 30 30 32 30 30 20 20 2f 2a 20   0x00000200  /* 
60e0: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  VFS only */.#def
60f0: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
6100: 54 52 41 4e 53 49 45 4e 54 5f 44 42 20 20 20 20  TRANSIENT_DB    
6110: 20 30 78 30 30 30 30 30 34 30 30 20 20 2f 2a 20   0x00000400  /* 
6120: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  VFS only */.#def
6130: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
6140: 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 20 20 20 20  MAIN_JOURNAL    
6150: 20 30 78 30 30 30 30 30 38 30 30 20 20 2f 2a 20   0x00000800  /* 
6160: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  VFS only */.#def
6170: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
6180: 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 20 20 20 20  TEMP_JOURNAL    
6190: 20 30 78 30 30 30 30 31 30 30 30 20 20 2f 2a 20   0x00001000  /* 
61a0: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  VFS only */.#def
61b0: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
61c0: 53 55 42 4a 4f 55 52 4e 41 4c 20 20 20 20 20 20  SUBJOURNAL      
61d0: 20 30 78 30 30 30 30 32 30 30 30 20 20 2f 2a 20   0x00002000  /* 
61e0: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  VFS only */.#def
61f0: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
6200: 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 20 20  MASTER_JOURNAL  
6210: 20 30 78 30 30 30 30 34 30 30 30 20 20 2f 2a 20   0x00004000  /* 
6220: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  VFS only */.#def
6230: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
6240: 4e 4f 4d 55 54 45 58 20 20 20 20 20 20 20 20 20  NOMUTEX         
6250: 20 30 78 30 30 30 30 38 30 30 30 20 20 2f 2a 20   0x00008000  /* 
6260: 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  Ok for sqlite3_o
6270: 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66  pen_v2() */.#def
6280: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
6290: 46 55 4c 4c 4d 55 54 45 58 20 20 20 20 20 20 20  FULLMUTEX       
62a0: 20 30 78 30 30 30 31 30 30 30 30 20 20 2f 2a 20   0x00010000  /* 
62b0: 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  Ok for sqlite3_o
62c0: 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66  pen_v2() */.#def
62d0: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
62e0: 53 48 41 52 45 44 43 41 43 48 45 20 20 20 20 20  SHAREDCACHE     
62f0: 20 30 78 30 30 30 32 30 30 30 30 20 20 2f 2a 20   0x00020000  /* 
6300: 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  Ok for sqlite3_o
6310: 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66  pen_v2() */.#def
6320: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
6330: 50 52 49 56 41 54 45 43 41 43 48 45 20 20 20 20  PRIVATECACHE    
6340: 20 30 78 30 30 30 34 30 30 30 30 20 20 2f 2a 20   0x00040000  /* 
6350: 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  Ok for sqlite3_o
6360: 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66  pen_v2() */.#def
6370: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
6380: 57 41 4c 20 20 20 20 20 20 20 20 20 20 20 20 20  WAL             
6390: 20 30 78 30 30 30 38 30 30 30 30 20 20 2f 2a 20   0x00080000  /* 
63a0: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 20  VFS only */../* 
63b0: 52 65 73 65 72 76 65 64 3a 20 20 20 20 20 20 20  Reserved:       
63c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
63d0: 20 20 30 78 30 30 46 30 30 30 30 30 20 2a 2f 0a    0x00F00000 */.
63e0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
63f0: 20 44 65 76 69 63 65 20 43 68 61 72 61 63 74 65   Device Characte
6400: 72 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 54 68  ristics.**.** Th
6410: 65 20 78 44 65 76 69 63 65 43 68 61 72 61 63 74  e xDeviceCharact
6420: 65 72 69 73 74 69 63 73 20 6d 65 74 68 6f 64 20  eristics method 
6430: 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
6440: 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 6f  io_methods].** o
6450: 62 6a 65 63 74 20 72 65 74 75 72 6e 73 20 61 6e  bject returns an
6460: 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 20 69   integer which i
6470: 73 20 61 20 76 65 63 74 6f 72 20 6f 66 20 74 68  s a vector of th
6480: 65 73 65 0a 2a 2a 20 62 69 74 20 76 61 6c 75 65  ese.** bit value
6490: 73 20 65 78 70 72 65 73 73 69 6e 67 20 49 2f 4f  s expressing I/O
64a0: 20 63 68 61 72 61 63 74 65 72 69 73 74 69 63 73   characteristics
64b0: 20 6f 66 20 74 68 65 20 6d 61 73 73 20 73 74 6f   of the mass sto
64c0: 72 61 67 65 0a 2a 2a 20 64 65 76 69 63 65 20 74  rage.** device t
64d0: 68 61 74 20 68 6f 6c 64 73 20 74 68 65 20 66 69  hat holds the fi
64e0: 6c 65 20 74 68 61 74 20 74 68 65 20 5b 73 71 6c  le that the [sql
64f0: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
6500: 0a 2a 2a 20 72 65 66 65 72 73 20 74 6f 2e 0a 2a  .** refers to..*
6510: 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f  *.** The SQLITE_
6520: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70 72 6f  IOCAP_ATOMIC pro
6530: 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74  perty means that
6540: 20 61 6c 6c 20 77 72 69 74 65 73 20 6f 66 0a 2a   all writes of.*
6550: 2a 20 61 6e 79 20 73 69 7a 65 20 61 72 65 20 61  * any size are a
6560: 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49  tomic.  The SQLI
6570: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 6e  TE_IOCAP_ATOMICn
6580: 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d 65 61  nn values.** mea
6590: 6e 20 74 68 61 74 20 77 72 69 74 65 73 20 6f 66  n that writes of
65a0: 20 62 6c 6f 63 6b 73 20 74 68 61 74 20 61 72 65   blocks that are
65b0: 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20 73 69   nnn bytes in si
65c0: 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20 61 6c  ze and.** are al
65d0: 69 67 6e 65 64 20 74 6f 20 61 6e 20 61 64 64 72  igned to an addr
65e0: 65 73 73 20 77 68 69 63 68 20 69 73 20 61 6e 20  ess which is an 
65f0: 69 6e 74 65 67 65 72 20 6d 75 6c 74 69 70 6c 65  integer multiple
6600: 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20 61   of.** nnn are a
6610: 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49  tomic.  The SQLI
6620: 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50  TE_IOCAP_SAFE_AP
6630: 50 45 4e 44 20 76 61 6c 75 65 20 6d 65 61 6e 73  PEND value means
6640: 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e 20 64 61  .** that when da
6650: 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 20 74  ta is appended t
6660: 6f 20 61 20 66 69 6c 65 2c 20 74 68 65 20 64 61  o a file, the da
6670: 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 0a 2a  ta is appended.*
6680: 2a 20 66 69 72 73 74 20 74 68 65 6e 20 74 68 65  * first then the
6690: 20 73 69 7a 65 20 6f 66 20 74 68 65 20 66 69 6c   size of the fil
66a0: 65 20 69 73 20 65 78 74 65 6e 64 65 64 2c 20 6e  e is extended, n
66b0: 65 76 65 72 20 74 68 65 20 6f 74 68 65 72 0a 2a  ever the other.*
66c0: 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e 20 20 54  * way around.  T
66d0: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
66e0: 53 45 51 55 45 4e 54 49 41 4c 20 70 72 6f 70 65  SEQUENTIAL prope
66f0: 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a  rty means that.*
6700: 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73  * information is
6710: 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69 73 6b   written to disk
6720: 20 69 6e 20 74 68 65 20 73 61 6d 65 20 6f 72 64   in the same ord
6730: 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a 20 74  er as calls.** t
6740: 6f 20 78 57 72 69 74 65 28 29 2e 20 20 54 68 65  o xWrite().  The
6750: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f   SQLITE_IOCAP_PO
6760: 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54  WERSAFE_OVERWRIT
6770: 45 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73  E property means
6780: 20 74 68 61 74 0a 2a 2a 20 61 66 74 65 72 20 72   that.** after r
6790: 65 62 6f 6f 74 20 66 6f 6c 6c 6f 77 69 6e 67 20  eboot following 
67a0: 61 20 63 72 61 73 68 20 6f 72 20 70 6f 77 65 72  a crash or power
67b0: 20 6c 6f 73 73 2c 20 74 68 65 20 6f 6e 6c 79 20   loss, the only 
67c0: 62 79 74 65 73 20 69 6e 20 61 0a 2a 2a 20 66 69  bytes in a.** fi
67d0: 6c 65 20 74 68 61 74 20 77 65 72 65 20 77 72 69  le that were wri
67e0: 74 74 65 6e 20 61 74 20 74 68 65 20 61 70 70 6c  tten at the appl
67f0: 69 63 61 74 69 6f 6e 20 6c 65 76 65 6c 20 6d 69  ication level mi
6800: 67 68 74 20 68 61 76 65 20 63 68 61 6e 67 65 64  ght have changed
6810: 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20 61 64 6a  .** and that adj
6820: 61 63 65 6e 74 20 62 79 74 65 73 2c 20 65 76 65  acent bytes, eve
6830: 6e 20 62 79 74 65 73 20 77 69 74 68 69 6e 20 74  n bytes within t
6840: 68 65 20 73 61 6d 65 20 73 65 63 74 6f 72 20 61  he same sector a
6850: 72 65 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65 64  re.** guaranteed
6860: 20 74 6f 20 62 65 20 75 6e 63 68 61 6e 67 65 64   to be unchanged
6870: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
6880: 43 41 50 5f 55 4e 44 45 4c 45 54 41 42 4c 45 5f  CAP_UNDELETABLE_
6890: 57 48 45 4e 5f 4f 50 45 4e 0a 2a 2a 20 66 6c 61  WHEN_OPEN.** fla
68a0: 67 20 69 6e 64 69 63 61 74 65 20 74 68 61 74 20  g indicate that 
68b0: 61 20 66 69 6c 65 20 63 61 6e 6e 6f 74 20 62 65  a file cannot be
68c0: 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20 6f 70   deleted when op
68d0: 65 6e 2e 20 20 54 68 65 0a 2a 2a 20 53 51 4c 49  en.  The.** SQLI
68e0: 54 45 5f 49 4f 43 41 50 5f 49 4d 4d 55 54 41 42  TE_IOCAP_IMMUTAB
68f0: 4c 45 20 66 6c 61 67 20 69 6e 64 69 63 61 74 65  LE flag indicate
6900: 73 20 74 68 61 74 20 74 68 65 20 66 69 6c 65 20  s that the file 
6910: 69 73 20 6f 6e 0a 2a 2a 20 72 65 61 64 2d 6f 6e  is on.** read-on
6920: 6c 79 20 6d 65 64 69 61 20 61 6e 64 20 63 61 6e  ly media and can
6930: 6e 6f 74 20 62 65 20 63 68 61 6e 67 65 64 20 65  not be changed e
6940: 76 65 6e 20 62 79 20 70 72 6f 63 65 73 73 65 73  ven by processes
6950: 20 77 69 74 68 0a 2a 2a 20 65 6c 65 76 61 74 65   with.** elevate
6960: 64 20 70 72 69 76 69 6c 65 67 65 73 2e 0a 2a 2f  d privileges..*/
6970: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6980: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 20 20 20  IOCAP_ATOMIC    
6990: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
69a0: 30 30 30 30 30 30 31 0a 23 64 65 66 69 6e 65 20  0000001.#define 
69b0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
69c0: 4d 49 43 35 31 32 20 20 20 20 20 20 20 20 20 20  MIC512          
69d0: 20 20 20 20 30 78 30 30 30 30 30 30 30 32 0a 23      0x00000002.#
69e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
69f0: 43 41 50 5f 41 54 4f 4d 49 43 31 4b 20 20 20 20  CAP_ATOMIC1K    
6a00: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
6a10: 30 30 30 30 34 0a 23 64 65 66 69 6e 65 20 53 51  00004.#define SQ
6a20: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
6a30: 43 32 4b 20 20 20 20 20 20 20 20 20 20 20 20 20  C2K             
6a40: 20 20 30 78 30 30 30 30 30 30 30 38 0a 23 64 65    0x00000008.#de
6a50: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
6a60: 50 5f 41 54 4f 4d 49 43 34 4b 20 20 20 20 20 20  P_ATOMIC4K      
6a70: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
6a80: 30 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  010.#define SQLI
6a90: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38  TE_IOCAP_ATOMIC8
6aa0: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  K               
6ab0: 30 78 30 30 30 30 30 30 32 30 0a 23 64 65 66 69  0x00000020.#defi
6ac0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
6ad0: 41 54 4f 4d 49 43 31 36 4b 20 20 20 20 20 20 20  ATOMIC16K       
6ae0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 34         0x0000004
6af0: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
6b00: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b  _IOCAP_ATOMIC32K
6b10: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
6b20: 30 30 30 30 30 30 38 30 0a 23 64 65 66 69 6e 65  00000080.#define
6b30: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
6b40: 4f 4d 49 43 36 34 4b 20 20 20 20 20 20 20 20 20  OMIC64K         
6b50: 20 20 20 20 20 30 78 30 30 30 30 30 31 30 30 0a       0x00000100.
6b60: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
6b70: 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44  OCAP_SAFE_APPEND
6b80: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
6b90: 30 30 30 32 30 30 0a 23 64 65 66 69 6e 65 20 53  000200.#define S
6ba0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55  QLITE_IOCAP_SEQU
6bb0: 45 4e 54 49 41 4c 20 20 20 20 20 20 20 20 20 20  ENTIAL          
6bc0: 20 20 20 30 78 30 30 30 30 30 34 30 30 0a 23 64     0x00000400.#d
6bd0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
6be0: 41 50 5f 55 4e 44 45 4c 45 54 41 42 4c 45 5f 57  AP_UNDELETABLE_W
6bf0: 48 45 4e 5f 4f 50 45 4e 20 20 30 78 30 30 30 30  HEN_OPEN  0x0000
6c00: 30 38 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0800.#define SQL
6c10: 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53  ITE_IOCAP_POWERS
6c20: 41 46 45 5f 4f 56 45 52 57 52 49 54 45 20 20 20  AFE_OVERWRITE   
6c30: 20 30 78 30 30 30 30 31 30 30 30 0a 23 64 65 66   0x00001000.#def
6c40: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
6c50: 5f 49 4d 4d 55 54 41 42 4c 45 20 20 20 20 20 20  _IMMUTABLE      
6c60: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 32 30          0x000020
6c70: 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  00../*.** CAPI3R
6c80: 45 46 3a 20 46 69 6c 65 20 4c 6f 63 6b 69 6e 67  EF: File Locking
6c90: 20 4c 65 76 65 6c 73 0a 2a 2a 0a 2a 2a 20 53 51   Levels.**.** SQ
6ca0: 4c 69 74 65 20 75 73 65 73 20 6f 6e 65 20 6f 66  Lite uses one of
6cb0: 20 74 68 65 73 65 20 69 6e 74 65 67 65 72 20 76   these integer v
6cc0: 61 6c 75 65 73 20 61 73 20 74 68 65 20 73 65 63  alues as the sec
6cd0: 6f 6e 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  ond.** argument 
6ce0: 74 6f 20 63 61 6c 6c 73 20 69 74 20 6d 61 6b 65  to calls it make
6cf0: 73 20 74 6f 20 74 68 65 20 78 4c 6f 63 6b 28 29  s to the xLock()
6d00: 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 6d   and xUnlock() m
6d10: 65 74 68 6f 64 73 0a 2a 2a 20 6f 66 20 61 6e 20  ethods.** of an 
6d20: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
6d30: 6f 64 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a  ods] object..*/.
6d40: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
6d50: 4f 43 4b 5f 4e 4f 4e 45 20 20 20 20 20 20 20 20  OCK_NONE        
6d60: 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    0.#define SQLI
6d70: 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 20 20  TE_LOCK_SHARED  
6d80: 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20        1.#define 
6d90: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45  SQLITE_LOCK_RESE
6da0: 52 56 45 44 20 20 20 20 20 20 32 0a 23 64 65 66  RVED      2.#def
6db0: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ine SQLITE_LOCK_
6dc0: 50 45 4e 44 49 4e 47 20 20 20 20 20 20 20 33 0a  PENDING       3.
6dd0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
6de0: 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 20 20 20  OCK_EXCLUSIVE   
6df0: 20 20 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33    4../*.** CAPI3
6e00: 52 45 46 3a 20 53 79 6e 63 68 72 6f 6e 69 7a 61  REF: Synchroniza
6e10: 74 69 6f 6e 20 54 79 70 65 20 46 6c 61 67 73 0a  tion Type Flags.
6e20: 2a 2a 0a 2a 2a 20 57 68 65 6e 20 53 51 4c 69 74  **.** When SQLit
6e30: 65 20 69 6e 76 6f 6b 65 73 20 74 68 65 20 78 53  e invokes the xS
6e40: 79 6e 63 28 29 20 6d 65 74 68 6f 64 20 6f 66 20  ync() method of 
6e50: 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69  an.** [sqlite3_i
6e60: 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63  o_methods] objec
6e70: 74 20 69 74 20 75 73 65 73 20 61 20 63 6f 6d 62  t it uses a comb
6e80: 69 6e 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 74 68  ination of.** th
6e90: 65 73 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75  ese integer valu
6ea0: 65 73 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  es as the second
6eb0: 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a   argument..**.**
6ec0: 20 57 68 65 6e 20 74 68 65 20 53 51 4c 49 54 45   When the SQLITE
6ed0: 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 66  _SYNC_DATAONLY f
6ee0: 6c 61 67 20 69 73 20 75 73 65 64 2c 20 69 74 20  lag is used, it 
6ef0: 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 0a 2a  means that the.*
6f00: 2a 20 73 79 6e 63 20 6f 70 65 72 61 74 69 6f 6e  * sync operation
6f10: 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20 66   only needs to f
6f20: 6c 75 73 68 20 64 61 74 61 20 74 6f 20 6d 61 73  lush data to mas
6f30: 73 20 73 74 6f 72 61 67 65 2e 20 20 49 6e 6f 64  s storage.  Inod
6f40: 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  e.** information
6f50: 20 6e 65 65 64 20 6e 6f 74 20 62 65 20 66 6c 75   need not be flu
6f60: 73 68 65 64 2e 20 49 66 20 74 68 65 20 6c 6f 77  shed. If the low
6f70: 65 72 20 66 6f 75 72 20 62 69 74 73 20 6f 66 20  er four bits of 
6f80: 74 68 65 20 66 6c 61 67 0a 2a 2a 20 65 71 75 61  the flag.** equa
6f90: 6c 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f  l SQLITE_SYNC_NO
6fa0: 52 4d 41 4c 2c 20 74 68 61 74 20 6d 65 61 6e 73  RMAL, that means
6fb0: 20 74 6f 20 75 73 65 20 6e 6f 72 6d 61 6c 20 66   to use normal f
6fc0: 73 79 6e 63 28 29 20 73 65 6d 61 6e 74 69 63 73  sync() semantics
6fd0: 2e 0a 2a 2a 20 49 66 20 74 68 65 20 6c 6f 77 65  ..** If the lowe
6fe0: 72 20 66 6f 75 72 20 62 69 74 73 20 65 71 75 61  r four bits equa
6ff0: 6c 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55  l SQLITE_SYNC_FU
7000: 4c 4c 2c 20 74 68 61 74 20 6d 65 61 6e 73 0a 2a  LL, that means.*
7010: 2a 20 74 6f 20 75 73 65 20 4d 61 63 20 4f 53 20  * to use Mac OS 
7020: 58 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63  X style fullsync
7030: 20 69 6e 73 74 65 61 64 20 6f 66 20 66 73 79 6e   instead of fsyn
7040: 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 44 6f 20 6e 6f  c()..**.** Do no
7050: 74 20 63 6f 6e 66 75 73 65 20 74 68 65 20 53 51  t confuse the SQ
7060: 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c  LITE_SYNC_NORMAL
7070: 20 61 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e 43   and SQLITE_SYNC
7080: 5f 46 55 4c 4c 20 66 6c 61 67 73 0a 2a 2a 20 77  _FULL flags.** w
7090: 69 74 68 20 74 68 65 20 5b 50 52 41 47 4d 41 20  ith the [PRAGMA 
70a0: 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 3d 4e 4f 52  synchronous]=NOR
70b0: 4d 41 4c 20 61 6e 64 20 5b 50 52 41 47 4d 41 20  MAL and [PRAGMA 
70c0: 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 3d 46 55 4c  synchronous]=FUL
70d0: 4c 0a 2a 2a 20 73 65 74 74 69 6e 67 73 2e 20 20  L.** settings.  
70e0: 54 68 65 20 5b 73 79 6e 63 68 72 6f 6e 6f 75 73  The [synchronous
70f0: 20 70 72 61 67 6d 61 5d 20 64 65 74 65 72 6d 69   pragma] determi
7100: 6e 65 73 20 77 68 65 6e 20 63 61 6c 6c 73 20 74  nes when calls t
7110: 6f 20 74 68 65 0a 2a 2a 20 78 53 79 6e 63 20 56  o the.** xSync V
7120: 46 53 20 6d 65 74 68 6f 64 20 6f 63 63 75 72 20  FS method occur 
7130: 61 6e 64 20 61 70 70 6c 69 65 73 20 75 6e 69 66  and applies unif
7140: 6f 72 6d 6c 79 20 61 63 72 6f 73 73 20 61 6c 6c  ormly across all
7150: 20 70 6c 61 74 66 6f 72 6d 73 2e 0a 2a 2a 20 54   platforms..** T
7160: 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e  he SQLITE_SYNC_N
7170: 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 45  ORMAL and SQLITE
7180: 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 67 73  _SYNC_FULL flags
7190: 20 64 65 74 65 72 6d 69 6e 65 20 68 6f 77 0a 2a   determine how.*
71a0: 2a 20 65 6e 65 72 67 65 74 69 63 20 6f 72 20 72  * energetic or r
71b0: 69 67 6f 72 6f 75 73 20 6f 72 20 66 6f 72 63 65  igorous or force
71c0: 66 75 6c 20 74 68 65 20 73 79 6e 63 20 6f 70 65  ful the sync ope
71d0: 72 61 74 69 6f 6e 73 20 61 72 65 20 61 6e 64 0a  rations are and.
71e0: 2a 2a 20 6f 6e 6c 79 20 6d 61 6b 65 20 61 20 64  ** only make a d
71f0: 69 66 66 65 72 65 6e 63 65 20 6f 6e 20 4d 61 63  ifference on Mac
7200: 20 4f 53 58 20 66 6f 72 20 74 68 65 20 64 65 66   OSX for the def
7210: 61 75 6c 74 20 53 51 4c 69 74 65 20 63 6f 64 65  ault SQLite code
7220: 2e 0a 2a 2a 20 28 54 68 69 72 64 2d 70 61 72 74  ..** (Third-part
7230: 79 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61  y VFS implementa
7240: 74 69 6f 6e 73 20 6d 69 67 68 74 20 61 6c 73 6f  tions might also
7250: 20 6d 61 6b 65 20 74 68 65 20 64 69 73 74 69 6e   make the distin
7260: 63 74 69 6f 6e 0a 2a 2a 20 62 65 74 77 65 65 6e  ction.** between
7270: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52   SQLITE_SYNC_NOR
7280: 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f 53  MAL and SQLITE_S
7290: 59 4e 43 5f 46 55 4c 4c 2c 20 62 75 74 20 61 6d  YNC_FULL, but am
72a0: 6f 6e 67 20 74 68 65 0a 2a 2a 20 6f 70 65 72 61  ong the.** opera
72b0: 74 69 6e 67 20 73 79 73 74 65 6d 73 20 6e 61 74  ting systems nat
72c0: 69 76 65 6c 79 20 73 75 70 70 6f 72 74 65 64 20  ively supported 
72d0: 62 79 20 53 51 4c 69 74 65 2c 20 6f 6e 6c 79 20  by SQLite, only 
72e0: 4d 61 63 20 4f 53 58 0a 2a 2a 20 63 61 72 65 73  Mac OSX.** cares
72f0: 20 61 62 6f 75 74 20 74 68 65 20 64 69 66 66 65   about the diffe
7300: 72 65 6e 63 65 2e 29 0a 2a 2f 0a 23 64 65 66 69  rence.).*/.#defi
7310: 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e  ne SQLITE_SYNC_N
7320: 4f 52 4d 41 4c 20 20 20 20 20 20 20 20 30 78 30  ORMAL        0x0
7330: 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51 4c  0002.#define SQL
7340: 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 20 20  ITE_SYNC_FULL   
7350: 20 20 20 20 20 20 20 30 78 30 30 30 30 33 0a 23         0x00003.#
7360: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59  define SQLITE_SY
7370: 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 20 20 20 20  NC_DATAONLY     
7380: 20 30 78 30 30 30 31 30 0a 0a 2f 2a 0a 2a 2a 20   0x00010../*.** 
7390: 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74  CAPI3REF: OS Int
73a0: 65 72 66 61 63 65 20 4f 70 65 6e 20 46 69 6c 65  erface Open File
73b0: 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 41 6e   Handle.**.** An
73c0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20   [sqlite3_file] 
73d0: 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74  object represent
73e0: 73 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 69  s an open file i
73f0: 6e 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74  n the .** [sqlit
7400: 65 33 5f 76 66 73 20 7c 20 4f 53 20 69 6e 74 65  e3_vfs | OS inte
7410: 72 66 61 63 65 20 6c 61 79 65 72 5d 2e 20 20 49  rface layer].  I
7420: 6e 64 69 76 69 64 75 61 6c 20 4f 53 20 69 6e 74  ndividual OS int
7430: 65 72 66 61 63 65 0a 2a 2a 20 69 6d 70 6c 65 6d  erface.** implem
7440: 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c 6c 0a 2a  entations will.*
7450: 2a 20 77 61 6e 74 20 74 6f 20 73 75 62 63 6c 61  * want to subcla
7460: 73 73 20 74 68 69 73 20 6f 62 6a 65 63 74 20 62  ss this object b
7470: 79 20 61 70 70 65 6e 64 69 6e 67 20 61 64 64 69  y appending addi
7480: 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 0a 2a 2a  tional fields.**
7490: 20 66 6f 72 20 74 68 65 69 72 20 6f 77 6e 20 75   for their own u
74a0: 73 65 2e 20 20 54 68 65 20 70 4d 65 74 68 6f 64  se.  The pMethod
74b0: 73 20 65 6e 74 72 79 20 69 73 20 61 20 70 6f 69  s entry is a poi
74c0: 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73  nter to an.** [s
74d0: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
74e0: 73 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 20 64  s] object that d
74f0: 65 66 69 6e 65 73 20 6d 65 74 68 6f 64 73 20 66  efines methods f
7500: 6f 72 20 70 65 72 66 6f 72 6d 69 6e 67 0a 2a 2a  or performing.**
7510: 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73 20   I/O operations 
7520: 6f 6e 20 74 68 65 20 6f 70 65 6e 20 66 69 6c 65  on the open file
7530: 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
7540: 75 63 74 20 73 71 6c 69 74 65 33 5f 66 69 6c 65  uct sqlite3_file
7550: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 3b 0a 73   sqlite3_file;.s
7560: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 66 69  truct sqlite3_fi
7570: 6c 65 20 7b 0a 20 20 63 6f 6e 73 74 20 73 74 72  le {.  const str
7580: 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  uct sqlite3_io_m
7590: 65 74 68 6f 64 73 20 2a 70 4d 65 74 68 6f 64 73  ethods *pMethods
75a0: 3b 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 66 6f  ;  /* Methods fo
75b0: 72 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 2a  r an open file *
75c0: 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.};../*.** CAPI
75d0: 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61  3REF: OS Interfa
75e0: 63 65 20 46 69 6c 65 20 56 69 72 74 75 61 6c 20  ce File Virtual 
75f0: 4d 65 74 68 6f 64 73 20 4f 62 6a 65 63 74 0a 2a  Methods Object.*
7600: 2a 0a 2a 2a 20 45 76 65 72 79 20 66 69 6c 65 20  *.** Every file 
7610: 6f 70 65 6e 65 64 20 62 79 20 74 68 65 20 5b 73  opened by the [s
7620: 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e  qlite3_vfs.xOpen
7630: 5d 20 6d 65 74 68 6f 64 20 70 6f 70 75 6c 61 74  ] method populat
7640: 65 73 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65  es an.** [sqlite
7650: 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 28  3_file] object (
7660: 6f 72 2c 20 6d 6f 72 65 20 63 6f 6d 6d 6f 6e 6c  or, more commonl
7670: 79 2c 20 61 20 73 75 62 63 6c 61 73 73 20 6f 66  y, a subclass of
7680: 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
7690: 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 29 20 77  _file] object) w
76a0: 69 74 68 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  ith a pointer to
76b0: 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   an instance of 
76c0: 74 68 69 73 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20  this object..** 
76d0: 54 68 69 73 20 6f 62 6a 65 63 74 20 64 65 66 69  This object defi
76e0: 6e 65 73 20 74 68 65 20 6d 65 74 68 6f 64 73 20  nes the methods 
76f0: 75 73 65 64 20 74 6f 20 70 65 72 66 6f 72 6d 20  used to perform 
7700: 76 61 72 69 6f 75 73 20 6f 70 65 72 61 74 69 6f  various operatio
7710: 6e 73 0a 2a 2a 20 61 67 61 69 6e 73 74 20 74 68  ns.** against th
7720: 65 20 6f 70 65 6e 20 66 69 6c 65 20 72 65 70 72  e open file repr
7730: 65 73 65 6e 74 65 64 20 62 79 20 74 68 65 20 5b  esented by the [
7740: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62  sqlite3_file] ob
7750: 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  ject..**.** If t
7760: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e  he [sqlite3_vfs.
7770: 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20 73 65  xOpen] method se
7780: 74 73 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66  ts the sqlite3_f
7790: 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 65 6c 65  ile.pMethods ele
77a0: 6d 65 6e 74 20 0a 2a 2a 20 74 6f 20 61 20 6e 6f  ment .** to a no
77b0: 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20  n-NULL pointer, 
77c0: 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33  then the sqlite3
77d0: 5f 69 6f 5f 6d 65 74 68 6f 64 73 2e 78 43 6c 6f  _io_methods.xClo
77e0: 73 65 20 6d 65 74 68 6f 64 0a 2a 2a 20 6d 61 79  se method.** may
77f0: 20 62 65 20 69 6e 76 6f 6b 65 64 20 65 76 65 6e   be invoked even
7800: 20 69 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   if the [sqlite3
7810: 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 72 65 70 6f  _vfs.xOpen] repo
7820: 72 74 65 64 20 74 68 61 74 20 69 74 20 66 61 69  rted that it fai
7830: 6c 65 64 2e 20 20 54 68 65 0a 2a 2a 20 6f 6e 6c  led.  The.** onl
7840: 79 20 77 61 79 20 74 6f 20 70 72 65 76 65 6e 74  y way to prevent
7850: 20 61 20 63 61 6c 6c 20 74 6f 20 78 43 6c 6f 73   a call to xClos
7860: 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 61  e following a fa
7870: 69 6c 65 64 20 5b 73 71 6c 69 74 65 33 5f 76 66  iled [sqlite3_vf
7880: 73 2e 78 4f 70 65 6e 5d 0a 2a 2a 20 69 73 20 66  s.xOpen].** is f
7890: 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  or the [sqlite3_
78a0: 76 66 73 2e 78 4f 70 65 6e 5d 20 74 6f 20 73 65  vfs.xOpen] to se
78b0: 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69  t the sqlite3_fi
78c0: 6c 65 2e 70 4d 65 74 68 6f 64 73 20 65 6c 65 6d  le.pMethods elem
78d0: 65 6e 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 0a  ent.** to NULL..
78e0: 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73 20  **.** The flags 
78f0: 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 53 79 6e  argument to xSyn
7900: 63 20 6d 61 79 20 62 65 20 6f 6e 65 20 6f 66 20  c may be one of 
7910: 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52  [SQLITE_SYNC_NOR
7920: 4d 41 4c 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49  MAL] or.** [SQLI
7930: 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 5d 2e 20 20  TE_SYNC_FULL].  
7940: 54 68 65 20 66 69 72 73 74 20 63 68 6f 69 63 65  The first choice
7950: 20 69 73 20 74 68 65 20 6e 6f 72 6d 61 6c 20 66   is the normal f
7960: 73 79 6e 63 28 29 2e 0a 2a 2a 20 54 68 65 20 73  sync()..** The s
7970: 65 63 6f 6e 64 20 63 68 6f 69 63 65 20 69 73 20  econd choice is 
7980: 61 20 4d 61 63 20 4f 53 20 58 20 73 74 79 6c 65  a Mac OS X style
7990: 20 66 75 6c 6c 73 79 6e 63 2e 20 20 54 68 65 20   fullsync.  The 
79a0: 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54  [SQLITE_SYNC_DAT
79b0: 41 4f 4e 4c 59 5d 0a 2a 2a 20 66 6c 61 67 20 6d  AONLY].** flag m
79c0: 61 79 20 62 65 20 4f 52 65 64 20 69 6e 20 74 6f  ay be ORed in to
79d0: 20 69 6e 64 69 63 61 74 65 20 74 68 61 74 20 6f   indicate that o
79e0: 6e 6c 79 20 74 68 65 20 64 61 74 61 20 6f 66 20  nly the data of 
79f0: 74 68 65 20 66 69 6c 65 0a 2a 2a 20 61 6e 64 20  the file.** and 
7a00: 6e 6f 74 20 69 74 73 20 69 6e 6f 64 65 20 6e 65  not its inode ne
7a10: 65 64 73 20 74 6f 20 62 65 20 73 79 6e 63 65 64  eds to be synced
7a20: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 74 65  ..**.** The inte
7a30: 67 65 72 20 76 61 6c 75 65 73 20 74 6f 20 78 4c  ger values to xL
7a40: 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63  ock() and xUnloc
7a50: 6b 28 29 20 61 72 65 20 6f 6e 65 20 6f 66 0a 2a  k() are one of.*
7a60: 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b  * <ul>.** <li> [
7a70: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45  SQLITE_LOCK_NONE
7a80: 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  ],.** <li> [SQLI
7a90: 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 5d 2c  TE_LOCK_SHARED],
7aa0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
7ab0: 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c  _LOCK_RESERVED],
7ac0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
7ad0: 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20  _LOCK_PENDING], 
7ae0: 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  or.** <li> [SQLI
7af0: 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56  TE_LOCK_EXCLUSIV
7b00: 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20  E]..** </ul>.** 
7b10: 78 4c 6f 63 6b 28 29 20 69 6e 63 72 65 61 73 65  xLock() increase
7b20: 73 20 74 68 65 20 6c 6f 63 6b 2e 20 78 55 6e 6c  s the lock. xUnl
7b30: 6f 63 6b 28 29 20 64 65 63 72 65 61 73 65 73 20  ock() decreases 
7b40: 74 68 65 20 6c 6f 63 6b 2e 0a 2a 2a 20 54 68 65  the lock..** The
7b50: 20 78 43 68 65 63 6b 52 65 73 65 72 76 65 64 4c   xCheckReservedL
7b60: 6f 63 6b 28 29 20 6d 65 74 68 6f 64 20 63 68 65  ock() method che
7b70: 63 6b 73 20 77 68 65 74 68 65 72 20 61 6e 79 20  cks whether any 
7b80: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
7b90: 69 6f 6e 2c 0a 2a 2a 20 65 69 74 68 65 72 20 69  ion,.** either i
7ba0: 6e 20 74 68 69 73 20 70 72 6f 63 65 73 73 20 6f  n this process o
7bb0: 72 20 69 6e 20 73 6f 6d 65 20 6f 74 68 65 72 20  r in some other 
7bc0: 70 72 6f 63 65 73 73 2c 20 69 73 20 68 6f 6c 64  process, is hold
7bd0: 69 6e 67 20 61 20 52 45 53 45 52 56 45 44 2c 0a  ing a RESERVED,.
7be0: 2a 2a 20 50 45 4e 44 49 4e 47 2c 20 6f 72 20 45  ** PENDING, or E
7bf0: 58 43 4c 55 53 49 56 45 20 6c 6f 63 6b 20 6f 6e  XCLUSIVE lock on
7c00: 20 74 68 65 20 66 69 6c 65 2e 20 20 49 74 20 72   the file.  It r
7c10: 65 74 75 72 6e 73 20 74 72 75 65 0a 2a 2a 20 69  eturns true.** i
7c20: 66 20 73 75 63 68 20 61 20 6c 6f 63 6b 20 65 78  f such a lock ex
7c30: 69 73 74 73 20 61 6e 64 20 66 61 6c 73 65 20 6f  ists and false o
7c40: 74 68 65 72 77 69 73 65 2e 0a 2a 2a 0a 2a 2a 20  therwise..**.** 
7c50: 54 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  The xFileControl
7c60: 28 29 20 6d 65 74 68 6f 64 20 69 73 20 61 20 67  () method is a g
7c70: 65 6e 65 72 69 63 20 69 6e 74 65 72 66 61 63 65  eneric interface
7c80: 20 74 68 61 74 20 61 6c 6c 6f 77 73 20 63 75 73   that allows cus
7c90: 74 6f 6d 0a 2a 2a 20 56 46 53 20 69 6d 70 6c 65  tom.** VFS imple
7ca0: 6d 65 6e 74 61 74 69 6f 6e 73 20 74 6f 20 64 69  mentations to di
7cb0: 72 65 63 74 6c 79 20 63 6f 6e 74 72 6f 6c 20 61  rectly control a
7cc0: 6e 20 6f 70 65 6e 20 66 69 6c 65 20 75 73 69 6e  n open file usin
7cd0: 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  g the.** [sqlite
7ce0: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
7cf0: 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 20 54 68  ] interface.  Th
7d00: 65 20 73 65 63 6f 6e 64 20 22 6f 70 22 20 61 72  e second "op" ar
7d10: 67 75 6d 65 6e 74 20 69 73 20 61 6e 0a 2a 2a 20  gument is an.** 
7d20: 69 6e 74 65 67 65 72 20 6f 70 63 6f 64 65 2e 20  integer opcode. 
7d30: 20 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d   The third argum
7d40: 65 6e 74 20 69 73 20 61 20 67 65 6e 65 72 69 63  ent is a generic
7d50: 20 70 6f 69 6e 74 65 72 20 69 6e 74 65 6e 64 65   pointer intende
7d60: 64 20 74 6f 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f  d to.** point to
7d70: 20 61 20 73 74 72 75 63 74 75 72 65 20 74 68 61   a structure tha
7d80: 74 20 6d 61 79 20 63 6f 6e 74 61 69 6e 20 61 72  t may contain ar
7d90: 67 75 6d 65 6e 74 73 20 6f 72 20 73 70 61 63 65  guments or space
7da0: 20 69 6e 20 77 68 69 63 68 20 74 6f 0a 2a 2a 20   in which to.** 
7db0: 77 72 69 74 65 20 72 65 74 75 72 6e 20 76 61 6c  write return val
7dc0: 75 65 73 2e 20 20 50 6f 74 65 6e 74 69 61 6c 20  ues.  Potential 
7dd0: 75 73 65 73 20 66 6f 72 20 78 46 69 6c 65 43 6f  uses for xFileCo
7de0: 6e 74 72 6f 6c 28 29 20 6d 69 67 68 74 20 62 65  ntrol() might be
7df0: 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f  .** functions to
7e00: 20 65 6e 61 62 6c 65 20 62 6c 6f 63 6b 69 6e 67   enable blocking
7e10: 20 6c 6f 63 6b 73 20 77 69 74 68 20 74 69 6d 65   locks with time
7e20: 6f 75 74 73 2c 20 74 6f 20 63 68 61 6e 67 65 20  outs, to change 
7e30: 74 68 65 0a 2a 2a 20 6c 6f 63 6b 69 6e 67 20 73  the.** locking s
7e40: 74 72 61 74 65 67 79 20 28 66 6f 72 20 65 78 61  trategy (for exa
7e50: 6d 70 6c 65 20 74 6f 20 75 73 65 20 64 6f 74 2d  mple to use dot-
7e60: 66 69 6c 65 20 6c 6f 63 6b 73 29 2c 20 74 6f 20  file locks), to 
7e70: 69 6e 71 75 69 72 65 0a 2a 2a 20 61 62 6f 75 74  inquire.** about
7e80: 20 74 68 65 20 73 74 61 74 75 73 20 6f 66 20 61   the status of a
7e90: 20 6c 6f 63 6b 2c 20 6f 72 20 74 6f 20 62 72 65   lock, or to bre
7ea0: 61 6b 20 73 74 61 6c 65 20 6c 6f 63 6b 73 2e 20  ak stale locks. 
7eb0: 20 54 68 65 20 53 51 4c 69 74 65 0a 2a 2a 20 63   The SQLite.** c
7ec0: 6f 72 65 20 72 65 73 65 72 76 65 73 20 61 6c 6c  ore reserves all
7ed0: 20 6f 70 63 6f 64 65 73 20 6c 65 73 73 20 74 68   opcodes less th
7ee0: 61 6e 20 31 30 30 20 66 6f 72 20 69 74 73 20 6f  an 100 for its o
7ef0: 77 6e 20 75 73 65 2e 0a 2a 2a 20 41 20 5b 66 69  wn use..** A [fi
7f00: 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64  le control opcod
7f10: 65 73 20 7c 20 6c 69 73 74 20 6f 66 20 6f 70 63  es | list of opc
7f20: 6f 64 65 73 5d 20 6c 65 73 73 20 74 68 61 6e 20  odes] less than 
7f30: 31 30 30 20 69 73 20 61 76 61 69 6c 61 62 6c 65  100 is available
7f40: 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e  ..** Application
7f50: 73 20 74 68 61 74 20 64 65 66 69 6e 65 20 61 20  s that define a 
7f60: 63 75 73 74 6f 6d 20 78 46 69 6c 65 43 6f 6e 74  custom xFileCont
7f70: 72 6f 6c 20 6d 65 74 68 6f 64 20 73 68 6f 75 6c  rol method shoul
7f80: 64 20 75 73 65 20 6f 70 63 6f 64 65 73 0a 2a 2a  d use opcodes.**
7f90: 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 31 30   greater than 10
7fa0: 30 20 74 6f 20 61 76 6f 69 64 20 63 6f 6e 66 6c  0 to avoid confl
7fb0: 69 63 74 73 2e 20 20 56 46 53 20 69 6d 70 6c 65  icts.  VFS imple
7fc0: 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c  mentations shoul
7fd0: 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c  d.** return [SQL
7fe0: 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 20 66 6f  ITE_NOTFOUND] fo
7ff0: 72 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f  r file control o
8000: 70 63 6f 64 65 73 20 74 68 61 74 20 74 68 65 79  pcodes that they
8010: 20 64 6f 20 6e 6f 74 0a 2a 2a 20 72 65 63 6f 67   do not.** recog
8020: 6e 69 7a 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  nize..**.** The 
8030: 78 53 65 63 74 6f 72 53 69 7a 65 28 29 20 6d 65  xSectorSize() me
8040: 74 68 6f 64 20 72 65 74 75 72 6e 73 20 74 68 65  thod returns the
8050: 20 73 65 63 74 6f 72 20 73 69 7a 65 20 6f 66 20   sector size of 
8060: 74 68 65 0a 2a 2a 20 64 65 76 69 63 65 20 74 68  the.** device th
8070: 61 74 20 75 6e 64 65 72 6c 69 65 73 20 74 68 65  at underlies the
8080: 20 66 69 6c 65 2e 20 20 54 68 65 20 73 65 63 74   file.  The sect
8090: 6f 72 20 73 69 7a 65 20 69 73 20 74 68 65 0a 2a  or size is the.*
80a0: 2a 20 6d 69 6e 69 6d 75 6d 20 77 72 69 74 65 20  * minimum write 
80b0: 74 68 61 74 20 63 61 6e 20 62 65 20 70 65 72 66  that can be perf
80c0: 6f 72 6d 65 64 20 77 69 74 68 6f 75 74 20 64 69  ormed without di
80d0: 73 74 75 72 62 69 6e 67 0a 2a 2a 20 6f 74 68 65  sturbing.** othe
80e0: 72 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 66  r bytes in the f
80f0: 69 6c 65 2e 20 20 54 68 65 20 78 44 65 76 69 63  ile.  The xDevic
8100: 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73  eCharacteristics
8110: 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74  ().** method ret
8120: 75 72 6e 73 20 61 20 62 69 74 20 76 65 63 74 6f  urns a bit vecto
8130: 72 20 64 65 73 63 72 69 62 69 6e 67 20 62 65 68  r describing beh
8140: 61 76 69 6f 72 73 20 6f 66 20 74 68 65 0a 2a 2a  aviors of the.**
8150: 20 75 6e 64 65 72 6c 79 69 6e 67 20 64 65 76 69   underlying devi
8160: 63 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  ce:.**.** <ul>.*
8170: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
8180: 4f 43 41 50 5f 41 54 4f 4d 49 43 5d 0a 2a 2a 20  OCAP_ATOMIC].** 
8190: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
81a0: 41 50 5f 41 54 4f 4d 49 43 35 31 32 5d 0a 2a 2a  AP_ATOMIC512].**
81b0: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f   <li> [SQLITE_IO
81c0: 43 41 50 5f 41 54 4f 4d 49 43 31 4b 5d 0a 2a 2a  CAP_ATOMIC1K].**
81d0: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f   <li> [SQLITE_IO
81e0: 43 41 50 5f 41 54 4f 4d 49 43 32 4b 5d 0a 2a 2a  CAP_ATOMIC2K].**
81f0: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f   <li> [SQLITE_IO
8200: 43 41 50 5f 41 54 4f 4d 49 43 34 4b 5d 0a 2a 2a  CAP_ATOMIC4K].**
8210: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f   <li> [SQLITE_IO
8220: 43 41 50 5f 41 54 4f 4d 49 43 38 4b 5d 0a 2a 2a  CAP_ATOMIC8K].**
8230: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f   <li> [SQLITE_IO
8240: 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b 5d 0a 2a  CAP_ATOMIC16K].*
8250: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
8260: 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b 5d 0a  OCAP_ATOMIC32K].
8270: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
8280: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b 5d  IOCAP_ATOMIC64K]
8290: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
82a0: 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45  _IOCAP_SAFE_APPE
82b0: 4e 44 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  ND].** <li> [SQL
82c0: 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e  ITE_IOCAP_SEQUEN
82d0: 54 49 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  TIAL].** </ul>.*
82e0: 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f  *.** The SQLITE_
82f0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70 72 6f  IOCAP_ATOMIC pro
8300: 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74  perty means that
8310: 20 61 6c 6c 20 77 72 69 74 65 73 20 6f 66 0a 2a   all writes of.*
8320: 2a 20 61 6e 79 20 73 69 7a 65 20 61 72 65 20 61  * any size are a
8330: 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49  tomic.  The SQLI
8340: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 6e  TE_IOCAP_ATOMICn
8350: 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d 65 61  nn values.** mea
8360: 6e 20 74 68 61 74 20 77 72 69 74 65 73 20 6f 66  n that writes of
8370: 20 62 6c 6f 63 6b 73 20 74 68 61 74 20 61 72 65   blocks that are
8380: 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20 73 69   nnn bytes in si
8390: 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20 61 6c  ze and.** are al
83a0: 69 67 6e 65 64 20 74 6f 20 61 6e 20 61 64 64 72  igned to an addr
83b0: 65 73 73 20 77 68 69 63 68 20 69 73 20 61 6e 20  ess which is an 
83c0: 69 6e 74 65 67 65 72 20 6d 75 6c 74 69 70 6c 65  integer multiple
83d0: 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20 61   of.** nnn are a
83e0: 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49  tomic.  The SQLI
83f0: 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50  TE_IOCAP_SAFE_AP
8400: 50 45 4e 44 20 76 61 6c 75 65 20 6d 65 61 6e 73  PEND value means
8410: 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e 20 64 61  .** that when da
8420: 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 20 74  ta is appended t
8430: 6f 20 61 20 66 69 6c 65 2c 20 74 68 65 20 64 61  o a file, the da
8440: 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 0a 2a  ta is appended.*
8450: 2a 20 66 69 72 73 74 20 74 68 65 6e 20 74 68 65  * first then the
8460: 20 73 69 7a 65 20 6f 66 20 74 68 65 20 66 69 6c   size of the fil
8470: 65 20 69 73 20 65 78 74 65 6e 64 65 64 2c 20 6e  e is extended, n
8480: 65 76 65 72 20 74 68 65 20 6f 74 68 65 72 0a 2a  ever the other.*
8490: 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e 20 20 54  * way around.  T
84a0: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
84b0: 53 45 51 55 45 4e 54 49 41 4c 20 70 72 6f 70 65  SEQUENTIAL prope
84c0: 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a  rty means that.*
84d0: 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73  * information is
84e0: 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69 73 6b   written to disk
84f0: 20 69 6e 20 74 68 65 20 73 61 6d 65 20 6f 72 64   in the same ord
8500: 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a 20 74  er as calls.** t
8510: 6f 20 78 57 72 69 74 65 28 29 2e 0a 2a 2a 0a 2a  o xWrite()..**.*
8520: 2a 20 49 66 20 78 52 65 61 64 28 29 20 72 65 74  * If xRead() ret
8530: 75 72 6e 73 20 53 51 4c 49 54 45 5f 49 4f 45 52  urns SQLITE_IOER
8540: 52 5f 53 48 4f 52 54 5f 52 45 41 44 20 69 74 20  R_SHORT_READ it 
8550: 6d 75 73 74 20 61 6c 73 6f 20 66 69 6c 6c 0a 2a  must also fill.*
8560: 2a 20 69 6e 20 74 68 65 20 75 6e 72 65 61 64 20  * in the unread 
8570: 70 6f 72 74 69 6f 6e 73 20 6f 66 20 74 68 65 20  portions of the 
8580: 62 75 66 66 65 72 20 77 69 74 68 20 7a 65 72 6f  buffer with zero
8590: 73 2e 20 20 41 20 56 46 53 20 74 68 61 74 0a 2a  s.  A VFS that.*
85a0: 2a 20 66 61 69 6c 73 20 74 6f 20 7a 65 72 6f 2d  * fails to zero-
85b0: 66 69 6c 6c 20 73 68 6f 72 74 20 72 65 61 64 73  fill short reads
85c0: 20 6d 69 67 68 74 20 73 65 65 6d 20 74 6f 20 77   might seem to w
85d0: 6f 72 6b 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a  ork.  However,.*
85e0: 2a 20 66 61 69 6c 75 72 65 20 74 6f 20 7a 65 72  * failure to zer
85f0: 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72 65 61  o-fill short rea
8600: 64 73 20 77 69 6c 6c 20 65 76 65 6e 74 75 61 6c  ds will eventual
8610: 6c 79 20 6c 65 61 64 20 74 6f 0a 2a 2a 20 64 61  ly lead to.** da
8620: 74 61 62 61 73 65 20 63 6f 72 72 75 70 74 69 6f  tabase corruptio
8630: 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  n..*/.typedef st
8640: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f  ruct sqlite3_io_
8650: 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65 33 5f  methods sqlite3_
8660: 69 6f 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75  io_methods;.stru
8670: 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  ct sqlite3_io_me
8680: 74 68 6f 64 73 20 7b 0a 20 20 69 6e 74 20 69 56  thods {.  int iV
8690: 65 72 73 69 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a  ersion;.  int (*
86a0: 78 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f  xClose)(sqlite3_
86b0: 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  file*);.  int (*
86c0: 78 52 65 61 64 29 28 73 71 6c 69 74 65 33 5f 66  xRead)(sqlite3_f
86d0: 69 6c 65 2a 2c 20 76 6f 69 64 2a 2c 20 69 6e 74  ile*, void*, int
86e0: 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69   iAmt, sqlite3_i
86f0: 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69  nt64 iOfst);.  i
8700: 6e 74 20 28 2a 78 57 72 69 74 65 29 28 73 71 6c  nt (*xWrite)(sql
8710: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 63 6f 6e 73  ite3_file*, cons
8720: 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d  t void*, int iAm
8730: 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  t, sqlite3_int64
8740: 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28   iOfst);.  int (
8750: 2a 78 54 72 75 6e 63 61 74 65 29 28 73 71 6c 69  *xTruncate)(sqli
8760: 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74  te3_file*, sqlit
8770: 65 33 5f 69 6e 74 36 34 20 73 69 7a 65 29 3b 0a  e3_int64 size);.
8780: 20 20 69 6e 74 20 28 2a 78 53 79 6e 63 29 28 73    int (*xSync)(s
8790: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e  qlite3_file*, in
87a0: 74 20 66 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20  t flags);.  int 
87b0: 28 2a 78 46 69 6c 65 53 69 7a 65 29 28 73 71 6c  (*xFileSize)(sql
87c0: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69  ite3_file*, sqli
87d0: 74 65 33 5f 69 6e 74 36 34 20 2a 70 53 69 7a 65  te3_int64 *pSize
87e0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4c 6f 63 6b  );.  int (*xLock
87f0: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
8800: 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78   int);.  int (*x
8810: 55 6e 6c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f  Unlock)(sqlite3_
8820: 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69  file*, int);.  i
8830: 6e 74 20 28 2a 78 43 68 65 63 6b 52 65 73 65 72  nt (*xCheckReser
8840: 76 65 64 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33  vedLock)(sqlite3
8850: 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 2a 70 52 65  _file*, int *pRe
8860: 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78  sOut);.  int (*x
8870: 46 69 6c 65 43 6f 6e 74 72 6f 6c 29 28 73 71 6c  FileControl)(sql
8880: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20  ite3_file*, int 
8890: 6f 70 2c 20 76 6f 69 64 20 2a 70 41 72 67 29 3b  op, void *pArg);
88a0: 0a 20 20 69 6e 74 20 28 2a 78 53 65 63 74 6f 72  .  int (*xSector
88b0: 53 69 7a 65 29 28 73 71 6c 69 74 65 33 5f 66 69  Size)(sqlite3_fi
88c0: 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44  le*);.  int (*xD
88d0: 65 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73  eviceCharacteris
88e0: 74 69 63 73 29 28 73 71 6c 69 74 65 33 5f 66 69  tics)(sqlite3_fi
88f0: 6c 65 2a 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f  le*);.  /* Metho
8900: 64 73 20 61 62 6f 76 65 20 61 72 65 20 76 61 6c  ds above are val
8910: 69 64 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 31  id for version 1
8920: 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d   */.  int (*xShm
8930: 4d 61 70 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  Map)(sqlite3_fil
8940: 65 2a 2c 20 69 6e 74 20 69 50 67 2c 20 69 6e 74  e*, int iPg, int
8950: 20 70 67 73 7a 2c 20 69 6e 74 2c 20 76 6f 69 64   pgsz, int, void
8960: 20 76 6f 6c 61 74 69 6c 65 2a 2a 29 3b 0a 20 20   volatile**);.  
8970: 69 6e 74 20 28 2a 78 53 68 6d 4c 6f 63 6b 29 28  int (*xShmLock)(
8980: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69  sqlite3_file*, i
8990: 6e 74 20 6f 66 66 73 65 74 2c 20 69 6e 74 20 6e  nt offset, int n
89a0: 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20  , int flags);.  
89b0: 76 6f 69 64 20 28 2a 78 53 68 6d 42 61 72 72 69  void (*xShmBarri
89c0: 65 72 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  er)(sqlite3_file
89d0: 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d  *);.  int (*xShm
89e0: 55 6e 6d 61 70 29 28 73 71 6c 69 74 65 33 5f 66  Unmap)(sqlite3_f
89f0: 69 6c 65 2a 2c 20 69 6e 74 20 64 65 6c 65 74 65  ile*, int delete
8a00: 46 6c 61 67 29 3b 0a 20 20 2f 2a 20 4d 65 74 68  Flag);.  /* Meth
8a10: 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 76 61  ods above are va
8a20: 6c 69 64 20 66 6f 72 20 76 65 72 73 69 6f 6e 20  lid for version 
8a30: 32 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 46 65  2 */.  int (*xFe
8a40: 74 63 68 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  tch)(sqlite3_fil
8a50: 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  e*, sqlite3_int6
8a60: 34 20 69 4f 66 73 74 2c 20 69 6e 74 20 69 41 6d  4 iOfst, int iAm
8a70: 74 2c 20 76 6f 69 64 20 2a 2a 70 70 29 3b 0a 20  t, void **pp);. 
8a80: 20 69 6e 74 20 28 2a 78 55 6e 66 65 74 63 68 29   int (*xUnfetch)
8a90: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
8aa0: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f  sqlite3_int64 iO
8ab0: 66 73 74 2c 20 76 6f 69 64 20 2a 70 29 3b 0a 20  fst, void *p);. 
8ac0: 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76   /* Methods abov
8ad0: 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20  e are valid for 
8ae0: 76 65 72 73 69 6f 6e 20 33 20 2a 2f 0a 20 20 2f  version 3 */.  /
8af0: 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 6d 65 74  * Additional met
8b00: 68 6f 64 73 20 6d 61 79 20 62 65 20 61 64 64 65  hods may be adde
8b10: 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65  d in future rele
8b20: 61 73 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a  ases */.};../*.*
8b30: 2a 20 43 41 50 49 33 52 45 46 3a 20 53 74 61 6e  * CAPI3REF: Stan
8b40: 64 61 72 64 20 46 69 6c 65 20 43 6f 6e 74 72 6f  dard File Contro
8b50: 6c 20 4f 70 63 6f 64 65 73 0a 2a 2a 20 4b 45 59  l Opcodes.** KEY
8b60: 57 4f 52 44 53 3a 20 7b 66 69 6c 65 20 63 6f 6e  WORDS: {file con
8b70: 74 72 6f 6c 20 6f 70 63 6f 64 65 73 7d 20 7b 66  trol opcodes} {f
8b80: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f  ile control opco
8b90: 64 65 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  de}.**.** These 
8ba0: 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74  integer constant
8bb0: 73 20 61 72 65 20 6f 70 63 6f 64 65 73 20 66 6f  s are opcodes fo
8bc0: 72 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72  r the xFileContr
8bd0: 6f 6c 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f 66 20  ol method.** of 
8be0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f  the [sqlite3_io_
8bf0: 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20  methods] object 
8c00: 61 6e 64 20 66 6f 72 20 74 68 65 20 5b 73 71 6c  and for the [sql
8c10: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f  ite3_file_contro
8c20: 6c 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63  l()].** interfac
8c30: 65 2e 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  e..**.** <ul>.**
8c40: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
8c50: 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d 5d 0a  NTL_LOCKSTATE]].
8c60: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
8c70: 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d 20  CNTL_LOCKSTATE] 
8c80: 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 66  opcode is used f
8c90: 6f 72 20 64 65 62 75 67 67 69 6e 67 2e 20 20 54  or debugging.  T
8ca0: 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 63 61  his.** opcode ca
8cb0: 75 73 65 73 20 74 68 65 20 78 46 69 6c 65 43 6f  uses the xFileCo
8cc0: 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 74 6f 20  ntrol method to 
8cd0: 77 72 69 74 65 20 74 68 65 20 63 75 72 72 65 6e  write the curren
8ce0: 74 20 73 74 61 74 65 20 6f 66 0a 2a 2a 20 74 68  t state of.** th
8cf0: 65 20 6c 6f 63 6b 20 28 6f 6e 65 20 6f 66 20 5b  e lock (one of [
8d00: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45  SQLITE_LOCK_NONE
8d10: 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ], [SQLITE_LOCK_
8d20: 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 5b 53 51 4c  SHARED],.** [SQL
8d30: 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45  ITE_LOCK_RESERVE
8d40: 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  D], [SQLITE_LOCK
8d50: 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 20 5b 53  _PENDING], or [S
8d60: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55  QLITE_LOCK_EXCLU
8d70: 53 49 56 45 5d 29 0a 2a 2a 20 69 6e 74 6f 20 61  SIVE]).** into a
8d80: 6e 20 69 6e 74 65 67 65 72 20 74 68 61 74 20 74  n integer that t
8d90: 68 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e 74  he pArg argument
8da0: 20 70 6f 69 6e 74 73 20 74 6f 2e 20 54 68 69 73   points to. This
8db0: 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69   capability.** i
8dc0: 73 20 75 73 65 64 20 64 75 72 69 6e 67 20 74 65  s used during te
8dd0: 73 74 69 6e 67 20 61 6e 64 20 69 73 20 6f 6e 6c  sting and is onl
8de0: 79 20 61 76 61 69 6c 61 62 6c 65 20 77 68 65 6e  y available when
8df0: 20 74 68 65 20 53 51 4c 49 54 45 5f 54 45 53 54   the SQLITE_TEST
8e00: 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  .** compile-time
8e10: 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 2e   option is used.
8e20: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
8e30: 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48  ITE_FCNTL_SIZE_H
8e40: 49 4e 54 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51  INT]].** The [SQ
8e50: 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f  LITE_FCNTL_SIZE_
8e60: 48 49 4e 54 5d 20 6f 70 63 6f 64 65 20 69 73 20  HINT] opcode is 
8e70: 75 73 65 64 20 62 79 20 53 51 4c 69 74 65 20 74  used by SQLite t
8e80: 6f 20 67 69 76 65 20 74 68 65 20 56 46 53 0a 2a  o give the VFS.*
8e90: 2a 20 6c 61 79 65 72 20 61 20 68 69 6e 74 20 6f  * layer a hint o
8ea0: 66 20 68 6f 77 20 6c 61 72 67 65 20 74 68 65 20  f how large the 
8eb0: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 69  database file wi
8ec0: 6c 6c 20 67 72 6f 77 20 74 6f 20 62 65 20 64 75  ll grow to be du
8ed0: 72 69 6e 67 20 74 68 65 0a 2a 2a 20 63 75 72 72  ring the.** curr
8ee0: 65 6e 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e  ent transaction.
8ef0: 20 20 54 68 69 73 20 68 69 6e 74 20 69 73 20 6e    This hint is n
8f00: 6f 74 20 67 75 61 72 61 6e 74 65 65 64 20 74 6f  ot guaranteed to
8f10: 20 62 65 20 61 63 63 75 72 61 74 65 20 62 75 74   be accurate but
8f20: 20 69 74 0a 2a 2a 20 69 73 20 6f 66 74 65 6e 20   it.** is often 
8f30: 63 6c 6f 73 65 2e 20 20 54 68 65 20 75 6e 64 65  close.  The unde
8f40: 72 6c 79 69 6e 67 20 56 46 53 20 6d 69 67 68 74  rlying VFS might
8f50: 20 63 68 6f 6f 73 65 20 74 6f 20 70 72 65 61 6c   choose to preal
8f60: 6c 6f 63 61 74 65 20 64 61 74 61 62 61 73 65 0a  locate database.
8f70: 2a 2a 20 66 69 6c 65 20 73 70 61 63 65 20 62 61  ** file space ba
8f80: 73 65 64 20 6f 6e 20 74 68 69 73 20 68 69 6e 74  sed on this hint
8f90: 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 68 65 6c   in order to hel
8fa0: 70 20 77 72 69 74 65 73 20 74 6f 20 74 68 65 20  p writes to the 
8fb0: 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65  database.** file
8fc0: 20 72 75 6e 20 66 61 73 74 65 72 2e 0a 2a 2a 0a   run faster..**.
8fd0: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
8fe0: 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45  FCNTL_CHUNK_SIZE
8ff0: 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  ]].** The [SQLIT
9000: 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49  E_FCNTL_CHUNK_SI
9010: 5a 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73  ZE] opcode is us
9020: 65 64 20 74 6f 20 72 65 71 75 65 73 74 20 74 68  ed to request th
9030: 61 74 20 74 68 65 20 56 46 53 0a 2a 2a 20 65 78  at the VFS.** ex
9040: 74 65 6e 64 73 20 61 6e 64 20 74 72 75 6e 63 61  tends and trunca
9050: 74 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65  tes the database
9060: 20 66 69 6c 65 20 69 6e 20 63 68 75 6e 6b 73 20   file in chunks 
9070: 6f 66 20 61 20 73 69 7a 65 20 73 70 65 63 69 66  of a size specif
9080: 69 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 75 73  ied.** by the us
9090: 65 72 2e 20 54 68 65 20 66 6f 75 72 74 68 20 61  er. The fourth a
90a0: 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69  rgument to [sqli
90b0: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
90c0: 28 29 5d 20 73 68 6f 75 6c 64 20 0a 2a 2a 20 70  ()] should .** p
90d0: 6f 69 6e 74 20 74 6f 20 61 6e 20 69 6e 74 65 67  oint to an integ
90e0: 65 72 20 28 74 79 70 65 20 69 6e 74 29 20 63 6f  er (type int) co
90f0: 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 6e 65 77  ntaining the new
9100: 20 63 68 75 6e 6b 2d 73 69 7a 65 20 74 6f 20 75   chunk-size to u
9110: 73 65 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6e 6f  se.** for the no
9120: 6d 69 6e 61 74 65 64 20 64 61 74 61 62 61 73 65  minated database
9130: 2e 20 41 6c 6c 6f 63 61 74 69 6e 67 20 64 61 74  . Allocating dat
9140: 61 62 61 73 65 20 66 69 6c 65 20 73 70 61 63 65  abase file space
9150: 20 69 6e 20 6c 61 72 67 65 0a 2a 2a 20 63 68 75   in large.** chu
9160: 6e 6b 73 20 28 73 61 79 20 31 4d 42 20 61 74 20  nks (say 1MB at 
9170: 61 20 74 69 6d 65 29 2c 20 6d 61 79 20 72 65 64  a time), may red
9180: 75 63 65 20 66 69 6c 65 2d 73 79 73 74 65 6d 20  uce file-system 
9190: 66 72 61 67 6d 65 6e 74 61 74 69 6f 6e 20 61 6e  fragmentation an
91a0: 64 0a 2a 2a 20 69 6d 70 72 6f 76 65 20 70 65 72  d.** improve per
91b0: 66 6f 72 6d 61 6e 63 65 20 6f 6e 20 73 6f 6d 65  formance on some
91c0: 20 73 79 73 74 65 6d 73 2e 0a 2a 2a 0a 2a 2a 20   systems..**.** 
91d0: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
91e0: 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 5d  TL_FILE_POINTER]
91f0: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ].** The [SQLITE
9200: 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e  _FCNTL_FILE_POIN
9210: 54 45 52 5d 20 6f 70 63 6f 64 65 20 69 73 20 75  TER] opcode is u
9220: 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 61 20  sed to obtain a 
9230: 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68  pointer.** to th
9240: 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  e [sqlite3_file]
9250: 20 6f 62 6a 65 63 74 20 61 73 73 6f 63 69 61 74   object associat
9260: 65 64 20 77 69 74 68 20 61 20 70 61 72 74 69 63  ed with a partic
9270: 75 6c 61 72 20 64 61 74 61 62 61 73 65 0a 2a 2a  ular database.**
9280: 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 53 65   connection.  Se
9290: 65 20 61 6c 73 6f 20 5b 53 51 4c 49 54 45 5f 46  e also [SQLITE_F
92a0: 43 4e 54 4c 5f 4a 4f 55 52 4e 41 4c 5f 50 4f 49  CNTL_JOURNAL_POI
92b0: 4e 54 45 52 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  NTER]..**.** <li
92c0: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
92d0: 4a 4f 55 52 4e 41 4c 5f 50 4f 49 4e 54 45 52 5d  JOURNAL_POINTER]
92e0: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ].** The [SQLITE
92f0: 5f 46 43 4e 54 4c 5f 4a 4f 55 52 4e 41 4c 5f 50  _FCNTL_JOURNAL_P
9300: 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64 65 20 69  OINTER] opcode i
9310: 73 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e  s used to obtain
9320: 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f   a pointer.** to
9330: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69   the [sqlite3_fi
9340: 6c 65 5d 20 6f 62 6a 65 63 74 20 61 73 73 6f 63  le] object assoc
9350: 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20 6a  iated with the j
9360: 6f 75 72 6e 61 6c 20 66 69 6c 65 20 28 65 69 74  ournal file (eit
9370: 68 65 72 0a 2a 2a 20 74 68 65 20 5b 72 6f 6c 6c  her.** the [roll
9380: 62 61 63 6b 20 6a 6f 75 72 6e 61 6c 5d 20 6f 72  back journal] or
9390: 20 74 68 65 20 5b 77 72 69 74 65 2d 61 68 65 61   the [write-ahea
93a0: 64 20 6c 6f 67 5d 29 20 66 6f 72 20 61 20 70 61  d log]) for a pa
93b0: 72 74 69 63 75 6c 61 72 20 64 61 74 61 62 61 73  rticular databas
93c0: 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e  e.** connection.
93d0: 20 20 53 65 65 20 61 6c 73 6f 20 5b 53 51 4c 49    See also [SQLI
93e0: 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f  TE_FCNTL_FILE_PO
93f0: 49 4e 54 45 52 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  INTER]..**.** <l
9400: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
9410: 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44 5d 5d 0a  _SYNC_OMITTED]].
9420: 2a 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 69 6e 20  ** No longer in 
9430: 75 73 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  use..**.** <li>[
9440: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59  [SQLITE_FCNTL_SY
9450: 4e 43 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  NC]].** The [SQL
9460: 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5d 20  ITE_FCNTL_SYNC] 
9470: 6f 70 63 6f 64 65 20 69 73 20 67 65 6e 65 72 61  opcode is genera
9480: 74 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62  ted internally b
9490: 79 20 53 51 4c 69 74 65 20 61 6e 64 0a 2a 2a 20  y SQLite and.** 
94a0: 73 65 6e 74 20 74 6f 20 74 68 65 20 56 46 53 20  sent to the VFS 
94b0: 69 6d 6d 65 64 69 61 74 65 6c 79 20 62 65 66 6f  immediately befo
94c0: 72 65 20 74 68 65 20 78 53 79 6e 63 20 6d 65 74  re the xSync met
94d0: 68 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f  hod is invoked o
94e0: 6e 20 61 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  n a.** database 
94f0: 66 69 6c 65 20 64 65 73 63 72 69 70 74 6f 72 2e  file descriptor.
9500: 20 4f 72 2c 20 69 66 20 74 68 65 20 78 53 79 6e   Or, if the xSyn
9510: 63 20 6d 65 74 68 6f 64 20 69 73 20 6e 6f 74 20  c method is not 
9520: 69 6e 76 6f 6b 65 64 20 0a 2a 2a 20 62 65 63 61  invoked .** beca
9530: 75 73 65 20 74 68 65 20 75 73 65 72 20 68 61 73  use the user has
9540: 20 63 6f 6e 66 69 67 75 72 65 64 20 53 51 4c 69   configured SQLi
9550: 74 65 20 77 69 74 68 20 0a 2a 2a 20 5b 50 52 41  te with .** [PRA
9560: 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 20  GMA synchronous 
9570: 7c 20 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f  | PRAGMA synchro
9580: 6e 6f 75 73 3d 4f 46 46 5d 20 69 74 20 69 73 20  nous=OFF] it is 
9590: 69 6e 76 6f 6b 65 64 20 69 6e 20 70 6c 61 63 65  invoked in place
95a0: 20 0a 2a 2a 20 6f 66 20 74 68 65 20 78 53 79 6e   .** of the xSyn
95b0: 63 20 6d 65 74 68 6f 64 2e 20 49 6e 20 6d 6f 73  c method. In mos
95c0: 74 20 63 61 73 65 73 2c 20 74 68 65 20 70 6f 69  t cases, the poi
95d0: 6e 74 65 72 20 61 72 67 75 6d 65 6e 74 20 70 61  nter argument pa
95e0: 73 73 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 69  ssed with.** thi
95f0: 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69  s file-control i
9600: 73 20 4e 55 4c 4c 2e 20 48 6f 77 65 76 65 72 2c  s NULL. However,
9610: 20 69 66 20 74 68 65 20 64 61 74 61 62 61 73 65   if the database
9620: 20 66 69 6c 65 20 69 73 20 62 65 69 6e 67 20 73   file is being s
9630: 79 6e 63 65 64 0a 2a 2a 20 61 73 20 70 61 72 74  ynced.** as part
9640: 20 6f 66 20 61 20 6d 75 6c 74 69 2d 64 61 74 61   of a multi-data
9650: 62 61 73 65 20 63 6f 6d 6d 69 74 2c 20 74 68 65  base commit, the
9660: 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 73   argument points
9670: 20 74 6f 20 61 20 6e 75 6c 2d 74 65 72 6d 69 6e   to a nul-termin
9680: 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 63  ated.** string c
9690: 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 74 72  ontaining the tr
96a0: 61 6e 73 61 63 74 69 6f 6e 73 20 6d 61 73 74 65  ansactions maste
96b0: 72 2d 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 6e  r-journal file n
96c0: 61 6d 65 2e 20 56 46 53 65 73 20 74 68 61 74 20  ame. VFSes that 
96d0: 0a 2a 2a 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20  .** do not need 
96e0: 74 68 69 73 20 73 69 67 6e 61 6c 20 73 68 6f 75  this signal shou
96f0: 6c 64 20 73 69 6c 65 6e 74 6c 79 20 69 67 6e 6f  ld silently igno
9700: 72 65 20 74 68 69 73 20 6f 70 63 6f 64 65 2e 20  re this opcode. 
9710: 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 0a 2a 2a  Applications .**
9720: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 63 61 6c 6c   should not call
9730: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63   [sqlite3_file_c
9740: 6f 6e 74 72 6f 6c 28 29 5d 20 77 69 74 68 20 74  ontrol()] with t
9750: 68 69 73 20 6f 70 63 6f 64 65 20 61 73 20 64 6f  his opcode as do
9760: 69 6e 67 20 73 6f 20 6d 61 79 20 0a 2a 2a 20 64  ing so may .** d
9770: 69 73 72 75 70 74 20 74 68 65 20 6f 70 65 72 61  isrupt the opera
9780: 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 70 65 63  tion of the spec
9790: 69 61 6c 69 7a 65 64 20 56 46 53 65 73 20 74 68  ialized VFSes th
97a0: 61 74 20 64 6f 20 72 65 71 75 69 72 65 20 69 74  at do require it
97b0: 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  .  .**.** <li>[[
97c0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d  SQLITE_FCNTL_COM
97d0: 4d 49 54 5f 50 48 41 53 45 54 57 4f 5d 5d 0a 2a  MIT_PHASETWO]].*
97e0: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  * The [SQLITE_FC
97f0: 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41 53 45  NTL_COMMIT_PHASE
9800: 54 57 4f 5d 20 6f 70 63 6f 64 65 20 69 73 20 67  TWO] opcode is g
9810: 65 6e 65 72 61 74 65 64 20 69 6e 74 65 72 6e 61  enerated interna
9820: 6c 6c 79 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a  lly by SQLite.**
9830: 20 61 6e 64 20 73 65 6e 74 20 74 6f 20 74 68 65   and sent to the
9840: 20 56 46 53 20 61 66 74 65 72 20 61 20 74 72 61   VFS after a tra
9850: 6e 73 61 63 74 69 6f 6e 20 68 61 73 20 62 65 65  nsaction has bee
9860: 6e 20 63 6f 6d 6d 69 74 74 65 64 20 69 6d 6d 65  n committed imme
9870: 64 69 61 74 65 6c 79 0a 2a 2a 20 62 75 74 20 62  diately.** but b
9880: 65 66 6f 72 65 20 74 68 65 20 64 61 74 61 62 61  efore the databa
9890: 73 65 20 69 73 20 75 6e 6c 6f 63 6b 65 64 2e 20  se is unlocked. 
98a0: 56 46 53 65 73 20 74 68 61 74 20 64 6f 20 6e 6f  VFSes that do no
98b0: 74 20 6e 65 65 64 20 74 68 69 73 20 73 69 67 6e  t need this sign
98c0: 61 6c 0a 2a 2a 20 73 68 6f 75 6c 64 20 73 69 6c  al.** should sil
98d0: 65 6e 74 6c 79 20 69 67 6e 6f 72 65 20 74 68 69  ently ignore thi
98e0: 73 20 6f 70 63 6f 64 65 2e 20 41 70 70 6c 69 63  s opcode. Applic
98f0: 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 6e 6f  ations should no
9900: 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74  t call.** [sqlit
9910: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
9920: 29 5d 20 77 69 74 68 20 74 68 69 73 20 6f 70 63  )] with this opc
9930: 6f 64 65 20 61 73 20 64 6f 69 6e 67 20 73 6f 20  ode as doing so 
9940: 6d 61 79 20 64 69 73 72 75 70 74 20 74 68 65 20  may disrupt the 
9950: 0a 2a 2a 20 6f 70 65 72 61 74 69 6f 6e 20 6f 66  .** operation of
9960: 20 74 68 65 20 73 70 65 63 69 61 6c 69 7a 65 64   the specialized
9970: 20 56 46 53 65 73 20 74 68 61 74 20 64 6f 20 72   VFSes that do r
9980: 65 71 75 69 72 65 20 69 74 2e 20 20 0a 2a 2a 0a  equire it.  .**.
9990: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
99a0: 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52  FCNTL_WIN32_AV_R
99b0: 45 54 52 59 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b  ETRY]].** ^The [
99c0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e  SQLITE_FCNTL_WIN
99d0: 33 32 5f 41 56 5f 52 45 54 52 59 5d 20 6f 70 63  32_AV_RETRY] opc
99e0: 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 63  ode is used to c
99f0: 6f 6e 66 69 67 75 72 65 20 61 75 74 6f 6d 61 74  onfigure automat
9a00: 69 63 0a 2a 2a 20 72 65 74 72 79 20 63 6f 75 6e  ic.** retry coun
9a10: 74 73 20 61 6e 64 20 69 6e 74 65 72 76 61 6c 73  ts and intervals
9a20: 20 66 6f 72 20 63 65 72 74 61 69 6e 20 64 69 73   for certain dis
9a30: 6b 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73  k I/O operations
9a40: 20 66 6f 72 20 74 68 65 0a 2a 2a 20 77 69 6e 64   for the.** wind
9a50: 6f 77 73 20 5b 56 46 53 5d 20 69 6e 20 6f 72 64  ows [VFS] in ord
9a60: 65 72 20 74 6f 20 70 72 6f 76 69 64 65 20 72 6f  er to provide ro
9a70: 62 75 73 74 6e 65 73 73 20 69 6e 20 74 68 65 20  bustness in the 
9a80: 70 72 65 73 65 6e 63 65 20 6f 66 0a 2a 2a 20 61  presence of.** a
9a90: 6e 74 69 2d 76 69 72 75 73 20 70 72 6f 67 72 61  nti-virus progra
9aa0: 6d 73 2e 20 20 42 79 20 64 65 66 61 75 6c 74 2c  ms.  By default,
9ab0: 20 74 68 65 20 77 69 6e 64 6f 77 73 20 56 46 53   the windows VFS
9ac0: 20 77 69 6c 6c 20 72 65 74 72 79 20 66 69 6c 65   will retry file
9ad0: 20 72 65 61 64 2c 0a 2a 2a 20 66 69 6c 65 20 77   read,.** file w
9ae0: 72 69 74 65 2c 20 61 6e 64 20 66 69 6c 65 20 64  rite, and file d
9af0: 65 6c 65 74 65 20 6f 70 65 72 61 74 69 6f 6e 73  elete operations
9b00: 20 75 70 20 74 6f 20 31 30 20 74 69 6d 65 73 2c   up to 10 times,
9b10: 20 77 69 74 68 20 61 20 64 65 6c 61 79 0a 2a 2a   with a delay.**
9b20: 20 6f 66 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f   of 25 milliseco
9b30: 6e 64 73 20 62 65 66 6f 72 65 20 74 68 65 20 66  nds before the f
9b40: 69 72 73 74 20 72 65 74 72 79 20 61 6e 64 20 77  irst retry and w
9b50: 69 74 68 20 74 68 65 20 64 65 6c 61 79 20 69 6e  ith the delay in
9b60: 63 72 65 61 73 69 6e 67 0a 2a 2a 20 62 79 20 61  creasing.** by a
9b70: 6e 20 61 64 64 69 74 69 6f 6e 61 6c 20 32 35 20  n additional 25 
9b80: 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 77 69 74  milliseconds wit
9b90: 68 20 65 61 63 68 20 73 75 62 73 65 71 75 65 6e  h each subsequen
9ba0: 74 20 72 65 74 72 79 2e 20 20 54 68 69 73 0a 2a  t retry.  This.*
9bb0: 2a 20 6f 70 63 6f 64 65 20 61 6c 6c 6f 77 73 20  * opcode allows 
9bc0: 74 68 65 73 65 20 74 77 6f 20 76 61 6c 75 65 73  these two values
9bd0: 20 28 31 30 20 72 65 74 72 69 65 73 20 61 6e 64   (10 retries and
9be0: 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73   25 milliseconds
9bf0: 20 6f 66 20 64 65 6c 61 79 29 0a 2a 2a 20 74 6f   of delay).** to
9c00: 20 62 65 20 61 64 6a 75 73 74 65 64 2e 20 20 54   be adjusted.  T
9c10: 68 65 20 76 61 6c 75 65 73 20 61 72 65 20 63 68  he values are ch
9c20: 61 6e 67 65 64 20 66 6f 72 20 61 6c 6c 20 64 61  anged for all da
9c30: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
9c40: 6e 73 0a 2a 2a 20 77 69 74 68 69 6e 20 74 68 65  ns.** within the
9c50: 20 73 61 6d 65 20 70 72 6f 63 65 73 73 2e 20 20   same process.  
9c60: 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20  The argument is 
9c70: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
9c80: 61 72 72 61 79 20 6f 66 20 74 77 6f 0a 2a 2a 20  array of two.** 
9c90: 69 6e 74 65 67 65 72 73 20 77 68 65 72 65 20 74  integers where t
9ca0: 68 65 20 66 69 72 73 74 20 69 6e 74 65 67 65 72  he first integer
9cb0: 20 69 20 74 68 65 20 6e 65 77 20 72 65 74 72 79   i the new retry
9cc0: 20 63 6f 75 6e 74 20 61 6e 64 20 74 68 65 20 73   count and the s
9cd0: 65 63 6f 6e 64 0a 2a 2a 20 69 6e 74 65 67 65 72  econd.** integer
9ce0: 20 69 73 20 74 68 65 20 64 65 6c 61 79 2e 20 20   is the delay.  
9cf0: 49 66 20 65 69 74 68 65 72 20 69 6e 74 65 67 65  If either intege
9d00: 72 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74  r is negative, t
9d10: 68 65 6e 20 74 68 65 20 73 65 74 74 69 6e 67 0a  hen the setting.
9d20: 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65  ** is not change
9d30: 64 20 62 75 74 20 69 6e 73 74 65 61 64 20 74 68  d but instead th
9d40: 65 20 70 72 69 6f 72 20 76 61 6c 75 65 20 6f 66  e prior value of
9d50: 20 74 68 61 74 20 73 65 74 74 69 6e 67 20 69 73   that setting is
9d60: 20 77 72 69 74 74 65 6e 0a 2a 2a 20 69 6e 74 6f   written.** into
9d70: 20 74 68 65 20 61 72 72 61 79 20 65 6e 74 72 79   the array entry
9d80: 2c 20 61 6c 6c 6f 77 69 6e 67 20 74 68 65 20 63  , allowing the c
9d90: 75 72 72 65 6e 74 20 72 65 74 72 79 20 73 65 74  urrent retry set
9da0: 74 69 6e 67 73 20 74 6f 20 62 65 0a 2a 2a 20 69  tings to be.** i
9db0: 6e 74 65 72 72 6f 67 61 74 65 64 2e 20 20 54 68  nterrogated.  Th
9dc0: 65 20 7a 44 62 4e 61 6d 65 20 70 61 72 61 6d 65  e zDbName parame
9dd0: 74 65 72 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a  ter is ignored..
9de0: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
9df0: 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54  TE_FCNTL_PERSIST
9e00: 5f 57 41 4c 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b  _WAL]].** ^The [
9e10: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52  SQLITE_FCNTL_PER
9e20: 53 49 53 54 5f 57 41 4c 5d 20 6f 70 63 6f 64 65  SIST_WAL] opcode
9e30: 20 69 73 20 75 73 65 64 20 74 6f 20 73 65 74 20   is used to set 
9e40: 6f 72 20 71 75 65 72 79 20 74 68 65 0a 2a 2a 20  or query the.** 
9e50: 70 65 72 73 69 73 74 65 6e 74 20 5b 57 41 4c 20  persistent [WAL 
9e60: 7c 20 57 72 69 74 65 20 41 68 65 61 64 20 4c 6f  | Write Ahead Lo
9e70: 67 5d 20 73 65 74 74 69 6e 67 2e 20 20 42 79 20  g] setting.  By 
9e80: 64 65 66 61 75 6c 74 2c 20 74 68 65 20 61 75 78  default, the aux
9e90: 69 6c 69 61 72 79 0a 2a 2a 20 77 72 69 74 65 20  iliary.** write 
9ea0: 61 68 65 61 64 20 6c 6f 67 20 61 6e 64 20 73 68  ahead log and sh
9eb0: 61 72 65 64 20 6d 65 6d 6f 72 79 20 66 69 6c 65  ared memory file
9ec0: 73 20 75 73 65 64 20 66 6f 72 20 74 72 61 6e 73  s used for trans
9ed0: 61 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 0a 2a  action control.*
9ee0: 2a 20 61 72 65 20 61 75 74 6f 6d 61 74 69 63 61  * are automatica
9ef0: 6c 6c 79 20 64 65 6c 65 74 65 64 20 77 68 65 6e  lly deleted when
9f00: 20 74 68 65 20 6c 61 74 65 73 74 20 63 6f 6e 6e   the latest conn
9f10: 65 63 74 69 6f 6e 20 74 6f 20 74 68 65 20 64 61  ection to the da
9f20: 74 61 62 61 73 65 0a 2a 2a 20 63 6c 6f 73 65 73  tabase.** closes
9f30: 2e 20 20 53 65 74 74 69 6e 67 20 70 65 72 73 69  .  Setting persi
9f40: 73 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20 63  stent WAL mode c
9f50: 61 75 73 65 73 20 74 68 6f 73 65 20 66 69 6c 65  auses those file
9f60: 73 20 74 6f 20 70 65 72 73 69 73 74 20 61 66 74  s to persist aft
9f70: 65 72 0a 2a 2a 20 63 6c 6f 73 65 2e 20 20 50 65  er.** close.  Pe
9f80: 72 73 69 73 74 69 6e 67 20 74 68 65 20 66 69 6c  rsisting the fil
9f90: 65 73 20 69 73 20 75 73 65 66 75 6c 20 77 68 65  es is useful whe
9fa0: 6e 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73 65  n other processe
9fb0: 73 20 74 68 61 74 20 64 6f 20 6e 6f 74 0a 2a 2a  s that do not.**
9fc0: 20 68 61 76 65 20 77 72 69 74 65 20 70 65 72 6d   have write perm
9fd0: 69 73 73 69 6f 6e 20 6f 6e 20 74 68 65 20 64 69  ission on the di
9fe0: 72 65 63 74 6f 72 79 20 63 6f 6e 74 61 69 6e 69  rectory containi
9ff0: 6e 67 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ng the database 
a000: 66 69 6c 65 20 77 61 6e 74 0a 2a 2a 20 74 6f 20  file want.** to 
a010: 72 65 61 64 20 74 68 65 20 64 61 74 61 62 61 73  read the databas
a020: 65 20 66 69 6c 65 2c 20 61 73 20 74 68 65 20 57  e file, as the W
a030: 41 4c 20 61 6e 64 20 73 68 61 72 65 64 20 6d 65  AL and shared me
a040: 6d 6f 72 79 20 66 69 6c 65 73 20 6d 75 73 74 20  mory files must 
a050: 65 78 69 73 74 0a 2a 2a 20 69 6e 20 6f 72 64 65  exist.** in orde
a060: 72 20 66 6f 72 20 74 68 65 20 64 61 74 61 62 61  r for the databa
a070: 73 65 20 74 6f 20 62 65 20 72 65 61 64 61 62 6c  se to be readabl
a080: 65 2e 20 20 54 68 65 20 66 6f 75 72 74 68 20 70  e.  The fourth p
a090: 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b  arameter to.** [
a0a0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
a0b0: 74 72 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69 73  trol()] for this
a0c0: 20 6f 70 63 6f 64 65 20 73 68 6f 75 6c 64 20 62   opcode should b
a0d0: 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  e a pointer to a
a0e0: 6e 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54 68  n integer..** Th
a0f0: 61 74 20 69 6e 74 65 67 65 72 20 69 73 20 30 20  at integer is 0 
a100: 74 6f 20 64 69 73 61 62 6c 65 20 70 65 72 73 69  to disable persi
a110: 73 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20 6f  stent WAL mode o
a120: 72 20 31 20 74 6f 20 65 6e 61 62 6c 65 20 70 65  r 1 to enable pe
a130: 72 73 69 73 74 65 6e 74 0a 2a 2a 20 57 41 4c 20  rsistent.** WAL 
a140: 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20 69 6e  mode.  If the in
a150: 74 65 67 65 72 20 69 73 20 2d 31 2c 20 74 68 65  teger is -1, the
a160: 6e 20 69 74 20 69 73 20 6f 76 65 72 77 72 69 74  n it is overwrit
a170: 74 65 6e 20 77 69 74 68 20 74 68 65 20 63 75 72  ten with the cur
a180: 72 65 6e 74 0a 2a 2a 20 57 41 4c 20 70 65 72 73  rent.** WAL pers
a190: 69 73 74 65 6e 63 65 20 73 65 74 74 69 6e 67 2e  istence setting.
a1a0: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
a1b0: 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53  ITE_FCNTL_POWERS
a1c0: 41 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 5d 0a  AFE_OVERWRITE]].
a1d0: 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  ** ^The [SQLITE_
a1e0: 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f  FCNTL_POWERSAFE_
a1f0: 4f 56 45 52 57 52 49 54 45 5d 20 6f 70 63 6f 64  OVERWRITE] opcod
a200: 65 20 69 73 20 75 73 65 64 20 74 6f 20 73 65 74  e is used to set
a210: 20 6f 72 20 71 75 65 72 79 20 74 68 65 0a 2a 2a   or query the.**
a220: 20 70 65 72 73 69 73 74 65 6e 74 20 22 70 6f 77   persistent "pow
a230: 65 72 73 61 66 65 2d 6f 76 65 72 77 72 69 74 65  ersafe-overwrite
a240: 22 20 6f 72 20 22 50 53 4f 57 22 20 73 65 74 74  " or "PSOW" sett
a250: 69 6e 67 2e 20 20 54 68 65 20 50 53 4f 57 20 73  ing.  The PSOW s
a260: 65 74 74 69 6e 67 0a 2a 2a 20 64 65 74 65 72 6d  etting.** determ
a270: 69 6e 65 73 20 74 68 65 20 5b 53 51 4c 49 54 45  ines the [SQLITE
a280: 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45  _IOCAP_POWERSAFE
a290: 5f 4f 56 45 52 57 52 49 54 45 5d 20 62 69 74 20  _OVERWRITE] bit 
a2a0: 6f 66 20 74 68 65 0a 2a 2a 20 78 44 65 76 69 63  of the.** xDevic
a2b0: 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73  eCharacteristics
a2c0: 20 6d 65 74 68 6f 64 73 2e 20 54 68 65 20 66 6f   methods. The fo
a2d0: 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74  urth parameter t
a2e0: 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69  o.** [sqlite3_fi
a2f0: 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 66 6f  le_control()] fo
a300: 72 20 74 68 69 73 20 6f 70 63 6f 64 65 20 73 68  r this opcode sh
a310: 6f 75 6c 64 20 62 65 20 61 20 70 6f 69 6e 74 65  ould be a pointe
a320: 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 2e  r to an integer.
a330: 0a 2a 2a 20 54 68 61 74 20 69 6e 74 65 67 65 72  .** That integer
a340: 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65   is 0 to disable
a350: 20 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d 6f 64   zero-damage mod
a360: 65 20 6f 72 20 31 20 74 6f 20 65 6e 61 62 6c 65  e or 1 to enable
a370: 20 7a 65 72 6f 2d 64 61 6d 61 67 65 0a 2a 2a 20   zero-damage.** 
a380: 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20 69 6e  mode.  If the in
a390: 74 65 67 65 72 20 69 73 20 2d 31 2c 20 74 68 65  teger is -1, the
a3a0: 6e 20 69 74 20 69 73 20 6f 76 65 72 77 72 69 74  n it is overwrit
a3b0: 74 65 6e 20 77 69 74 68 20 74 68 65 20 63 75 72  ten with the cur
a3c0: 72 65 6e 74 0a 2a 2a 20 7a 65 72 6f 2d 64 61 6d  rent.** zero-dam
a3d0: 61 67 65 20 6d 6f 64 65 20 73 65 74 74 69 6e 67  age mode setting
a3e0: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
a3f0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57  LITE_FCNTL_OVERW
a400: 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b  RITE]].** ^The [
a410: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45  SQLITE_FCNTL_OVE
a420: 52 57 52 49 54 45 5d 20 6f 70 63 6f 64 65 20 69  RWRITE] opcode i
a430: 73 20 69 6e 76 6f 6b 65 64 20 62 79 20 53 51 4c  s invoked by SQL
a440: 69 74 65 20 61 66 74 65 72 20 6f 70 65 6e 69 6e  ite after openin
a450: 67 0a 2a 2a 20 61 20 77 72 69 74 65 20 74 72 61  g.** a write tra
a460: 6e 73 61 63 74 69 6f 6e 20 74 6f 20 69 6e 64 69  nsaction to indi
a470: 63 61 74 65 20 74 68 61 74 2c 20 75 6e 6c 65 73  cate that, unles
a480: 73 20 69 74 20 69 73 20 72 6f 6c 6c 65 64 20 62  s it is rolled b
a490: 61 63 6b 20 66 6f 72 20 73 6f 6d 65 0a 2a 2a 20  ack for some.** 
a4a0: 72 65 61 73 6f 6e 2c 20 74 68 65 20 65 6e 74 69  reason, the enti
a4b0: 72 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  re database file
a4c0: 20 77 69 6c 6c 20 62 65 20 6f 76 65 72 77 72 69   will be overwri
a4d0: 74 74 65 6e 20 62 79 20 74 68 65 20 63 75 72 72  tten by the curr
a4e0: 65 6e 74 20 0a 2a 2a 20 74 72 61 6e 73 61 63 74  ent .** transact
a4f0: 69 6f 6e 2e 20 54 68 69 73 20 69 73 20 75 73 65  ion. This is use
a500: 64 20 62 79 20 56 41 43 55 55 4d 20 6f 70 65 72  d by VACUUM oper
a510: 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  ations..**.** <l
a520: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
a530: 5f 56 46 53 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 54  _VFSNAME]].** ^T
a540: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
a550: 5f 56 46 53 4e 41 4d 45 5d 20 6f 70 63 6f 64 65  _VFSNAME] opcode
a560: 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
a570: 6f 62 74 61 69 6e 20 74 68 65 20 6e 61 6d 65 73  obtain the names
a580: 20 6f 66 0a 2a 2a 20 61 6c 6c 20 5b 56 46 53 65   of.** all [VFSe
a590: 73 5d 20 69 6e 20 74 68 65 20 56 46 53 20 73 74  s] in the VFS st
a5a0: 61 63 6b 2e 20 20 54 68 65 20 6e 61 6d 65 73 20  ack.  The names 
a5b0: 61 72 65 20 6f 66 20 61 6c 6c 20 56 46 53 20 73  are of all VFS s
a5c0: 68 69 6d 73 20 61 6e 64 20 74 68 65 0a 2a 2a 20  hims and the.** 
a5d0: 66 69 6e 61 6c 20 62 6f 74 74 6f 6d 2d 6c 65 76  final bottom-lev
a5e0: 65 6c 20 56 46 53 20 61 72 65 20 77 72 69 74 74  el VFS are writt
a5f0: 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f  en into memory o
a600: 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a  btained from .**
a610: 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
a620: 28 29 5d 20 61 6e 64 20 74 68 65 20 72 65 73 75  ()] and the resu
a630: 6c 74 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20  lt is stored in 
a640: 74 68 65 20 63 68 61 72 2a 20 76 61 72 69 61 62  the char* variab
a650: 6c 65 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 66  le.** that the f
a660: 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
a670: 6f 66 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  of [sqlite3_file
a680: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 70 6f 69 6e  _control()] poin
a690: 74 73 20 74 6f 2e 0a 2a 2a 20 54 68 65 20 63 61  ts to..** The ca
a6a0: 6c 6c 65 72 20 69 73 20 72 65 73 70 6f 6e 73 69  ller is responsi
a6b0: 62 6c 65 20 66 6f 72 20 66 72 65 65 69 6e 67 20  ble for freeing 
a6c0: 74 68 65 20 6d 65 6d 6f 72 79 20 77 68 65 6e 20  the memory when 
a6d0: 64 6f 6e 65 2e 20 20 41 73 20 77 69 74 68 0a 2a  done.  As with.*
a6e0: 2a 20 61 6c 6c 20 66 69 6c 65 2d 63 6f 6e 74 72  * all file-contr
a6f0: 6f 6c 20 61 63 74 69 6f 6e 73 2c 20 74 68 65 72  ol actions, ther
a700: 65 20 69 73 20 6e 6f 20 67 75 61 72 61 6e 74 65  e is no guarante
a710: 65 20 74 68 61 74 20 74 68 69 73 20 77 69 6c 6c  e that this will
a720: 20 61 63 74 75 61 6c 6c 79 0a 2a 2a 20 64 6f 20   actually.** do 
a730: 61 6e 79 74 68 69 6e 67 2e 20 20 43 61 6c 6c 65  anything.  Calle
a740: 72 73 20 73 68 6f 75 6c 64 20 69 6e 69 74 69 61  rs should initia
a750: 6c 69 7a 65 20 74 68 65 20 63 68 61 72 2a 20 76  lize the char* v
a760: 61 72 69 61 62 6c 65 20 74 6f 20 61 20 4e 55 4c  ariable to a NUL
a770: 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e 20  L.** pointer in 
a780: 63 61 73 65 20 74 68 69 73 20 66 69 6c 65 2d 63  case this file-c
a790: 6f 6e 74 72 6f 6c 20 69 73 20 6e 6f 74 20 69 6d  ontrol is not im
a7a0: 70 6c 65 6d 65 6e 74 65 64 2e 20 20 54 68 69 73  plemented.  This
a7b0: 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a   file-control.**
a7c0: 20 69 73 20 69 6e 74 65 6e 64 65 64 20 66 6f 72   is intended for
a7d0: 20 64 69 61 67 6e 6f 73 74 69 63 20 75 73 65 20   diagnostic use 
a7e0: 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  only..**.** <li>
a7f0: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56  [[SQLITE_FCNTL_V
a800: 46 53 5f 50 4f 49 4e 54 45 52 5d 5d 0a 2a 2a 20  FS_POINTER]].** 
a810: 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e  ^The [SQLITE_FCN
a820: 54 4c 5f 56 46 53 5f 50 4f 49 4e 54 45 52 5d 20  TL_VFS_POINTER] 
a830: 6f 70 63 6f 64 65 20 66 69 6e 64 73 20 61 20 70  opcode finds a p
a840: 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 74 6f  ointer to the to
a850: 70 2d 6c 65 76 65 6c 0a 2a 2a 20 5b 56 46 53 65  p-level.** [VFSe
a860: 73 5d 20 63 75 72 72 65 6e 74 6c 79 20 69 6e 20  s] currently in 
a870: 75 73 65 2e 20 20 5e 28 54 68 65 20 61 72 67 75  use.  ^(The argu
a880: 6d 65 6e 74 20 58 20 69 6e 0a 2a 2a 20 73 71 6c  ment X in.** sql
a890: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f  ite3_file_contro
a8a0: 6c 28 64 62 2c 53 51 4c 49 54 45 5f 46 43 4e 54  l(db,SQLITE_FCNT
a8b0: 4c 5f 56 46 53 5f 50 4f 49 4e 54 45 52 2c 58 29  L_VFS_POINTER,X)
a8c0: 20 6d 75 73 74 20 62 65 0a 2a 2a 20 6f 66 20 74   must be.** of t
a8d0: 79 70 65 20 22 5b 73 71 6c 69 74 65 33 5f 76 66  ype "[sqlite3_vf
a8e0: 73 5d 20 2a 2a 22 2e 20 20 54 68 69 73 20 6f 70  s] **".  This op
a8f0: 63 6f 64 65 73 20 77 69 6c 6c 20 73 65 74 20 2a  codes will set *
a900: 58 0a 2a 2a 20 74 6f 20 61 20 70 6f 69 6e 74 65  X.** to a pointe
a910: 72 20 74 6f 20 74 68 65 20 74 6f 70 2d 6c 65 76  r to the top-lev
a920: 65 6c 20 56 46 53 2e 29 5e 0a 2a 2a 20 5e 57 68  el VFS.)^.** ^Wh
a930: 65 6e 20 74 68 65 72 65 20 61 72 65 20 6d 75 6c  en there are mul
a940: 74 69 70 6c 65 20 56 46 53 20 73 68 69 6d 73 20  tiple VFS shims 
a950: 69 6e 20 74 68 65 20 73 74 61 63 6b 2c 20 74 68  in the stack, th
a960: 69 73 20 6f 70 63 6f 64 65 20 66 69 6e 64 73 20  is opcode finds 
a970: 74 68 65 0a 2a 2a 20 75 70 70 65 72 2d 6d 6f 73  the.** upper-mos
a980: 74 20 73 68 69 6d 20 6f 6e 6c 79 2e 0a 2a 2a 0a  t shim only..**.
a990: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
a9a0: 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 5d 0a 2a  FCNTL_PRAGMA]].*
a9b0: 2a 20 5e 57 68 65 6e 65 76 65 72 20 61 20 5b 50  * ^Whenever a [P
a9c0: 52 41 47 4d 41 5d 20 73 74 61 74 65 6d 65 6e 74  RAGMA] statement
a9d0: 20 69 73 20 70 61 72 73 65 64 2c 20 61 6e 20 5b   is parsed, an [
a9e0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41  SQLITE_FCNTL_PRA
a9f0: 47 4d 41 5d 20 0a 2a 2a 20 66 69 6c 65 20 63 6f  GMA] .** file co
aa00: 6e 74 72 6f 6c 20 69 73 20 73 65 6e 74 20 74 6f  ntrol is sent to
aa10: 20 74 68 65 20 6f 70 65 6e 20 5b 73 71 6c 69 74   the open [sqlit
aa20: 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20  e3_file] object 
aa30: 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a  corresponding.**
aa40: 20 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65   to the database
aa50: 20 66 69 6c 65 20 74 6f 20 77 68 69 63 68 20 74   file to which t
aa60: 68 65 20 70 72 61 67 6d 61 20 73 74 61 74 65 6d  he pragma statem
aa70: 65 6e 74 20 72 65 66 65 72 73 2e 20 5e 54 68 65  ent refers. ^The
aa80: 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20   argument.** to 
aa90: 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  the [SQLITE_FCNT
aaa0: 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63  L_PRAGMA] file c
aab0: 6f 6e 74 72 6f 6c 20 69 73 20 61 6e 20 61 72 72  ontrol is an arr
aac0: 61 79 20 6f 66 0a 2a 2a 20 70 6f 69 6e 74 65 72  ay of.** pointer
aad0: 73 20 74 6f 20 73 74 72 69 6e 67 73 20 28 63 68  s to strings (ch
aae0: 61 72 2a 2a 29 20 69 6e 20 77 68 69 63 68 20 74  ar**) in which t
aaf0: 68 65 20 73 65 63 6f 6e 64 20 65 6c 65 6d 65 6e  he second elemen
ab00: 74 20 6f 66 20 74 68 65 20 61 72 72 61 79 0a 2a  t of the array.*
ab10: 2a 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  * is the name of
ab20: 20 74 68 65 20 70 72 61 67 6d 61 20 61 6e 64 20   the pragma and 
ab30: 74 68 65 20 74 68 69 72 64 20 65 6c 65 6d 65 6e  the third elemen
ab40: 74 20 69 73 20 74 68 65 20 61 72 67 75 6d 65 6e  t is the argumen
ab50: 74 20 74 6f 20 74 68 65 0a 2a 2a 20 70 72 61 67  t to the.** prag
ab60: 6d 61 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68  ma or NULL if th
ab70: 65 20 70 72 61 67 6d 61 20 68 61 73 20 6e 6f 20  e pragma has no 
ab80: 61 72 67 75 6d 65 6e 74 2e 20 20 5e 54 68 65 20  argument.  ^The 
ab90: 68 61 6e 64 6c 65 72 20 66 6f 72 20 61 6e 0a 2a  handler for an.*
aba0: 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  * [SQLITE_FCNTL_
abb0: 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e  PRAGMA] file con
abc0: 74 72 6f 6c 20 63 61 6e 20 6f 70 74 69 6f 6e 61  trol can optiona
abd0: 6c 6c 79 20 6d 61 6b 65 20 74 68 65 20 66 69 72  lly make the fir
abe0: 73 74 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20 6f 66  st element.** of
abf0: 20 74 68 65 20 63 68 61 72 2a 2a 20 61 72 67 75   the char** argu
ac00: 6d 65 6e 74 20 70 6f 69 6e 74 20 74 6f 20 61 20  ment point to a 
ac10: 73 74 72 69 6e 67 20 6f 62 74 61 69 6e 65 64 20  string obtained 
ac20: 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 70  from [sqlite3_mp
ac30: 72 69 6e 74 66 28 29 5d 0a 2a 2a 20 6f 72 20 74  rintf()].** or t
ac40: 68 65 20 65 71 75 69 76 61 6c 65 6e 74 20 61 6e  he equivalent an
ac50: 64 20 74 68 61 74 20 73 74 72 69 6e 67 20 77 69  d that string wi
ac60: 6c 6c 20 62 65 63 6f 6d 65 20 74 68 65 20 72 65  ll become the re
ac70: 73 75 6c 74 20 6f 66 20 74 68 65 20 70 72 61 67  sult of the prag
ac80: 6d 61 20 6f 72 0a 2a 2a 20 74 68 65 20 65 72 72  ma or.** the err
ac90: 6f 72 20 6d 65 73 73 61 67 65 20 69 66 20 74 68  or message if th
aca0: 65 20 70 72 61 67 6d 61 20 66 61 69 6c 73 2e 20  e pragma fails. 
acb0: 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  ^If the.** [SQLI
acc0: 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d  TE_FCNTL_PRAGMA]
acd0: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65   file control re
ace0: 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4e 4f  turns [SQLITE_NO
acf0: 54 46 4f 55 4e 44 5d 2c 20 74 68 65 6e 20 6e 6f  TFOUND], then no
ad00: 72 6d 61 6c 20 0a 2a 2a 20 5b 50 52 41 47 4d 41  rmal .** [PRAGMA
ad10: 5d 20 70 72 6f 63 65 73 73 69 6e 67 20 63 6f 6e  ] processing con
ad20: 74 69 6e 75 65 73 2e 20 20 5e 49 66 20 74 68 65  tinues.  ^If the
ad30: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50   [SQLITE_FCNTL_P
ad40: 52 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20 63  RAGMA].** file c
ad50: 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 20 5b  ontrol returns [
ad60: 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 65 6e  SQLITE_OK], then
ad70: 20 74 68 65 20 70 61 72 73 65 72 20 61 73 73 75   the parser assu
ad80: 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20  mes that the.** 
ad90: 56 46 53 20 68 61 73 20 68 61 6e 64 6c 65 64 20  VFS has handled 
ada0: 74 68 65 20 50 52 41 47 4d 41 20 69 74 73 65 6c  the PRAGMA itsel
adb0: 66 20 61 6e 64 20 74 68 65 20 70 61 72 73 65 72  f and the parser
adc0: 20 67 65 6e 65 72 61 74 65 73 20 61 20 6e 6f 2d   generates a no-
add0: 6f 70 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 73  op.** prepared s
ade0: 74 61 74 65 6d 65 6e 74 20 69 66 20 72 65 73 75  tatement if resu
adf0: 6c 74 20 73 74 72 69 6e 67 20 69 73 20 4e 55 4c  lt string is NUL
ae00: 4c 2c 20 6f 72 20 74 68 61 74 20 72 65 74 75 72  L, or that retur
ae10: 6e 73 20 61 20 63 6f 70 79 0a 2a 2a 20 6f 66 20  ns a copy.** of 
ae20: 74 68 65 20 72 65 73 75 6c 74 20 73 74 72 69 6e  the result strin
ae30: 67 20 69 66 20 74 68 65 20 73 74 72 69 6e 67 20  g if the string 
ae40: 69 73 20 6e 6f 6e 2d 4e 55 4c 4c 2e 0a 2a 2a 20  is non-NULL..** 
ae50: 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ^If the [SQLITE_
ae60: 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69  FCNTL_PRAGMA] fi
ae70: 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72  le control retur
ae80: 6e 73 0a 2a 2a 20 61 6e 79 20 72 65 73 75 6c 74  ns.** any result
ae90: 20 63 6f 64 65 20 6f 74 68 65 72 20 74 68 61 6e   code other than
aea0: 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20   [SQLITE_OK] or 
aeb0: 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44  [SQLITE_NOTFOUND
aec0: 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73 0a 2a 2a  ], that means.**
aed0: 20 74 68 61 74 20 74 68 65 20 56 46 53 20 65 6e   that the VFS en
aee0: 63 6f 75 6e 74 65 72 65 64 20 61 6e 20 65 72 72  countered an err
aef0: 6f 72 20 77 68 69 6c 65 20 68 61 6e 64 6c 69 6e  or while handlin
af00: 67 20 74 68 65 20 5b 50 52 41 47 4d 41 5d 20 61  g the [PRAGMA] a
af10: 6e 64 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 69 6c  nd the.** compil
af20: 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 50 52 41  ation of the PRA
af30: 47 4d 41 20 66 61 69 6c 73 20 77 69 74 68 20 61  GMA fails with a
af40: 6e 20 65 72 72 6f 72 2e 20 20 5e 54 68 65 20 5b  n error.  ^The [
af50: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41  SQLITE_FCNTL_PRA
af60: 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e  GMA].** file con
af70: 74 72 6f 6c 20 6f 63 63 75 72 73 20 61 74 20 74  trol occurs at t
af80: 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20  he beginning of 
af90: 70 72 61 67 6d 61 20 73 74 61 74 65 6d 65 6e 74  pragma statement
afa0: 20 61 6e 61 6c 79 73 69 73 20 61 6e 64 20 73 6f   analysis and so
afb0: 0a 2a 2a 20 69 74 20 69 73 20 61 62 6c 65 20 74  .** it is able t
afc0: 6f 20 6f 76 65 72 72 69 64 65 20 62 75 69 6c 74  o override built
afd0: 2d 69 6e 20 5b 50 52 41 47 4d 41 5d 20 73 74 61  -in [PRAGMA] sta
afe0: 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 3c  tements..**.** <
aff0: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
b000: 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52 5d 5d 0a  L_BUSYHANDLER]].
b010: 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  ** ^The [SQLITE_
b020: 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45  FCNTL_BUSYHANDLE
b030: 52 5d 0a 2a 2a 20 66 69 6c 65 2d 63 6f 6e 74 72  R].** file-contr
b040: 6f 6c 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65  ol may be invoke
b050: 64 20 62 79 20 53 51 4c 69 74 65 20 6f 6e 20 74  d by SQLite on t
b060: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
b070: 20 68 61 6e 64 6c 65 0a 2a 2a 20 73 68 6f 72 74   handle.** short
b080: 6c 79 20 61 66 74 65 72 20 69 74 20 69 73 20 6f  ly after it is o
b090: 70 65 6e 65 64 20 69 6e 20 6f 72 64 65 72 20 74  pened in order t
b0a0: 6f 20 70 72 6f 76 69 64 65 20 61 20 63 75 73 74  o provide a cust
b0b0: 6f 6d 20 56 46 53 20 77 69 74 68 20 61 63 63 65  om VFS with acce
b0c0: 73 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63 6f 6e  ss.** to the con
b0d0: 6e 65 63 74 69 6f 6e 73 20 62 75 73 79 2d 68 61  nections busy-ha
b0e0: 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 2e 20  ndler callback. 
b0f0: 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20  The argument is 
b100: 6f 66 20 74 79 70 65 20 28 76 6f 69 64 20 2a 2a  of type (void **
b110: 29 0a 2a 2a 20 2d 20 61 6e 20 61 72 72 61 79 20  ).** - an array 
b120: 6f 66 20 74 77 6f 20 28 76 6f 69 64 20 2a 29 20  of two (void *) 
b130: 76 61 6c 75 65 73 2e 20 54 68 65 20 66 69 72 73  values. The firs
b140: 74 20 28 76 6f 69 64 20 2a 29 20 61 63 74 75 61  t (void *) actua
b150: 6c 6c 79 20 70 6f 69 6e 74 73 0a 2a 2a 20 74 6f  lly points.** to
b160: 20 61 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74   a function of t
b170: 79 70 65 20 28 69 6e 74 20 28 2a 29 28 76 6f 69  ype (int (*)(voi
b180: 64 20 2a 29 29 2e 20 49 6e 20 6f 72 64 65 72 20  d *)). In order 
b190: 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65 20 63 6f  to invoke the co
b1a0: 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 62 75 73  nnections.** bus
b1b0: 79 2d 68 61 6e 64 6c 65 72 2c 20 74 68 69 73 20  y-handler, this 
b1c0: 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20  function should 
b1d0: 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20  be invoked with 
b1e0: 74 68 65 20 73 65 63 6f 6e 64 20 28 76 6f 69 64  the second (void
b1f0: 20 2a 29 20 69 6e 0a 2a 2a 20 74 68 65 20 61 72   *) in.** the ar
b200: 72 61 79 20 61 73 20 74 68 65 20 6f 6e 6c 79 20  ray as the only 
b210: 61 72 67 75 6d 65 6e 74 2e 20 49 66 20 69 74 20  argument. If it 
b220: 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f  returns non-zero
b230: 2c 20 74 68 65 6e 20 74 68 65 20 6f 70 65 72 61  , then the opera
b240: 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62  tion.** should b
b250: 65 20 72 65 74 72 69 65 64 2e 20 49 66 20 69 74  e retried. If it
b260: 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2c 20 74   returns zero, t
b270: 68 65 20 63 75 73 74 6f 6d 20 56 46 53 20 73 68  he custom VFS sh
b280: 6f 75 6c 64 20 61 62 61 6e 64 6f 6e 20 74 68 65  ould abandon the
b290: 0a 2a 2a 20 63 75 72 72 65 6e 74 20 6f 70 65 72  .** current oper
b2a0: 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  ation..**.** <li
b2b0: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
b2c0: 54 45 4d 50 46 49 4c 45 4e 41 4d 45 5d 5d 0a 2a  TEMPFILENAME]].*
b2d0: 2a 20 5e 41 70 70 6c 69 63 61 74 69 6f 6e 20 63  * ^Application c
b2e0: 61 6e 20 69 6e 76 6f 6b 65 20 74 68 65 20 5b 53  an invoke the [S
b2f0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50  QLITE_FCNTL_TEMP
b300: 46 49 4c 45 4e 41 4d 45 5d 20 66 69 6c 65 2d 63  FILENAME] file-c
b310: 6f 6e 74 72 6f 6c 0a 2a 2a 20 74 6f 20 68 61 76  ontrol.** to hav
b320: 65 20 53 51 4c 69 74 65 20 67 65 6e 65 72 61 74  e SQLite generat
b330: 65 20 61 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79  e a.** temporary
b340: 20 66 69 6c 65 6e 61 6d 65 20 75 73 69 6e 67 20   filename using 
b350: 74 68 65 20 73 61 6d 65 20 61 6c 67 6f 72 69 74  the same algorit
b360: 68 6d 20 74 68 61 74 20 69 73 20 66 6f 6c 6c 6f  hm that is follo
b370: 77 65 64 20 74 6f 20 67 65 6e 65 72 61 74 65 0a  wed to generate.
b380: 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c  ** temporary fil
b390: 65 6e 61 6d 65 73 20 66 6f 72 20 54 45 4d 50 20  enames for TEMP 
b3a0: 74 61 62 6c 65 73 20 61 6e 64 20 6f 74 68 65 72  tables and other
b3b0: 20 69 6e 74 65 72 6e 61 6c 20 75 73 65 73 2e 20   internal uses. 
b3c0: 20 54 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74   The.** argument
b3d0: 20 73 68 6f 75 6c 64 20 62 65 20 61 20 63 68 61   should be a cha
b3e0: 72 2a 2a 20 77 68 69 63 68 20 77 69 6c 6c 20 62  r** which will b
b3f0: 65 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68  e filled with th
b400: 65 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 77 72  e filename.** wr
b410: 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72  itten into memor
b420: 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  y obtained from 
b430: 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
b440: 29 5d 2e 20 20 54 68 65 20 63 61 6c 6c 65 72 20  )].  The caller 
b450: 73 68 6f 75 6c 64 0a 2a 2a 20 69 6e 76 6f 6b 65  should.** invoke
b460: 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
b470: 5d 20 6f 6e 20 74 68 65 20 72 65 73 75 6c 74 20  ] on the result 
b480: 74 6f 20 61 76 6f 69 64 20 61 20 6d 65 6d 6f 72  to avoid a memor
b490: 79 20 6c 65 61 6b 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  y leak..**.** <l
b4a0: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
b4b0: 5f 4d 4d 41 50 5f 53 49 5a 45 5d 5d 0a 2a 2a 20  _MMAP_SIZE]].** 
b4c0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
b4d0: 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 66 69 6c  L_MMAP_SIZE] fil
b4e0: 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 75 73 65  e control is use
b4f0: 64 20 74 6f 20 71 75 65 72 79 20 6f 72 20 73 65  d to query or se
b500: 74 20 74 68 65 0a 2a 2a 20 6d 61 78 69 6d 75 6d  t the.** maximum
b510: 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
b520: 20 74 68 61 74 20 77 69 6c 6c 20 62 65 20 75 73   that will be us
b530: 65 64 20 66 6f 72 20 6d 65 6d 6f 72 79 2d 6d 61  ed for memory-ma
b540: 70 70 65 64 20 49 2f 4f 2e 0a 2a 2a 20 54 68 65  pped I/O..** The
b550: 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70   argument is a p
b560: 6f 69 6e 74 65 72 20 74 6f 20 61 20 76 61 6c 75  ointer to a valu
b570: 65 20 6f 66 20 74 79 70 65 20 73 71 6c 69 74 65  e of type sqlite
b580: 33 5f 69 6e 74 36 34 20 74 68 61 74 0a 2a 2a 20  3_int64 that.** 
b590: 69 73 20 61 6e 20 61 64 76 69 73 6f 72 79 20 6d  is an advisory m
b5a0: 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
b5b0: 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 66 69   bytes in the fi
b5c0: 6c 65 20 74 6f 20 6d 65 6d 6f 72 79 20 6d 61 70  le to memory map
b5d0: 2e 20 20 54 68 65 0a 2a 2a 20 70 6f 69 6e 74 65  .  The.** pointe
b5e0: 72 20 69 73 20 6f 76 65 72 77 72 69 74 74 65 6e  r is overwritten
b5f0: 20 77 69 74 68 20 74 68 65 20 6f 6c 64 20 76 61   with the old va
b600: 6c 75 65 2e 20 20 54 68 65 20 6c 69 6d 69 74 20  lue.  The limit 
b610: 69 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 20 69  is not changed i
b620: 66 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 6f  f.** the value o
b630: 72 69 67 69 6e 61 6c 6c 79 20 70 6f 69 6e 74 65  riginally pointe
b640: 64 20 74 6f 20 69 73 20 6e 65 67 61 74 69 76 65  d to is negative
b650: 2c 20 61 6e 64 20 73 6f 20 74 68 65 20 63 75 72  , and so the cur
b660: 72 65 6e 74 20 6c 69 6d 69 74 20 0a 2a 2a 20 63  rent limit .** c
b670: 61 6e 20 62 65 20 71 75 65 72 69 65 64 20 62 79  an be queried by
b680: 20 70 61 73 73 69 6e 67 20 69 6e 20 61 20 70 6f   passing in a po
b690: 69 6e 74 65 72 20 74 6f 20 61 20 6e 65 67 61 74  inter to a negat
b6a0: 69 76 65 20 6e 75 6d 62 65 72 2e 20 20 54 68 69  ive number.  Thi
b6b0: 73 0a 2a 2a 20 66 69 6c 65 2d 63 6f 6e 74 72 6f  s.** file-contro
b6c0: 6c 20 69 73 20 75 73 65 64 20 69 6e 74 65 72 6e  l is used intern
b6d0: 61 6c 6c 79 20 74 6f 20 69 6d 70 6c 65 6d 65 6e  ally to implemen
b6e0: 74 20 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73  t [PRAGMA mmap_s
b6f0: 69 7a 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  ize]..**.** <li>
b700: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54  [[SQLITE_FCNTL_T
b710: 52 41 43 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53  RACE]].** The [S
b720: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 52 41 43  QLITE_FCNTL_TRAC
b730: 45 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  E] file control 
b740: 70 72 6f 76 69 64 65 73 20 61 64 76 69 73 6f 72  provides advisor
b750: 79 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a  y information.**
b760: 20 74 6f 20 74 68 65 20 56 46 53 20 61 62 6f 75   to the VFS abou
b770: 74 20 77 68 61 74 20 74 68 65 20 68 69 67 68 65  t what the highe
b780: 72 20 6c 61 79 65 72 73 20 6f 66 20 74 68 65 20  r layers of the 
b790: 53 51 4c 69 74 65 20 73 74 61 63 6b 20 61 72 65  SQLite stack are
b7a0: 20 64 6f 69 6e 67 2e 0a 2a 2a 20 54 68 69 73 20   doing..** This 
b7b0: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20  file control is 
b7c0: 75 73 65 64 20 62 79 20 73 6f 6d 65 20 56 46 53  used by some VFS
b7d0: 20 61 63 74 69 76 69 74 79 20 74 72 61 63 69 6e   activity tracin
b7e0: 67 20 5b 73 68 69 6d 73 5d 2e 0a 2a 2a 20 54 68  g [shims]..** Th
b7f0: 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20  e argument is a 
b800: 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
b810: 73 74 72 69 6e 67 2e 20 20 48 69 67 68 65 72 20  string.  Higher 
b820: 6c 61 79 65 72 73 20 69 6e 20 74 68 65 0a 2a 2a  layers in the.**
b830: 20 53 51 4c 69 74 65 20 73 74 61 63 6b 20 6d 61   SQLite stack ma
b840: 79 20 67 65 6e 65 72 61 74 65 20 69 6e 73 74 61  y generate insta
b850: 6e 63 65 73 20 6f 66 20 74 68 69 73 20 66 69 6c  nces of this fil
b860: 65 20 63 6f 6e 74 72 6f 6c 20 69 66 0a 2a 2a 20  e control if.** 
b870: 74 68 65 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f  the [SQLITE_USE_
b880: 46 43 4e 54 4c 5f 54 52 41 43 45 5d 20 63 6f 6d  FCNTL_TRACE] com
b890: 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
b8a0: 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a   is enabled..**.
b8b0: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
b8c0: 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45 44 5d  FCNTL_HAS_MOVED]
b8d0: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ].** The [SQLITE
b8e0: 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45 44  _FCNTL_HAS_MOVED
b8f0: 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69  ] file control i
b900: 6e 74 65 72 70 72 65 74 73 20 69 74 73 20 61 72  nterprets its ar
b910: 67 75 6d 65 6e 74 20 61 73 20 61 0a 2a 2a 20 70  gument as a.** p
b920: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74  ointer to an int
b930: 65 67 65 72 20 61 6e 64 20 69 74 20 77 72 69 74  eger and it writ
b940: 65 73 20 61 20 62 6f 6f 6c 65 61 6e 20 69 6e 74  es a boolean int
b950: 6f 20 74 68 61 74 20 69 6e 74 65 67 65 72 20 64  o that integer d
b960: 65 70 65 6e 64 69 6e 67 0a 2a 2a 20 6f 6e 20 77  epending.** on w
b970: 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68  hether or not th
b980: 65 20 66 69 6c 65 20 68 61 73 20 62 65 65 6e 20  e file has been 
b990: 72 65 6e 61 6d 65 64 2c 20 6d 6f 76 65 64 2c 20  renamed, moved, 
b9a0: 6f 72 20 64 65 6c 65 74 65 64 20 73 69 6e 63 65  or deleted since
b9b0: 20 69 74 0a 2a 2a 20 77 61 73 20 66 69 72 73 74   it.** was first
b9c0: 20 6f 70 65 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c   opened..**.** <
b9d0: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
b9e0: 4c 5f 57 49 4e 33 32 5f 53 45 54 5f 48 41 4e 44  L_WIN32_SET_HAND
b9f0: 4c 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  LE]].** The [SQL
ba00: 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f  ITE_FCNTL_WIN32_
ba10: 53 45 54 5f 48 41 4e 44 4c 45 5d 20 6f 70 63 6f  SET_HANDLE] opco
ba20: 64 65 20 69 73 20 75 73 65 64 20 66 6f 72 20 64  de is used for d
ba30: 65 62 75 67 67 69 6e 67 2e 20 20 54 68 69 73 0a  ebugging.  This.
ba40: 2a 2a 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73  ** opcode causes
ba50: 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f   the xFileContro
ba60: 6c 20 6d 65 74 68 6f 64 20 74 6f 20 73 77 61 70  l method to swap
ba70: 20 74 68 65 20 66 69 6c 65 20 68 61 6e 64 6c 65   the file handle
ba80: 20 77 69 74 68 20 74 68 65 20 6f 6e 65 0a 2a 2a   with the one.**
ba90: 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74   pointed to by t
baa0: 68 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e 74  he pArg argument
bab0: 2e 20 20 54 68 69 73 20 63 61 70 61 62 69 6c 69  .  This capabili
bac0: 74 79 20 69 73 20 75 73 65 64 20 64 75 72 69 6e  ty is used durin
bad0: 67 20 74 65 73 74 69 6e 67 0a 2a 2a 20 61 6e 64  g testing.** and
bae0: 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20 62   only needs to b
baf0: 65 20 73 75 70 70 6f 72 74 65 64 20 77 68 65 6e  e supported when
bb00: 20 53 51 4c 49 54 45 5f 54 45 53 54 20 69 73 20   SQLITE_TEST is 
bb10: 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c  defined..**.** <
bb20: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
bb30: 4c 5f 57 41 4c 5f 42 4c 4f 43 4b 5d 5d 0a 2a 2a  L_WAL_BLOCK]].**
bb40: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
bb50: 54 4c 5f 57 41 4c 5f 42 4c 4f 43 4b 5d 20 69 73  TL_WAL_BLOCK] is
bb60: 20 61 20 73 69 67 6e 61 6c 20 74 6f 20 74 68 65   a signal to the
bb70: 20 56 46 53 20 6c 61 79 65 72 20 74 68 61 74 20   VFS layer that 
bb80: 69 74 20 6d 69 67 68 74 0a 2a 2a 20 62 65 20 61  it might.** be a
bb90: 64 76 61 6e 74 61 67 65 6f 75 73 20 74 6f 20 62  dvantageous to b
bba0: 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 6e 65 78 74  lock on the next
bbb0: 20 57 41 4c 20 6c 6f 63 6b 20 69 66 20 74 68 65   WAL lock if the
bbc0: 20 6c 6f 63 6b 20 69 73 20 6e 6f 74 20 69 6d 6d   lock is not imm
bbd0: 65 64 69 61 74 65 6c 79 0a 2a 2a 20 61 76 61 69  ediately.** avai
bbe0: 6c 61 62 6c 65 2e 20 20 54 68 65 20 57 41 4c 20  lable.  The WAL 
bbf0: 73 75 62 73 79 73 74 65 6d 20 69 73 73 75 65 73  subsystem issues
bc00: 20 74 68 69 73 20 73 69 67 6e 61 6c 20 64 75 72   this signal dur
bc10: 69 6e 67 20 72 61 72 65 0a 2a 2a 20 63 69 72 63  ing rare.** circ
bc20: 75 6d 73 74 61 6e 63 65 73 20 69 6e 20 6f 72 64  umstances in ord
bc30: 65 72 20 74 6f 20 66 69 78 20 61 20 70 72 6f 62  er to fix a prob
bc40: 6c 65 6d 20 77 69 74 68 20 70 72 69 6f 72 69 74  lem with priorit
bc50: 79 20 69 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 20  y inversion..** 
bc60: 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f  Applications sho
bc70: 75 6c 64 20 3c 65 6d 3e 6e 6f 74 3c 2f 65 6d 3e  uld <em>not</em>
bc80: 20 75 73 65 20 74 68 69 73 20 66 69 6c 65 2d 63   use this file-c
bc90: 6f 6e 74 72 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  ontrol..**.** <l
bca0: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
bcb0: 5f 5a 49 50 56 46 53 5d 5d 0a 2a 2a 20 54 68 65  _ZIPVFS]].** The
bcc0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 5a   [SQLITE_FCNTL_Z
bcd0: 49 50 56 46 53 5d 20 6f 70 63 6f 64 65 20 69 73  IPVFS] opcode is
bce0: 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 62 79 20   implemented by 
bcf0: 7a 69 70 76 66 73 20 6f 6e 6c 79 2e 20 41 6c 6c  zipvfs only. All
bd00: 20 6f 74 68 65 72 0a 2a 2a 20 56 46 53 20 73 68   other.** VFS sh
bd10: 6f 75 6c 64 20 72 65 74 75 72 6e 20 53 51 4c 49  ould return SQLI
bd20: 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 66 6f 72 20  TE_NOTFOUND for 
bd30: 74 68 69 73 20 6f 70 63 6f 64 65 2e 0a 2a 2a 0a  this opcode..**.
bd40: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
bd50: 46 43 4e 54 4c 5f 52 42 55 5d 5d 0a 2a 2a 20 54  FCNTL_RBU]].** T
bd60: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
bd70: 5f 52 42 55 5d 20 6f 70 63 6f 64 65 20 69 73 20  _RBU] opcode is 
bd80: 69 6d 70 6c 65 6d 65 6e 74 65 64 20 62 79 20 74  implemented by t
bd90: 68 65 20 73 70 65 63 69 61 6c 20 56 46 53 20 75  he special VFS u
bda0: 73 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 52 42  sed by.** the RB
bdb0: 55 20 65 78 74 65 6e 73 69 6f 6e 20 6f 6e 6c 79  U extension only
bdc0: 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 56 46 53  .  All other VFS
bdd0: 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 53   should return S
bde0: 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 66  QLITE_NOTFOUND f
bdf0: 6f 72 0a 2a 2a 20 74 68 69 73 20 6f 70 63 6f 64  or.** this opcod
be00: 65 2e 20 20 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f  e.  .** </ul>.*/
be10: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
be20: 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20  FCNTL_LOCKSTATE 
be30: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 0a                1.
be40: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
be50: 43 4e 54 4c 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f  CNTL_GET_LOCKPRO
be60: 58 59 46 49 4c 45 20 20 20 20 20 20 20 32 0a 23  XYFILE       2.#
be70: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
be80: 4e 54 4c 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58  NTL_SET_LOCKPROX
be90: 59 46 49 4c 45 20 20 20 20 20 20 20 33 0a 23 64  YFILE       3.#d
bea0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
beb0: 54 4c 5f 4c 41 53 54 5f 45 52 52 4e 4f 20 20 20  TL_LAST_ERRNO   
bec0: 20 20 20 20 20 20 20 20 20 20 20 34 0a 23 64 65             4.#de
bed0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
bee0: 4c 5f 53 49 5a 45 5f 48 49 4e 54 20 20 20 20 20  L_SIZE_HINT     
bef0: 20 20 20 20 20 20 20 20 20 20 35 0a 23 64 65 66            5.#def
bf00: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
bf10: 5f 43 48 55 4e 4b 5f 53 49 5a 45 20 20 20 20 20  _CHUNK_SIZE     
bf20: 20 20 20 20 20 20 20 20 20 36 0a 23 64 65 66 69           6.#defi
bf30: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
bf40: 46 49 4c 45 5f 50 4f 49 4e 54 45 52 20 20 20 20  FILE_POINTER    
bf50: 20 20 20 20 20 20 20 20 37 0a 23 64 65 66 69 6e          7.#defin
bf60: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53  e SQLITE_FCNTL_S
bf70: 59 4e 43 5f 4f 4d 49 54 54 45 44 20 20 20 20 20  YNC_OMITTED     
bf80: 20 20 20 20 20 20 20 38 0a 23 64 65 66 69 6e 65         8.#define
bf90: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49   SQLITE_FCNTL_WI
bfa0: 4e 33 32 5f 41 56 5f 52 45 54 52 59 20 20 20 20  N32_AV_RETRY    
bfb0: 20 20 20 20 20 20 39 0a 23 64 65 66 69 6e 65 20        9.#define 
bfc0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52  SQLITE_FCNTL_PER
bfd0: 53 49 53 54 5f 57 41 4c 20 20 20 20 20 20 20 20  SIST_WAL        
bfe0: 20 20 20 20 31 30 0a 23 64 65 66 69 6e 65 20 53      10.#define S
bff0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52  QLITE_FCNTL_OVER
c000: 57 52 49 54 45 20 20 20 20 20 20 20 20 20 20 20  WRITE           
c010: 20 20 20 31 31 0a 23 64 65 66 69 6e 65 20 53 51     11.#define SQ
c020: 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41  LITE_FCNTL_VFSNA
c030: 4d 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ME              
c040: 20 20 31 32 0a 23 64 65 66 69 6e 65 20 53 51 4c    12.#define SQL
c050: 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53  ITE_FCNTL_POWERS
c060: 41 46 45 5f 4f 56 45 52 57 52 49 54 45 20 20 20  AFE_OVERWRITE   
c070: 20 31 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   13.#define SQLI
c080: 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 20  TE_FCNTL_PRAGMA 
c090: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
c0a0: 31 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  14.#define SQLIT
c0b0: 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44  E_FCNTL_BUSYHAND
c0c0: 4c 45 52 20 20 20 20 20 20 20 20 20 20 20 20 31  LER            1
c0d0: 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  5.#define SQLITE
c0e0: 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e  _FCNTL_TEMPFILEN
c0f0: 41 4d 45 20 20 20 20 20 20 20 20 20 20 20 31 36  AME           16
c100: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
c110: 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 20  FCNTL_MMAP_SIZE 
c120: 20 20 20 20 20 20 20 20 20 20 20 20 20 31 38 0a               18.
c130: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
c140: 43 4e 54 4c 5f 54 52 41 43 45 20 20 20 20 20 20  CNTL_TRACE      
c150: 20 20 20 20 20 20 20 20 20 20 20 20 31 39 0a 23              19.#
c160: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
c170: 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45 44 20 20 20  NTL_HAS_MOVED   
c180: 20 20 20 20 20 20 20 20 20 20 20 32 30 0a 23 64             20.#d
c190: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
c1a0: 54 4c 5f 53 59 4e 43 20 20 20 20 20 20 20 20 20  TL_SYNC         
c1b0: 20 20 20 20 20 20 20 20 20 20 32 31 0a 23 64 65            21.#de
c1c0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
c1d0: 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41 53 45 54 57  L_COMMIT_PHASETW
c1e0: 4f 20 20 20 20 20 20 20 20 32 32 0a 23 64 65 66  O        22.#def
c1f0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
c200: 5f 57 49 4e 33 32 5f 53 45 54 5f 48 41 4e 44 4c  _WIN32_SET_HANDL
c210: 45 20 20 20 20 20 20 20 32 33 0a 23 64 65 66 69  E       23.#defi
c220: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
c230: 57 41 4c 5f 42 4c 4f 43 4b 20 20 20 20 20 20 20  WAL_BLOCK       
c240: 20 20 20 20 20 20 20 32 34 0a 23 64 65 66 69 6e         24.#defin
c250: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 5a  e SQLITE_FCNTL_Z
c260: 49 50 56 46 53 20 20 20 20 20 20 20 20 20 20 20  IPVFS           
c270: 20 20 20 20 20 20 32 35 0a 23 64 65 66 69 6e 65        25.#define
c280: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 52 42   SQLITE_FCNTL_RB
c290: 55 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  U               
c2a0: 20 20 20 20 20 32 36 0a 23 64 65 66 69 6e 65 20       26.#define 
c2b0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53  SQLITE_FCNTL_VFS
c2c0: 5f 50 4f 49 4e 54 45 52 20 20 20 20 20 20 20 20  _POINTER        
c2d0: 20 20 20 20 32 37 0a 23 64 65 66 69 6e 65 20 53      27.#define S
c2e0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4a 4f 55 52  QLITE_FCNTL_JOUR
c2f0: 4e 41 4c 5f 50 4f 49 4e 54 45 52 20 20 20 20 20  NAL_POINTER     
c300: 20 20 20 32 38 0a 0a 2f 2a 20 64 65 70 72 65 63     28../* deprec
c310: 61 74 65 64 20 6e 61 6d 65 73 20 2a 2f 0a 23 64  ated names */.#d
c320: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 47 45 54  efine SQLITE_GET
c330: 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20  _LOCKPROXYFILE  
c340: 20 20 20 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c      SQLITE_FCNTL
c350: 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49  _GET_LOCKPROXYFI
c360: 4c 45 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  LE.#define SQLIT
c370: 45 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46  E_SET_LOCKPROXYF
c380: 49 4c 45 20 20 20 20 20 20 53 51 4c 49 54 45 5f  ILE      SQLITE_
c390: 46 43 4e 54 4c 5f 53 45 54 5f 4c 4f 43 4b 50 52  FCNTL_SET_LOCKPR
c3a0: 4f 58 59 46 49 4c 45 0a 23 64 65 66 69 6e 65 20  OXYFILE.#define 
c3b0: 53 51 4c 49 54 45 5f 4c 41 53 54 5f 45 52 52 4e  SQLITE_LAST_ERRN
c3c0: 4f 20 20 20 20 20 20 20 20 20 20 20 20 20 53 51  O             SQ
c3d0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 41 53 54 5f  LITE_FCNTL_LAST_
c3e0: 45 52 52 4e 4f 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41  ERRNO.../*.** CA
c3f0: 50 49 33 52 45 46 3a 20 4d 75 74 65 78 20 48 61  PI3REF: Mutex Ha
c400: 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d  ndle.**.** The m
c410: 75 74 65 78 20 6d 6f 64 75 6c 65 20 77 69 74 68  utex module with
c420: 69 6e 20 53 51 4c 69 74 65 20 64 65 66 69 6e 65  in SQLite define
c430: 73 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  s [sqlite3_mutex
c440: 5d 20 74 6f 20 62 65 20 61 6e 0a 2a 2a 20 61 62  ] to be an.** ab
c450: 73 74 72 61 63 74 20 74 79 70 65 20 66 6f 72 20  stract type for 
c460: 61 20 6d 75 74 65 78 20 6f 62 6a 65 63 74 2e 20  a mutex object. 
c470: 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   The SQLite core
c480: 20 6e 65 76 65 72 20 6c 6f 6f 6b 73 0a 2a 2a 20   never looks.** 
c490: 61 74 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20  at the internal 
c4a0: 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 6f  representation o
c4b0: 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 6d 75  f an [sqlite3_mu
c4c0: 74 65 78 5d 2e 20 20 49 74 20 6f 6e 6c 79 0a 2a  tex].  It only.*
c4d0: 2a 20 64 65 61 6c 73 20 77 69 74 68 20 70 6f 69  * deals with poi
c4e0: 6e 74 65 72 73 20 74 6f 20 74 68 65 20 5b 73 71  nters to the [sq
c4f0: 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 6f 62 6a  lite3_mutex] obj
c500: 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74 65 78  ect..**.** Mutex
c510: 65 73 20 61 72 65 20 63 72 65 61 74 65 64 20 75  es are created u
c520: 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75  sing [sqlite3_mu
c530: 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f  tex_alloc()]..*/
c540: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
c550: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 73 71  sqlite3_mutex sq
c560: 6c 69 74 65 33 5f 6d 75 74 65 78 3b 0a 0a 2f 2a  lite3_mutex;../*
c570: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53  .** CAPI3REF: OS
c580: 20 49 6e 74 65 72 66 61 63 65 20 4f 62 6a 65 63   Interface Objec
c590: 74 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61  t.**.** An insta
c5a0: 6e 63 65 20 6f 66 20 74 68 65 20 73 71 6c 69 74  nce of the sqlit
c5b0: 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 64 65  e3_vfs object de
c5c0: 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65 72 66  fines the interf
c5d0: 61 63 65 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74  ace between.** t
c5e0: 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 61  he SQLite core a
c5f0: 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e  nd the underlyin
c600: 67 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74  g operating syst
c610: 65 6d 2e 20 20 54 68 65 20 22 76 66 73 22 0a 2a  em.  The "vfs".*
c620: 2a 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66  * in the name of
c630: 20 74 68 65 20 6f 62 6a 65 63 74 20 73 74 61 6e   the object stan
c640: 64 73 20 66 6f 72 20 22 76 69 72 74 75 61 6c 20  ds for "virtual 
c650: 66 69 6c 65 20 73 79 73 74 65 6d 22 2e 20 20 53  file system".  S
c660: 65 65 0a 2a 2a 20 74 68 65 20 5b 56 46 53 20 7c  ee.** the [VFS |
c670: 20 56 46 53 20 64 6f 63 75 6d 65 6e 74 61 74 69   VFS documentati
c680: 6f 6e 5d 20 66 6f 72 20 66 75 72 74 68 65 72 20  on] for further 
c690: 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a  information..**.
c6a0: 2a 2a 20 54 68 65 20 76 61 6c 75 65 20 6f 66 20  ** The value of 
c6b0: 74 68 65 20 69 56 65 72 73 69 6f 6e 20 66 69 65  the iVersion fie
c6c0: 6c 64 20 69 73 20 69 6e 69 74 69 61 6c 6c 79 20  ld is initially 
c6d0: 31 20 62 75 74 20 6d 61 79 20 62 65 20 6c 61 72  1 but may be lar
c6e0: 67 65 72 20 69 6e 0a 2a 2a 20 66 75 74 75 72 65  ger in.** future
c6f0: 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
c700: 69 74 65 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c  ite.  Additional
c710: 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61   fields may be a
c720: 70 70 65 6e 64 65 64 20 74 6f 20 74 68 69 73 0a  ppended to this.
c730: 2a 2a 20 6f 62 6a 65 63 74 20 77 68 65 6e 20 74  ** object when t
c740: 68 65 20 69 56 65 72 73 69 6f 6e 20 76 61 6c 75  he iVersion valu
c750: 65 20 69 73 20 69 6e 63 72 65 61 73 65 64 2e 20  e is increased. 
c760: 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 73   Note that the s
c770: 74 72 75 63 74 75 72 65 0a 2a 2a 20 6f 66 20 74  tructure.** of t
c780: 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f  he sqlite3_vfs o
c790: 62 6a 65 63 74 20 63 68 61 6e 67 65 73 20 69 6e  bject changes in
c7a0: 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e   the transaction
c7b0: 20 62 65 74 77 65 65 6e 0a 2a 2a 20 53 51 4c 69   between.** SQLi
c7c0: 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 39  te version 3.5.9
c7d0: 20 61 6e 64 20 33 2e 36 2e 30 20 61 6e 64 20 79   and 3.6.0 and y
c7e0: 65 74 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20  et the iVersion 
c7f0: 66 69 65 6c 64 20 77 61 73 20 6e 6f 74 0a 2a 2a  field was not.**
c800: 20 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a 0a 2a 2a   modified..**.**
c810: 20 54 68 65 20 73 7a 4f 73 46 69 6c 65 20 66 69   The szOsFile fi
c820: 65 6c 64 20 69 73 20 74 68 65 20 73 69 7a 65 20  eld is the size 
c830: 6f 66 20 74 68 65 20 73 75 62 63 6c 61 73 73 65  of the subclasse
c840: 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  d [sqlite3_file]
c850: 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 75 73  .** structure us
c860: 65 64 20 62 79 20 74 68 69 73 20 56 46 53 2e 20  ed by this VFS. 
c870: 20 6d 78 50 61 74 68 6e 61 6d 65 20 69 73 20 74   mxPathname is t
c880: 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  he maximum lengt
c890: 68 20 6f 66 0a 2a 2a 20 61 20 70 61 74 68 6e 61  h of.** a pathna
c8a0: 6d 65 20 69 6e 20 74 68 69 73 20 56 46 53 2e 0a  me in this VFS..
c8b0: 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65 72 65 64  **.** Registered
c8c0: 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a   sqlite3_vfs obj
c8d0: 65 63 74 73 20 61 72 65 20 6b 65 70 74 20 6f 6e  ects are kept on
c8e0: 20 61 20 6c 69 6e 6b 65 64 20 6c 69 73 74 20 66   a linked list f
c8f0: 6f 72 6d 65 64 20 62 79 0a 2a 2a 20 74 68 65 20  ormed by.** the 
c900: 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e 20 20  pNext pointer.  
c910: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  The [sqlite3_vfs
c920: 5f 72 65 67 69 73 74 65 72 28 29 5d 0a 2a 2a 20  _register()].** 
c930: 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  and [sqlite3_vfs
c940: 5f 75 6e 72 65 67 69 73 74 65 72 28 29 5d 20 69  _unregister()] i
c950: 6e 74 65 72 66 61 63 65 73 20 6d 61 6e 61 67 65  nterfaces manage
c960: 20 74 68 69 73 20 6c 69 73 74 0a 2a 2a 20 69 6e   this list.** in
c970: 20 61 20 74 68 72 65 61 64 2d 73 61 66 65 20 77   a thread-safe w
c980: 61 79 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65  ay.  The [sqlite
c990: 33 5f 76 66 73 5f 66 69 6e 64 28 29 5d 20 69 6e  3_vfs_find()] in
c9a0: 74 65 72 66 61 63 65 0a 2a 2a 20 73 65 61 72 63  terface.** searc
c9b0: 68 65 73 20 74 68 65 20 6c 69 73 74 2e 20 20 4e  hes the list.  N
c9c0: 65 69 74 68 65 72 20 74 68 65 20 61 70 70 6c 69  either the appli
c9d0: 63 61 74 69 6f 6e 20 63 6f 64 65 20 6e 6f 72 20  cation code nor 
c9e0: 74 68 65 20 56 46 53 0a 2a 2a 20 69 6d 70 6c 65  the VFS.** imple
c9f0: 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75 6c 64  mentation should
ca00: 20 75 73 65 20 74 68 65 20 70 4e 65 78 74 20 70   use the pNext p
ca10: 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68  ointer..**.** Th
ca20: 65 20 70 4e 65 78 74 20 66 69 65 6c 64 20 69 73  e pNext field is
ca30: 20 74 68 65 20 6f 6e 6c 79 20 66 69 65 6c 64 20   the only field 
ca40: 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76  in the sqlite3_v
ca50: 66 73 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20  fs.** structure 
ca60: 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c  that SQLite will
ca70: 20 65 76 65 72 20 6d 6f 64 69 66 79 2e 20 20 53   ever modify.  S
ca80: 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e 6c 79 20  QLite will only 
ca90: 61 63 63 65 73 73 0a 2a 2a 20 6f 72 20 6d 6f 64  access.** or mod
caa0: 69 66 79 20 74 68 69 73 20 66 69 65 6c 64 20 77  ify this field w
cab0: 68 69 6c 65 20 68 6f 6c 64 69 6e 67 20 61 20 70  hile holding a p
cac0: 61 72 74 69 63 75 6c 61 72 20 73 74 61 74 69 63  articular static
cad0: 20 6d 75 74 65 78 2e 0a 2a 2a 20 54 68 65 20 61   mutex..** The a
cae0: 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c  pplication shoul
caf0: 64 20 6e 65 76 65 72 20 6d 6f 64 69 66 79 20 61  d never modify a
cb00: 6e 79 74 68 69 6e 67 20 77 69 74 68 69 6e 20 74  nything within t
cb10: 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a  he sqlite3_vfs.*
cb20: 2a 20 6f 62 6a 65 63 74 20 6f 6e 63 65 20 74 68  * object once th
cb30: 65 20 6f 62 6a 65 63 74 20 68 61 73 20 62 65 65  e object has bee
cb40: 6e 20 72 65 67 69 73 74 65 72 65 64 2e 0a 2a 2a  n registered..**
cb50: 0a 2a 2a 20 54 68 65 20 7a 4e 61 6d 65 20 66 69  .** The zName fi
cb60: 65 6c 64 20 68 6f 6c 64 73 20 74 68 65 20 6e 61  eld holds the na
cb70: 6d 65 20 6f 66 20 74 68 65 20 56 46 53 20 6d 6f  me of the VFS mo
cb80: 64 75 6c 65 2e 20 20 54 68 65 20 6e 61 6d 65 20  dule.  The name 
cb90: 6d 75 73 74 0a 2a 2a 20 62 65 20 75 6e 69 71 75  must.** be uniqu
cba0: 65 20 61 63 72 6f 73 73 20 61 6c 6c 20 56 46 53  e across all VFS
cbb0: 20 6d 6f 64 75 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20   modules..**.** 
cbc0: 5b 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f  [[sqlite3_vfs.xO
cbd0: 70 65 6e 5d 5d 0a 2a 2a 20 5e 53 51 4c 69 74 65  pen]].** ^SQLite
cbe0: 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74   guarantees that
cbf0: 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70   the zFilename p
cc00: 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 65  arameter to xOpe
cc10: 6e 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 20 61  n.** is either a
cc20: 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6f 72   NULL pointer or
cc30: 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e 65 64   string obtained
cc40: 0a 2a 2a 20 66 72 6f 6d 20 78 46 75 6c 6c 50 61  .** from xFullPa
cc50: 74 68 6e 61 6d 65 28 29 20 77 69 74 68 20 61 6e  thname() with an
cc60: 20 6f 70 74 69 6f 6e 61 6c 20 73 75 66 66 69 78   optional suffix
cc70: 20 61 64 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 61   added..** ^If a
cc80: 20 73 75 66 66 69 78 20 69 73 20 61 64 64 65 64   suffix is added
cc90: 20 74 6f 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d   to the zFilenam
cca0: 65 20 70 61 72 61 6d 65 74 65 72 2c 20 69 74 20  e parameter, it 
ccb0: 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 73 69 73 74 20  will.** consist 
ccc0: 6f 66 20 61 20 73 69 6e 67 6c 65 20 22 2d 22 20  of a single "-" 
ccd0: 63 68 61 72 61 63 74 65 72 20 66 6f 6c 6c 6f 77  character follow
cce0: 65 64 20 62 79 20 6e 6f 20 6d 6f 72 65 20 74 68  ed by no more th
ccf0: 61 6e 0a 2a 2a 20 31 31 20 61 6c 70 68 61 6e 75  an.** 11 alphanu
cd00: 6d 65 72 69 63 20 61 6e 64 2f 6f 72 20 22 2d 22  meric and/or "-"
cd10: 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 20   characters..** 
cd20: 5e 53 51 4c 69 74 65 20 66 75 72 74 68 65 72 20  ^SQLite further 
cd30: 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 0a  guarantees that.
cd40: 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20 77 69  ** the string wi
cd50: 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 6e 64 20  ll be valid and 
cd60: 75 6e 63 68 61 6e 67 65 64 20 75 6e 74 69 6c 20  unchanged until 
cd70: 78 43 6c 6f 73 65 28 29 20 69 73 0a 2a 2a 20 63  xClose() is.** c
cd80: 61 6c 6c 65 64 2e 20 42 65 63 61 75 73 65 20 6f  alled. Because o
cd90: 66 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 73  f the previous s
cda0: 65 6e 74 65 6e 63 65 2c 0a 2a 2a 20 74 68 65 20  entence,.** the 
cdb0: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 63  [sqlite3_file] c
cdc0: 61 6e 20 73 61 66 65 6c 79 20 73 74 6f 72 65 20  an safely store 
cdd0: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
cde0: 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69 66 20  .** filename if 
cdf0: 69 74 20 6e 65 65 64 73 20 74 6f 20 72 65 6d 65  it needs to reme
ce00: 6d 62 65 72 20 74 68 65 20 66 69 6c 65 6e 61 6d  mber the filenam
ce10: 65 20 66 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f  e for some reaso
ce20: 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 20 7a 46 69  n..** If the zFi
ce30: 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72  lename parameter
ce40: 20 74 6f 20 78 4f 70 65 6e 20 69 73 20 61 20 4e   to xOpen is a N
ce50: 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e  ULL pointer then
ce60: 20 78 4f 70 65 6e 0a 2a 2a 20 6d 75 73 74 20 69   xOpen.** must i
ce70: 6e 76 65 6e 74 20 69 74 73 20 6f 77 6e 20 74 65  nvent its own te
ce80: 6d 70 6f 72 61 72 79 20 6e 61 6d 65 20 66 6f 72  mporary name for
ce90: 20 74 68 65 20 66 69 6c 65 2e 20 20 5e 57 68 65   the file.  ^Whe
cea0: 6e 65 76 65 72 20 74 68 65 20 0a 2a 2a 20 78 46  never the .** xF
ceb0: 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65  ilename paramete
cec0: 72 20 69 73 20 4e 55 4c 4c 20 69 74 20 77 69 6c  r is NULL it wil
ced0: 6c 20 61 6c 73 6f 20 62 65 20 74 68 65 20 63 61  l also be the ca
cee0: 73 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 66  se that the.** f
cef0: 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 77  lags parameter w
cf00: 69 6c 6c 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c  ill include [SQL
cf10: 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f  ITE_OPEN_DELETEO
cf20: 4e 43 4c 4f 53 45 5d 2e 0a 2a 2a 0a 2a 2a 20 54  NCLOSE]..**.** T
cf30: 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e  he flags argumen
cf40: 74 20 74 6f 20 78 4f 70 65 6e 28 29 20 69 6e 63  t to xOpen() inc
cf50: 6c 75 64 65 73 20 61 6c 6c 20 62 69 74 73 20 73  ludes all bits s
cf60: 65 74 20 69 6e 0a 2a 2a 20 74 68 65 20 66 6c 61  et in.** the fla
cf70: 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b  gs argument to [
cf80: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
cf90: 29 5d 2e 20 20 4f 72 20 69 66 20 5b 73 71 6c 69  )].  Or if [sqli
cfa0: 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 6f  te3_open()].** o
cfb0: 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  r [sqlite3_open1
cfc0: 36 28 29 5d 20 69 73 20 75 73 65 64 2c 20 74 68  6()] is used, th
cfd0: 65 6e 20 66 6c 61 67 73 20 69 6e 63 6c 75 64 65  en flags include
cfe0: 73 20 61 74 20 6c 65 61 73 74 0a 2a 2a 20 5b 53  s at least.** [S
cff0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57  QLITE_OPEN_READW
d000: 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f  RITE] | [SQLITE_
d010: 4f 50 45 4e 5f 43 52 45 41 54 45 5d 2e 20 0a 2a  OPEN_CREATE]. .*
d020: 2a 20 49 66 20 78 4f 70 65 6e 28 29 20 6f 70 65  * If xOpen() ope
d030: 6e 73 20 61 20 66 69 6c 65 20 72 65 61 64 2d 6f  ns a file read-o
d040: 6e 6c 79 20 74 68 65 6e 20 69 74 20 73 65 74 73  nly then it sets
d050: 20 2a 70 4f 75 74 46 6c 61 67 73 20 74 6f 0a 2a   *pOutFlags to.*
d060: 2a 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54  * include [SQLIT
d070: 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d  E_OPEN_READONLY]
d080: 2e 20 20 4f 74 68 65 72 20 62 69 74 73 20 69 6e  .  Other bits in
d090: 20 2a 70 4f 75 74 46 6c 61 67 73 20 6d 61 79 20   *pOutFlags may 
d0a0: 62 65 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28  be set..**.** ^(
d0b0: 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 73 6f  SQLite will also
d0c0: 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 20   add one of the 
d0d0: 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20  following flags 
d0e0: 74 6f 20 74 68 65 20 78 4f 70 65 6e 28 29 0a 2a  to the xOpen().*
d0f0: 2a 20 63 61 6c 6c 2c 20 64 65 70 65 6e 64 69 6e  * call, dependin
d100: 67 20 6f 6e 20 74 68 65 20 6f 62 6a 65 63 74 20  g on the object 
d110: 62 65 69 6e 67 20 6f 70 65 6e 65 64 3a 0a 2a 2a  being opened:.**
d120: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
d130: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d    [SQLITE_OPEN_M
d140: 41 49 4e 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20  AIN_DB].** <li> 
d150: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41   [SQLITE_OPEN_MA
d160: 49 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c  IN_JOURNAL].** <
d170: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
d180: 4e 5f 54 45 4d 50 5f 44 42 5d 0a 2a 2a 20 3c 6c  N_TEMP_DB].** <l
d190: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
d1a0: 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a  _TEMP_JOURNAL].*
d1b0: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
d1c0: 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44  OPEN_TRANSIENT_D
d1d0: 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  B].** <li>  [SQL
d1e0: 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52  ITE_OPEN_SUBJOUR
d1f0: 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  NAL].** <li>  [S
d200: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45  QLITE_OPEN_MASTE
d210: 52 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c  R_JOURNAL].** <l
d220: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
d230: 5f 57 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e  _WAL].** </ul>)^
d240: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 6c 65 20  .**.** The file 
d250: 49 2f 4f 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  I/O implementati
d260: 6f 6e 20 63 61 6e 20 75 73 65 20 74 68 65 20 6f  on can use the o
d270: 62 6a 65 63 74 20 74 79 70 65 20 66 6c 61 67 73  bject type flags
d280: 20 74 6f 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68   to.** change th
d290: 65 20 77 61 79 20 69 74 20 64 65 61 6c 73 20 77  e way it deals w
d2a0: 69 74 68 20 66 69 6c 65 73 2e 20 20 46 6f 72 20  ith files.  For 
d2b0: 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c  example, an appl
d2c0: 69 63 61 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20  ication.** that 
d2d0: 64 6f 65 73 20 6e 6f 74 20 63 61 72 65 20 61 62  does not care ab
d2e0: 6f 75 74 20 63 72 61 73 68 20 72 65 63 6f 76 65  out crash recove
d2f0: 72 79 20 6f 72 20 72 6f 6c 6c 62 61 63 6b 20 6d  ry or rollback m
d300: 69 67 68 74 20 6d 61 6b 65 0a 2a 2a 20 74 68 65  ight make.** the
d310: 20 6f 70 65 6e 20 6f 66 20 61 20 6a 6f 75 72 6e   open of a journ
d320: 61 6c 20 66 69 6c 65 20 61 20 6e 6f 2d 6f 70 2e  al file a no-op.
d330: 20 20 57 72 69 74 65 73 20 74 6f 20 74 68 69 73    Writes to this
d340: 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 0a 2a   journal would.*
d350: 2a 20 61 6c 73 6f 20 62 65 20 6e 6f 2d 6f 70 73  * also be no-ops
d360: 2c 20 61 6e 64 20 61 6e 79 20 61 74 74 65 6d 70  , and any attemp
d370: 74 20 74 6f 20 72 65 61 64 20 74 68 65 20 6a 6f  t to read the jo
d380: 75 72 6e 61 6c 20 77 6f 75 6c 64 20 72 65 74 75  urnal would retu
d390: 72 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f 45  rn.** SQLITE_IOE
d3a0: 52 52 2e 20 20 4f 72 20 74 68 65 20 69 6d 70 6c  RR.  Or the impl
d3b0: 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 69 67 68 74  ementation might
d3c0: 20 72 65 63 6f 67 6e 69 7a 65 20 74 68 61 74 20   recognize that 
d3d0: 61 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69  a database.** fi
d3e0: 6c 65 20 77 69 6c 6c 20 62 65 20 64 6f 69 6e 67  le will be doing
d3f0: 20 70 61 67 65 2d 61 6c 69 67 6e 65 64 20 73 65   page-aligned se
d400: 63 74 6f 72 20 72 65 61 64 73 20 61 6e 64 20 77  ctor reads and w
d410: 72 69 74 65 73 20 69 6e 20 61 20 72 61 6e 64 6f  rites in a rando
d420: 6d 0a 2a 2a 20 6f 72 64 65 72 20 61 6e 64 20 73  m.** order and s
d430: 65 74 20 75 70 20 69 74 73 20 49 2f 4f 20 73 75  et up its I/O su
d440: 62 73 79 73 74 65 6d 20 61 63 63 6f 72 64 69 6e  bsystem accordin
d450: 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  gly..**.** SQLit
d460: 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 61 64 64  e might also add
d470: 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c   one of the foll
d480: 6f 77 69 6e 67 20 66 6c 61 67 73 20 74 6f 20 74  owing flags to t
d490: 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 3a  he xOpen method:
d4a0: 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
d4b0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  li> [SQLITE_OPEN
d4c0: 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a  _DELETEONCLOSE].
d4d0: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
d4e0: 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d 0a  OPEN_EXCLUSIVE].
d4f0: 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54  ** </ul>.**.** T
d500: 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
d510: 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 20 66  DELETEONCLOSE] f
d520: 6c 61 67 20 6d 65 61 6e 73 20 74 68 65 20 66 69  lag means the fi
d530: 6c 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20  le should be.** 
d540: 64 65 6c 65 74 65 64 20 77 68 65 6e 20 69 74 20  deleted when it 
d550: 69 73 20 63 6c 6f 73 65 64 2e 20 20 5e 54 68 65  is closed.  ^The
d560: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45   [SQLITE_OPEN_DE
d570: 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20  LETEONCLOSE].** 
d580: 77 69 6c 6c 20 62 65 20 73 65 74 20 66 6f 72 20  will be set for 
d590: 54 45 4d 50 20 64 61 74 61 62 61 73 65 73 20 61  TEMP databases a
d5a0: 6e 64 20 74 68 65 69 72 20 6a 6f 75 72 6e 61 6c  nd their journal
d5b0: 73 2c 20 74 72 61 6e 73 69 65 6e 74 0a 2a 2a 20  s, transient.** 
d5c0: 64 61 74 61 62 61 73 65 73 2c 20 61 6e 64 20 73  databases, and s
d5d0: 75 62 6a 6f 75 72 6e 61 6c 73 2e 0a 2a 2a 0a 2a  ubjournals..**.*
d5e0: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f  * ^The [SQLITE_O
d5f0: 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d 20 66  PEN_EXCLUSIVE] f
d600: 6c 61 67 20 69 73 20 61 6c 77 61 79 73 20 75 73  lag is always us
d610: 65 64 20 69 6e 20 63 6f 6e 6a 75 6e 63 74 69 6f  ed in conjunctio
d620: 6e 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 53  n.** with the [S
d630: 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
d640: 45 5d 20 66 6c 61 67 2c 20 77 68 69 63 68 20 61  E] flag, which a
d650: 72 65 20 62 6f 74 68 20 64 69 72 65 63 74 6c 79  re both directly
d660: 0a 2a 2a 20 61 6e 61 6c 6f 67 6f 75 73 20 74 6f  .** analogous to
d670: 20 74 68 65 20 4f 5f 45 58 43 4c 20 61 6e 64 20   the O_EXCL and 
d680: 4f 5f 43 52 45 41 54 20 66 6c 61 67 73 20 6f 66  O_CREAT flags of
d690: 20 74 68 65 20 50 4f 53 49 58 20 6f 70 65 6e 28   the POSIX open(
d6a0: 29 0a 2a 2a 20 41 50 49 2e 20 20 54 68 65 20 53  ).** API.  The S
d6b0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55  QLITE_OPEN_EXCLU
d6c0: 53 49 56 45 20 66 6c 61 67 2c 20 77 68 65 6e 20  SIVE flag, when 
d6d0: 70 61 69 72 65 64 20 77 69 74 68 20 74 68 65 20  paired with the 
d6e0: 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  .** SQLITE_OPEN_
d6f0: 43 52 45 41 54 45 2c 20 69 73 20 75 73 65 64 20  CREATE, is used 
d700: 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 74  to indicate that
d710: 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 61 6c 77   file should alw
d720: 61 79 73 0a 2a 2a 20 62 65 20 63 72 65 61 74 65  ays.** be create
d730: 64 2c 20 61 6e 64 20 74 68 61 74 20 69 74 20 69  d, and that it i
d740: 73 20 61 6e 20 65 72 72 6f 72 20 69 66 20 69 74  s an error if it
d750: 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 73 2e   already exists.
d760: 0a 2a 2a 20 49 74 20 69 73 20 3c 69 3e 6e 6f 74  .** It is <i>not
d770: 3c 2f 69 3e 20 75 73 65 64 20 74 6f 20 69 6e 64  </i> used to ind
d780: 69 63 61 74 65 20 74 68 65 20 66 69 6c 65 20 73  icate the file s
d790: 68 6f 75 6c 64 20 62 65 20 6f 70 65 6e 65 64 20  hould be opened 
d7a0: 0a 2a 2a 20 66 6f 72 20 65 78 63 6c 75 73 69 76  .** for exclusiv
d7b0: 65 20 61 63 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20  e access..**.** 
d7c0: 5e 41 74 20 6c 65 61 73 74 20 73 7a 4f 73 46 69  ^At least szOsFi
d7d0: 6c 65 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f  le bytes of memo
d7e0: 72 79 20 61 72 65 20 61 6c 6c 6f 63 61 74 65 64  ry are allocated
d7f0: 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 74 6f   by SQLite.** to
d800: 20 68 6f 6c 64 20 74 68 65 20 20 5b 73 71 6c 69   hold the  [sqli
d810: 74 65 33 5f 66 69 6c 65 5d 20 73 74 72 75 63 74  te3_file] struct
d820: 75 72 65 20 70 61 73 73 65 64 20 61 73 20 74 68  ure passed as th
d830: 65 20 74 68 69 72 64 0a 2a 2a 20 61 72 67 75 6d  e third.** argum
d840: 65 6e 74 20 74 6f 20 78 4f 70 65 6e 2e 20 20 54  ent to xOpen.  T
d850: 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20  he xOpen method 
d860: 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 74 6f  does not have to
d870: 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 20 74 68 65  .** allocate the
d880: 20 73 74 72 75 63 74 75 72 65 3b 20 69 74 20 73   structure; it s
d890: 68 6f 75 6c 64 20 6a 75 73 74 20 66 69 6c 6c 20  hould just fill 
d8a0: 69 74 20 69 6e 2e 20 20 4e 6f 74 65 20 74 68 61  it in.  Note tha
d8b0: 74 0a 2a 2a 20 74 68 65 20 78 4f 70 65 6e 20 6d  t.** the xOpen m
d8c0: 65 74 68 6f 64 20 6d 75 73 74 20 73 65 74 20 74  ethod must set t
d8d0: 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e  he sqlite3_file.
d8e0: 70 4d 65 74 68 6f 64 73 20 74 6f 20 65 69 74 68  pMethods to eith
d8f0: 65 72 0a 2a 2a 20 61 20 76 61 6c 69 64 20 5b 73  er.** a valid [s
d900: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
d910: 73 5d 20 6f 62 6a 65 63 74 20 6f 72 20 74 6f 20  s] object or to 
d920: 4e 55 4c 4c 2e 20 20 78 4f 70 65 6e 20 6d 75 73  NULL.  xOpen mus
d930: 74 20 64 6f 0a 2a 2a 20 74 68 69 73 20 65 76 65  t do.** this eve
d940: 6e 20 69 66 20 74 68 65 20 6f 70 65 6e 20 66 61  n if the open fa
d950: 69 6c 73 2e 20 20 53 51 4c 69 74 65 20 65 78 70  ils.  SQLite exp
d960: 65 63 74 73 20 74 68 61 74 20 74 68 65 20 73 71  ects that the sq
d970: 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68  lite3_file.pMeth
d980: 6f 64 73 0a 2a 2a 20 65 6c 65 6d 65 6e 74 20 77  ods.** element w
d990: 69 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 66 74  ill be valid aft
d9a0: 65 72 20 78 4f 70 65 6e 20 72 65 74 75 72 6e 73  er xOpen returns
d9b0: 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 74   regardless of t
d9c0: 68 65 20 73 75 63 63 65 73 73 0a 2a 2a 20 6f 72  he success.** or
d9d0: 20 66 61 69 6c 75 72 65 20 6f 66 20 74 68 65 20   failure of the 
d9e0: 78 4f 70 65 6e 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a  xOpen call..**.*
d9f0: 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e  * [[sqlite3_vfs.
da00: 78 41 63 63 65 73 73 5d 5d 0a 2a 2a 20 5e 54 68  xAccess]].** ^Th
da10: 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74  e flags argument
da20: 20 74 6f 20 78 41 63 63 65 73 73 28 29 20 6d 61   to xAccess() ma
da30: 79 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 43 43  y be [SQLITE_ACC
da40: 45 53 53 5f 45 58 49 53 54 53 5d 0a 2a 2a 20 74  ESS_EXISTS].** t
da50: 6f 20 74 65 73 74 20 66 6f 72 20 74 68 65 20 65  o test for the e
da60: 78 69 73 74 65 6e 63 65 20 6f 66 20 61 20 66 69  xistence of a fi
da70: 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41  le, or [SQLITE_A
da80: 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 5d  CCESS_READWRITE]
da90: 20 74 6f 0a 2a 2a 20 74 65 73 74 20 77 68 65 74   to.** test whet
daa0: 68 65 72 20 61 20 66 69 6c 65 20 69 73 20 72 65  her a file is re
dab0: 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74 61  adable and writa
dac0: 62 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  ble, or [SQLITE_
dad0: 41 43 43 45 53 53 5f 52 45 41 44 5d 0a 2a 2a 20  ACCESS_READ].** 
dae0: 74 6f 20 74 65 73 74 20 77 68 65 74 68 65 72 20  to test whether 
daf0: 61 20 66 69 6c 65 20 69 73 20 61 74 20 6c 65 61  a file is at lea
db00: 73 74 20 72 65 61 64 61 62 6c 65 2e 20 20 20 54  st readable.   T
db10: 68 65 20 66 69 6c 65 20 63 61 6e 20 62 65 20 61  he file can be a
db20: 0a 2a 2a 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a  .** directory..*
db30: 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c  *.** ^SQLite wil
db40: 6c 20 61 6c 77 61 79 73 20 61 6c 6c 6f 63 61 74  l always allocat
db50: 65 20 61 74 20 6c 65 61 73 74 20 6d 78 50 61 74  e at least mxPat
db60: 68 6e 61 6d 65 2b 31 20 62 79 74 65 73 20 66 6f  hname+1 bytes fo
db70: 72 20 74 68 65 0a 2a 2a 20 6f 75 74 70 75 74 20  r the.** output 
db80: 62 75 66 66 65 72 20 78 46 75 6c 6c 50 61 74 68  buffer xFullPath
db90: 6e 61 6d 65 2e 20 20 54 68 65 20 65 78 61 63 74  name.  The exact
dba0: 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6f 75 74   size of the out
dbb0: 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 69 73  put buffer.** is
dbc0: 20 61 6c 73 6f 20 70 61 73 73 65 64 20 61 73 20   also passed as 
dbd0: 61 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62  a parameter to b
dbe0: 6f 74 68 20 20 6d 65 74 68 6f 64 73 2e 20 49 66  oth  methods. If
dbf0: 20 74 68 65 20 6f 75 74 70 75 74 20 62 75 66 66   the output buff
dc00: 65 72 0a 2a 2a 20 69 73 20 6e 6f 74 20 6c 61 72  er.** is not lar
dc10: 67 65 20 65 6e 6f 75 67 68 2c 20 5b 53 51 4c 49  ge enough, [SQLI
dc20: 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 73 68 6f  TE_CANTOPEN] sho
dc30: 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e  uld be returned.
dc40: 20 53 69 6e 63 65 20 74 68 69 73 20 69 73 0a 2a   Since this is.*
dc50: 2a 20 68 61 6e 64 6c 65 64 20 61 73 20 61 20 66  * handled as a f
dc60: 61 74 61 6c 20 65 72 72 6f 72 20 62 79 20 53 51  atal error by SQ
dc70: 4c 69 74 65 2c 20 76 66 73 20 69 6d 70 6c 65 6d  Lite, vfs implem
dc80: 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64  entations should
dc90: 20 65 6e 64 65 61 76 6f 72 0a 2a 2a 20 74 6f 20   endeavor.** to 
dca0: 70 72 65 76 65 6e 74 20 74 68 69 73 20 62 79 20  prevent this by 
dcb0: 73 65 74 74 69 6e 67 20 6d 78 50 61 74 68 6e 61  setting mxPathna
dcc0: 6d 65 20 74 6f 20 61 20 73 75 66 66 69 63 69 65  me to a sufficie
dcd0: 6e 74 6c 79 20 6c 61 72 67 65 20 76 61 6c 75 65  ntly large value
dce0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 61 6e  ..**.** The xRan
dcf0: 64 6f 6d 6e 65 73 73 28 29 2c 20 78 53 6c 65 65  domness(), xSlee
dd00: 70 28 29 2c 20 78 43 75 72 72 65 6e 74 54 69 6d  p(), xCurrentTim
dd10: 65 28 29 2c 20 61 6e 64 20 78 43 75 72 72 65 6e  e(), and xCurren
dd20: 74 54 69 6d 65 49 6e 74 36 34 28 29 0a 2a 2a 20  tTimeInt64().** 
dd30: 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 6e  interfaces are n
dd40: 6f 74 20 73 74 72 69 63 74 6c 79 20 61 20 70 61  ot strictly a pa
dd50: 72 74 20 6f 66 20 74 68 65 20 66 69 6c 65 73 79  rt of the filesy
dd60: 73 74 65 6d 2c 20 62 75 74 20 74 68 65 79 20 61  stem, but they a
dd70: 72 65 0a 2a 2a 20 69 6e 63 6c 75 64 65 64 20 69  re.** included i
dd80: 6e 20 74 68 65 20 56 46 53 20 73 74 72 75 63 74  n the VFS struct
dd90: 75 72 65 20 66 6f 72 20 63 6f 6d 70 6c 65 74 65  ure for complete
dda0: 6e 65 73 73 2e 0a 2a 2a 20 54 68 65 20 78 52 61  ness..** The xRa
ddb0: 6e 64 6f 6d 6e 65 73 73 28 29 20 66 75 6e 63 74  ndomness() funct
ddc0: 69 6f 6e 20 61 74 74 65 6d 70 74 73 20 74 6f 20  ion attempts to 
ddd0: 72 65 74 75 72 6e 20 6e 42 79 74 65 73 20 62 79  return nBytes by
dde0: 74 65 73 0a 2a 2a 20 6f 66 20 67 6f 6f 64 2d 71  tes.** of good-q
ddf0: 75 61 6c 69 74 79 20 72 61 6e 64 6f 6d 6e 65 73  uality randomnes
de00: 73 20 69 6e 74 6f 20 7a 4f 75 74 2e 20 20 54 68  s into zOut.  Th
de10: 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 69  e return value i
de20: 73 0a 2a 2a 20 74 68 65 20 61 63 74 75 61 6c 20  s.** the actual 
de30: 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
de40: 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62  of randomness ob
de50: 74 61 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 78  tained..** The x
de60: 53 6c 65 65 70 28 29 20 6d 65 74 68 6f 64 20 63  Sleep() method c
de70: 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c 69 6e  auses the callin
de80: 67 20 74 68 72 65 61 64 20 74 6f 20 73 6c 65 65  g thread to slee
de90: 70 20 66 6f 72 20 61 74 0a 2a 2a 20 6c 65 61 73  p for at.** leas
dea0: 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  t the number of 
deb0: 6d 69 63 72 6f 73 65 63 6f 6e 64 73 20 67 69 76  microseconds giv
dec0: 65 6e 2e 20 20 5e 54 68 65 20 78 43 75 72 72 65  en.  ^The xCurre
ded0: 6e 74 54 69 6d 65 28 29 0a 2a 2a 20 6d 65 74 68  ntTime().** meth
dee0: 6f 64 20 72 65 74 75 72 6e 73 20 61 20 4a 75 6c  od returns a Jul
def0: 69 61 6e 20 44 61 79 20 4e 75 6d 62 65 72 20 66  ian Day Number f
df00: 6f 72 20 74 68 65 20 63 75 72 72 65 6e 74 20 64  or the current d
df10: 61 74 65 20 61 6e 64 20 74 69 6d 65 20 61 73 0a  ate and time as.
df20: 2a 2a 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f  ** a floating po
df30: 69 6e 74 20 76 61 6c 75 65 2e 0a 2a 2a 20 5e 54  int value..** ^T
df40: 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49  he xCurrentTimeI
df50: 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20 72 65  nt64() method re
df60: 74 75 72 6e 73 2c 20 61 73 20 61 6e 20 69 6e 74  turns, as an int
df70: 65 67 65 72 2c 20 74 68 65 20 4a 75 6c 69 61 6e  eger, the Julian
df80: 0a 2a 2a 20 44 61 79 20 4e 75 6d 62 65 72 20 6d  .** Day Number m
df90: 75 6c 74 69 70 6c 69 65 64 20 62 79 20 38 36 34  ultiplied by 864
dfa0: 30 30 30 30 30 20 28 74 68 65 20 6e 75 6d 62 65  00000 (the numbe
dfb0: 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  r of millisecond
dfc0: 73 20 69 6e 20 0a 2a 2a 20 61 20 32 34 2d 68 6f  s in .** a 24-ho
dfd0: 75 72 20 64 61 79 29 2e 20 20 0a 2a 2a 20 5e 53  ur day).  .** ^S
dfe0: 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 74  QLite will use t
dff0: 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49  he xCurrentTimeI
e000: 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20 74 6f  nt64() method to
e010: 20 67 65 74 20 74 68 65 20 63 75 72 72 65 6e 74   get the current
e020: 0a 2a 2a 20 64 61 74 65 20 61 6e 64 20 74 69 6d  .** date and tim
e030: 65 20 69 66 20 74 68 61 74 20 6d 65 74 68 6f 64  e if that method
e040: 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20 28 69   is available (i
e050: 66 20 69 56 65 72 73 69 6f 6e 20 69 73 20 32 20  f iVersion is 2 
e060: 6f 72 20 0a 2a 2a 20 67 72 65 61 74 65 72 20 61  or .** greater a
e070: 6e 64 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  nd the function 
e080: 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e  pointer is not N
e090: 55 4c 4c 29 20 61 6e 64 20 77 69 6c 6c 20 66 61  ULL) and will fa
e0a0: 6c 6c 20 62 61 63 6b 0a 2a 2a 20 74 6f 20 78 43  ll back.** to xC
e0b0: 75 72 72 65 6e 74 54 69 6d 65 28 29 20 69 66 20  urrentTime() if 
e0c0: 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36  xCurrentTimeInt6
e0d0: 34 28 29 20 69 73 20 75 6e 61 76 61 69 6c 61 62  4() is unavailab
e0e0: 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 78  le..**.** ^The x
e0f0: 53 65 74 53 79 73 74 65 6d 43 61 6c 6c 28 29 2c  SetSystemCall(),
e100: 20 78 47 65 74 53 79 73 74 65 6d 43 61 6c 6c 28   xGetSystemCall(
e110: 29 2c 20 61 6e 64 20 78 4e 65 73 74 53 79 73 74  ), and xNestSyst
e120: 65 6d 43 61 6c 6c 28 29 20 69 6e 74 65 72 66 61  emCall() interfa
e130: 63 65 73 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 75  ces.** are not u
e140: 73 65 64 20 62 79 20 74 68 65 20 53 51 4c 69 74  sed by the SQLit
e150: 65 20 63 6f 72 65 2e 20 20 54 68 65 73 65 20 6f  e core.  These o
e160: 70 74 69 6f 6e 61 6c 20 69 6e 74 65 72 66 61 63  ptional interfac
e170: 65 73 20 61 72 65 20 70 72 6f 76 69 64 65 64 0a  es are provided.
e180: 2a 2a 20 62 79 20 73 6f 6d 65 20 56 46 53 65 73  ** by some VFSes
e190: 20 74 6f 20 66 61 63 69 6c 69 74 61 74 65 20 74   to facilitate t
e1a0: 65 73 74 69 6e 67 20 6f 66 20 74 68 65 20 56 46  esting of the VF
e1b0: 53 20 63 6f 64 65 2e 20 42 79 20 6f 76 65 72 72  S code. By overr
e1c0: 69 64 69 6e 67 20 0a 2a 2a 20 73 79 73 74 65 6d  iding .** system
e1d0: 20 63 61 6c 6c 73 20 77 69 74 68 20 66 75 6e 63   calls with func
e1e0: 74 69 6f 6e 73 20 75 6e 64 65 72 20 69 74 73 20  tions under its 
e1f0: 63 6f 6e 74 72 6f 6c 2c 20 61 20 74 65 73 74 20  control, a test 
e200: 70 72 6f 67 72 61 6d 20 63 61 6e 0a 2a 2a 20 73  program can.** s
e210: 69 6d 75 6c 61 74 65 20 66 61 75 6c 74 73 20 61  imulate faults a
e220: 6e 64 20 65 72 72 6f 72 20 63 6f 6e 64 69 74 69  nd error conditi
e230: 6f 6e 73 20 74 68 61 74 20 77 6f 75 6c 64 20 6f  ons that would o
e240: 74 68 65 72 77 69 73 65 20 62 65 20 64 69 66 66  therwise be diff
e250: 69 63 75 6c 74 0a 2a 2a 20 6f 72 20 69 6d 70 6f  icult.** or impo
e260: 73 73 69 62 6c 65 20 74 6f 20 69 6e 64 75 63 65  ssible to induce
e270: 2e 20 20 54 68 65 20 73 65 74 20 6f 66 20 73 79  .  The set of sy
e280: 73 74 65 6d 20 63 61 6c 6c 73 20 74 68 61 74 20  stem calls that 
e290: 63 61 6e 20 62 65 20 6f 76 65 72 72 69 64 64 65  can be overridde
e2a0: 6e 0a 2a 2a 20 76 61 72 69 65 73 20 66 72 6f 6d  n.** varies from
e2b0: 20 6f 6e 65 20 56 46 53 20 74 6f 20 61 6e 6f 74   one VFS to anot
e2c0: 68 65 72 2c 20 61 6e 64 20 66 72 6f 6d 20 6f 6e  her, and from on
e2d0: 65 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68 65  e version of the
e2e0: 20 73 61 6d 65 20 56 46 53 20 74 6f 20 74 68 65   same VFS to the
e2f0: 0a 2a 2a 20 6e 65 78 74 2e 20 20 41 70 70 6c 69  .** next.  Appli
e300: 63 61 74 69 6f 6e 73 20 74 68 61 74 20 75 73 65  cations that use
e310: 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65   these interface
e320: 73 20 6d 75 73 74 20 62 65 20 70 72 65 70 61 72  s must be prepar
e330: 65 64 20 66 6f 72 20 61 6e 79 0a 2a 2a 20 6f 72  ed for any.** or
e340: 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 69 6e   all of these in
e350: 74 65 72 66 61 63 65 73 20 74 6f 20 62 65 20 4e  terfaces to be N
e360: 55 4c 4c 20 6f 72 20 66 6f 72 20 74 68 65 69 72  ULL or for their
e370: 20 62 65 68 61 76 69 6f 72 20 74 6f 20 63 68 61   behavior to cha
e380: 6e 67 65 0a 2a 2a 20 66 72 6f 6d 20 6f 6e 65 20  nge.** from one 
e390: 72 65 6c 65 61 73 65 20 74 6f 20 74 68 65 20 6e  release to the n
e3a0: 65 78 74 2e 20 20 41 70 70 6c 69 63 61 74 69 6f  ext.  Applicatio
e3b0: 6e 73 20 6d 75 73 74 20 6e 6f 74 20 61 74 74 65  ns must not atte
e3c0: 6d 70 74 20 74 6f 20 61 63 63 65 73 73 0a 2a 2a  mpt to access.**
e3d0: 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 6d 65   any of these me
e3e0: 74 68 6f 64 73 20 69 66 20 74 68 65 20 69 56 65  thods if the iVe
e3f0: 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 56 46 53  rsion of the VFS
e400: 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 33 2e   is less than 3.
e410: 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
e420: 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73 20 73  ct sqlite3_vfs s
e430: 71 6c 69 74 65 33 5f 76 66 73 3b 0a 74 79 70 65  qlite3_vfs;.type
e440: 64 65 66 20 76 6f 69 64 20 28 2a 73 71 6c 69 74  def void (*sqlit
e450: 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29 28  e3_syscall_ptr)(
e460: 76 6f 69 64 29 3b 0a 73 74 72 75 63 74 20 73 71  void);.struct sq
e470: 6c 69 74 65 33 5f 76 66 73 20 7b 0a 20 20 69 6e  lite3_vfs {.  in
e480: 74 20 69 56 65 72 73 69 6f 6e 3b 20 20 20 20 20  t iVersion;     
e490: 20 20 20 20 20 20 20 2f 2a 20 53 74 72 75 63 74         /* Struct
e4a0: 75 72 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62  ure version numb
e4b0: 65 72 20 28 63 75 72 72 65 6e 74 6c 79 20 33 29  er (currently 3)
e4c0: 20 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f 73 46 69   */.  int szOsFi
e4d0: 6c 65 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f  le;            /
e4e0: 2a 20 53 69 7a 65 20 6f 66 20 73 75 62 63 6c 61  * Size of subcla
e4f0: 73 73 65 64 20 73 71 6c 69 74 65 33 5f 66 69 6c  ssed sqlite3_fil
e500: 65 20 2a 2f 0a 20 20 69 6e 74 20 6d 78 50 61 74  e */.  int mxPat
e510: 68 6e 61 6d 65 3b 20 20 20 20 20 20 20 20 20 20  hname;          
e520: 2f 2a 20 4d 61 78 69 6d 75 6d 20 66 69 6c 65 20  /* Maximum file 
e530: 70 61 74 68 6e 61 6d 65 20 6c 65 6e 67 74 68 20  pathname length 
e540: 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 76 66 73  */.  sqlite3_vfs
e550: 20 2a 70 4e 65 78 74 3b 20 20 20 20 20 20 2f 2a   *pNext;      /*
e560: 20 4e 65 78 74 20 72 65 67 69 73 74 65 72 65 64   Next registered
e570: 20 56 46 53 20 2a 2f 0a 20 20 63 6f 6e 73 74 20   VFS */.  const 
e580: 63 68 61 72 20 2a 7a 4e 61 6d 65 3b 20 20 20 20  char *zName;    
e590: 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68     /* Name of th
e5a0: 69 73 20 76 69 72 74 75 61 6c 20 66 69 6c 65 20  is virtual file 
e5b0: 73 79 73 74 65 6d 20 2a 2f 0a 20 20 76 6f 69 64  system */.  void
e5c0: 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20 20   *pAppData;     
e5d0: 20 20 20 20 20 2f 2a 20 50 6f 69 6e 74 65 72 20       /* Pointer 
e5e0: 74 6f 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73  to application-s
e5f0: 70 65 63 69 66 69 63 20 64 61 74 61 20 2a 2f 0a  pecific data */.
e600: 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29 28 73    int (*xOpen)(s
e610: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
e620: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20  st char *zName, 
e630: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 0a 20  sqlite3_file*,. 
e640: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 69 6e                in
e650: 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 4f  t flags, int *pO
e660: 75 74 46 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20  utFlags);.  int 
e670: 28 2a 78 44 65 6c 65 74 65 29 28 73 71 6c 69 74  (*xDelete)(sqlit
e680: 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63  e3_vfs*, const c
e690: 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20  har *zName, int 
e6a0: 73 79 6e 63 44 69 72 29 3b 0a 20 20 69 6e 74 20  syncDir);.  int 
e6b0: 28 2a 78 41 63 63 65 73 73 29 28 73 71 6c 69 74  (*xAccess)(sqlit
e6c0: 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63  e3_vfs*, const c
e6d0: 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20  har *zName, int 
e6e0: 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 52 65 73  flags, int *pRes
e6f0: 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46  Out);.  int (*xF
e700: 75 6c 6c 50 61 74 68 6e 61 6d 65 29 28 73 71 6c  ullPathname)(sql
e710: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
e720: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e   char *zName, in
e730: 74 20 6e 4f 75 74 2c 20 63 68 61 72 20 2a 7a 4f  t nOut, char *zO
e740: 75 74 29 3b 0a 20 20 76 6f 69 64 20 2a 28 2a 78  ut);.  void *(*x
e750: 44 6c 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f  DlOpen)(sqlite3_
e760: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
e770: 20 2a 7a 46 69 6c 65 6e 61 6d 65 29 3b 0a 20 20   *zFilename);.  
e780: 76 6f 69 64 20 28 2a 78 44 6c 45 72 72 6f 72 29  void (*xDlError)
e790: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69  (sqlite3_vfs*, i
e7a0: 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20 2a  nt nByte, char *
e7b0: 7a 45 72 72 4d 73 67 29 3b 0a 20 20 76 6f 69 64  zErrMsg);.  void
e7c0: 20 28 2a 28 2a 78 44 6c 53 79 6d 29 28 73 71 6c   (*(*xDlSym)(sql
e7d0: 69 74 65 33 5f 76 66 73 2a 2c 76 6f 69 64 2a 2c  ite3_vfs*,void*,
e7e0: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 79   const char *zSy
e7f0: 6d 62 6f 6c 29 29 28 76 6f 69 64 29 3b 0a 20 20  mbol))(void);.  
e800: 76 6f 69 64 20 28 2a 78 44 6c 43 6c 6f 73 65 29  void (*xDlClose)
e810: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 76  (sqlite3_vfs*, v
e820: 6f 69 64 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  oid*);.  int (*x
e830: 52 61 6e 64 6f 6d 6e 65 73 73 29 28 73 71 6c 69  Randomness)(sqli
e840: 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42  te3_vfs*, int nB
e850: 79 74 65 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29  yte, char *zOut)
e860: 3b 0a 20 20 69 6e 74 20 28 2a 78 53 6c 65 65 70  ;.  int (*xSleep
e870: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
e880: 69 6e 74 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73  int microseconds
e890: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 75 72 72  );.  int (*xCurr
e8a0: 65 6e 74 54 69 6d 65 29 28 73 71 6c 69 74 65 33  entTime)(sqlite3
e8b0: 5f 76 66 73 2a 2c 20 64 6f 75 62 6c 65 2a 29 3b  _vfs*, double*);
e8c0: 0a 20 20 69 6e 74 20 28 2a 78 47 65 74 4c 61 73  .  int (*xGetLas
e8d0: 74 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33 5f  tError)(sqlite3_
e8e0: 76 66 73 2a 2c 20 69 6e 74 2c 20 63 68 61 72 20  vfs*, int, char 
e8f0: 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68  *);.  /*.  ** Th
e900: 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20  e methods above 
e910: 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 20 31  are in version 1
e920: 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f 76   of the sqlite_v
e930: 66 73 20 6f 62 6a 65 63 74 0a 20 20 2a 2a 20 64  fs object.  ** d
e940: 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68 6f 73  efinition.  Thos
e950: 65 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 61 72  e that follow ar
e960: 65 20 61 64 64 65 64 20 69 6e 20 76 65 72 73 69  e added in versi
e970: 6f 6e 20 32 20 6f 72 20 6c 61 74 65 72 0a 20 20  on 2 or later.  
e980: 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 43 75 72 72  */.  int (*xCurr
e990: 65 6e 74 54 69 6d 65 49 6e 74 36 34 29 28 73 71  entTimeInt64)(sq
e9a0: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 73 71 6c 69  lite3_vfs*, sqli
e9b0: 74 65 33 5f 69 6e 74 36 34 2a 29 3b 0a 20 20 2f  te3_int64*);.  /
e9c0: 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f  *.  ** The metho
e9d0: 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20  ds above are in 
e9e0: 76 65 72 73 69 6f 6e 73 20 31 20 61 6e 64 20 32  versions 1 and 2
e9f0: 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f 76   of the sqlite_v
ea00: 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a 20  fs object..  ** 
ea10: 54 68 6f 73 65 20 62 65 6c 6f 77 20 61 72 65 20  Those below are 
ea20: 66 6f 72 20 76 65 72 73 69 6f 6e 20 33 20 61 6e  for version 3 an
ea30: 64 20 67 72 65 61 74 65 72 2e 0a 20 20 2a 2f 0a  d greater..  */.
ea40: 20 20 69 6e 74 20 28 2a 78 53 65 74 53 79 73 74    int (*xSetSyst
ea50: 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f  emCall)(sqlite3_
ea60: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
ea70: 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33   *zName, sqlite3
ea80: 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29 3b 0a 20  _syscall_ptr);. 
ea90: 20 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c   sqlite3_syscall
eaa0: 5f 70 74 72 20 28 2a 78 47 65 74 53 79 73 74 65  _ptr (*xGetSyste
eab0: 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76  mCall)(sqlite3_v
eac0: 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  fs*, const char 
ead0: 2a 7a 4e 61 6d 65 29 3b 0a 20 20 63 6f 6e 73 74  *zName);.  const
eae0: 20 63 68 61 72 20 2a 28 2a 78 4e 65 78 74 53 79   char *(*xNextSy
eaf0: 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65  stemCall)(sqlite
eb00: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
eb10: 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 2f 2a  ar *zName);.  /*
eb20: 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64  .  ** The method
eb30: 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20 76  s above are in v
eb40: 65 72 73 69 6f 6e 73 20 31 20 74 68 72 6f 75 67  ersions 1 throug
eb50: 68 20 33 20 6f 66 20 74 68 65 20 73 71 6c 69 74  h 3 of the sqlit
eb60: 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20  e_vfs object..  
eb70: 2a 2a 20 4e 65 77 20 66 69 65 6c 64 73 20 6d 61  ** New fields ma
eb80: 79 20 62 65 20 61 70 70 65 6e 64 65 64 20 69 6e  y be appended in
eb90: 20 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73   future versions
eba0: 2e 20 20 54 68 65 20 69 56 65 72 73 69 6f 6e 0a  .  The iVersion.
ebb0: 20 20 2a 2a 20 76 61 6c 75 65 20 77 69 6c 6c 20    ** value will 
ebc0: 69 6e 63 72 65 6d 65 6e 74 20 77 68 65 6e 65 76  increment whenev
ebd0: 65 72 20 74 68 69 73 20 68 61 70 70 65 6e 73 2e  er this happens.
ebe0: 20 0a 20 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a   .  */.};../*.**
ebf0: 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73   CAPI3REF: Flags
ec00: 20 66 6f 72 20 74 68 65 20 78 41 63 63 65 73 73   for the xAccess
ec10: 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a   VFS method.**.*
ec20: 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20  * These integer 
ec30: 63 6f 6e 73 74 61 6e 74 73 20 63 61 6e 20 62 65  constants can be
ec40: 20 75 73 65 64 20 61 73 20 74 68 65 20 74 68 69   used as the thi
ec50: 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  rd parameter to.
ec60: 2a 2a 20 74 68 65 20 78 41 63 63 65 73 73 20 6d  ** the xAccess m
ec70: 65 74 68 6f 64 20 6f 66 20 61 6e 20 5b 73 71 6c  ethod of an [sql
ec80: 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74  ite3_vfs] object
ec90: 2e 20 20 54 68 65 79 20 64 65 74 65 72 6d 69 6e  .  They determin
eca0: 65 0a 2a 2a 20 77 68 61 74 20 6b 69 6e 64 20 6f  e.** what kind o
ecb0: 66 20 70 65 72 6d 69 73 73 69 6f 6e 73 20 74 68  f permissions th
ecc0: 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64  e xAccess method
ecd0: 20 69 73 20 6c 6f 6f 6b 69 6e 67 20 66 6f 72 2e   is looking for.
ece0: 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f  .** With SQLITE_
ecf0: 41 43 43 45 53 53 5f 45 58 49 53 54 53 2c 20 74  ACCESS_EXISTS, t
ed00: 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f  he xAccess metho
ed10: 64 0a 2a 2a 20 73 69 6d 70 6c 79 20 63 68 65 63  d.** simply chec
ed20: 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20 66  ks whether the f
ed30: 69 6c 65 20 65 78 69 73 74 73 2e 0a 2a 2a 20 57  ile exists..** W
ed40: 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53  ith SQLITE_ACCES
ed50: 53 5f 52 45 41 44 57 52 49 54 45 2c 20 74 68 65  S_READWRITE, the
ed60: 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a   xAccess method.
ed70: 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68 65  ** checks whethe
ed80: 72 20 74 68 65 20 6e 61 6d 65 64 20 64 69 72 65  r the named dire
ed90: 63 74 6f 72 79 20 69 73 20 62 6f 74 68 20 72 65  ctory is both re
eda0: 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74 61  adable and writa
edb0: 62 6c 65 0a 2a 2a 20 28 69 6e 20 6f 74 68 65 72  ble.** (in other
edc0: 20 77 6f 72 64 73 2c 20 69 66 20 66 69 6c 65 73   words, if files
edd0: 20 63 61 6e 20 62 65 20 61 64 64 65 64 2c 20 72   can be added, r
ede0: 65 6d 6f 76 65 64 2c 20 61 6e 64 20 72 65 6e 61  emoved, and rena
edf0: 6d 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68  med within.** th
ee00: 65 20 64 69 72 65 63 74 6f 72 79 29 2e 0a 2a 2a  e directory)..**
ee10: 20 54 68 65 20 53 51 4c 49 54 45 5f 41 43 43 45   The SQLITE_ACCE
ee20: 53 53 5f 52 45 41 44 57 52 49 54 45 20 63 6f 6e  SS_READWRITE con
ee30: 73 74 61 6e 74 20 69 73 20 63 75 72 72 65 6e 74  stant is current
ee40: 6c 79 20 75 73 65 64 20 6f 6e 6c 79 20 62 79 20  ly used only by 
ee50: 74 68 65 0a 2a 2a 20 5b 74 65 6d 70 5f 73 74 6f  the.** [temp_sto
ee60: 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61  re_directory pra
ee70: 67 6d 61 5d 2c 20 74 68 6f 75 67 68 20 74 68 69  gma], though thi
ee80: 73 20 63 6f 75 6c 64 20 63 68 61 6e 67 65 20 69  s could change i
ee90: 6e 20 61 20 66 75 74 75 72 65 0a 2a 2a 20 72 65  n a future.** re
eea0: 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 2e  lease of SQLite.
eeb0: 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f  .** With SQLITE_
eec0: 41 43 43 45 53 53 5f 52 45 41 44 2c 20 74 68 65  ACCESS_READ, the
eed0: 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a   xAccess method.
eee0: 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68 65  ** checks whethe
eef0: 72 20 74 68 65 20 66 69 6c 65 20 69 73 20 72 65  r the file is re
ef00: 61 64 61 62 6c 65 2e 20 20 54 68 65 20 53 51 4c  adable.  The SQL
ef10: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 20  ITE_ACCESS_READ 
ef20: 63 6f 6e 73 74 61 6e 74 20 69 73 0a 2a 2a 20 63  constant is.** c
ef30: 75 72 72 65 6e 74 6c 79 20 75 6e 75 73 65 64 2c  urrently unused,
ef40: 20 74 68 6f 75 67 68 20 69 74 20 6d 69 67 68 74   though it might
ef50: 20 62 65 20 75 73 65 64 20 69 6e 20 61 20 66 75   be used in a fu
ef60: 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66 0a  ture release of.
ef70: 2a 2a 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64  ** SQLite..*/.#d
ef80: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43  efine SQLITE_ACC
ef90: 45 53 53 5f 45 58 49 53 54 53 20 20 20 20 30 0a  ESS_EXISTS    0.
efa0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
efb0: 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 20  CCESS_READWRITE 
efc0: 31 20 20 20 2f 2a 20 55 73 65 64 20 62 79 20 50  1   /* Used by P
efd0: 52 41 47 4d 41 20 74 65 6d 70 5f 73 74 6f 72 65  RAGMA temp_store
efe0: 5f 64 69 72 65 63 74 6f 72 79 20 2a 2f 0a 23 64  _directory */.#d
eff0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43  efine SQLITE_ACC
f000: 45 53 53 5f 52 45 41 44 20 20 20 20 20 20 32 20  ESS_READ      2 
f010: 20 20 2f 2a 20 55 6e 75 73 65 64 20 2a 2f 0a 0a    /* Unused */..
f020: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
f030: 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20 78 53  Flags for the xS
f040: 68 6d 4c 6f 63 6b 20 56 46 53 20 6d 65 74 68 6f  hmLock VFS metho
f050: 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e  d.**.** These in
f060: 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20  teger constants 
f070: 64 65 66 69 6e 65 20 74 68 65 20 76 61 72 69 6f  define the vario
f080: 75 73 20 6c 6f 63 6b 69 6e 67 20 6f 70 65 72 61  us locking opera
f090: 74 69 6f 6e 73 0a 2a 2a 20 61 6c 6c 6f 77 65 64  tions.** allowed
f0a0: 20 62 79 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b   by the xShmLock
f0b0: 20 6d 65 74 68 6f 64 20 6f 66 20 5b 73 71 6c 69   method of [sqli
f0c0: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 2e  te3_io_methods].
f0d0: 20 20 54 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 69    The.** followi
f0e0: 6e 67 20 61 72 65 20 74 68 65 20 6f 6e 6c 79 20  ng are the only 
f0f0: 6c 65 67 61 6c 20 63 6f 6d 62 69 6e 61 74 69 6f  legal combinatio
f100: 6e 73 20 6f 66 20 66 6c 61 67 73 20 74 6f 20 74  ns of flags to t
f110: 68 65 0a 2a 2a 20 78 53 68 6d 4c 6f 63 6b 20 6d  he.** xShmLock m
f120: 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  ethod:.**.** <ul
f130: 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54  >.** <li>  SQLIT
f140: 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c  E_SHM_LOCK | SQL
f150: 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a 2a  ITE_SHM_SHARED.*
f160: 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53  * <li>  SQLITE_S
f170: 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45  HM_LOCK | SQLITE
f180: 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 0a 2a  _SHM_EXCLUSIVE.*
f190: 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53  * <li>  SQLITE_S
f1a0: 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49  HM_UNLOCK | SQLI
f1b0: 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a 2a 2a  TE_SHM_SHARED.**
f1c0: 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48   <li>  SQLITE_SH
f1d0: 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49 54  M_UNLOCK | SQLIT
f1e0: 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 0a  E_SHM_EXCLUSIVE.
f1f0: 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 57  ** </ul>.**.** W
f200: 68 65 6e 20 75 6e 6c 6f 63 6b 69 6e 67 2c 20 74  hen unlocking, t
f210: 68 65 20 73 61 6d 65 20 53 48 41 52 45 44 20 6f  he same SHARED o
f220: 72 20 45 58 43 4c 55 53 49 56 45 20 66 6c 61 67  r EXCLUSIVE flag
f230: 20 6d 75 73 74 20 62 65 20 73 75 70 70 6c 69 65   must be supplie
f240: 64 20 61 73 0a 2a 2a 20 77 61 73 20 67 69 76 65  d as.** was give
f250: 6e 20 6f 6e 20 74 68 65 20 63 6f 72 72 65 73 70  n on the corresp
f260: 6f 6e 64 69 6e 67 20 6c 6f 63 6b 2e 20 20 0a 2a  onding lock.  .*
f270: 2a 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63  *.** The xShmLoc
f280: 6b 20 6d 65 74 68 6f 64 20 63 61 6e 20 74 72 61  k method can tra
f290: 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 65 6e 20  nsition between 
f2a0: 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 53 48 41  unlocked and SHA
f2b0: 52 45 44 20 6f 72 0a 2a 2a 20 62 65 74 77 65 65  RED or.** betwee
f2c0: 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 45  n unlocked and E
f2d0: 58 43 4c 55 53 49 56 45 2e 20 20 49 74 20 63 61  XCLUSIVE.  It ca
f2e0: 6e 6e 6f 74 20 74 72 61 6e 73 69 74 69 6f 6e 20  nnot transition 
f2f0: 62 65 74 77 65 65 6e 20 53 48 41 52 45 44 0a 2a  between SHARED.*
f300: 2a 20 61 6e 64 20 45 58 43 4c 55 53 49 56 45 2e  * and EXCLUSIVE.
f310: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
f320: 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 20 20  TE_SHM_UNLOCK   
f330: 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51      1.#define SQ
f340: 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 20 20  LITE_SHM_LOCK   
f350: 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20        2.#define 
f360: 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45  SQLITE_SHM_SHARE
f370: 44 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e  D       4.#defin
f380: 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43  e SQLITE_SHM_EXC
f390: 4c 55 53 49 56 45 20 20 20 20 38 0a 0a 2f 2a 0a  LUSIVE    8../*.
f3a0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 61 78  ** CAPI3REF: Max
f3b0: 69 6d 75 6d 20 78 53 68 6d 4c 6f 63 6b 20 69 6e  imum xShmLock in
f3c0: 64 65 78 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53  dex.**.** The xS
f3d0: 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f 6e  hmLock method on
f3e0: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
f3f0: 68 6f 64 73 5d 20 6d 61 79 20 75 73 65 20 76 61  hods] may use va
f400: 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20  lues.** between 
f410: 30 20 61 6e 64 20 74 68 69 73 20 75 70 70 65 72  0 and this upper
f420: 20 62 6f 75 6e 64 20 61 73 20 69 74 73 20 22 6f   bound as its "o
f430: 66 66 73 65 74 22 20 61 72 67 75 6d 65 6e 74 2e  ffset" argument.
f440: 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63  .** The SQLite c
f450: 6f 72 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 61  ore will never a
f460: 74 74 65 6d 70 74 20 74 6f 20 61 63 71 75 69 72  ttempt to acquir
f470: 65 20 6f 72 20 72 65 6c 65 61 73 65 20 61 0a 2a  e or release a.*
f480: 2a 20 6c 6f 63 6b 20 6f 75 74 73 69 64 65 20 6f  * lock outside o
f490: 66 20 74 68 69 73 20 72 61 6e 67 65 0a 2a 2f 0a  f this range.*/.
f4a0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
f4b0: 48 4d 5f 4e 4c 4f 43 4b 20 20 20 20 20 20 20 20  HM_NLOCK        
f4c0: 38 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  8.../*.** CAPI3R
f4d0: 45 46 3a 20 49 6e 69 74 69 61 6c 69 7a 65 20 54  EF: Initialize T
f4e0: 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61 72  he SQLite Librar
f4f0: 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  y.**.** ^The sql
f500: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
f510: 29 20 72 6f 75 74 69 6e 65 20 69 6e 69 74 69 61  ) routine initia
f520: 6c 69 7a 65 73 20 74 68 65 0a 2a 2a 20 53 51 4c  lizes the.** SQL
f530: 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20 5e 54  ite library.  ^T
f540: 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  he sqlite3_shutd
f550: 6f 77 6e 28 29 20 72 6f 75 74 69 6e 65 0a 2a 2a  own() routine.**
f560: 20 64 65 61 6c 6c 6f 63 61 74 65 73 20 61 6e 79   deallocates any
f570: 20 72 65 73 6f 75 72 63 65 73 20 74 68 61 74 20   resources that 
f580: 77 65 72 65 20 61 6c 6c 6f 63 61 74 65 64 20 62  were allocated b
f590: 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  y sqlite3_initia
f5a0: 6c 69 7a 65 28 29 2e 0a 2a 2a 20 54 68 65 73 65  lize()..** These
f5b0: 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 64 65   routines are de
f5c0: 73 69 67 6e 65 64 20 74 6f 20 61 69 64 20 69 6e  signed to aid in
f5d0: 20 70 72 6f 63 65 73 73 20 69 6e 69 74 69 61 6c   process initial
f5e0: 69 7a 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 73  ization and.** s
f5f0: 68 75 74 64 6f 77 6e 20 6f 6e 20 65 6d 62 65 64  hutdown on embed
f600: 64 65 64 20 73 79 73 74 65 6d 73 2e 20 20 57 6f  ded systems.  Wo
f610: 72 6b 73 74 61 74 69 6f 6e 20 61 70 70 6c 69 63  rkstation applic
f620: 61 74 69 6f 6e 73 20 75 73 69 6e 67 0a 2a 2a 20  ations using.** 
f630: 53 51 4c 69 74 65 20 6e 6f 72 6d 61 6c 6c 79 20  SQLite normally 
f640: 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 69  do not need to i
f650: 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 6f 66 20  nvoke either of 
f660: 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a  these routines..
f670: 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20  **.** A call to 
f680: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
f690: 7a 65 28 29 20 69 73 20 61 6e 20 22 65 66 66 65  ze() is an "effe
f6a0: 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66 20 69  ctive" call if i
f6b0: 74 20 69 73 0a 2a 2a 20 74 68 65 20 66 69 72 73  t is.** the firs
f6c0: 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f 69  t time sqlite3_i
f6d0: 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69  nitialize() is i
f6e0: 6e 76 6f 6b 65 64 20 64 75 72 69 6e 67 20 74 68  nvoked during th
f6f0: 65 20 6c 69 66 65 74 69 6d 65 20 6f 66 0a 2a 2a  e lifetime of.**
f700: 20 74 68 65 20 70 72 6f 63 65 73 73 2c 20 6f 72   the process, or
f710: 20 69 66 20 69 74 20 69 73 20 74 68 65 20 66 69   if it is the fi
f720: 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33  rst time sqlite3
f730: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73  _initialize() is
f740: 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 66 6f 6c 6c   invoked.** foll
f750: 6f 77 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20  owing a call to 
f760: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
f770: 28 29 2e 20 20 5e 28 4f 6e 6c 79 20 61 6e 20 65  ().  ^(Only an e
f780: 66 66 65 63 74 69 76 65 20 63 61 6c 6c 0a 2a 2a  ffective call.**
f790: 20 6f 66 20 73 71 6c 69 74 65 33 5f 69 6e 69 74   of sqlite3_init
f7a0: 69 61 6c 69 7a 65 28 29 20 64 6f 65 73 20 61 6e  ialize() does an
f7b0: 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e  y initialization
f7c0: 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 63 61 6c  .  All other cal
f7d0: 6c 73 0a 2a 2a 20 61 72 65 20 68 61 72 6d 6c 65  ls.** are harmle
f7e0: 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a  ss no-ops.)^.**.
f7f0: 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c  ** A call to sql
f800: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20  ite3_shutdown() 
f810: 69 73 20 61 6e 20 22 65 66 66 65 63 74 69 76 65  is an "effective
f820: 22 20 63 61 6c 6c 20 69 66 20 69 74 20 69 73 20  " call if it is 
f830: 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 63 61 6c  the first.** cal
f840: 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75  l to sqlite3_shu
f850: 74 64 6f 77 6e 28 29 20 73 69 6e 63 65 20 74 68  tdown() since th
f860: 65 20 6c 61 73 74 20 73 71 6c 69 74 65 33 5f 69  e last sqlite3_i
f870: 6e 69 74 69 61 6c 69 7a 65 28 29 2e 20 20 5e 28  nitialize().  ^(
f880: 4f 6e 6c 79 0a 2a 2a 20 61 6e 20 65 66 66 65 63  Only.** an effec
f890: 74 69 76 65 20 63 61 6c 6c 20 74 6f 20 73 71 6c  tive call to sql
f8a0: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20  ite3_shutdown() 
f8b0: 64 6f 65 73 20 61 6e 79 20 64 65 69 6e 69 74 69  does any deiniti
f8c0: 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 20 41 6c  alization..** Al
f8d0: 6c 20 6f 74 68 65 72 20 76 61 6c 69 64 20 63 61  l other valid ca
f8e0: 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  lls to sqlite3_s
f8f0: 68 75 74 64 6f 77 6e 28 29 20 61 72 65 20 68 61  hutdown() are ha
f900: 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e  rmless no-ops.)^
f910: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
f920: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
f930: 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 68 72  interface is thr
f940: 65 61 64 73 61 66 65 2c 20 62 75 74 20 73 71 6c  eadsafe, but sql
f950: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a  ite3_shutdown().
f960: 2a 2a 20 69 73 20 6e 6f 74 2e 20 20 54 68 65 20  ** is not.  The 
f970: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
f980: 28 29 20 69 6e 74 65 72 66 61 63 65 20 6d 75 73  () interface mus
f990: 74 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64  t only be called
f9a0: 20 66 72 6f 6d 20 61 0a 2a 2a 20 73 69 6e 67 6c   from a.** singl
f9b0: 65 20 74 68 72 65 61 64 2e 20 20 41 6c 6c 20 6f  e thread.  All o
f9c0: 70 65 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f  pen [database co
f9d0: 6e 6e 65 63 74 69 6f 6e 73 5d 20 6d 75 73 74 20  nnections] must 
f9e0: 62 65 20 63 6c 6f 73 65 64 20 61 6e 64 20 61 6c  be closed and al
f9f0: 6c 0a 2a 2a 20 6f 74 68 65 72 20 53 51 4c 69 74  l.** other SQLit
fa00: 65 20 72 65 73 6f 75 72 63 65 73 20 6d 75 73 74  e resources must
fa10: 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20   be deallocated 
fa20: 70 72 69 6f 72 20 74 6f 20 69 6e 76 6f 6b 69 6e  prior to invokin
fa30: 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 68 75  g.** sqlite3_shu
fa40: 74 64 6f 77 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 41  tdown()..**.** A
fa50: 6d 6f 6e 67 20 6f 74 68 65 72 20 74 68 69 6e 67  mong other thing
fa60: 73 2c 20 5e 73 71 6c 69 74 65 33 5f 69 6e 69 74  s, ^sqlite3_init
fa70: 69 61 6c 69 7a 65 28 29 20 77 69 6c 6c 20 69 6e  ialize() will in
fa80: 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  voke.** sqlite3_
fa90: 6f 73 5f 69 6e 69 74 28 29 2e 20 20 53 69 6d 69  os_init().  Simi
faa0: 6c 61 72 6c 79 2c 20 5e 73 71 6c 69 74 65 33 5f  larly, ^sqlite3_
fab0: 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 77 69  shutdown().** wi
fac0: 6c 6c 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65  ll invoke sqlite
fad0: 33 5f 6f 73 5f 65 6e 64 28 29 2e 0a 2a 2a 0a 2a  3_os_end()..**.*
fae0: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69  * ^The sqlite3_i
faf0: 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74  nitialize() rout
fb00: 69 6e 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  ine returns [SQL
fb10: 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65  ITE_OK] on succe
fb20: 73 73 2e 0a 2a 2a 20 5e 49 66 20 66 6f 72 20 73  ss..** ^If for s
fb30: 6f 6d 65 20 72 65 61 73 6f 6e 2c 20 73 71 6c 69  ome reason, sqli
fb40: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
fb50: 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 69 6e   is unable to in
fb60: 69 74 69 61 6c 69 7a 65 0a 2a 2a 20 74 68 65 20  itialize.** the 
fb70: 6c 69 62 72 61 72 79 20 28 70 65 72 68 61 70 73  library (perhaps
fb80: 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20 74 6f   it is unable to
fb90: 20 61 6c 6c 6f 63 61 74 65 20 61 20 6e 65 65 64   allocate a need
fba0: 65 64 20 72 65 73 6f 75 72 63 65 20 73 75 63 68  ed resource such
fbb0: 0a 2a 2a 20 61 73 20 61 20 6d 75 74 65 78 29 20  .** as a mutex) 
fbc0: 69 74 20 72 65 74 75 72 6e 73 20 61 6e 20 5b 65  it returns an [e
fbd0: 72 72 6f 72 20 63 6f 64 65 5d 20 6f 74 68 65 72  rror code] other
fbe0: 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b   than [SQLITE_OK
fbf0: 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  ]..**.** ^The sq
fc00: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
fc10: 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61  () routine is ca
fc20: 6c 6c 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20  lled internally 
fc30: 62 79 20 6d 61 6e 79 20 6f 74 68 65 72 0a 2a 2a  by many other.**
fc40: 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
fc50: 65 73 20 73 6f 20 74 68 61 74 20 61 6e 20 61 70  es so that an ap
fc60: 70 6c 69 63 61 74 69 6f 6e 20 75 73 75 61 6c 6c  plication usuall
fc70: 79 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20  y does not need 
fc80: 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 6c  to.** invoke sql
fc90: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
fca0: 29 20 64 69 72 65 63 74 6c 79 2e 20 20 46 6f 72  ) directly.  For
fcb0: 20 65 78 61 6d 70 6c 65 2c 20 5b 73 71 6c 69 74   example, [sqlit
fcc0: 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 63 61  e3_open()].** ca
fcd0: 6c 6c 73 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  lls sqlite3_init
fce0: 69 61 6c 69 7a 65 28 29 20 73 6f 20 74 68 65 20  ialize() so the 
fcf0: 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77  SQLite library w
fd00: 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63  ill be automatic
fd10: 61 6c 6c 79 0a 2a 2a 20 69 6e 69 74 69 61 6c 69  ally.** initiali
fd20: 7a 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65  zed when [sqlite
fd30: 33 5f 6f 70 65 6e 28 29 5d 20 69 73 20 63 61 6c  3_open()] is cal
fd40: 6c 65 64 20 69 66 20 69 74 20 68 61 73 20 6e 6f  led if it has no
fd50: 74 20 62 65 20 69 6e 69 74 69 61 6c 69 7a 65 64  t be initialized
fd60: 0a 2a 2a 20 61 6c 72 65 61 64 79 2e 20 20 5e 48  .** already.  ^H
fd70: 6f 77 65 76 65 72 2c 20 69 66 20 53 51 4c 69 74  owever, if SQLit
fd80: 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
fd90: 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  th the [SQLITE_O
fda0: 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d 0a 2a 2a  MIT_AUTOINIT].**
fdb0: 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
fdc0: 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 61  tion, then the a
fdd0: 75 74 6f 6d 61 74 69 63 20 63 61 6c 6c 73 20 74  utomatic calls t
fde0: 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  o sqlite3_initia
fdf0: 6c 69 7a 65 28 29 0a 2a 2a 20 61 72 65 20 6f 6d  lize().** are om
fe00: 69 74 74 65 64 20 61 6e 64 20 74 68 65 20 61 70  itted and the ap
fe10: 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 63  plication must c
fe20: 61 6c 6c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  all sqlite3_init
fe30: 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63 74 6c  ialize() directl
fe40: 79 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 75 73  y.** prior to us
fe50: 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51  ing any other SQ
fe60: 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20  Lite interface. 
fe70: 20 46 6f 72 20 6d 61 78 69 6d 75 6d 20 70 6f 72   For maximum por
fe80: 74 61 62 69 6c 69 74 79 2c 0a 2a 2a 20 69 74 20  tability,.** it 
fe90: 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74  is recommended t
fea0: 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  hat applications
feb0: 20 61 6c 77 61 79 73 20 69 6e 76 6f 6b 65 20 73   always invoke s
fec0: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
fed0: 65 28 29 0a 2a 2a 20 64 69 72 65 63 74 6c 79 20  e().** directly 
fee0: 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61  prior to using a
fef0: 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20  ny other SQLite 
ff00: 69 6e 74 65 72 66 61 63 65 2e 20 20 46 75 74 75  interface.  Futu
ff10: 72 65 20 72 65 6c 65 61 73 65 73 0a 2a 2a 20 6f  re releases.** o
ff20: 66 20 53 51 4c 69 74 65 20 6d 61 79 20 72 65 71  f SQLite may req
ff30: 75 69 72 65 20 74 68 69 73 2e 20 20 49 6e 20 6f  uire this.  In o
ff40: 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20  ther words, the 
ff50: 62 65 68 61 76 69 6f 72 20 65 78 68 69 62 69 74  behavior exhibit
ff60: 65 64 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74  ed.** when SQLit
ff70: 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
ff80: 74 68 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  th [SQLITE_OMIT_
ff90: 41 55 54 4f 49 4e 49 54 5d 20 6d 69 67 68 74 20  AUTOINIT] might 
ffa0: 62 65 63 6f 6d 65 20 74 68 65 0a 2a 2a 20 64 65  become the.** de
ffb0: 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20 69  fault behavior i
ffc0: 6e 20 73 6f 6d 65 20 66 75 74 75 72 65 20 72 65  n some future re
ffd0: 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 2e  lease of SQLite.
ffe0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
fff0: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 72 6f 75  e3_os_init() rou
10000 74 69 6e 65 20 64 6f 65 73 20 6f 70 65 72 61 74  tine does operat
10010 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69  ing-system speci
10020 66 69 63 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a  fic.** initializ
10030 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 53 51 4c  ation of the SQL
10040 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20 54 68  ite library.  Th
10050 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  e sqlite3_os_end
10060 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 75 6e  ().** routine un
10070 64 6f 65 73 20 74 68 65 20 65 66 66 65 63 74 20  does the effect 
10080 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  of sqlite3_os_in
10090 69 74 28 29 2e 20 20 54 79 70 69 63 61 6c 20 74  it().  Typical t
100a0 61 73 6b 73 0a 2a 2a 20 70 65 72 66 6f 72 6d 65  asks.** performe
100b0 64 20 62 79 20 74 68 65 73 65 20 72 6f 75 74 69  d by these routi
100c0 6e 65 73 20 69 6e 63 6c 75 64 65 20 61 6c 6c 6f  nes include allo
100d0 63 61 74 69 6f 6e 20 6f 72 20 64 65 61 6c 6c 6f  cation or deallo
100e0 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 73 74 61  cation.** of sta
100f0 74 69 63 20 72 65 73 6f 75 72 63 65 73 2c 20 69  tic resources, i
10100 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66  nitialization of
10110 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c 65   global variable
10120 73 2c 0a 2a 2a 20 73 65 74 74 69 6e 67 20 75 70  s,.** setting up
10130 20 61 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69   a default [sqli
10140 74 65 33 5f 76 66 73 5d 20 6d 6f 64 75 6c 65 2c  te3_vfs] module,
10150 20 6f 72 20 73 65 74 74 69 6e 67 20 75 70 0a 2a   or setting up.*
10160 2a 20 61 20 64 65 66 61 75 6c 74 20 63 6f 6e 66  * a default conf
10170 69 67 75 72 61 74 69 6f 6e 20 75 73 69 6e 67 20  iguration using 
10180 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
10190 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70  )]..**.** The ap
101a0 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64  plication should
101b0 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 65 69   never invoke ei
101c0 74 68 65 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f  ther sqlite3_os_
101d0 69 6e 69 74 28 29 0a 2a 2a 20 6f 72 20 73 71 6c  init().** or sql
101e0 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 64 69  ite3_os_end() di
101f0 72 65 63 74 6c 79 2e 20 20 54 68 65 20 61 70 70  rectly.  The app
10200 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20  lication should 
10210 6f 6e 6c 79 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73  only invoke.** s
10220 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
10230 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  e() and sqlite3_
10240 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 54 68 65  shutdown().  The
10250 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
10260 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  ().** interface 
10270 69 73 20 63 61 6c 6c 65 64 20 61 75 74 6f 6d 61  is called automa
10280 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c 69 74  tically by sqlit
10290 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
102a0 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f  and.** sqlite3_o
102b0 73 5f 65 6e 64 28 29 20 69 73 20 63 61 6c 6c 65  s_end() is calle
102c0 64 20 62 79 20 73 71 6c 69 74 65 33 5f 73 68 75  d by sqlite3_shu
102d0 74 64 6f 77 6e 28 29 2e 20 20 41 70 70 72 6f 70  tdown().  Approp
102e0 72 69 61 74 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65  riate.** impleme
102f0 6e 74 61 74 69 6f 6e 73 20 66 6f 72 20 73 71 6c  ntations for sql
10300 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61  ite3_os_init() a
10310 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  nd sqlite3_os_en
10320 64 28 29 0a 2a 2a 20 61 72 65 20 62 75 69 6c 74  d().** are built
10330 20 69 6e 74 6f 20 53 51 4c 69 74 65 20 77 68 65   into SQLite whe
10340 6e 20 69 74 20 69 73 20 63 6f 6d 70 69 6c 65 64  n it is compiled
10350 20 66 6f 72 20 55 6e 69 78 2c 20 57 69 6e 64 6f   for Unix, Windo
10360 77 73 2c 20 6f 72 20 4f 53 2f 32 2e 0a 2a 2a 20  ws, or OS/2..** 
10370 57 68 65 6e 20 5b 63 75 73 74 6f 6d 20 62 75 69  When [custom bui
10380 6c 64 73 20 7c 20 62 75 69 6c 74 20 66 6f 72 20  lds | built for 
10390 6f 74 68 65 72 20 70 6c 61 74 66 6f 72 6d 73 5d  other platforms]
103a0 0a 2a 2a 20 28 75 73 69 6e 67 20 74 68 65 20 5b  .** (using the [
103b0 53 51 4c 49 54 45 5f 4f 53 5f 4f 54 48 45 52 3d  SQLITE_OS_OTHER=
103c0 31 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a  1] compile-time.
103d0 2a 2a 20 6f 70 74 69 6f 6e 29 20 74 68 65 20 61  ** option) the a
103e0 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
103f0 73 75 70 70 6c 79 20 61 20 73 75 69 74 61 62 6c  supply a suitabl
10400 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
10410 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   for.** sqlite3_
10420 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71  os_init() and sq
10430 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 20  lite3_os_end(). 
10440 20 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d   An application-
10450 73 75 70 70 6c 69 65 64 0a 2a 2a 20 69 6d 70 6c  supplied.** impl
10460 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71  ementation of sq
10470 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20  lite3_os_init() 
10480 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  or sqlite3_os_en
10490 64 28 29 0a 2a 2a 20 6d 75 73 74 20 72 65 74 75  d().** must retu
104a0 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f  rn [SQLITE_OK] o
104b0 6e 20 73 75 63 63 65 73 73 20 61 6e 64 20 73 6f  n success and so
104c0 6d 65 20 6f 74 68 65 72 20 5b 65 72 72 6f 72 20  me other [error 
104d0 63 6f 64 65 5d 20 75 70 6f 6e 0a 2a 2a 20 66 61  code] upon.** fa
104e0 69 6c 75 72 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ilure..*/.int sq
104f0 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
10500 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69  (void);.int sqli
10510 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 76 6f 69  te3_shutdown(voi
10520 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  d);.int sqlite3_
10530 6f 73 5f 69 6e 69 74 28 76 6f 69 64 29 3b 0a 69  os_init(void);.i
10540 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  nt sqlite3_os_en
10550 64 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20  d(void);../*.** 
10560 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67  CAPI3REF: Config
10570 75 72 69 6e 67 20 54 68 65 20 53 51 4c 69 74 65  uring The SQLite
10580 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 54   Library.**.** T
10590 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  he sqlite3_confi
105a0 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73  g() interface is
105b0 20 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 67 6c   used to make gl
105c0 6f 62 61 6c 20 63 6f 6e 66 69 67 75 72 61 74 69  obal configurati
105d0 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f  on.** changes to
105e0 20 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72   SQLite in order
105f0 20 74 6f 20 74 75 6e 65 20 53 51 4c 69 74 65 20   to tune SQLite 
10600 74 6f 20 74 68 65 20 73 70 65 63 69 66 69 63 20  to the specific 
10610 6e 65 65 64 73 20 6f 66 0a 2a 2a 20 74 68 65 20  needs of.** the 
10620 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 54 68  application.  Th
10630 65 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67  e default config
10640 75 72 61 74 69 6f 6e 20 69 73 20 72 65 63 6f 6d  uration is recom
10650 6d 65 6e 64 65 64 20 66 6f 72 20 6d 6f 73 74 0a  mended for most.
10660 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  ** applications 
10670 61 6e 64 20 73 6f 20 74 68 69 73 20 72 6f 75 74  and so this rout
10680 69 6e 65 20 69 73 20 75 73 75 61 6c 6c 79 20 6e  ine is usually n
10690 6f 74 20 6e 65 63 65 73 73 61 72 79 2e 20 20 49  ot necessary.  I
106a0 74 20 69 73 0a 2a 2a 20 70 72 6f 76 69 64 65 64  t is.** provided
106b0 20 74 6f 20 73 75 70 70 6f 72 74 20 72 61 72 65   to support rare
106c0 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 77 69   applications wi
106d0 74 68 20 75 6e 75 73 75 61 6c 20 6e 65 65 64 73  th unusual needs
106e0 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 54 68 65 20 73  ..**.** <b>The s
106f0 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
10700 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74  interface is not
10710 20 74 68 72 65 61 64 73 61 66 65 2e 20 54 68 65   threadsafe. The
10720 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20   application.** 
10730 6d 75 73 74 20 65 6e 73 75 72 65 20 74 68 61 74  must ensure that
10740 20 6e 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65   no other SQLite
10750 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20   interfaces are 
10760 69 6e 76 6f 6b 65 64 20 62 79 20 6f 74 68 65 72  invoked by other
10770 0a 2a 2a 20 74 68 72 65 61 64 73 20 77 68 69 6c  .** threads whil
10780 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  e sqlite3_config
10790 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 3c 2f  () is running.</
107a0 62 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  b>.**.** The sql
107b0 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e  ite3_config() in
107c0 74 65 72 66 61 63 65 0a 2a 2a 20 6d 61 79 20 6f  terface.** may o
107d0 6e 6c 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 70  nly be invoked p
107e0 72 69 6f 72 20 74 6f 20 6c 69 62 72 61 72 79 20  rior to library 
107f0 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 75  initialization u
10800 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  sing.** [sqlite3
10810 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 6f  _initialize()] o
10820 72 20 61 66 74 65 72 20 73 68 75 74 64 6f 77 6e  r after shutdown
10830 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 68 75   by [sqlite3_shu
10840 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 20 5e 49 66  tdown()]..** ^If
10850 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
10860 29 20 69 73 20 63 61 6c 6c 65 64 20 61 66 74 65  ) is called afte
10870 72 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  r [sqlite3_initi
10880 61 6c 69 7a 65 28 29 5d 20 61 6e 64 20 62 65 66  alize()] and bef
10890 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ore.** [sqlite3_
108a0 73 68 75 74 64 6f 77 6e 28 29 5d 20 74 68 65 6e  shutdown()] then
108b0 20 69 74 20 77 69 6c 6c 20 72 65 74 75 72 6e 20   it will return 
108c0 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 2e 0a 2a  SQLITE_MISUSE..*
108d0 2a 20 4e 6f 74 65 2c 20 68 6f 77 65 76 65 72 2c  * Note, however,
108e0 20 74 68 61 74 20 5e 73 71 6c 69 74 65 33 5f 63   that ^sqlite3_c
108f0 6f 6e 66 69 67 28 29 20 63 61 6e 20 62 65 20 63  onfig() can be c
10900 61 6c 6c 65 64 20 61 73 20 70 61 72 74 20 6f 66  alled as part of
10910 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e   the.** implemen
10920 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 61 70 70  tation of an app
10930 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
10940 20 5b 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69   [sqlite3_os_ini
10950 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  t()]..**.** The 
10960 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
10970 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  o sqlite3_config
10980 28 29 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  () is an integer
10990 0a 2a 2a 20 5b 63 6f 6e 66 69 67 75 72 61 74 69  .** [configurati
109a0 6f 6e 20 6f 70 74 69 6f 6e 5d 20 74 68 61 74 20  on option] that 
109b0 64 65 74 65 72 6d 69 6e 65 73 0a 2a 2a 20 77 68  determines.** wh
109c0 61 74 20 70 72 6f 70 65 72 74 79 20 6f 66 20 53  at property of S
109d0 51 4c 69 74 65 20 69 73 20 74 6f 20 62 65 20 63  QLite is to be c
109e0 6f 6e 66 69 67 75 72 65 64 2e 20 20 53 75 62 73  onfigured.  Subs
109f0 65 71 75 65 6e 74 20 61 72 67 75 6d 65 6e 74 73  equent arguments
10a00 0a 2a 2a 20 76 61 72 79 20 64 65 70 65 6e 64 69  .** vary dependi
10a10 6e 67 20 6f 6e 20 74 68 65 20 5b 63 6f 6e 66 69  ng on the [confi
10a20 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d  guration option]
10a30 0a 2a 2a 20 69 6e 20 74 68 65 20 66 69 72 73 74  .** in the first
10a40 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a   argument..**.**
10a50 20 5e 57 68 65 6e 20 61 20 63 6f 6e 66 69 67 75   ^When a configu
10a60 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73  ration option is
10a70 20 73 65 74 2c 20 73 71 6c 69 74 65 33 5f 63 6f   set, sqlite3_co
10a80 6e 66 69 67 28 29 20 72 65 74 75 72 6e 73 20 5b  nfig() returns [
10a90 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 20 5e  SQLITE_OK]..** ^
10aa0 49 66 20 74 68 65 20 6f 70 74 69 6f 6e 20 69 73  If the option is
10ab0 20 75 6e 6b 6e 6f 77 6e 20 6f 72 20 53 51 4c 69   unknown or SQLi
10ac0 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  te is unable to 
10ad0 73 65 74 20 74 68 65 20 6f 70 74 69 6f 6e 0a 2a  set the option.*
10ae0 2a 20 74 68 65 6e 20 74 68 69 73 20 72 6f 75 74  * then this rout
10af0 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 6e 6f  ine returns a no
10b00 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f  n-zero [error co
10b10 64 65 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  de]..*/.int sqli
10b20 74 65 33 5f 63 6f 6e 66 69 67 28 69 6e 74 2c 20  te3_config(int, 
10b30 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ...);../*.** CAP
10b40 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 65  I3REF: Configure
10b50 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
10b60 74 69 6f 6e 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a  tions.** METHOD:
10b70 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54   sqlite3.**.** T
10b80 68 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  he sqlite3_db_co
10b90 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65  nfig() interface
10ba0 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b 65   is used to make
10bb0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a   configuration.*
10bc0 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 61 20 5b  * changes to a [
10bd0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
10be0 69 6f 6e 5d 2e 20 20 54 68 65 20 69 6e 74 65 72  ion].  The inter
10bf0 66 61 63 65 20 69 73 20 73 69 6d 69 6c 61 72 20  face is similar 
10c00 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  to.** [sqlite3_c
10c10 6f 6e 66 69 67 28 29 5d 20 65 78 63 65 70 74 20  onfig()] except 
10c20 74 68 61 74 20 74 68 65 20 63 68 61 6e 67 65 73  that the changes
10c30 20 61 70 70 6c 79 20 74 6f 20 61 20 73 69 6e 67   apply to a sing
10c40 6c 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  le.** [database 
10c50 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 73 70 65  connection] (spe
10c60 63 69 66 69 65 64 20 69 6e 20 74 68 65 20 66 69  cified in the fi
10c70 72 73 74 20 61 72 67 75 6d 65 6e 74 29 2e 0a 2a  rst argument)..*
10c80 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  *.** The second 
10c90 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69  argument to sqli
10ca0 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 44 2c  te3_db_config(D,
10cb0 56 2c 2e 2e 2e 29 20 20 69 73 20 74 68 65 0a 2a  V,...)  is the.*
10cc0 2a 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  * [SQLITE_DBCONF
10cd0 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 7c 20 63  IG_LOOKASIDE | c
10ce0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 76 65 72  onfiguration ver
10cf0 62 5d 20 2d 20 61 6e 20 69 6e 74 65 67 65 72 20  b] - an integer 
10d00 63 6f 64 65 20 0a 2a 2a 20 74 68 61 74 20 69 6e  code .** that in
10d10 64 69 63 61 74 65 73 20 77 68 61 74 20 61 73 70  dicates what asp
10d20 65 63 74 20 6f 66 20 74 68 65 20 5b 64 61 74 61  ect of the [data
10d30 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
10d40 20 69 73 20 62 65 69 6e 67 20 63 6f 6e 66 69 67   is being config
10d50 75 72 65 64 2e 0a 2a 2a 20 53 75 62 73 65 71 75  ured..** Subsequ
10d60 65 6e 74 20 61 72 67 75 6d 65 6e 74 73 20 76 61  ent arguments va
10d70 72 79 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20  ry depending on 
10d80 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  the configuratio
10d90 6e 20 76 65 72 62 2e 0a 2a 2a 0a 2a 2a 20 5e 43  n verb..**.** ^C
10da0 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
10db0 64 62 5f 63 6f 6e 66 69 67 28 29 20 72 65 74 75  db_config() retu
10dc0 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69 66 20  rn SQLITE_OK if 
10dd0 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20 74  and only if.** t
10de0 68 65 20 63 61 6c 6c 20 69 73 20 63 6f 6e 73 69  he call is consi
10df0 64 65 72 65 64 20 73 75 63 63 65 73 73 66 75 6c  dered successful
10e00 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
10e10 5f 64 62 5f 63 6f 6e 66 69 67 28 73 71 6c 69 74  _db_config(sqlit
10e20 65 33 2a 2c 20 69 6e 74 20 6f 70 2c 20 2e 2e 2e  e3*, int op, ...
10e30 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
10e40 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63  EF: Memory Alloc
10e50 61 74 69 6f 6e 20 52 6f 75 74 69 6e 65 73 0a 2a  ation Routines.*
10e60 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65  *.** An instance
10e70 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20   of this object 
10e80 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65  defines the inte
10e90 72 66 61 63 65 20 62 65 74 77 65 65 6e 20 53 51  rface between SQ
10ea0 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 6c 6f 77 2d  Lite.** and low-
10eb0 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c  level memory all
10ec0 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73  ocation routines
10ed0 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 6f 62 6a  ..**.** This obj
10ee0 65 63 74 20 69 73 20 75 73 65 64 20 69 6e 20 6f  ect is used in o
10ef0 6e 6c 79 20 6f 6e 65 20 70 6c 61 63 65 20 69 6e  nly one place in
10f00 20 74 68 65 20 53 51 4c 69 74 65 20 69 6e 74 65   the SQLite inte
10f10 72 66 61 63 65 2e 0a 2a 2a 20 41 20 70 6f 69 6e  rface..** A poin
10f20 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e  ter to an instan
10f30 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63  ce of this objec
10f40 74 20 69 73 20 74 68 65 20 61 72 67 75 6d 65 6e  t is the argumen
10f50 74 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  t to.** [sqlite3
10f60 5f 63 6f 6e 66 69 67 28 29 5d 20 77 68 65 6e 20  _config()] when 
10f70 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  the configuratio
10f80 6e 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 5b  n option is.** [
10f90 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41  SQLITE_CONFIG_MA
10fa0 4c 4c 4f 43 5d 20 6f 72 20 5b 53 51 4c 49 54 45  LLOC] or [SQLITE
10fb0 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f  _CONFIG_GETMALLO
10fc0 43 5d 2e 20 20 0a 2a 2a 20 42 79 20 63 72 65 61  C].  .** By crea
10fd0 74 69 6e 67 20 61 6e 20 69 6e 73 74 61 6e 63 65  ting an instance
10fe0 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 0a   of this object.
10ff0 2a 2a 20 61 6e 64 20 70 61 73 73 69 6e 67 20 69  ** and passing i
11000 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f  t to [sqlite3_co
11010 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f  nfig]([SQLITE_CO
11020 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 29 0a 2a 2a  NFIG_MALLOC]).**
11030 20 64 75 72 69 6e 67 20 63 6f 6e 66 69 67 75 72   during configur
11040 61 74 69 6f 6e 2c 20 61 6e 20 61 70 70 6c 69 63  ation, an applic
11050 61 74 69 6f 6e 20 63 61 6e 20 73 70 65 63 69 66  ation can specif
11060 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65  y an alternative
11070 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  .** memory alloc
11080 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 20  ation subsystem 
11090 66 6f 72 20 53 51 4c 69 74 65 20 74 6f 20 75 73  for SQLite to us
110a0 65 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73  e for all of its
110b0 0a 2a 2a 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f  .** dynamic memo
110c0 72 79 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20  ry needs..**.** 
110d0 4e 6f 74 65 20 74 68 61 74 20 53 51 4c 69 74 65  Note that SQLite
110e0 20 63 6f 6d 65 73 20 77 69 74 68 20 73 65 76 65   comes with seve
110f0 72 61 6c 20 5b 62 75 69 6c 74 2d 69 6e 20 6d 65  ral [built-in me
11100 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73 5d  mory allocators]
11110 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 70 65 72  .** that are per
11120 66 65 63 74 6c 79 20 61 64 65 71 75 61 74 65 20  fectly adequate 
11130 66 6f 72 20 74 68 65 20 6f 76 65 72 77 68 65 6c  for the overwhel
11140 6d 69 6e 67 20 6d 61 6a 6f 72 69 74 79 20 6f 66  ming majority of
11150 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a   applications.**
11160 20 61 6e 64 20 74 68 61 74 20 74 68 69 73 20 6f   and that this o
11170 62 6a 65 63 74 20 69 73 20 6f 6e 6c 79 20 75 73  bject is only us
11180 65 66 75 6c 20 74 6f 20 61 20 74 69 6e 79 20 6d  eful to a tiny m
11190 69 6e 6f 72 69 74 79 20 6f 66 20 61 70 70 6c 69  inority of appli
111a0 63 61 74 69 6f 6e 73 0a 2a 2a 20 77 69 74 68 20  cations.** with 
111b0 73 70 65 63 69 61 6c 69 7a 65 64 20 6d 65 6d 6f  specialized memo
111c0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65  ry allocation re
111d0 71 75 69 72 65 6d 65 6e 74 73 2e 20 20 54 68 69  quirements.  Thi
111e0 73 20 6f 62 6a 65 63 74 20 69 73 0a 2a 2a 20 61  s object is.** a
111f0 6c 73 6f 20 75 73 65 64 20 64 75 72 69 6e 67 20  lso used during 
11200 74 65 73 74 69 6e 67 20 6f 66 20 53 51 4c 69 74  testing of SQLit
11210 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 73 70  e in order to sp
11220 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e 61  ecify an alterna
11230 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61  tive.** memory a
11240 6c 6c 6f 63 61 74 6f 72 20 74 68 61 74 20 73 69  llocator that si
11250 6d 75 6c 61 74 65 73 20 6d 65 6d 6f 72 79 20 6f  mulates memory o
11260 75 74 2d 6f 66 2d 6d 65 6d 6f 72 79 20 63 6f 6e  ut-of-memory con
11270 64 69 74 69 6f 6e 73 20 69 6e 0a 2a 2a 20 6f 72  ditions in.** or
11280 64 65 72 20 74 6f 20 76 65 72 69 66 79 20 74 68  der to verify th
11290 61 74 20 53 51 4c 69 74 65 20 72 65 63 6f 76 65  at SQLite recove
112a0 72 73 20 67 72 61 63 65 66 75 6c 6c 79 20 66 72  rs gracefully fr
112b0 6f 6d 20 73 75 63 68 0a 2a 2a 20 63 6f 6e 64 69  om such.** condi
112c0 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  tions..**.** The
112d0 20 78 4d 61 6c 6c 6f 63 2c 20 78 52 65 61 6c 6c   xMalloc, xReall
112e0 6f 63 2c 20 61 6e 64 20 78 46 72 65 65 20 6d 65  oc, and xFree me
112f0 74 68 6f 64 73 20 6d 75 73 74 20 77 6f 72 6b 20  thods must work 
11300 6c 69 6b 65 20 74 68 65 0a 2a 2a 20 6d 61 6c 6c  like the.** mall
11310 6f 63 28 29 2c 20 72 65 61 6c 6c 6f 63 28 29 20  oc(), realloc() 
11320 61 6e 64 20 66 72 65 65 28 29 20 66 75 6e 63 74  and free() funct
11330 69 6f 6e 73 20 66 72 6f 6d 20 74 68 65 20 73 74  ions from the st
11340 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79  andard C library
11350 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 67 75 61  ..** ^SQLite gua
11360 72 61 6e 74 65 65 73 20 74 68 61 74 20 74 68 65  rantees that the
11370 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
11380 20 74 6f 0a 2a 2a 20 78 52 65 61 6c 6c 6f 63 20   to.** xRealloc 
11390 69 73 20 61 6c 77 61 79 73 20 61 20 76 61 6c 75  is always a valu
113a0 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 61 20  e returned by a 
113b0 70 72 69 6f 72 20 63 61 6c 6c 20 74 6f 20 78 52  prior call to xR
113c0 6f 75 6e 64 75 70 2e 0a 2a 2a 0a 2a 2a 20 78 53  oundup..**.** xS
113d0 69 7a 65 20 73 68 6f 75 6c 64 20 72 65 74 75 72  ize should retur
113e0 6e 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 20  n the allocated 
113f0 73 69 7a 65 20 6f 66 20 61 20 6d 65 6d 6f 72 79  size of a memory
11400 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 70   allocation.** p
11410 72 65 76 69 6f 75 73 6c 79 20 6f 62 74 61 69 6e  reviously obtain
11420 65 64 20 66 72 6f 6d 20 78 4d 61 6c 6c 6f 63 20  ed from xMalloc 
11430 6f 72 20 78 52 65 61 6c 6c 6f 63 2e 20 20 54 68  or xRealloc.  Th
11440 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65  e allocated size
11450 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61 74  .** is always at
11460 20 6c 65 61 73 74 20 61 73 20 62 69 67 20 61 73   least as big as
11470 20 74 68 65 20 72 65 71 75 65 73 74 65 64 20 73   the requested s
11480 69 7a 65 20 62 75 74 20 6d 61 79 20 62 65 20 6c  ize but may be l
11490 61 72 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  arger..**.** The
114a0 20 78 52 6f 75 6e 64 75 70 20 6d 65 74 68 6f 64   xRoundup method
114b0 20 72 65 74 75 72 6e 73 20 77 68 61 74 20 77 6f   returns what wo
114c0 75 6c 64 20 62 65 20 74 68 65 20 61 6c 6c 6f 63  uld be the alloc
114d0 61 74 65 64 20 73 69 7a 65 20 6f 66 0a 2a 2a 20  ated size of.** 
114e0 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  a memory allocat
114f0 69 6f 6e 20 67 69 76 65 6e 20 61 20 70 61 72 74  ion given a part
11500 69 63 75 6c 61 72 20 72 65 71 75 65 73 74 65 64  icular requested
11510 20 73 69 7a 65 2e 20 20 4d 6f 73 74 20 6d 65 6d   size.  Most mem
11520 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72  ory.** allocator
11530 73 20 72 6f 75 6e 64 20 75 70 20 6d 65 6d 6f 72  s round up memor
11540 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 61 74  y allocations at
11550 20 6c 65 61 73 74 20 74 6f 20 74 68 65 20 6e 65   least to the ne
11560 78 74 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 6f  xt multiple.** o
11570 66 20 38 2e 20 20 53 6f 6d 65 20 61 6c 6c 6f 63  f 8.  Some alloc
11580 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20 74  ators round up t
11590 6f 20 61 20 6c 61 72 67 65 72 20 6d 75 6c 74 69  o a larger multi
115a0 70 6c 65 20 6f 72 20 74 6f 20 61 20 70 6f 77 65  ple or to a powe
115b0 72 20 6f 66 20 32 2e 0a 2a 2a 20 45 76 65 72 79  r of 2..** Every
115c0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
115d0 6f 6e 20 72 65 71 75 65 73 74 20 63 6f 6d 69 6e  on request comin
115e0 67 20 69 6e 20 74 68 72 6f 75 67 68 20 5b 73 71  g in through [sq
115f0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 0a  lite3_malloc()].
11600 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72  ** or [sqlite3_r
11610 65 61 6c 6c 6f 63 28 29 5d 20 66 69 72 73 74 20  ealloc()] first 
11620 63 61 6c 6c 73 20 78 52 6f 75 6e 64 75 70 2e 20  calls xRoundup. 
11630 20 49 66 20 78 52 6f 75 6e 64 75 70 20 72 65 74   If xRoundup ret
11640 75 72 6e 73 20 30 2c 20 0a 2a 2a 20 74 68 61 74  urns 0, .** that
11650 20 63 61 75 73 65 73 20 74 68 65 20 63 6f 72 72   causes the corr
11660 65 73 70 6f 6e 64 69 6e 67 20 6d 65 6d 6f 72 79  esponding memory
11670 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 66   allocation to f
11680 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  ail..**.** The x
11690 49 6e 69 74 20 6d 65 74 68 6f 64 20 69 6e 69 74  Init method init
116a0 69 61 6c 69 7a 65 73 20 74 68 65 20 6d 65 6d 6f  ializes the memo
116b0 72 79 20 61 6c 6c 6f 63 61 74 6f 72 2e 20 20 46  ry allocator.  F
116c0 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 69  or example,.** i
116d0 74 20 6d 69 67 68 74 20 61 6c 6c 6f 63 61 74 65  t might allocate
116e0 20 61 6e 79 20 72 65 71 75 69 72 65 20 6d 75 74   any require mut
116f0 65 78 65 73 20 6f 72 20 69 6e 69 74 69 61 6c 69  exes or initiali
11700 7a 65 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61  ze internal data
11710 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 73 2e 20  .** structures. 
11720 20 54 68 65 20 78 53 68 75 74 64 6f 77 6e 20 6d   The xShutdown m
11730 65 74 68 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64  ethod is invoked
11740 20 28 69 6e 64 69 72 65 63 74 6c 79 29 20 62 79   (indirectly) by
11750 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68 75  .** [sqlite3_shu
11760 74 64 6f 77 6e 28 29 5d 20 61 6e 64 20 73 68 6f  tdown()] and sho
11770 75 6c 64 20 64 65 61 6c 6c 6f 63 61 74 65 20 61  uld deallocate a
11780 6e 79 20 72 65 73 6f 75 72 63 65 73 20 61 63 71  ny resources acq
11790 75 69 72 65 64 0a 2a 2a 20 62 79 20 78 49 6e 69  uired.** by xIni
117a0 74 2e 20 20 54 68 65 20 70 41 70 70 44 61 74 61  t.  The pAppData
117b0 20 70 6f 69 6e 74 65 72 20 69 73 20 75 73 65 64   pointer is used
117c0 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 70 61 72   as the only par
117d0 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 78 49 6e  ameter to.** xIn
117e0 69 74 20 61 6e 64 20 78 53 68 75 74 64 6f 77 6e  it and xShutdown
117f0 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 68  ..**.** SQLite h
11800 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c 49 54 45  olds the [SQLITE
11810 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 41  _MUTEX_STATIC_MA
11820 53 54 45 52 5d 20 6d 75 74 65 78 20 77 68 65 6e  STER] mutex when
11830 20 69 74 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 74   it invokes.** t
11840 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 2c  he xInit method,
11850 20 73 6f 20 74 68 65 20 78 49 6e 69 74 20 6d 65   so the xInit me
11860 74 68 6f 64 20 6e 65 65 64 20 6e 6f 74 20 62 65  thod need not be
11870 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 54 68   threadsafe.  Th
11880 65 0a 2a 2a 20 78 53 68 75 74 64 6f 77 6e 20 6d  e.** xShutdown m
11890 65 74 68 6f 64 20 69 73 20 6f 6e 6c 79 20 63 61  ethod is only ca
118a0 6c 6c 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74  lled from [sqlit
118b0 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 73  e3_shutdown()] s
118c0 6f 20 69 74 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74  o it does.** not
118d0 20 6e 65 65 64 20 74 6f 20 62 65 20 74 68 72 65   need to be thre
118e0 61 64 73 61 66 65 20 65 69 74 68 65 72 2e 20 20  adsafe either.  
118f0 46 6f 72 20 61 6c 6c 20 6f 74 68 65 72 20 6d 65  For all other me
11900 74 68 6f 64 73 2c 20 53 51 4c 69 74 65 0a 2a 2a  thods, SQLite.**
11910 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c 49   holds the [SQLI
11920 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f  TE_MUTEX_STATIC_
11930 4d 45 4d 5d 20 6d 75 74 65 78 20 61 73 20 6c 6f  MEM] mutex as lo
11940 6e 67 20 61 73 20 74 68 65 0a 2a 2a 20 5b 53 51  ng as the.** [SQ
11950 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53  LITE_CONFIG_MEMS
11960 54 41 54 55 53 5d 20 63 6f 6e 66 69 67 75 72 61  TATUS] configura
11970 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 74  tion option is t
11980 75 72 6e 65 64 20 6f 6e 20 28 77 68 69 63 68 0a  urned on (which.
11990 2a 2a 20 69 74 20 69 73 20 62 79 20 64 65 66 61  ** it is by defa
119a0 75 6c 74 29 20 61 6e 64 20 73 6f 20 74 68 65 20  ult) and so the 
119b0 6d 65 74 68 6f 64 73 20 61 72 65 20 61 75 74 6f  methods are auto
119c0 6d 61 74 69 63 61 6c 6c 79 20 73 65 72 69 61 6c  matically serial
119d0 69 7a 65 64 2e 0a 2a 2a 20 48 6f 77 65 76 65 72  ized..** However
119e0 2c 20 69 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  , if [SQLITE_CON
119f0 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20 69  FIG_MEMSTATUS] i
11a00 73 20 64 69 73 61 62 6c 65 64 2c 20 74 68 65 6e  s disabled, then
11a10 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 6d 65   the other.** me
11a20 74 68 6f 64 73 20 6d 75 73 74 20 62 65 20 74 68  thods must be th
11a30 72 65 61 64 73 61 66 65 20 6f 72 20 65 6c 73 65  readsafe or else
11a40 20 6d 61 6b 65 20 74 68 65 69 72 20 6f 77 6e 20   make their own 
11a50 61 72 72 61 6e 67 65 6d 65 6e 74 73 20 66 6f 72  arrangements for
11a60 0a 2a 2a 20 73 65 72 69 61 6c 69 7a 61 74 69 6f  .** serializatio
11a70 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  n..**.** SQLite 
11a80 77 69 6c 6c 20 6e 65 76 65 72 20 69 6e 76 6f 6b  will never invok
11a90 65 20 78 49 6e 69 74 28 29 20 6d 6f 72 65 20 74  e xInit() more t
11aa0 68 61 6e 20 6f 6e 63 65 20 77 69 74 68 6f 75 74  han once without
11ab0 20 61 6e 20 69 6e 74 65 72 76 65 6e 69 6e 67 0a   an intervening.
11ac0 2a 2a 20 63 61 6c 6c 20 74 6f 20 78 53 68 75 74  ** call to xShut
11ad0 64 6f 77 6e 28 29 2e 0a 2a 2f 0a 74 79 70 65 64  down()..*/.typed
11ae0 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
11af0 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 73 71  3_mem_methods sq
11b00 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
11b10 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65  s;.struct sqlite
11b20 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 7b 0a  3_mem_methods {.
11b30 20 20 76 6f 69 64 20 2a 28 2a 78 4d 61 6c 6c 6f    void *(*xMallo
11b40 63 29 28 69 6e 74 29 3b 20 20 20 20 20 20 20 20  c)(int);        
11b50 20 2f 2a 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63   /* Memory alloc
11b60 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 2a  ation function *
11b70 2f 0a 20 20 76 6f 69 64 20 28 2a 78 46 72 65 65  /.  void (*xFree
11b80 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20  )(void*);       
11b90 20 20 20 2f 2a 20 46 72 65 65 20 61 20 70 72 69     /* Free a pri
11ba0 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f  or allocation */
11bb0 0a 20 20 76 6f 69 64 20 2a 28 2a 78 52 65 61 6c  .  void *(*xReal
11bc0 6c 6f 63 29 28 76 6f 69 64 2a 2c 69 6e 74 29 3b  loc)(void*,int);
11bd0 20 20 2f 2a 20 52 65 73 69 7a 65 20 61 6e 20 61    /* Resize an a
11be0 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69  llocation */.  i
11bf0 6e 74 20 28 2a 78 53 69 7a 65 29 28 76 6f 69 64  nt (*xSize)(void
11c00 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a  *);           /*
11c10 20 52 65 74 75 72 6e 20 74 68 65 20 73 69 7a 65   Return the size
11c20 20 6f 66 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f   of an allocatio
11c30 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 52 6f  n */.  int (*xRo
11c40 75 6e 64 75 70 29 28 69 6e 74 29 3b 20 20 20 20  undup)(int);    
11c50 20 20 20 20 20 20 2f 2a 20 52 6f 75 6e 64 20 75        /* Round u
11c60 70 20 72 65 71 75 65 73 74 20 73 69 7a 65 20 74  p request size t
11c70 6f 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a  o allocation siz
11c80 65 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 49 6e  e */.  int (*xIn
11c90 69 74 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20  it)(void*);     
11ca0 20 20 20 20 20 20 2f 2a 20 49 6e 69 74 69 61 6c        /* Initial
11cb0 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 61  ize the memory a
11cc0 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f  llocator */.  vo
11cd0 69 64 20 28 2a 78 53 68 75 74 64 6f 77 6e 29 28  id (*xShutdown)(
11ce0 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 2f 2a 20  void*);      /* 
11cf0 44 65 69 6e 69 74 69 61 6c 69 7a 65 20 74 68 65  Deinitialize the
11d00 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
11d10 72 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70  r */.  void *pAp
11d20 70 44 61 74 61 3b 20 20 20 20 20 20 20 20 20 20  pData;          
11d30 20 20 20 20 20 20 2f 2a 20 41 72 67 75 6d 65 6e        /* Argumen
11d40 74 20 74 6f 20 78 49 6e 69 74 28 29 20 61 6e 64  t to xInit() and
11d50 20 78 53 68 75 74 64 6f 77 6e 28 29 20 2a 2f 0a   xShutdown() */.
11d60 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  };../*.** CAPI3R
11d70 45 46 3a 20 43 6f 6e 66 69 67 75 72 61 74 69 6f  EF: Configuratio
11d80 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59  n Options.** KEY
11d90 57 4f 52 44 53 3a 20 7b 63 6f 6e 66 69 67 75 72  WORDS: {configur
11da0 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 7d 0a 2a 2a  ation option}.**
11db0 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61  .** These consta
11dc0 6e 74 73 20 61 72 65 20 74 68 65 20 61 76 61 69  nts are the avai
11dd0 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20 63 6f  lable integer co
11de0 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
11df0 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20  ons that.** can 
11e00 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65  be passed as the
11e10 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
11e20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
11e30 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66  config()] interf
11e40 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63  ace..**.** New c
11e50 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
11e60 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64 65  ions may be adde
11e70 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65  d in future rele
11e80 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a  ases of SQLite..
11e90 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e 66  ** Existing conf
11ea0 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
11eb0 73 20 6d 69 67 68 74 20 62 65 20 64 69 73 63 6f  s might be disco
11ec0 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69 63  ntinued.  Applic
11ed0 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64  ations.** should
11ee0 20 63 68 65 63 6b 20 74 68 65 20 72 65 74 75 72   check the retur
11ef0 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c  n code from [sql
11f00 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 74  ite3_config()] t
11f10 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74  o make sure that
11f20 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f 72  .** the call wor
11f30 6b 65 64 2e 20 20 54 68 65 20 5b 73 71 6c 69 74  ked.  The [sqlit
11f40 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74  e3_config()] int
11f50 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65 74 75  erface will retu
11f60 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f  rn a.** non-zero
11f70 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66   [error code] if
11f80 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 20   a discontinued 
11f90 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64 20 63  or unsupported c
11fa0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
11fb0 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65  ion.** is invoke
11fc0 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a  d..**.** <dl>.**
11fd0 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
11fe0 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 5d 20  _SINGLETHREAD]] 
11ff0 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
12000 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 3c 2f  G_SINGLETHREAD</
12010 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65  dt>.** <dd>There
12020 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74   are no argument
12030 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e  s to this option
12040 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  .  ^This option 
12050 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72  sets the.** [thr
12060 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20  eading mode] to 
12070 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 2e 20 20  Single-thread.  
12080 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20  In other words, 
12090 69 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20 61  it disables.** a
120a0 6c 6c 20 6d 75 74 65 78 69 6e 67 20 61 6e 64 20  ll mutexing and 
120b0 70 75 74 73 20 53 51 4c 69 74 65 20 69 6e 74 6f  puts SQLite into
120c0 20 61 20 6d 6f 64 65 20 77 68 65 72 65 20 69 74   a mode where it
120d0 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 75 73 65   can only be use
120e0 64 0a 2a 2a 20 62 79 20 61 20 73 69 6e 67 6c 65  d.** by a single
120f0 20 74 68 72 65 61 64 2e 20 20 20 5e 49 66 20 53   thread.   ^If S
12100 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
12110 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53  d with.** the [S
12120 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
12130 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44   | SQLITE_THREAD
12140 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d  SAFE=0] compile-
12150 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e  time option then
12160 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f  .** it is not po
12170 73 73 69 62 6c 65 20 74 6f 20 63 68 61 6e 67 65  ssible to change
12180 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e 67 20   the [threading 
12190 6d 6f 64 65 5d 20 66 72 6f 6d 20 69 74 73 20 64  mode] from its d
121a0 65 66 61 75 6c 74 0a 2a 2a 20 76 61 6c 75 65 20  efault.** value 
121b0 6f 66 20 53 69 6e 67 6c 65 2d 74 68 72 65 61 64  of Single-thread
121c0 20 61 6e 64 20 73 6f 20 5b 73 71 6c 69 74 65 33   and so [sqlite3
121d0 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20  _config()] will 
121e0 72 65 74 75 72 6e 20 0a 2a 2a 20 5b 53 51 4c 49  return .** [SQLI
121f0 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c  TE_ERROR] if cal
12200 6c 65 64 20 77 69 74 68 20 74 68 65 20 53 51 4c  led with the SQL
12210 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c  ITE_CONFIG_SINGL
12220 45 54 48 52 45 41 44 0a 2a 2a 20 63 6f 6e 66 69  ETHREAD.** confi
12230 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e  guration option.
12240 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
12250 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54  LITE_CONFIG_MULT
12260 49 54 48 52 45 41 44 5d 5d 20 3c 64 74 3e 53 51  ITHREAD]] <dt>SQ
12270 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54  LITE_CONFIG_MULT
12280 49 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20  ITHREAD</dt>.** 
12290 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f  <dd>There are no
122a0 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68   arguments to th
122b0 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69  is option.  ^Thi
122c0 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68  s option sets th
122d0 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20  e.** [threading 
122e0 6d 6f 64 65 5d 20 74 6f 20 4d 75 6c 74 69 2d 74  mode] to Multi-t
122f0 68 72 65 61 64 2e 20 20 49 6e 20 6f 74 68 65 72  hread.  In other
12300 20 77 6f 72 64 73 2c 20 69 74 20 64 69 73 61 62   words, it disab
12310 6c 65 73 0a 2a 2a 20 6d 75 74 65 78 69 6e 67 20  les.** mutexing 
12320 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  on [database con
12330 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72  nection] and [pr
12340 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
12350 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 54 68  ] objects..** Th
12360 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73  e application is
12370 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72   responsible for
12380 20 73 65 72 69 61 6c 69 7a 69 6e 67 20 61 63 63   serializing acc
12390 65 73 73 20 74 6f 0a 2a 2a 20 5b 64 61 74 61 62  ess to.** [datab
123a0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d  ase connections]
123b0 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73   and [prepared s
123c0 74 61 74 65 6d 65 6e 74 73 5d 2e 20 20 42 75 74  tatements].  But
123d0 20 6f 74 68 65 72 20 6d 75 74 65 78 65 73 0a 2a   other mutexes.*
123e0 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20 73 6f  * are enabled so
123f0 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c   that SQLite wil
12400 6c 20 62 65 20 73 61 66 65 20 74 6f 20 75 73 65  l be safe to use
12410 20 69 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72 65   in a multi-thre
12420 61 64 65 64 0a 2a 2a 20 65 6e 76 69 72 6f 6e 6d  aded.** environm
12430 65 6e 74 20 61 73 20 6c 6f 6e 67 20 61 73 20 6e  ent as long as n
12440 6f 20 74 77 6f 20 74 68 72 65 61 64 73 20 61 74  o two threads at
12450 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68 65  tempt to use the
12460 20 73 61 6d 65 0a 2a 2a 20 5b 64 61 74 61 62 61   same.** [databa
12470 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61  se connection] a
12480 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 2e  t the same time.
12490 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20    ^If SQLite is 
124a0 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
124b0 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
124c0 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45  EADSAFE | SQLITE
124d0 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63  _THREADSAFE=0] c
124e0 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
124f0 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73  on then.** it is
12500 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f   not possible to
12510 20 73 65 74 20 74 68 65 20 4d 75 6c 74 69 2d 74   set the Multi-t
12520 68 72 65 61 64 20 5b 74 68 72 65 61 64 69 6e 67  hread [threading
12530 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73   mode] and.** [s
12540 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
12550 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51   will return [SQ
12560 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63  LITE_ERROR] if c
12570 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a  alled with the.*
12580 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  * SQLITE_CONFIG_
12590 4d 55 4c 54 49 54 48 52 45 41 44 20 63 6f 6e 66  MULTITHREAD conf
125a0 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
125b0 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  .</dd>.**.** [[S
125c0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52  QLITE_CONFIG_SER
125d0 49 41 4c 49 5a 45 44 5d 5d 20 3c 64 74 3e 53 51  IALIZED]] <dt>SQ
125e0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49  LITE_CONFIG_SERI
125f0 41 4c 49 5a 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c  ALIZED</dt>.** <
12600 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20  dd>There are no 
12610 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69  arguments to thi
12620 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73  s option.  ^This
12630 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65   option sets the
12640 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  .** [threading m
12650 6f 64 65 5d 20 74 6f 20 53 65 72 69 61 6c 69 7a  ode] to Serializ
12660 65 64 2e 20 49 6e 20 6f 74 68 65 72 20 77 6f 72  ed. In other wor
12670 64 73 2c 20 74 68 69 73 20 6f 70 74 69 6f 6e 20  ds, this option 
12680 65 6e 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d  enables.** all m
12690 75 74 65 78 65 73 20 69 6e 63 6c 75 64 69 6e 67  utexes including
126a0 20 74 68 65 20 72 65 63 75 72 73 69 76 65 0a 2a   the recursive.*
126b0 2a 20 6d 75 74 65 78 65 73 20 6f 6e 20 5b 64 61  * mutexes on [da
126c0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
126d0 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64  n] and [prepared
126e0 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65   statement] obje
126f0 63 74 73 2e 0a 2a 2a 20 49 6e 20 74 68 69 73 20  cts..** In this 
12700 6d 6f 64 65 20 28 77 68 69 63 68 20 69 73 20 74  mode (which is t
12710 68 65 20 64 65 66 61 75 6c 74 20 77 68 65 6e 20  he default when 
12720 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
12730 65 64 20 77 69 74 68 0a 2a 2a 20 5b 53 51 4c 49  ed with.** [SQLI
12740 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 31 5d  TE_THREADSAFE=1]
12750 29 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62  ) the SQLite lib
12760 72 61 72 79 20 77 69 6c 6c 20 69 74 73 65 6c 66  rary will itself
12770 20 73 65 72 69 61 6c 69 7a 65 20 61 63 63 65 73   serialize acces
12780 73 0a 2a 2a 20 74 6f 20 5b 64 61 74 61 62 61 73  s.** to [databas
12790 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61  e connections] a
127a0 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  nd [prepared sta
127b0 74 65 6d 65 6e 74 73 5d 20 73 6f 20 74 68 61 74  tements] so that
127c0 20 74 68 65 0a 2a 2a 20 61 70 70 6c 69 63 61 74   the.** applicat
127d0 69 6f 6e 20 69 73 20 66 72 65 65 20 74 6f 20 75  ion is free to u
127e0 73 65 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74  se the same [dat
127f0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
12800 5d 20 6f 72 20 74 68 65 0a 2a 2a 20 73 61 6d 65  ] or the.** same
12810 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
12820 6d 65 6e 74 5d 20 69 6e 20 64 69 66 66 65 72 65  ment] in differe
12830 6e 74 20 74 68 72 65 61 64 73 20 61 74 20 74 68  nt threads at th
12840 65 20 73 61 6d 65 20 74 69 6d 65 2e 0a 2a 2a 20  e same time..** 
12850 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f  ^If SQLite is co
12860 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74  mpiled with.** t
12870 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  he [SQLITE_THREA
12880 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54  DSAFE | SQLITE_T
12890 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d  HREADSAFE=0] com
128a0 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
128b0 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e   then.** it is n
128c0 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 73  ot possible to s
128d0 65 74 20 74 68 65 20 53 65 72 69 61 6c 69 7a 65  et the Serialize
128e0 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  d [threading mod
128f0 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  e] and.** [sqlit
12900 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c  e3_config()] wil
12910 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  l return [SQLITE
12920 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65  _ERROR] if calle
12930 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 51  d with the.** SQ
12940 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49  LITE_CONFIG_SERI
12950 41 4c 49 5a 45 44 20 63 6f 6e 66 69 67 75 72 61  ALIZED configura
12960 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64  tion option.</dd
12970 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
12980 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 5d  _CONFIG_MALLOC]]
12990 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
129a0 49 47 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a  IG_MALLOC</dt>.*
129b0 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c  * <dd> ^(The SQL
129c0 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f  ITE_CONFIG_MALLO
129d0 43 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  C option takes a
129e0 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
129f0 20 77 68 69 63 68 20 69 73 20 0a 2a 2a 20 61 20   which is .** a 
12a00 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
12a10 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73  stance of the [s
12a20 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
12a30 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 0a 2a  ds] structure..*
12a40 2a 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 73  * The argument s
12a50 70 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65  pecifies.** alte
12a60 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65  rnative low-leve
12a70 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  l memory allocat
12a80 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 74 6f 20  ion routines to 
12a90 62 65 20 75 73 65 64 20 69 6e 20 70 6c 61 63 65  be used in place
12aa0 20 6f 66 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72   of.** the memor
12ab0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75  y allocation rou
12ac0 74 69 6e 65 73 20 62 75 69 6c 74 20 69 6e 74 6f  tines built into
12ad0 20 53 51 4c 69 74 65 2e 29 5e 20 5e 53 51 4c 69   SQLite.)^ ^SQLi
12ae0 74 65 20 6d 61 6b 65 73 0a 2a 2a 20 69 74 73 20  te makes.** its 
12af0 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79  own private copy
12b00 20 6f 66 20 74 68 65 20 63 6f 6e 74 65 6e 74 20   of the content 
12b10 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
12b20 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72  mem_methods] str
12b30 75 63 74 75 72 65 0a 2a 2a 20 62 65 66 6f 72 65  ucture.** before
12b40 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   the [sqlite3_co
12b50 6e 66 69 67 28 29 5d 20 63 61 6c 6c 20 72 65 74  nfig()] call ret
12b60 75 72 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  urns.</dd>.**.**
12b70 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
12b80 5f 47 45 54 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74  _GETMALLOC]] <dt
12b90 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47  >SQLITE_CONFIG_G
12ba0 45 54 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a  ETMALLOC</dt>.**
12bb0 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49   <dd> ^(The SQLI
12bc0 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c  TE_CONFIG_GETMAL
12bd0 4c 4f 43 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  LOC option takes
12be0 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65   a single argume
12bf0 6e 74 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 61  nt which.** is a
12c00 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
12c10 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b  nstance of the [
12c20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
12c30 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 0a  ods] structure..
12c40 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** The [sqlite3_
12c50 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20  mem_methods].** 
12c60 73 74 72 75 63 74 75 72 65 20 69 73 20 66 69 6c  structure is fil
12c70 6c 65 64 20 77 69 74 68 20 74 68 65 20 63 75 72  led with the cur
12c80 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 6d  rently defined m
12c90 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
12ca0 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20   routines.)^.** 
12cb0 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20  This option can 
12cc0 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72 6c  be used to overl
12cd0 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c 74 20  oad the default 
12ce0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
12cf0 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 69  n.** routines wi
12d00 74 68 20 61 20 77 72 61 70 70 65 72 20 74 68 61  th a wrapper tha
12d10 74 20 73 69 6d 75 6c 61 74 69 6f 6e 73 20 6d 65  t simulations me
12d20 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
12d30 66 61 69 6c 75 72 65 20 6f 72 0a 2a 2a 20 74 72  failure or.** tr
12d40 61 63 6b 73 20 6d 65 6d 6f 72 79 20 75 73 61 67  acks memory usag
12d50 65 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20  e, for example. 
12d60 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
12d70 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53  LITE_CONFIG_MEMS
12d80 54 41 54 55 53 5d 5d 20 3c 64 74 3e 53 51 4c 49  TATUS]] <dt>SQLI
12d90 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41  TE_CONFIG_MEMSTA
12da0 54 55 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  TUS</dt>.** <dd>
12db0 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e   ^The SQLITE_CON
12dc0 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 20 6f 70  FIG_MEMSTATUS op
12dd0 74 69 6f 6e 20 74 61 6b 65 73 20 73 69 6e 67 6c  tion takes singl
12de0 65 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 79  e argument of ty
12df0 70 65 20 69 6e 74 2c 0a 2a 2a 20 69 6e 74 65 72  pe int,.** inter
12e00 70 72 65 74 65 64 20 61 73 20 61 20 62 6f 6f 6c  preted as a bool
12e10 65 61 6e 2c 20 77 68 69 63 68 20 65 6e 61 62 6c  ean, which enabl
12e20 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74  es or disables t
12e30 68 65 20 63 6f 6c 6c 65 63 74 69 6f 6e 20 6f 66  he collection of
12e40 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  .** memory alloc
12e50 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73  ation statistics
12e60 2e 20 5e 28 57 68 65 6e 20 6d 65 6d 6f 72 79 20  . ^(When memory 
12e70 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69  allocation stati
12e80 73 74 69 63 73 20 61 72 65 0a 2a 2a 20 64 69 73  stics are.** dis
12e90 61 62 6c 65 64 2c 20 74 68 65 20 66 6f 6c 6c 6f  abled, the follo
12ea0 77 69 6e 67 20 53 51 4c 69 74 65 20 69 6e 74 65  wing SQLite inte
12eb0 72 66 61 63 65 73 20 62 65 63 6f 6d 65 20 6e 6f  rfaces become no
12ec0 6e 2d 6f 70 65 72 61 74 69 6f 6e 61 6c 3a 0a 2a  n-operational:.*
12ed0 2a 20 20 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c  *   <ul>.**   <l
12ee0 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  i> [sqlite3_memo
12ef0 72 79 5f 75 73 65 64 28 29 5d 0a 2a 2a 20 20 20  ry_used()].**   
12f00 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65  <li> [sqlite3_me
12f10 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29  mory_highwater()
12f20 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c  ].**   <li> [sql
12f30 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c  ite3_soft_heap_l
12f40 69 6d 69 74 36 34 28 29 5d 0a 2a 2a 20 20 20 3c  imit64()].**   <
12f50 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 74 61  li> [sqlite3_sta
12f60 74 75 73 36 34 28 29 5d 0a 2a 2a 20 20 20 3c 2f  tus64()].**   </
12f70 75 6c 3e 29 5e 0a 2a 2a 20 5e 4d 65 6d 6f 72 79  ul>)^.** ^Memory
12f80 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74   allocation stat
12f90 69 73 74 69 63 73 20 61 72 65 20 65 6e 61 62 6c  istics are enabl
12fa0 65 64 20 62 79 20 64 65 66 61 75 6c 74 20 75 6e  ed by default un
12fb0 6c 65 73 73 20 53 51 4c 69 74 65 20 69 73 0a 2a  less SQLite is.*
12fc0 2a 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20  * compiled with 
12fd0 5b 53 51 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f  [SQLITE_DEFAULT_
12fe0 4d 45 4d 53 54 41 54 55 53 5d 3d 30 20 69 6e 20  MEMSTATUS]=0 in 
12ff0 77 68 69 63 68 20 63 61 73 65 20 6d 65 6d 6f 72  which case memor
13000 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  y.** allocation 
13010 73 74 61 74 69 73 74 69 63 73 20 61 72 65 20 64  statistics are d
13020 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75  isabled by defau
13030 6c 74 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a  lt..** </dd>.**.
13040 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
13050 49 47 5f 53 43 52 41 54 43 48 5d 5d 20 3c 64 74  IG_SCRATCH]] <dt
13060 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  >SQLITE_CONFIG_S
13070 43 52 41 54 43 48 3c 2f 64 74 3e 0a 2a 2a 20 3c  CRATCH</dt>.** <
13080 64 64 3e 20 5e 54 68 65 20 53 51 4c 49 54 45 5f  dd> ^The SQLITE_
13090 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 20 6f  CONFIG_SCRATCH o
130a0 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20  ption specifies 
130b0 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20  a static memory 
130c0 62 75 66 66 65 72 0a 2a 2a 20 74 68 61 74 20 53  buffer.** that S
130d0 51 4c 69 74 65 20 63 61 6e 20 75 73 65 20 66 6f  QLite can use fo
130e0 72 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79  r scratch memory
130f0 2e 20 20 5e 28 54 68 65 72 65 20 61 72 65 20 74  .  ^(There are t
13100 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 0a 2a  hree arguments.*
13110 2a 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46  * to SQLITE_CONF
13120 49 47 5f 53 43 52 41 54 43 48 3a 20 20 41 20 70  IG_SCRATCH:  A p
13130 6f 69 6e 74 65 72 20 61 6e 20 38 2d 62 79 74 65  ointer an 8-byte
13140 0a 2a 2a 20 61 6c 69 67 6e 65 64 20 6d 65 6d 6f  .** aligned memo
13150 72 79 20 62 75 66 66 65 72 20 66 72 6f 6d 20 77  ry buffer from w
13160 68 69 63 68 20 74 68 65 20 73 63 72 61 74 63 68  hich the scratch
13170 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 77 69 6c   allocations wil
13180 6c 20 62 65 0a 2a 2a 20 64 72 61 77 6e 2c 20 74  l be.** drawn, t
13190 68 65 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20  he size of each 
131a0 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 69  scratch allocati
131b0 6f 6e 20 28 73 7a 29 2c 0a 2a 2a 20 61 6e 64 20  on (sz),.** and 
131c0 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  the maximum numb
131d0 65 72 20 6f 66 20 73 63 72 61 74 63 68 20 61 6c  er of scratch al
131e0 6c 6f 63 61 74 69 6f 6e 73 20 28 4e 29 2e 29 5e  locations (N).)^
131f0 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72  .** The first ar
13200 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 61  gument must be a
13210 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 38   pointer to an 8
13220 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20 62 75  -byte aligned bu
13230 66 66 65 72 0a 2a 2a 20 6f 66 20 61 74 20 6c 65  ffer.** of at le
13240 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f  ast sz*N bytes o
13250 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 51  f memory..** ^SQ
13260 4c 69 74 65 20 77 69 6c 6c 20 6e 6f 74 20 75 73  Lite will not us
13270 65 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20  e more than one 
13280 73 63 72 61 74 63 68 20 62 75 66 66 65 72 73 20  scratch buffers 
13290 70 65 72 20 74 68 72 65 61 64 2e 0a 2a 2a 20 5e  per thread..** ^
132a0 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 65  SQLite will neve
132b0 72 20 72 65 71 75 65 73 74 20 61 20 73 63 72 61  r request a scra
132c0 74 63 68 20 62 75 66 66 65 72 20 74 68 61 74 20  tch buffer that 
132d0 69 73 20 6d 6f 72 65 20 74 68 61 6e 20 36 0a 2a  is more than 6.*
132e0 2a 20 74 69 6d 65 73 20 74 68 65 20 64 61 74 61  * times the data
132f0 62 61 73 65 20 70 61 67 65 20 73 69 7a 65 2e 0a  base page size..
13300 2a 2a 20 5e 49 66 20 53 51 4c 69 74 65 20 6e 65  ** ^If SQLite ne
13310 65 64 73 20 6e 65 65 64 73 20 61 64 64 69 74 69  eds needs additi
13320 6f 6e 61 6c 0a 2a 2a 20 73 63 72 61 74 63 68 20  onal.** scratch 
13330 6d 65 6d 6f 72 79 20 62 65 79 6f 6e 64 20 77 68  memory beyond wh
13340 61 74 20 69 73 20 70 72 6f 76 69 64 65 64 20 62  at is provided b
13350 79 20 74 68 69 73 20 63 6f 6e 66 69 67 75 72 61  y this configura
13360 74 69 6f 6e 20 6f 70 74 69 6f 6e 2c 20 74 68 65  tion option, the
13370 6e 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  n .** [sqlite3_m
13380 61 6c 6c 6f 63 28 29 5d 20 77 69 6c 6c 20 62 65  alloc()] will be
13390 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20   used to obtain 
133a0 74 68 65 20 6d 65 6d 6f 72 79 20 6e 65 65 64 65  the memory neede
133b0 64 2e 3c 70 3e 0a 2a 2a 20 5e 57 68 65 6e 20 74  d.<p>.** ^When t
133c0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 70  he application p
133d0 72 6f 76 69 64 65 73 20 61 6e 79 20 61 6d 6f 75  rovides any amou
133e0 6e 74 20 6f 66 20 73 63 72 61 74 63 68 20 6d 65  nt of scratch me
133f0 6d 6f 72 79 20 75 73 69 6e 67 0a 2a 2a 20 53 51  mory using.** SQ
13400 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41  LITE_CONFIG_SCRA
13410 54 43 48 2c 20 53 51 4c 69 74 65 20 61 76 6f 69  TCH, SQLite avoi
13420 64 73 20 75 6e 6e 65 63 65 73 73 61 72 79 20 6c  ds unnecessary l
13430 61 72 67 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  arge.** [sqlite3
13440 5f 6d 61 6c 6c 6f 63 7c 68 65 61 70 20 61 6c 6c  _malloc|heap all
13450 6f 63 61 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68  ocations]..** Th
13460 69 73 20 63 61 6e 20 68 65 6c 70 20 5b 52 6f 62  is can help [Rob
13470 73 6f 6e 20 70 72 6f 6f 66 7c 70 72 65 76 65 6e  son proof|preven
13480 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  t memory allocat
13490 69 6f 6e 20 66 61 69 6c 75 72 65 73 5d 20 64 75  ion failures] du
134a0 65 20 74 6f 20 68 65 61 70 0a 2a 2a 20 66 72 61  e to heap.** fra
134b0 67 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 20 6c 6f  gmentation in lo
134c0 77 2d 6d 65 6d 6f 72 79 20 65 6d 62 65 64 64 65  w-memory embedde
134d0 64 20 73 79 73 74 65 6d 73 2e 0a 2a 2a 20 3c 2f  d systems..** </
134e0 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
134f0 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41  TE_CONFIG_PAGECA
13500 43 48 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  CHE]] <dt>SQLITE
13510 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48  _CONFIG_PAGECACH
13520 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  E</dt>.** <dd> ^
13530 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
13540 47 5f 50 41 47 45 43 41 43 48 45 20 6f 70 74 69  G_PAGECACHE opti
13550 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 20 6d  on specifies a m
13560 65 6d 6f 72 79 20 70 6f 6f 6c 0a 2a 2a 20 74 68  emory pool.** th
13570 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20 75 73  at SQLite can us
13580 65 20 66 6f 72 20 74 68 65 20 64 61 74 61 62 61  e for the databa
13590 73 65 20 70 61 67 65 20 63 61 63 68 65 20 77 69  se page cache wi
135a0 74 68 20 74 68 65 20 64 65 66 61 75 6c 74 20 70  th the default p
135b0 61 67 65 0a 2a 2a 20 63 61 63 68 65 20 69 6d 70  age.** cache imp
135c0 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 0a 2a  lementation.  .*
135d0 2a 20 54 68 69 73 20 63 6f 6e 66 69 67 75 72 61  * This configura
135e0 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 61  tion option is a
135f0 20 6e 6f 2d 6f 70 20 69 66 20 61 6e 20 61 70 70   no-op if an app
13600 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 20  lication-define 
13610 70 61 67 65 0a 2a 2a 20 63 61 63 68 65 20 69 6d  page.** cache im
13620 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20  plementation is 
13630 6c 6f 61 64 65 64 20 75 73 69 6e 67 20 74 68 65  loaded using the
13640 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
13650 50 43 41 43 48 45 32 5d 2e 0a 2a 2a 20 5e 54 68  PCACHE2]..** ^Th
13660 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72  ere are three ar
13670 67 75 6d 65 6e 74 73 20 74 6f 20 53 51 4c 49 54  guments to SQLIT
13680 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43  E_CONFIG_PAGECAC
13690 48 45 3a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f  HE: A pointer to
136a0 0a 2a 2a 20 38 2d 62 79 74 65 20 61 6c 69 67 6e  .** 8-byte align
136b0 65 64 20 6d 65 6d 6f 72 79 20 28 70 4d 65 6d 29  ed memory (pMem)
136c0 2c 20 74 68 65 20 73 69 7a 65 20 6f 66 20 65 61  , the size of ea
136d0 63 68 20 70 61 67 65 20 63 61 63 68 65 20 6c 69  ch page cache li
136e0 6e 65 20 28 73 7a 29 2c 0a 2a 2a 20 61 6e 64 20  ne (sz),.** and 
136f0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 61  the number of ca
13700 63 68 65 20 6c 69 6e 65 73 20 28 4e 29 2e 0a 2a  che lines (N)..*
13710 2a 20 54 68 65 20 73 7a 20 61 72 67 75 6d 65 6e  * The sz argumen
13720 74 20 73 68 6f 75 6c 64 20 62 65 20 74 68 65 20  t should be the 
13730 73 69 7a 65 20 6f 66 20 74 68 65 20 6c 61 72 67  size of the larg
13740 65 73 74 20 64 61 74 61 62 61 73 65 20 70 61 67  est database pag
13750 65 0a 2a 2a 20 28 61 20 70 6f 77 65 72 20 6f 66  e.** (a power of
13760 20 74 77 6f 20 62 65 74 77 65 65 6e 20 35 31 32   two between 512
13770 20 61 6e 64 20 36 35 35 33 36 29 20 70 6c 75 73   and 65536) plus
13780 20 73 6f 6d 65 20 65 78 74 72 61 20 62 79 74 65   some extra byte
13790 73 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 70 61  s for each.** pa
137a0 67 65 20 68 65 61 64 65 72 2e 20 20 5e 54 68 65  ge header.  ^The
137b0 20 6e 75 6d 62 65 72 20 6f 66 20 65 78 74 72 61   number of extra
137c0 20 62 79 74 65 73 20 6e 65 65 64 65 64 20 62 79   bytes needed by
137d0 20 74 68 65 20 70 61 67 65 20 68 65 61 64 65 72   the page header
137e0 0a 2a 2a 20 63 61 6e 20 62 65 20 64 65 74 65 72  .** can be deter
137f0 6d 69 6e 65 64 20 75 73 69 6e 67 20 5b 53 51 4c  mined using [SQL
13800 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48  ITE_CONFIG_PCACH
13810 45 5f 48 44 52 53 5a 5d 2e 0a 2a 2a 20 5e 49 74  E_HDRSZ]..** ^It
13820 20 69 73 20 68 61 72 6d 6c 65 73 73 2c 20 61 70   is harmless, ap
13830 61 72 74 20 66 72 6f 6d 20 74 68 65 20 77 61 73  art from the was
13840 74 65 64 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 66  ted memory,.** f
13850 6f 72 20 74 68 65 20 73 7a 20 70 61 72 61 6d 65  or the sz parame
13860 74 65 72 20 74 6f 20 62 65 20 6c 61 72 67 65 72  ter to be larger
13870 20 74 68 61 6e 20 6e 65 63 65 73 73 61 72 79 2e   than necessary.
13880 20 20 54 68 65 20 70 4d 65 6d 0a 2a 2a 20 61 72    The pMem.** ar
13890 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 65  gument must be e
138a0 69 74 68 65 72 20 61 20 4e 55 4c 4c 20 70 6f 69  ither a NULL poi
138b0 6e 74 65 72 20 6f 72 20 61 20 70 6f 69 6e 74 65  nter or a pointe
138c0 72 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 0a 2a  r to an 8-byte.*
138d0 2a 20 61 6c 69 67 6e 65 64 20 62 6c 6f 63 6b 20  * aligned block 
138e0 6f 66 20 6d 65 6d 6f 72 79 20 6f 66 20 61 74 20  of memory of at 
138f0 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 73  least sz*N bytes
13900 2c 20 6f 74 68 65 72 77 69 73 65 0a 2a 2a 20 73  , otherwise.** s
13910 75 62 73 65 71 75 65 6e 74 20 62 65 68 61 76 69  ubsequent behavi
13920 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  or is undefined.
13930 0a 2a 2a 20 5e 57 68 65 6e 20 70 4d 65 6d 20 69  .** ^When pMem i
13940 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 53 51 4c 69  s not NULL, SQLi
13950 74 65 20 77 69 6c 6c 20 73 74 72 69 76 65 20 74  te will strive t
13960 6f 20 75 73 65 20 74 68 65 20 6d 65 6d 6f 72 79  o use the memory
13970 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 74 6f 20   provided.** to 
13980 73 61 74 69 73 66 79 20 70 61 67 65 20 63 61 63  satisfy page cac
13990 68 65 20 6e 65 65 64 73 2c 20 66 61 6c 6c 69 6e  he needs, fallin
139a0 67 20 62 61 63 6b 20 74 6f 20 5b 73 71 6c 69 74  g back to [sqlit
139b0 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69 66 0a  e3_malloc()] if.
139c0 2a 2a 20 61 20 70 61 67 65 20 63 61 63 68 65 20  ** a page cache 
139d0 6c 69 6e 65 20 69 73 20 6c 61 72 67 65 72 20 74  line is larger t
139e0 68 61 6e 20 73 7a 20 62 79 74 65 73 20 6f 72 20  han sz bytes or 
139f0 69 66 20 61 6c 6c 20 6f 66 20 74 68 65 20 70 4d  if all of the pM
13a00 65 6d 20 62 75 66 66 65 72 0a 2a 2a 20 69 73 20  em buffer.** is 
13a10 65 78 68 61 75 73 74 65 64 2e 0a 2a 2a 20 5e 49  exhausted..** ^I
13a20 66 20 70 4d 65 6d 20 69 73 20 4e 55 4c 4c 20 61  f pMem is NULL a
13a30 6e 64 20 4e 20 69 73 20 6e 6f 6e 2d 7a 65 72 6f  nd N is non-zero
13a40 2c 20 74 68 65 6e 20 65 61 63 68 20 64 61 74 61  , then each data
13a50 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a  base connection.
13a60 2a 2a 20 64 6f 65 73 20 61 6e 20 69 6e 69 74 69  ** does an initi
13a70 61 6c 20 62 75 6c 6b 20 61 6c 6c 6f 63 61 74 69  al bulk allocati
13a80 6f 6e 20 66 6f 72 20 70 61 67 65 20 63 61 63 68  on for page cach
13a90 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 66 72 6f 6d  e memory.** from
13aa0 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
13ab0 28 29 5d 20 73 75 66 66 69 63 69 65 6e 74 20 66  ()] sufficient f
13ac0 6f 72 20 4e 20 63 61 63 68 65 20 6c 69 6e 65 73  or N cache lines
13ad0 20 69 66 20 4e 20 69 73 20 70 6f 73 69 74 69 76   if N is positiv
13ae0 65 20 6f 72 0a 2a 2a 20 6f 66 20 2d 31 30 32 34  e or.** of -1024
13af0 2a 4e 20 62 79 74 65 73 20 69 66 20 4e 20 69 73  *N bytes if N is
13b00 20 6e 65 67 61 74 69 76 65 2c 20 2e 20 5e 49 66   negative, . ^If
13b10 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 70   additional.** p
13b20 61 67 65 20 63 61 63 68 65 20 6d 65 6d 6f 72 79  age cache memory
13b30 20 69 73 20 6e 65 65 64 65 64 20 62 65 79 6f 6e   is needed beyon
13b40 64 20 77 68 61 74 20 69 73 20 70 72 6f 76 69 64  d what is provid
13b50 65 64 20 62 79 20 74 68 65 20 69 6e 69 74 69 61  ed by the initia
13b60 6c 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c  l.** allocation,
13b70 20 74 68 65 6e 20 53 51 4c 69 74 65 20 67 6f 65   then SQLite goe
13b80 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61  s to [sqlite3_ma
13b90 6c 6c 6f 63 28 29 5d 20 73 65 70 61 72 61 74 65  lloc()] separate
13ba0 6c 79 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 61  ly for each.** a
13bb0 64 64 69 74 69 6f 6e 61 6c 20 63 61 63 68 65 20  dditional cache 
13bc0 6c 69 6e 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a  line. </dd>.**.*
13bd0 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
13be0 47 5f 48 45 41 50 5d 5d 20 3c 64 74 3e 53 51 4c  G_HEAP]] <dt>SQL
13bf0 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 3c  ITE_CONFIG_HEAP<
13c00 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68  /dt>.** <dd> ^Th
13c10 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
13c20 48 45 41 50 20 6f 70 74 69 6f 6e 20 73 70 65 63  HEAP option spec
13c30 69 66 69 65 73 20 61 20 73 74 61 74 69 63 20 6d  ifies a static m
13c40 65 6d 6f 72 79 20 62 75 66 66 65 72 20 0a 2a 2a  emory buffer .**
13c50 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c   that SQLite wil
13c60 6c 20 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66  l use for all of
13c70 20 69 74 73 20 64 79 6e 61 6d 69 63 20 6d 65 6d   its dynamic mem
13c80 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e  ory allocation n
13c90 65 65 64 73 0a 2a 2a 20 62 65 79 6f 6e 64 20 74  eeds.** beyond t
13ca0 68 6f 73 65 20 70 72 6f 76 69 64 65 64 20 66 6f  hose provided fo
13cb0 72 20 62 79 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  r by [SQLITE_CON
13cc0 46 49 47 5f 53 43 52 41 54 43 48 5d 20 61 6e 64  FIG_SCRATCH] and
13cd0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  .** [SQLITE_CONF
13ce0 49 47 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a  IG_PAGECACHE]..*
13cf0 2a 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f  * ^The SQLITE_CO
13d00 4e 46 49 47 5f 48 45 41 50 20 6f 70 74 69 6f 6e  NFIG_HEAP option
13d10 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62   is only availab
13d20 6c 65 20 69 66 20 53 51 4c 69 74 65 20 69 73 20  le if SQLite is 
13d30 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 77 69 74 68  compiled.** with
13d40 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f   either [SQLITE_
13d50 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 33 5d 20  ENABLE_MEMSYS3] 
13d60 6f 72 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c  or [SQLITE_ENABL
13d70 45 5f 4d 45 4d 53 59 53 35 5d 20 61 6e 64 20 72  E_MEMSYS5] and r
13d80 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54  eturns.** [SQLIT
13d90 45 5f 45 52 52 4f 52 5d 20 69 66 20 69 6e 76 6f  E_ERROR] if invo
13da0 6b 65 64 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a  ked otherwise..*
13db0 2a 20 5e 54 68 65 72 65 20 61 72 65 20 74 68 72  * ^There are thr
13dc0 65 65 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20  ee arguments to 
13dd0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45  SQLITE_CONFIG_HE
13de0 41 50 3a 0a 2a 2a 20 41 6e 20 38 2d 62 79 74 65  AP:.** An 8-byte
13df0 20 61 6c 69 67 6e 65 64 20 70 6f 69 6e 74 65 72   aligned pointer
13e00 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79 2c 0a   to the memory,.
13e10 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ** the number of
13e20 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 6d 65   bytes in the me
13e30 6d 6f 72 79 20 62 75 66 66 65 72 2c 20 61 6e 64  mory buffer, and
13e40 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c   the minimum all
13e50 6f 63 61 74 69 6f 6e 20 73 69 7a 65 2e 0a 2a 2a  ocation size..**
13e60 20 5e 49 66 20 74 68 65 20 66 69 72 73 74 20 70   ^If the first p
13e70 6f 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f  ointer (the memo
13e80 72 79 20 70 6f 69 6e 74 65 72 29 20 69 73 20 4e  ry pointer) is N
13e90 55 4c 4c 2c 20 74 68 65 6e 20 53 51 4c 69 74 65  ULL, then SQLite
13ea0 20 72 65 76 65 72 74 73 0a 2a 2a 20 74 6f 20 75   reverts.** to u
13eb0 73 69 6e 67 20 69 74 73 20 64 65 66 61 75 6c 74  sing its default
13ec0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
13ed0 72 20 28 74 68 65 20 73 79 73 74 65 6d 20 6d 61  r (the system ma
13ee0 6c 6c 6f 63 28 29 20 69 6d 70 6c 65 6d 65 6e 74  lloc() implement
13ef0 61 74 69 6f 6e 29 2c 0a 2a 2a 20 75 6e 64 6f 69  ation),.** undoi
13f00 6e 67 20 61 6e 79 20 70 72 69 6f 72 20 69 6e 76  ng any prior inv
13f10 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 53 51 4c 49  ocation of [SQLI
13f20 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43  TE_CONFIG_MALLOC
13f30 5d 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 6d  ].  ^If the.** m
13f40 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 20 69 73  emory pointer is
13f50 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 74   not NULL then t
13f60 68 65 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6d  he alternative m
13f70 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74  emory.** allocat
13f80 6f 72 20 69 73 20 65 6e 67 61 67 65 64 20 74 6f  or is engaged to
13f90 20 68 61 6e 64 6c 65 20 61 6c 6c 20 6f 66 20 53   handle all of S
13fa0 51 4c 69 74 65 73 20 6d 65 6d 6f 72 79 20 61 6c  QLites memory al
13fb0 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 0a  location needs..
13fc0 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 6f 69  ** The first poi
13fd0 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 79  nter (the memory
13fe0 20 70 6f 69 6e 74 65 72 29 20 6d 75 73 74 20 62   pointer) must b
13ff0 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20  e aligned to an 
14000 38 2d 62 79 74 65 0a 2a 2a 20 62 6f 75 6e 64 61  8-byte.** bounda
14010 72 79 20 6f 72 20 73 75 62 73 65 71 75 65 6e 74  ry or subsequent
14020 20 62 65 68 61 76 69 6f 72 20 6f 66 20 53 51 4c   behavior of SQL
14030 69 74 65 20 77 69 6c 6c 20 62 65 20 75 6e 64 65  ite will be unde
14040 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 6d 69  fined..** The mi
14050 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e  nimum allocation
14060 20 73 69 7a 65 20 69 73 20 63 61 70 70 65 64 20   size is capped 
14070 61 74 20 32 2a 2a 31 32 2e 20 52 65 61 73 6f 6e  at 2**12. Reason
14080 61 62 6c 65 20 76 61 6c 75 65 73 0a 2a 2a 20 66  able values.** f
14090 6f 72 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61  or the minimum a
140a0 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 61  llocation size a
140b0 72 65 20 32 2a 2a 35 20 74 68 72 6f 75 67 68 20  re 2**5 through 
140c0 32 2a 2a 38 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  2**8.</dd>.**.**
140d0 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
140e0 5f 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c  _MUTEX]] <dt>SQL
140f0 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58  ITE_CONFIG_MUTEX
14100 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28  </dt>.** <dd> ^(
14110 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
14120 47 5f 4d 55 54 45 58 20 6f 70 74 69 6f 6e 20 74  G_MUTEX option t
14130 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72  akes a single ar
14140 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20  gument which is 
14150 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20  a.** pointer to 
14160 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  an instance of t
14170 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  he [sqlite3_mute
14180 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63  x_methods] struc
14190 74 75 72 65 2e 0a 2a 2a 20 54 68 65 20 61 72 67  ture..** The arg
141a0 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73 20  ument specifies 
141b0 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d  alternative low-
141c0 6c 65 76 65 6c 20 6d 75 74 65 78 20 72 6f 75 74  level mutex rout
141d0 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65 64 0a  ines to be used.
141e0 2a 2a 20 69 6e 20 70 6c 61 63 65 20 74 68 65 20  ** in place the 
141f0 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20 62  mutex routines b
14200 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65  uilt into SQLite
14210 2e 29 5e 20 20 5e 53 51 4c 69 74 65 20 6d 61 6b  .)^  ^SQLite mak
14220 65 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20  es a copy of.** 
14230 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74  the content of t
14240 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  he [sqlite3_mute
14250 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63  x_methods] struc
14260 74 75 72 65 20 62 65 66 6f 72 65 20 74 68 65 20  ture before the 
14270 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  call to.** [sqli
14280 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 72 65  te3_config()] re
14290 74 75 72 6e 73 2e 20 5e 49 66 20 53 51 4c 69 74  turns. ^If SQLit
142a0 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
142b0 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54  th.** the [SQLIT
142c0 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53  E_THREADSAFE | S
142d0 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
142e0 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  =0] compile-time
142f0 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20   option then.** 
14300 74 68 65 20 65 6e 74 69 72 65 20 6d 75 74 65 78  the entire mutex
14310 69 6e 67 20 73 75 62 73 79 73 74 65 6d 20 69 73  ing subsystem is
14320 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68   omitted from th
14330 65 20 62 75 69 6c 64 20 61 6e 64 20 68 65 6e 63  e build and henc
14340 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73  e calls to.** [s
14350 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
14360 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45   with the SQLITE
14370 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 63 6f  _CONFIG_MUTEX co
14380 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
14390 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72  on will.** retur
143a0 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  n [SQLITE_ERROR]
143b0 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  .</dd>.**.** [[S
143c0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
143d0 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c 49  MUTEX]] <dt>SQLI
143e0 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54  TE_CONFIG_GETMUT
143f0 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  EX</dt>.** <dd> 
14400 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  ^(The SQLITE_CON
14410 46 49 47 5f 47 45 54 4d 55 54 45 58 20 6f 70 74  FIG_GETMUTEX opt
14420 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
14430 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63  le argument whic
14440 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74 65  h.** is a pointe
14450 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65  r to an instance
14460 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
14470 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20  _mutex_methods] 
14480 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 0a  structure.  The.
14490 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  ** [sqlite3_mute
144a0 78 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74  x_methods].** st
144b0 72 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c 65  ructure is fille
144c0 64 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65  d with the curre
144d0 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 75 74  ntly defined mut
144e0 65 78 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a  ex routines.)^.*
144f0 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61  * This option ca
14500 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65  n be used to ove
14510 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c  rload the defaul
14520 74 20 6d 75 74 65 78 20 61 6c 6c 6f 63 61 74 69  t mutex allocati
14530 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77  on.** routines w
14540 69 74 68 20 61 20 77 72 61 70 70 65 72 20 75 73  ith a wrapper us
14550 65 64 20 74 6f 20 74 72 61 63 6b 20 6d 75 74 65  ed to track mute
14560 78 20 75 73 61 67 65 20 66 6f 72 20 70 65 72 66  x usage for perf
14570 6f 72 6d 61 6e 63 65 0a 2a 2a 20 70 72 6f 66 69  ormance.** profi
14580 6c 69 6e 67 20 6f 72 20 74 65 73 74 69 6e 67 2c  ling or testing,
14590 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20 20 20   for example.   
145a0 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f  ^If SQLite is co
145b0 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74  mpiled with.** t
145c0 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  he [SQLITE_THREA
145d0 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54  DSAFE | SQLITE_T
145e0 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d  HREADSAFE=0] com
145f0 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
14600 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74   then.** the ent
14610 69 72 65 20 6d 75 74 65 78 69 6e 67 20 73 75 62  ire mutexing sub
14620 73 79 73 74 65 6d 20 69 73 20 6f 6d 69 74 74 65  system is omitte
14630 64 20 66 72 6f 6d 20 74 68 65 20 62 75 69 6c 64  d from the build
14640 20 61 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c 73   and hence calls
14650 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
14660 63 6f 6e 66 69 67 28 29 5d 20 77 69 74 68 20 74  config()] with t
14670 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
14680 5f 47 45 54 4d 55 54 45 58 20 63 6f 6e 66 69 67  _GETMUTEX config
14690 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77  uration option w
146a0 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53  ill.** return [S
146b0 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64  QLITE_ERROR].</d
146c0 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
146d0 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  E_CONFIG_LOOKASI
146e0 44 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  DE]] <dt>SQLITE_
146f0 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
14700 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28  </dt>.** <dd> ^(
14710 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
14720 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 6f 70 74 69  G_LOOKASIDE opti
14730 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20 61 72 67  on takes two arg
14740 75 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74 65  uments that dete
14750 72 6d 69 6e 65 0a 2a 2a 20 74 68 65 20 64 65 66  rmine.** the def
14760 61 75 6c 74 20 73 69 7a 65 20 6f 66 20 6c 6f 6f  ault size of loo
14770 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 6f 6e  kaside memory on
14780 20 65 61 63 68 20 5b 64 61 74 61 62 61 73 65 20   each [database 
14790 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20  connection]..** 
147a0 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
147b0 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a  nt is the.** siz
147c0 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73  e of each lookas
147d0 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74 20  ide buffer slot 
147e0 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 69  and the second i
147f0 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a  s the number of.
14800 2a 2a 20 73 6c 6f 74 73 20 61 6c 6c 6f 63 61 74  ** slots allocat
14810 65 64 20 74 6f 20 65 61 63 68 20 64 61 74 61 62  ed to each datab
14820 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 29  ase connection.)
14830 5e 20 20 5e 28 53 51 4c 49 54 45 5f 43 4f 4e 46  ^  ^(SQLITE_CONF
14840 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 0a 2a 2a 20  IG_LOOKASIDE.** 
14850 73 65 74 73 20 74 68 65 20 3c 69 3e 64 65 66 61  sets the <i>defa
14860 75 6c 74 3c 2f 69 3e 20 6c 6f 6f 6b 61 73 69 64  ult</i> lookasid
14870 65 20 73 69 7a 65 2e 20 54 68 65 20 5b 53 51 4c  e size. The [SQL
14880 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f  ITE_DBCONFIG_LOO
14890 4b 41 53 49 44 45 5d 0a 2a 2a 20 6f 70 74 69 6f  KASIDE].** optio
148a0 6e 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62  n to [sqlite3_db
148b0 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61 6e 20 62  _config()] can b
148c0 65 20 75 73 65 64 20 74 6f 20 63 68 61 6e 67 65  e used to change
148d0 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a   the lookaside.*
148e0 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  * configuration 
148f0 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c 20 63 6f  on individual co
14900 6e 6e 65 63 74 69 6f 6e 73 2e 29 5e 20 3c 2f 64  nnections.)^ </d
14910 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
14920 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32  E_CONFIG_PCACHE2
14930 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
14940 4e 46 49 47 5f 50 43 41 43 48 45 32 3c 2f 64 74  NFIG_PCACHE2</dt
14950 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20  >.** <dd> ^(The 
14960 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
14970 41 43 48 45 32 20 6f 70 74 69 6f 6e 20 74 61 6b  ACHE2 option tak
14980 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  es a single argu
14990 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 0a 2a  ment which is .*
149a0 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  * a pointer to a
149b0 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68  n [sqlite3_pcach
149c0 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65  e_methods2] obje
149d0 63 74 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 74  ct.  This object
149e0 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 74 68   specifies.** th
149f0 65 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20 61  e interface to a
14a00 20 63 75 73 74 6f 6d 20 70 61 67 65 20 63 61 63   custom page cac
14a10 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
14a20 6e 2e 29 5e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  n.)^.** ^SQLite 
14a30 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20  makes a copy of 
14a40 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 63 61  the [sqlite3_pca
14a50 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62  che_methods2] ob
14a60 6a 65 63 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ject.</dd>.**.**
14a70 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
14a80 5f 47 45 54 50 43 41 43 48 45 32 5d 5d 20 3c 64  _GETPCACHE2]] <d
14a90 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
14aa0 47 45 54 50 43 41 43 48 45 32 3c 2f 64 74 3e 0a  GETPCACHE2</dt>.
14ab0 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51  ** <dd> ^(The SQ
14ac0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50  LITE_CONFIG_GETP
14ad0 43 41 43 48 45 32 20 6f 70 74 69 6f 6e 20 74 61  CACHE2 option ta
14ae0 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67  kes a single arg
14af0 75 6d 65 6e 74 20 77 68 69 63 68 0a 2a 2a 20 69  ument which.** i
14b00 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
14b10 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68  n [sqlite3_pcach
14b20 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65  e_methods2] obje
14b30 63 74 2e 20 20 53 51 4c 69 74 65 20 63 6f 70 69  ct.  SQLite copi
14b40 65 73 20 6f 66 0a 2a 2a 20 74 68 65 20 63 75 72  es of.** the cur
14b50 72 65 6e 74 20 70 61 67 65 20 63 61 63 68 65 20  rent page cache 
14b60 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69  implementation i
14b70 6e 74 6f 20 74 68 61 74 20 6f 62 6a 65 63 74 2e  nto that object.
14b80 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  )^ </dd>.**.** [
14b90 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c  [SQLITE_CONFIG_L
14ba0 4f 47 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  OG]] <dt>SQLITE_
14bb0 43 4f 4e 46 49 47 5f 4c 4f 47 3c 2f 64 74 3e 0a  CONFIG_LOG</dt>.
14bc0 2a 2a 20 3c 64 64 3e 20 54 68 65 20 53 51 4c 49  ** <dd> The SQLI
14bd0 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70  TE_CONFIG_LOG op
14be0 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20  tion is used to 
14bf0 63 6f 6e 66 69 67 75 72 65 20 74 68 65 20 53 51  configure the SQ
14c00 4c 69 74 65 0a 2a 2a 20 67 6c 6f 62 61 6c 20 5b  Lite.** global [
14c10 65 72 72 6f 72 20 6c 6f 67 5d 2e 0a 2a 2a 20 28  error log]..** (
14c20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  ^The SQLITE_CONF
14c30 49 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20 74 61  IG_LOG option ta
14c40 6b 65 73 20 74 77 6f 20 61 72 67 75 6d 65 6e 74  kes two argument
14c50 73 3a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  s: a pointer to 
14c60 61 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 69  a.** function wi
14c70 74 68 20 61 20 63 61 6c 6c 20 73 69 67 6e 61 74  th a call signat
14c80 75 72 65 20 6f 66 20 76 6f 69 64 28 2a 29 28 76  ure of void(*)(v
14c90 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63  oid*,int,const c
14ca0 68 61 72 2a 29 2c 20 0a 2a 2a 20 61 6e 64 20 61  har*), .** and a
14cb0 20 70 6f 69 6e 74 65 72 20 74 6f 20 76 6f 69 64   pointer to void
14cc0 2e 20 5e 49 66 20 74 68 65 20 66 75 6e 63 74 69  . ^If the functi
14cd0 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f  on pointer is no
14ce0 74 20 4e 55 4c 4c 2c 20 69 74 20 69 73 0a 2a 2a  t NULL, it is.**
14cf0 20 69 6e 76 6f 6b 65 64 20 62 79 20 5b 73 71 6c   invoked by [sql
14d00 69 74 65 33 5f 6c 6f 67 28 29 5d 20 74 6f 20 70  ite3_log()] to p
14d10 72 6f 63 65 73 73 20 65 61 63 68 20 6c 6f 67 67  rocess each logg
14d20 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 66 20  ing event.  ^If 
14d30 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  the.** function 
14d40 70 6f 69 6e 74 65 72 20 69 73 20 4e 55 4c 4c 2c  pointer is NULL,
14d50 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f   the [sqlite3_lo
14d60 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 62  g()] interface b
14d70 65 63 6f 6d 65 73 20 61 20 6e 6f 2d 6f 70 2e 0a  ecomes a no-op..
14d80 2a 2a 20 5e 54 68 65 20 76 6f 69 64 20 70 6f 69  ** ^The void poi
14d90 6e 74 65 72 20 74 68 61 74 20 69 73 20 74 68 65  nter that is the
14da0 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
14db0 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49   to SQLITE_CONFI
14dc0 47 5f 4c 4f 47 20 69 73 0a 2a 2a 20 70 61 73 73  G_LOG is.** pass
14dd0 65 64 20 74 68 72 6f 75 67 68 20 61 73 20 74 68  ed through as th
14de0 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
14df0 72 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61  r to the applica
14e00 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67  tion-defined log
14e10 67 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ger.** function 
14e20 77 68 65 6e 65 76 65 72 20 74 68 61 74 20 66 75  whenever that fu
14e30 6e 63 74 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65  nction is invoke
14e40 64 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e 64 20  d.  ^The second 
14e50 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20  parameter to.** 
14e60 74 68 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 74  the logger funct
14e70 69 6f 6e 20 69 73 20 61 20 63 6f 70 79 20 6f 66  ion is a copy of
14e80 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   the first param
14e90 65 74 65 72 20 74 6f 20 74 68 65 20 63 6f 72 72  eter to the corr
14ea0 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 5b 73 71  esponding.** [sq
14eb0 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 63 61 6c  lite3_log()] cal
14ec0 6c 20 61 6e 64 20 69 73 20 69 6e 74 65 6e 64 65  l and is intende
14ed0 64 20 74 6f 20 62 65 20 61 20 5b 72 65 73 75 6c  d to be a [resul
14ee0 74 20 63 6f 64 65 5d 20 6f 72 20 61 6e 0a 2a 2a  t code] or an.**
14ef0 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c   [extended resul
14f00 74 20 63 6f 64 65 5d 2e 20 20 5e 54 68 65 20 74  t code].  ^The t
14f10 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 70  hird parameter p
14f20 61 73 73 65 64 20 74 6f 20 74 68 65 20 6c 6f 67  assed to the log
14f30 67 65 72 20 69 73 0a 2a 2a 20 6c 6f 67 20 6d 65  ger is.** log me
14f40 73 73 61 67 65 20 61 66 74 65 72 20 66 6f 72 6d  ssage after form
14f50 61 74 74 69 6e 67 20 76 69 61 20 5b 73 71 6c 69  atting via [sqli
14f60 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 2e  te3_snprintf()].
14f70 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 6c  .** The SQLite l
14f80 6f 67 67 69 6e 67 20 69 6e 74 65 72 66 61 63 65  ogging interface
14f90 20 69 73 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e   is not reentran
14fa0 74 3b 20 74 68 65 20 6c 6f 67 67 65 72 20 66 75  t; the logger fu
14fb0 6e 63 74 69 6f 6e 0a 2a 2a 20 73 75 70 70 6c 69  nction.** suppli
14fc0 65 64 20 62 79 20 74 68 65 20 61 70 70 6c 69 63  ed by the applic
14fd0 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 69  ation must not i
14fe0 6e 76 6f 6b 65 20 61 6e 79 20 53 51 4c 69 74 65  nvoke any SQLite
14ff0 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 49   interface..** I
15000 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 64  n a multi-thread
15010 65 64 20 61 70 70 6c 69 63 61 74 69 6f 6e 2c 20  ed application, 
15020 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
15030 64 65 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a  defined logger.*
15040 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20  * function must 
15050 62 65 20 74 68 72 65 61 64 73 61 66 65 2e 20 3c  be threadsafe. <
15060 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
15070 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 5d  ITE_CONFIG_URI]]
15080 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
15090 49 47 5f 55 52 49 0a 2a 2a 20 3c 64 64 3e 5e 28  IG_URI.** <dd>^(
150a0 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
150b0 47 5f 55 52 49 20 6f 70 74 69 6f 6e 20 74 61 6b  G_URI option tak
150c0 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  es a single argu
150d0 6d 65 6e 74 20 6f 66 20 74 79 70 65 20 69 6e 74  ment of type int
150e0 2e 0a 2a 2a 20 49 66 20 6e 6f 6e 2d 7a 65 72 6f  ..** If non-zero
150f0 2c 20 74 68 65 6e 20 55 52 49 20 68 61 6e 64 6c  , then URI handl
15100 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20  ing is globally 
15110 65 6e 61 62 6c 65 64 2e 20 49 66 20 74 68 65 20  enabled. If the 
15120 70 61 72 61 6d 65 74 65 72 20 69 73 20 7a 65 72  parameter is zer
15130 6f 2c 0a 2a 2a 20 74 68 65 6e 20 55 52 49 20 68  o,.** then URI h
15140 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61  andling is globa
15150 6c 6c 79 20 64 69 73 61 62 6c 65 64 2e 29 5e 20  lly disabled.)^ 
15160 5e 49 66 20 55 52 49 20 68 61 6e 64 6c 69 6e 67  ^If URI handling
15170 20 69 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a 20   is globally.** 
15180 65 6e 61 62 6c 65 64 2c 20 61 6c 6c 20 66 69 6c  enabled, all fil
15190 65 6e 61 6d 65 73 20 70 61 73 73 65 64 20 74 6f  enames passed to
151a0 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
151b0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ], [sqlite3_open
151c0 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  _v2()],.** [sqli
151d0 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 6f 72  te3_open16()] or
151e0 0a 2a 2a 20 73 70 65 63 69 66 69 65 64 20 61 73  .** specified as
151f0 20 70 61 72 74 20 6f 66 20 5b 41 54 54 41 43 48   part of [ATTACH
15200 5d 20 63 6f 6d 6d 61 6e 64 73 20 61 72 65 20 69  ] commands are i
15210 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 55 52  nterpreted as UR
15220 49 73 2c 20 72 65 67 61 72 64 6c 65 73 73 0a 2a  Is, regardless.*
15230 2a 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20  * of whether or 
15240 6e 6f 74 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  not the [SQLITE_
15250 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20 69  OPEN_URI] flag i
15260 73 20 73 65 74 20 77 68 65 6e 20 74 68 65 20 64  s set when the d
15270 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65  atabase.** conne
15280 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64 2e  ction is opened.
15290 20 5e 49 66 20 69 74 20 69 73 20 67 6c 6f 62 61   ^If it is globa
152a0 6c 6c 79 20 64 69 73 61 62 6c 65 64 2c 20 66 69  lly disabled, fi
152b0 6c 65 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20 6f  lenames are.** o
152c0 6e 6c 79 20 69 6e 74 65 72 70 72 65 74 65 64 20  nly interpreted 
152d0 61 73 20 55 52 49 73 20 69 66 20 74 68 65 20 53  as URIs if the S
152e0 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 20 66  QLITE_OPEN_URI f
152f0 6c 61 67 20 69 73 20 73 65 74 20 77 68 65 6e 20  lag is set when 
15300 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  the.** database 
15310 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 70  connection is op
15320 65 6e 65 64 2e 20 5e 28 42 79 20 64 65 66 61 75  ened. ^(By defau
15330 6c 74 2c 20 55 52 49 20 68 61 6e 64 6c 69 6e 67  lt, URI handling
15340 20 69 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a 20   is globally.** 
15350 64 69 73 61 62 6c 65 64 2e 20 54 68 65 20 64 65  disabled. The de
15360 66 61 75 6c 74 20 76 61 6c 75 65 20 6d 61 79 20  fault value may 
15370 62 65 20 63 68 61 6e 67 65 64 20 62 79 20 63 6f  be changed by co
15380 6d 70 69 6c 69 6e 67 20 77 69 74 68 20 74 68 65  mpiling with the
15390 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f  .** [SQLITE_USE_
153a0 55 52 49 5d 20 73 79 6d 62 6f 6c 20 64 65 66 69  URI] symbol defi
153b0 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  ned.)^.**.** [[S
153c0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56  QLITE_CONFIG_COV
153d0 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e  ERING_INDEX_SCAN
153e0 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
153f0 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e  NFIG_COVERING_IN
15400 44 45 58 5f 53 43 41 4e 0a 2a 2a 20 3c 64 64 3e  DEX_SCAN.** <dd>
15410 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  ^The SQLITE_CONF
15420 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45  IG_COVERING_INDE
15430 58 5f 53 43 41 4e 20 6f 70 74 69 6f 6e 20 74 61  X_SCAN option ta
15440 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 69 6e 74  kes a single int
15450 65 67 65 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  eger.** argument
15460 20 77 68 69 63 68 20 69 73 20 69 6e 74 65 72 70   which is interp
15470 72 65 74 65 64 20 61 73 20 61 20 62 6f 6f 6c 65  reted as a boole
15480 61 6e 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 65  an in order to e
15490 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65  nable or disable
154a0 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f 66 20 63  .** the use of c
154b0 6f 76 65 72 69 6e 67 20 69 6e 64 69 63 65 73 20  overing indices 
154c0 66 6f 72 20 66 75 6c 6c 20 74 61 62 6c 65 20 73  for full table s
154d0 63 61 6e 73 20 69 6e 20 74 68 65 20 71 75 65 72  cans in the quer
154e0 79 20 6f 70 74 69 6d 69 7a 65 72 2e 0a 2a 2a 20  y optimizer..** 
154f0 5e 54 68 65 20 64 65 66 61 75 6c 74 20 73 65 74  ^The default set
15500 74 69 6e 67 20 69 73 20 64 65 74 65 72 6d 69 6e  ting is determin
15510 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 5b 53 51  ed.** by the [SQ
15520 4c 49 54 45 5f 41 4c 4c 4f 57 5f 43 4f 56 45 52  LITE_ALLOW_COVER
15530 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 5d 20  ING_INDEX_SCAN] 
15540 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
15550 69 6f 6e 2c 20 6f 72 20 69 73 20 22 6f 6e 22 0a  ion, or is "on".
15560 2a 2a 20 69 66 20 74 68 61 74 20 63 6f 6d 70 69  ** if that compi
15570 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69  le-time option i
15580 73 20 6f 6d 69 74 74 65 64 2e 0a 2a 2a 20 54 68  s omitted..** Th
15590 65 20 61 62 69 6c 69 74 79 20 74 6f 20 64 69 73  e ability to dis
155a0 61 62 6c 65 20 74 68 65 20 75 73 65 20 6f 66 20  able the use of 
155b0 63 6f 76 65 72 69 6e 67 20 69 6e 64 69 63 65 73  covering indices
155c0 20 66 6f 72 20 66 75 6c 6c 20 74 61 62 6c 65 20   for full table 
155d0 73 63 61 6e 73 0a 2a 2a 20 69 73 20 62 65 63 61  scans.** is beca
155e0 75 73 65 20 73 6f 6d 65 20 69 6e 63 6f 72 72 65  use some incorre
155f0 63 74 6c 79 20 63 6f 64 65 64 20 6c 65 67 61 63  ctly coded legac
15600 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d  y applications m
15610 69 67 68 74 20 6d 61 6c 66 75 6e 63 74 69 6f 6e  ight malfunction
15620 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20 6f 70 74  .** when the opt
15630 69 6d 69 7a 61 74 69 6f 6e 20 69 73 20 65 6e 61  imization is ena
15640 62 6c 65 64 2e 20 20 50 72 6f 76 69 64 69 6e 67  bled.  Providing
15650 20 74 68 65 20 61 62 69 6c 69 74 79 20 74 6f 0a   the ability to.
15660 2a 2a 20 64 69 73 61 62 6c 65 20 74 68 65 20 6f  ** disable the o
15670 70 74 69 6d 69 7a 61 74 69 6f 6e 20 61 6c 6c 6f  ptimization allo
15680 77 73 20 74 68 65 20 6f 6c 64 65 72 2c 20 62 75  ws the older, bu
15690 67 67 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  ggy application 
156a0 63 6f 64 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20  code to work.** 
156b0 77 69 74 68 6f 75 74 20 63 68 61 6e 67 65 20 65  without change e
156c0 76 65 6e 20 77 69 74 68 20 6e 65 77 65 72 20 76  ven with newer v
156d0 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
156e0 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  e..**.** [[SQLIT
156f0 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5d  E_CONFIG_PCACHE]
15700 5d 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ] [[SQLITE_CONFI
15710 47 5f 47 45 54 50 43 41 43 48 45 5d 5d 0a 2a 2a  G_GETPCACHE]].**
15720 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
15730 49 47 5f 50 43 41 43 48 45 20 61 6e 64 20 53 51  IG_PCACHE and SQ
15740 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50  LITE_CONFIG_GETP
15750 43 41 43 48 45 0a 2a 2a 20 3c 64 64 3e 20 54 68  CACHE.** <dd> Th
15760 65 73 65 20 6f 70 74 69 6f 6e 73 20 61 72 65 20  ese options are 
15770 6f 62 73 6f 6c 65 74 65 20 61 6e 64 20 73 68 6f  obsolete and sho
15780 75 6c 64 20 6e 6f 74 20 62 65 20 75 73 65 64 20  uld not be used 
15790 62 79 20 6e 65 77 20 63 6f 64 65 2e 0a 2a 2a 20  by new code..** 
157a0 54 68 65 79 20 61 72 65 20 72 65 74 61 69 6e 65  They are retaine
157b0 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20  d for backwards 
157c0 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 62 75  compatibility bu
157d0 74 20 61 72 65 20 6e 6f 77 20 6e 6f 2d 6f 70 73  t are now no-ops
157e0 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ..** </dd>.**.**
157f0 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
15800 5f 53 51 4c 4c 4f 47 5d 5d 0a 2a 2a 20 3c 64 74  _SQLLOG]].** <dt
15810 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  >SQLITE_CONFIG_S
15820 51 4c 4c 4f 47 0a 2a 2a 20 3c 64 64 3e 54 68 69  QLLOG.** <dd>Thi
15830 73 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6e 6c 79  s option is only
15840 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20 73 71   available if sq
15850 6c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  lite is compiled
15860 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51   with the.** [SQ
15870 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 53 51 4c 4c  LITE_ENABLE_SQLL
15880 4f 47 5d 20 70 72 65 2d 70 72 6f 63 65 73 73 6f  OG] pre-processo
15890 72 20 6d 61 63 72 6f 20 64 65 66 69 6e 65 64 2e  r macro defined.
158a0 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
158b0 65 6e 74 20 73 68 6f 75 6c 64 0a 2a 2a 20 62 65  ent should.** be
158c0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
158d0 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 79 70 65  function of type
158e0 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73   void(*)(void*,s
158f0 71 6c 69 74 65 33 2a 2c 63 6f 6e 73 74 20 63 68  qlite3*,const ch
15900 61 72 2a 2c 20 69 6e 74 29 2e 0a 2a 2a 20 54 68  ar*, int)..** Th
15910 65 20 73 65 63 6f 6e 64 20 73 68 6f 75 6c 64 20  e second should 
15920 62 65 20 6f 66 20 74 79 70 65 20 28 76 6f 69 64  be of type (void
15930 2a 29 2e 20 54 68 65 20 63 61 6c 6c 62 61 63 6b  *). The callback
15940 20 69 73 20 69 6e 76 6f 6b 65 64 20 62 79 20 74   is invoked by t
15950 68 65 20 6c 69 62 72 61 72 79 0a 2a 2a 20 69 6e  he library.** in
15960 20 74 68 72 65 65 20 73 65 70 61 72 61 74 65 20   three separate 
15970 63 69 72 63 75 6d 73 74 61 6e 63 65 73 2c 20 69  circumstances, i
15980 64 65 6e 74 69 66 69 65 64 20 62 79 20 74 68 65  dentified by the
15990 20 76 61 6c 75 65 20 70 61 73 73 65 64 20 61 73   value passed as
159a0 20 74 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20 70   the.** fourth p
159b0 61 72 61 6d 65 74 65 72 2e 20 49 66 20 74 68 65  arameter. If the
159c0 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
159d0 72 20 69 73 20 30 2c 20 74 68 65 6e 20 74 68 65  r is 0, then the
159e0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
159f0 74 69 6f 6e 0a 2a 2a 20 70 61 73 73 65 64 20 61  tion.** passed a
15a00 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  s the second arg
15a10 75 6d 65 6e 74 20 68 61 73 20 6a 75 73 74 20 62  ument has just b
15a20 65 65 6e 20 6f 70 65 6e 65 64 2e 20 54 68 65 20  een opened. The 
15a30 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 0a 2a  third argument.*
15a40 2a 20 70 6f 69 6e 74 73 20 74 6f 20 61 20 62 75  * points to a bu
15a50 66 66 65 72 20 63 6f 6e 74 61 69 6e 69 6e 67 20  ffer containing 
15a60 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
15a70 6d 61 69 6e 20 64 61 74 61 62 61 73 65 20 66 69  main database fi
15a80 6c 65 2e 20 49 66 20 74 68 65 0a 2a 2a 20 66 6f  le. If the.** fo
15a90 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  urth parameter i
15aa0 73 20 31 2c 20 74 68 65 6e 20 74 68 65 20 53 51  s 1, then the SQ
15ab0 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74  L statement that
15ac0 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d   the third param
15ad0 65 74 65 72 0a 2a 2a 20 70 6f 69 6e 74 73 20 74  eter.** points t
15ae0 6f 20 68 61 73 20 6a 75 73 74 20 62 65 65 6e 20  o has just been 
15af0 65 78 65 63 75 74 65 64 2e 20 4f 72 2c 20 69 66  executed. Or, if
15b00 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   the fourth para
15b10 6d 65 74 65 72 20 69 73 20 32 2c 20 74 68 65 6e  meter is 2, then
15b20 0a 2a 2a 20 74 68 65 20 63 6f 6e 6e 65 63 74 69  .** the connecti
15b30 6f 6e 20 62 65 69 6e 67 20 70 61 73 73 65 64 20  on being passed 
15b40 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61  as the second pa
15b50 72 61 6d 65 74 65 72 20 69 73 20 62 65 69 6e 67  rameter is being
15b60 20 63 6c 6f 73 65 64 2e 20 54 68 65 0a 2a 2a 20   closed. The.** 
15b70 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
15b80 69 73 20 70 61 73 73 65 64 20 4e 55 4c 4c 20 49  is passed NULL I
15b90 6e 20 74 68 69 73 20 63 61 73 65 2e 20 20 41 6e  n this case.  An
15ba0 20 65 78 61 6d 70 6c 65 20 6f 66 20 75 73 69 6e   example of usin
15bb0 67 20 74 68 69 73 0a 2a 2a 20 63 6f 6e 66 69 67  g this.** config
15bc0 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 63  uration option c
15bd0 61 6e 20 62 65 20 73 65 65 6e 20 69 6e 20 74 68  an be seen in th
15be0 65 20 22 74 65 73 74 5f 73 71 6c 6c 6f 67 2e 63  e "test_sqllog.c
15bf0 22 20 73 6f 75 72 63 65 20 66 69 6c 65 20 69 6e  " source file in
15c00 0a 2a 2a 20 74 68 65 20 63 61 6e 6f 6e 69 63 61  .** the canonica
15c10 6c 20 53 51 4c 69 74 65 20 73 6f 75 72 63 65 20  l SQLite source 
15c20 74 72 65 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  tree.</dd>.**.**
15c30 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
15c40 5f 4d 4d 41 50 5f 53 49 5a 45 5d 5d 0a 2a 2a 20  _MMAP_SIZE]].** 
15c50 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
15c60 47 5f 4d 4d 41 50 5f 53 49 5a 45 0a 2a 2a 20 3c  G_MMAP_SIZE.** <
15c70 64 64 3e 5e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  dd>^SQLITE_CONFI
15c80 47 5f 4d 4d 41 50 5f 53 49 5a 45 20 74 61 6b 65  G_MMAP_SIZE take
15c90 73 20 74 77 6f 20 36 34 2d 62 69 74 20 69 6e 74  s two 64-bit int
15ca0 65 67 65 72 20 28 73 71 6c 69 74 65 33 5f 69 6e  eger (sqlite3_in
15cb0 74 36 34 29 20 76 61 6c 75 65 73 0a 2a 2a 20 74  t64) values.** t
15cc0 68 61 74 20 61 72 65 20 74 68 65 20 64 65 66 61  hat are the defa
15cd0 75 6c 74 20 6d 6d 61 70 20 73 69 7a 65 20 6c 69  ult mmap size li
15ce0 6d 69 74 20 28 74 68 65 20 64 65 66 61 75 6c 74  mit (the default
15cf0 20 73 65 74 74 69 6e 67 20 66 6f 72 0a 2a 2a 20   setting for.** 
15d00 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69 7a  [PRAGMA mmap_siz
15d10 65 5d 29 20 61 6e 64 20 74 68 65 20 6d 61 78 69  e]) and the maxi
15d20 6d 75 6d 20 61 6c 6c 6f 77 65 64 20 6d 6d 61 70  mum allowed mmap
15d30 20 73 69 7a 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20   size limit..** 
15d40 5e 54 68 65 20 64 65 66 61 75 6c 74 20 73 65 74  ^The default set
15d50 74 69 6e 67 20 63 61 6e 20 62 65 20 6f 76 65 72  ting can be over
15d60 72 69 64 64 65 6e 20 62 79 20 65 61 63 68 20 64  ridden by each d
15d70 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
15d80 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 65 69 74 68  on using.** eith
15d90 65 72 20 74 68 65 20 5b 50 52 41 47 4d 41 20 6d  er the [PRAGMA m
15da0 6d 61 70 5f 73 69 7a 65 5d 20 63 6f 6d 6d 61 6e  map_size] comman
15db0 64 2c 20 6f 72 20 62 79 20 75 73 69 6e 67 20 74  d, or by using t
15dc0 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43  he.** [SQLITE_FC
15dd0 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 66  NTL_MMAP_SIZE] f
15de0 69 6c 65 20 63 6f 6e 74 72 6f 6c 2e 20 20 5e 28  ile control.  ^(
15df0 54 68 65 20 6d 61 78 69 6d 75 6d 20 61 6c 6c 6f  The maximum allo
15e00 77 65 64 20 6d 6d 61 70 20 73 69 7a 65 0a 2a 2a  wed mmap size.**
15e10 20 77 69 6c 6c 20 62 65 20 73 69 6c 65 6e 74 6c   will be silentl
15e20 79 20 74 72 75 6e 63 61 74 65 64 20 69 66 20 6e  y truncated if n
15e30 65 63 65 73 73 61 72 79 20 73 6f 20 74 68 61 74  ecessary so that
15e40 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 65 78 63   it does not exc
15e50 65 65 64 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 69  eed the.** compi
15e60 6c 65 2d 74 69 6d 65 20 6d 61 78 69 6d 75 6d 20  le-time maximum 
15e70 6d 6d 61 70 20 73 69 7a 65 20 73 65 74 20 62 79  mmap size set by
15e80 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
15e90 4d 41 58 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 63  MAX_MMAP_SIZE] c
15ea0 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
15eb0 6f 6e 2e 29 5e 0a 2a 2a 20 5e 49 66 20 65 69 74  on.)^.** ^If eit
15ec0 68 65 72 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  her argument to 
15ed0 74 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 6e  this option is n
15ee0 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68  egative, then th
15ef0 61 74 20 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a  at argument is.*
15f00 2a 20 63 68 61 6e 67 65 64 20 74 6f 20 69 74 73  * changed to its
15f10 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 64 65   compile-time de
15f20 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  fault..**.** [[S
15f30 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e  QLITE_CONFIG_WIN
15f40 33 32 5f 48 45 41 50 53 49 5a 45 5d 5d 0a 2a 2a  32_HEAPSIZE]].**
15f50 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
15f60 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a  IG_WIN32_HEAPSIZ
15f70 45 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51  E.** <dd>^The SQ
15f80 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33  LITE_CONFIG_WIN3
15f90 32 5f 48 45 41 50 53 49 5a 45 20 6f 70 74 69 6f  2_HEAPSIZE optio
15fa0 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61  n is only availa
15fb0 62 6c 65 20 69 66 20 53 51 4c 69 74 65 20 69 73  ble if SQLite is
15fc0 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72  .** compiled for
15fd0 20 57 69 6e 64 6f 77 73 20 77 69 74 68 20 74 68   Windows with th
15fe0 65 20 5b 53 51 4c 49 54 45 5f 57 49 4e 33 32 5f  e [SQLITE_WIN32_
15ff0 4d 41 4c 4c 4f 43 5d 20 70 72 65 2d 70 72 6f 63  MALLOC] pre-proc
16000 65 73 73 6f 72 20 6d 61 63 72 6f 0a 2a 2a 20 64  essor macro.** d
16010 65 66 69 6e 65 64 2e 20 5e 53 51 4c 49 54 45 5f  efined. ^SQLITE_
16020 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41  CONFIG_WIN32_HEA
16030 50 53 49 5a 45 20 74 61 6b 65 73 20 61 20 33 32  PSIZE takes a 32
16040 2d 62 69 74 20 75 6e 73 69 67 6e 65 64 20 69 6e  -bit unsigned in
16050 74 65 67 65 72 20 76 61 6c 75 65 0a 2a 2a 20 74  teger value.** t
16060 68 61 74 20 73 70 65 63 69 66 69 65 73 20 74 68  hat specifies th
16070 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f  e maximum size o
16080 66 20 74 68 65 20 63 72 65 61 74 65 64 20 68 65  f the created he
16090 61 70 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  ap..**.** [[SQLI
160a0 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
160b0 5f 48 44 52 53 5a 5d 5d 0a 2a 2a 20 3c 64 74 3e  _HDRSZ]].** <dt>
160c0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
160d0 41 43 48 45 5f 48 44 52 53 5a 0a 2a 2a 20 3c 64  ACHE_HDRSZ.** <d
160e0 64 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f  d>^The SQLITE_CO
160f0 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44 52 53  NFIG_PCACHE_HDRS
16100 5a 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  Z option takes a
16110 20 73 69 6e 67 6c 65 20 70 61 72 61 6d 65 74 65   single paramete
16120 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 61 20  r which.** is a 
16130 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
16140 74 65 67 65 72 20 61 6e 64 20 77 72 69 74 65 73  teger and writes
16150 20 69 6e 74 6f 20 74 68 61 74 20 69 6e 74 65 67   into that integ
16160 65 72 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  er the number of
16170 20 65 78 74 72 61 0a 2a 2a 20 62 79 74 65 73 20   extra.** bytes 
16180 70 65 72 20 70 61 67 65 20 72 65 71 75 69 72 65  per page require
16190 64 20 66 6f 72 20 65 61 63 68 20 70 61 67 65 20  d for each page 
161a0 69 6e 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  in [SQLITE_CONFI
161b0 47 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a 2a  G_PAGECACHE]..**
161c0 20 54 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 65   The amount of e
161d0 78 74 72 61 20 73 70 61 63 65 20 72 65 71 75 69  xtra space requi
161e0 72 65 64 20 63 61 6e 20 63 68 61 6e 67 65 20 64  red can change d
161f0 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20  epending on the 
16200 63 6f 6d 70 69 6c 65 72 2c 0a 2a 2a 20 74 61 72  compiler,.** tar
16210 67 65 74 20 70 6c 61 74 66 6f 72 6d 2c 20 61 6e  get platform, an
16220 64 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  d SQLite version
16230 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ..**.** [[SQLITE
16240 5f 43 4f 4e 46 49 47 5f 50 4d 41 53 5a 5d 5d 0a  _CONFIG_PMASZ]].
16250 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ** <dt>SQLITE_CO
16260 4e 46 49 47 5f 50 4d 41 53 5a 0a 2a 2a 20 3c 64  NFIG_PMASZ.** <d
16270 64 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f  d>^The SQLITE_CO
16280 4e 46 49 47 5f 50 4d 41 53 5a 20 6f 70 74 69 6f  NFIG_PMASZ optio
16290 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  n takes a single
162a0 20 70 61 72 61 6d 65 74 65 72 20 77 68 69 63 68   parameter which
162b0 0a 2a 2a 20 69 73 20 61 6e 20 75 6e 73 69 67 6e  .** is an unsign
162c0 65 64 20 69 6e 74 65 67 65 72 20 61 6e 64 20 73  ed integer and s
162d0 65 74 73 20 74 68 65 20 22 4d 69 6e 69 6d 75 6d  ets the "Minimum
162e0 20 50 4d 41 20 53 69 7a 65 22 20 66 6f 72 20 74   PMA Size" for t
162f0 68 65 20 6d 75 6c 74 69 74 68 72 65 61 64 65 64  he multithreaded
16300 0a 2a 2a 20 73 6f 72 74 65 72 20 74 6f 20 74 68  .** sorter to th
16310 61 74 20 69 6e 74 65 67 65 72 2e 20 20 54 68 65  at integer.  The
16320 20 64 65 66 61 75 6c 74 20 6d 69 6e 69 6d 75 6d   default minimum
16330 20 50 4d 41 20 53 69 7a 65 20 69 73 20 73 65 74   PMA Size is set
16340 20 62 79 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49   by the.** [SQLI
16350 54 45 5f 53 4f 52 54 45 52 5f 50 4d 41 53 5a 5d  TE_SORTER_PMASZ]
16360 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
16370 74 69 6f 6e 2e 20 20 4e 65 77 20 74 68 72 65 61  tion.  New threa
16380 64 73 20 61 72 65 20 6c 61 75 6e 63 68 65 64 0a  ds are launched.
16390 2a 2a 20 74 6f 20 68 65 6c 70 20 77 69 74 68 20  ** to help with 
163a0 73 6f 72 74 20 6f 70 65 72 61 74 69 6f 6e 73 20  sort operations 
163b0 77 68 65 6e 20 6d 75 6c 74 69 74 68 72 65 61 64  when multithread
163c0 65 64 20 73 6f 72 74 69 6e 67 0a 2a 2a 20 69 73  ed sorting.** is
163d0 20 65 6e 61 62 6c 65 64 20 28 75 73 69 6e 67 20   enabled (using 
163e0 74 68 65 20 5b 50 52 41 47 4d 41 20 74 68 72 65  the [PRAGMA thre
163f0 61 64 73 5d 20 63 6f 6d 6d 61 6e 64 29 20 61 6e  ads] command) an
16400 64 20 74 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20  d the amount of 
16410 63 6f 6e 74 65 6e 74 0a 2a 2a 20 74 6f 20 62 65  content.** to be
16420 20 73 6f 72 74 65 64 20 65 78 63 65 65 64 73 20   sorted exceeds 
16430 74 68 65 20 70 61 67 65 20 73 69 7a 65 20 74 69  the page size ti
16440 6d 65 73 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20  mes the minimum 
16450 6f 66 20 74 68 65 0a 2a 2a 20 5b 50 52 41 47 4d  of the.** [PRAGM
16460 41 20 63 61 63 68 65 5f 73 69 7a 65 5d 20 73 65  A cache_size] se
16470 74 74 69 6e 67 20 61 6e 64 20 74 68 69 73 20 76  tting and this v
16480 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  alue..**.** [[SQ
16490 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 54 4d 54  LITE_CONFIG_STMT
164a0 4a 52 4e 4c 5f 53 50 49 4c 4c 5d 5d 0a 2a 2a 20  JRNL_SPILL]].** 
164b0 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
164c0 47 5f 53 54 4d 54 4a 52 4e 4c 5f 53 50 49 4c 4c  G_STMTJRNL_SPILL
164d0 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c  .** <dd>^The SQL
164e0 49 54 45 5f 43 4f 4e 46 49 47 5f 53 54 4d 54 4a  ITE_CONFIG_STMTJ
164f0 52 4e 4c 5f 53 50 49 4c 4c 20 6f 70 74 69 6f 6e  RNL_SPILL option
16500 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
16510 70 61 72 61 6d 65 74 65 72 20 77 68 69 63 68 0a  parameter which.
16520 2a 2a 20 62 65 63 6f 6d 65 73 20 74 68 65 20 5b  ** becomes the [
16530 73 74 61 74 65 6d 65 6e 74 20 6a 6f 75 72 6e 61  statement journa
16540 6c 5d 20 73 70 69 6c 6c 2d 74 6f 2d 64 69 73 6b  l] spill-to-disk
16550 20 74 68 72 65 73 68 6f 6c 64 2e 20 20 0a 2a 2a   threshold.  .**
16560 20 5b 53 74 61 74 65 6d 65 6e 74 20 6a 6f 75 72   [Statement jour
16570 6e 61 6c 73 5d 20 61 72 65 20 68 65 6c 64 20 69  nals] are held i
16580 6e 20 6d 65 6d 6f 72 79 20 75 6e 74 69 6c 20 74  n memory until t
16590 68 65 69 72 20 73 69 7a 65 20 28 69 6e 20 62 79  heir size (in by
165a0 74 65 73 29 0a 2a 2a 20 65 78 63 65 65 64 73 20  tes).** exceeds 
165b0 74 68 69 73 20 74 68 72 65 73 68 6f 6c 64 2c 20  this threshold, 
165c0 61 74 20 77 68 69 63 68 20 70 6f 69 6e 74 20 74  at which point t
165d0 68 65 79 20 61 72 65 20 77 72 69 74 74 65 6e 20  hey are written 
165e0 74 6f 20 64 69 73 6b 2e 0a 2a 2a 20 4f 72 20 69  to disk..** Or i
165f0 66 20 74 68 65 20 74 68 72 65 73 68 6f 6c 64 20  f the threshold 
16600 69 73 20 2d 31 2c 20 73 74 61 74 65 6d 65 6e 74  is -1, statement
16610 20 6a 6f 75 72 6e 61 6c 73 20 61 72 65 20 61 6c   journals are al
16620 77 61 79 73 20 68 65 6c 64 0a 2a 2a 20 65 78 63  ways held.** exc
16630 6c 75 73 69 76 65 6c 79 20 69 6e 20 6d 65 6d 6f  lusively in memo
16640 72 79 2e 0a 2a 2a 20 53 69 6e 63 65 20 6d 61 6e  ry..** Since man
16650 79 20 73 74 61 74 65 6d 65 6e 74 20 6a 6f 75 72  y statement jour
16660 6e 61 6c 73 20 6e 65 76 65 72 20 62 65 63 6f 6d  nals never becom
16670 65 20 6c 61 72 67 65 2c 20 73 65 74 74 69 6e 67  e large, setting
16680 20 74 68 65 20 73 70 69 6c 6c 0a 2a 2a 20 74 68   the spill.** th
16690 72 65 73 68 6f 6c 64 20 74 6f 20 61 20 76 61 6c  reshold to a val
166a0 75 65 20 73 75 63 68 20 61 73 20 36 34 4b 69 42  ue such as 64KiB
166b0 20 63 61 6e 20 67 72 65 61 74 6c 79 20 72 65 64   can greatly red
166c0 75 63 65 20 74 68 65 20 61 6d 6f 75 6e 74 20 6f  uce the amount o
166d0 66 0a 2a 2a 20 49 2f 4f 20 72 65 71 75 69 72 65  f.** I/O require
166e0 64 20 74 6f 20 73 75 70 70 6f 72 74 20 73 74 61  d to support sta
166f0 74 65 6d 65 6e 74 20 72 6f 6c 6c 62 61 63 6b 2e  tement rollback.
16700 0a 2a 2a 20 54 68 65 20 64 65 66 61 75 6c 74 20  .** The default 
16710 76 61 6c 75 65 20 66 6f 72 20 74 68 69 73 20 73  value for this s
16720 65 74 74 69 6e 67 20 69 73 20 63 6f 6e 74 72 6f  etting is contro
16730 6c 6c 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b  lled by the.** [
16740 53 51 4c 49 54 45 5f 53 54 4d 54 4a 52 4e 4c 5f  SQLITE_STMTJRNL_
16750 53 50 49 4c 4c 5d 20 63 6f 6d 70 69 6c 65 2d 74  SPILL] compile-t
16760 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 3c  ime option..** <
16770 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  /dl>.*/.#define 
16780 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49  SQLITE_CONFIG_SI
16790 4e 47 4c 45 54 48 52 45 41 44 20 20 31 20 20 2f  NGLETHREAD  1  /
167a0 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65  * nil */.#define
167b0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
167c0 55 4c 54 49 54 48 52 45 41 44 20 20 20 32 20 20  ULTITHREAD   2  
167d0 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e  /* nil */.#defin
167e0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
167f0 53 45 52 49 41 4c 49 5a 45 44 20 20 20 20 33 20  SERIALIZED    3 
16800 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69   /* nil */.#defi
16810 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
16820 5f 4d 41 4c 4c 4f 43 20 20 20 20 20 20 20 20 34  _MALLOC        4
16830 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d    /* sqlite3_mem
16840 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65  _methods* */.#de
16850 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
16860 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 20 20 20  IG_GETMALLOC    
16870 20 35 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d   5  /* sqlite3_m
16880 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23  em_methods* */.#
16890 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
168a0 4e 46 49 47 5f 53 43 52 41 54 43 48 20 20 20 20  NFIG_SCRATCH    
168b0 20 20 20 36 20 20 2f 2a 20 76 6f 69 64 2a 2c 20     6  /* void*, 
168c0 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f  int sz, int N */
168d0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
168e0 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45  CONFIG_PAGECACHE
168f0 20 20 20 20 20 37 20 20 2f 2a 20 76 6f 69 64 2a       7  /* void*
16900 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20  , int sz, int N 
16910 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
16920 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20 20 20  E_CONFIG_HEAP   
16930 20 20 20 20 20 20 20 38 20 20 2f 2a 20 76 6f 69         8  /* voi
16940 64 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 69  d*, int nByte, i
16950 6e 74 20 6d 69 6e 20 2a 2f 0a 23 64 65 66 69 6e  nt min */.#defin
16960 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
16970 4d 45 4d 53 54 41 54 55 53 20 20 20 20 20 39 20  MEMSTATUS     9 
16980 20 2f 2a 20 62 6f 6f 6c 65 61 6e 20 2a 2f 0a 23   /* boolean */.#
16990 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
169a0 4e 46 49 47 5f 4d 55 54 45 58 20 20 20 20 20 20  NFIG_MUTEX      
169b0 20 20 31 30 20 20 2f 2a 20 73 71 6c 69 74 65 33    10  /* sqlite3
169c0 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20  _mutex_methods* 
169d0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
169e0 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45  E_CONFIG_GETMUTE
169f0 58 20 20 20 20 20 31 31 20 20 2f 2a 20 73 71 6c  X     11  /* sql
16a00 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f  ite3_mutex_metho
16a10 64 73 2a 20 2a 2f 0a 2f 2a 20 70 72 65 76 69 6f  ds* */./* previo
16a20 75 73 6c 79 20 53 51 4c 49 54 45 5f 43 4f 4e 46  usly SQLITE_CONF
16a30 49 47 5f 43 48 55 4e 4b 41 4c 4c 4f 43 20 31 32  IG_CHUNKALLOC 12
16a40 20 77 68 69 63 68 20 69 73 20 6e 6f 77 20 75 6e   which is now un
16a50 75 73 65 64 2e 20 2a 2f 20 0a 23 64 65 66 69 6e  used. */ .#defin
16a60 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
16a70 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 31 33 20  LOOKASIDE    13 
16a80 20 2f 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23   /* int int */.#
16a90 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
16aa0 4e 46 49 47 5f 50 43 41 43 48 45 20 20 20 20 20  NFIG_PCACHE     
16ab0 20 20 31 34 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a    14  /* no-op *
16ac0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
16ad0 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48  _CONFIG_GETPCACH
16ae0 45 20 20 20 20 31 35 20 20 2f 2a 20 6e 6f 2d 6f  E    15  /* no-o
16af0 70 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  p */.#define SQL
16b00 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 20  ITE_CONFIG_LOG  
16b10 20 20 20 20 20 20 20 20 31 36 20 20 2f 2a 20 78          16  /* x
16b20 46 75 6e 63 2c 20 76 6f 69 64 2a 20 2a 2f 0a 23  Func, void* */.#
16b30 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
16b40 4e 46 49 47 5f 55 52 49 20 20 20 20 20 20 20 20  NFIG_URI        
16b50 20 20 31 37 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a    17  /* int */.
16b60 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
16b70 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 20 20 20  ONFIG_PCACHE2   
16b80 20 20 20 31 38 20 20 2f 2a 20 73 71 6c 69 74 65     18  /* sqlite
16b90 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73  3_pcache_methods
16ba0 32 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  2* */.#define SQ
16bb0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50  LITE_CONFIG_GETP
16bc0 43 41 43 48 45 32 20 20 20 31 39 20 20 2f 2a 20  CACHE2   19  /* 
16bd0 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d  sqlite3_pcache_m
16be0 65 74 68 6f 64 73 32 2a 20 2a 2f 0a 23 64 65 66  ethods2* */.#def
16bf0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
16c00 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58  G_COVERING_INDEX
16c10 5f 53 43 41 4e 20 32 30 20 20 2f 2a 20 69 6e 74  _SCAN 20  /* int
16c20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
16c30 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47  TE_CONFIG_SQLLOG
16c40 20 20 20 20 20 20 20 32 31 20 20 2f 2a 20 78 53         21  /* xS
16c50 71 6c 6c 6f 67 2c 20 76 6f 69 64 2a 20 2a 2f 0a  qllog, void* */.
16c60 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
16c70 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 20  ONFIG_MMAP_SIZE 
16c80 20 20 20 32 32 20 20 2f 2a 20 73 71 6c 69 74 65     22  /* sqlite
16c90 33 5f 69 6e 74 36 34 2c 20 73 71 6c 69 74 65 33  3_int64, sqlite3
16ca0 5f 69 6e 74 36 34 20 2a 2f 0a 23 64 65 66 69 6e  _int64 */.#defin
16cb0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
16cc0 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 20 20  WIN32_HEAPSIZE  
16cd0 20 20 20 20 32 33 20 20 2f 2a 20 69 6e 74 20 6e      23  /* int n
16ce0 42 79 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  Byte */.#define 
16cf0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
16d00 41 43 48 45 5f 48 44 52 53 5a 20 20 20 20 20 20  ACHE_HDRSZ      
16d10 20 20 32 34 20 20 2f 2a 20 69 6e 74 20 2a 70 73    24  /* int *ps
16d20 7a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  z */.#define SQL
16d30 49 54 45 5f 43 4f 4e 46 49 47 5f 50 4d 41 53 5a  ITE_CONFIG_PMASZ
16d40 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
16d50 35 20 20 2f 2a 20 75 6e 73 69 67 6e 65 64 20 69  5  /* unsigned i
16d60 6e 74 20 73 7a 50 6d 61 20 2a 2f 0a 23 64 65 66  nt szPma */.#def
16d70 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
16d80 47 5f 53 54 4d 54 4a 52 4e 4c 5f 53 50 49 4c 4c  G_STMTJRNL_SPILL
16d90 20 20 20 20 20 20 32 36 20 20 2f 2a 20 69 6e 74        26  /* int
16da0 20 6e 42 79 74 65 20 2a 2f 0a 0a 2f 2a 0a 2a 2a   nByte */../*.**
16db0 20 43 41 50 49 33 52 45 46 3a 20 44 61 74 61 62   CAPI3REF: Datab
16dc0 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 43  ase Connection C
16dd0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 74  onfiguration Opt
16de0 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ions.**.** These
16df0 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 74   constants are t
16e00 68 65 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 74  he available int
16e10 65 67 65 72 20 63 6f 6e 66 69 67 75 72 61 74 69  eger configurati
16e20 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a  on options that.
16e30 2a 2a 20 63 61 6e 20 62 65 20 70 61 73 73 65 64  ** can be passed
16e40 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61   as the second a
16e50 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b  rgument to the [
16e60 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
16e70 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a  g()] interface..
16e80 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67  **.** New config
16e90 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20  uration options 
16ea0 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20  may be added in 
16eb0 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20  future releases 
16ec0 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78  of SQLite..** Ex
16ed0 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 72 61  isting configura
16ee0 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67  tion options mig
16ef0 68 74 20 62 65 20 64 69 73 63 6f 6e 74 69 6e 75  ht be discontinu
16f00 65 64 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e  ed.  Application
16f10 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65 63  s.** should chec
16f20 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64  k the return cod
16f30 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  e from [sqlite3_
16f40 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20  db_config()] to 
16f50 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74 0a 2a  make sure that.*
16f60 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65  * the call worke
16f70 64 2e 20 20 5e 54 68 65 20 5b 73 71 6c 69 74 65  d.  ^The [sqlite
16f80 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69  3_db_config()] i
16f90 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65  nterface will re
16fa0 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65  turn a.** non-ze
16fb0 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  ro [error code] 
16fc0 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65  if a discontinue
16fd0 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64  d or unsupported
16fe0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
16ff0 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f  ption.** is invo
17000 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a  ked..**.** <dl>.
17010 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42  ** <dt>SQLITE_DB
17020 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
17030 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
17040 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  his option takes
17050 20 74 68 72 65 65 20 61 64 64 69 74 69 6f 6e 61   three additiona
17060 6c 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74  l arguments that
17070 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20 0a   determine the .
17080 2a 2a 20 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d 65  ** [lookaside me
17090 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d 20  mory allocator] 
170a0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 66 6f  configuration fo
170b0 72 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  r the [database 
170c0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20  connection]..** 
170d0 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d  ^The first argum
170e0 65 6e 74 20 28 74 68 65 20 74 68 69 72 64 20 70  ent (the third p
170f0 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c  arameter to [sql
17100 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29  ite3_db_config()
17110 5d 20 69 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65  ] is a.** pointe
17120 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20 62 75  r to a memory bu
17130 66 66 65 72 20 74 6f 20 75 73 65 20 66 6f 72 20  ffer to use for 
17140 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79  lookaside memory
17150 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  ..** ^The first 
17160 61 72 67 75 6d 65 6e 74 20 61 66 74 65 72 20 74  argument after t
17170 68 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  he SQLITE_DBCONF
17180 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 76 65 72  IG_LOOKASIDE ver
17190 62 0a 2a 2a 20 6d 61 79 20 62 65 20 4e 55 4c 4c  b.** may be NULL
171a0 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 53   in which case S
171b0 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 6c 6f 63  QLite will alloc
171c0 61 74 65 20 74 68 65 0a 2a 2a 20 6c 6f 6f 6b 61  ate the.** looka
171d0 73 69 64 65 20 62 75 66 66 65 72 20 69 74 73 65  side buffer itse
171e0 6c 66 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  lf using [sqlite
171f0 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 5e 54 68  3_malloc()]. ^Th
17200 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
17210 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65  t is the.** size
17220 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69   of each lookasi
17230 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74 2e 20  de buffer slot. 
17240 20 5e 54 68 65 20 74 68 69 72 64 20 61 72 67 75   ^The third argu
17250 6d 65 6e 74 20 69 73 20 74 68 65 20 6e 75 6d 62  ment is the numb
17260 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 2e 20  er of.** slots. 
17270 20 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   The size of the
17280 20 62 75 66 66 65 72 20 69 6e 20 74 68 65 20 66   buffer in the f
17290 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75  irst argument mu
172a0 73 74 20 62 65 20 67 72 65 61 74 65 72 20 74 68  st be greater th
172b0 61 6e 0a 2a 2a 20 6f 72 20 65 71 75 61 6c 20 74  an.** or equal t
172c0 6f 20 74 68 65 20 70 72 6f 64 75 63 74 20 6f 66  o the product of
172d0 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20   the second and 
172e0 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 73 2e  third arguments.
172f0 20 20 54 68 65 20 62 75 66 66 65 72 0a 2a 2a 20    The buffer.** 
17300 6d 75 73 74 20 62 65 20 61 6c 69 67 6e 65 64 20  must be aligned 
17310 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 62 6f 75  to an 8-byte bou
17320 6e 64 61 72 79 2e 20 20 5e 49 66 20 74 68 65 20  ndary.  ^If the 
17330 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
17340 74 6f 0a 2a 2a 20 53 51 4c 49 54 45 5f 44 42 43  to.** SQLITE_DBC
17350 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20  ONFIG_LOOKASIDE 
17360 69 73 20 6e 6f 74 20 61 20 6d 75 6c 74 69 70 6c  is not a multipl
17370 65 20 6f 66 20 38 2c 20 69 74 20 69 73 20 69 6e  e of 8, it is in
17380 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 72 6f 75 6e  ternally.** roun
17390 64 65 64 20 64 6f 77 6e 20 74 6f 20 74 68 65 20  ded down to the 
173a0 6e 65 78 74 20 73 6d 61 6c 6c 65 72 20 6d 75 6c  next smaller mul
173b0 74 69 70 6c 65 20 6f 66 20 38 2e 20 20 5e 28 54  tiple of 8.  ^(T
173c0 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d  he lookaside mem
173d0 6f 72 79 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61  ory.** configura
173e0 74 69 6f 6e 20 66 6f 72 20 61 20 64 61 74 61 62  tion for a datab
173f0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63  ase connection c
17400 61 6e 20 6f 6e 6c 79 20 62 65 20 63 68 61 6e 67  an only be chang
17410 65 64 20 77 68 65 6e 20 74 68 61 74 0a 2a 2a 20  ed when that.** 
17420 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6e 6f  connection is no
17430 74 20 63 75 72 72 65 6e 74 6c 79 20 75 73 69 6e  t currently usin
17440 67 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f  g lookaside memo
17450 72 79 2c 20 6f 72 20 69 6e 20 6f 74 68 65 72 20  ry, or in other 
17460 77 6f 72 64 73 0a 2a 2a 20 77 68 65 6e 20 74 68  words.** when th
17470 65 20 22 63 75 72 72 65 6e 74 20 76 61 6c 75 65  e "current value
17480 22 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a  " returned by.**
17490 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 73 74 61   [sqlite3_db_sta
174a0 74 75 73 5d 28 44 2c 5b 53 51 4c 49 54 45 5f 43  tus](D,[SQLITE_C
174b0 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d  ONFIG_LOOKASIDE]
174c0 2c 2e 2e 2e 29 20 69 73 20 7a 65 72 6f 2e 0a 2a  ,...) is zero..*
174d0 2a 20 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f  * Any attempt to
174e0 20 63 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f 6b   change the look
174f0 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 63 6f 6e  aside memory con
17500 66 69 67 75 72 61 74 69 6f 6e 20 77 68 65 6e 20  figuration when 
17510 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 6d 65 6d  lookaside.** mem
17520 6f 72 79 20 69 73 20 69 6e 20 75 73 65 20 6c 65  ory is in use le
17530 61 76 65 73 20 74 68 65 20 63 6f 6e 66 69 67 75  aves the configu
17540 72 61 74 69 6f 6e 20 75 6e 63 68 61 6e 67 65 64  ration unchanged
17550 20 61 6e 64 20 72 65 74 75 72 6e 73 20 0a 2a 2a   and returns .**
17560 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 29   [SQLITE_BUSY].)
17570 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74  ^</dd>.**.** <dt
17580 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47  >SQLITE_DBCONFIG
17590 5f 45 4e 41 42 4c 45 5f 46 4b 45 59 3c 2f 64 74  _ENABLE_FKEY</dt
175a0 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20  >.** <dd> ^This 
175b0 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74  option is used t
175c0 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61  o enable or disa
175d0 62 6c 65 20 74 68 65 20 65 6e 66 6f 72 63 65 6d  ble the enforcem
175e0 65 6e 74 20 6f 66 0a 2a 2a 20 5b 66 6f 72 65 69  ent of.** [forei
175f0 67 6e 20 6b 65 79 20 63 6f 6e 73 74 72 61 69 6e  gn key constrain
17600 74 73 5d 2e 20 20 54 68 65 72 65 20 73 68 6f 75  ts].  There shou
17610 6c 64 20 62 65 20 74 77 6f 20 61 64 64 69 74 69  ld be two additi
17620 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a  onal arguments..
17630 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67  ** The first arg
17640 75 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e 74 65  ument is an inte
17650 67 65 72 20 77 68 69 63 68 20 69 73 20 30 20 74  ger which is 0 t
17660 6f 20 64 69 73 61 62 6c 65 20 46 4b 20 65 6e 66  o disable FK enf
17670 6f 72 63 65 6d 65 6e 74 2c 0a 2a 2a 20 70 6f 73  orcement,.** pos
17680 69 74 69 76 65 20 74 6f 20 65 6e 61 62 6c 65 20  itive to enable 
17690 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 6f  FK enforcement o
176a0 72 20 6e 65 67 61 74 69 76 65 20 74 6f 20 6c 65  r negative to le
176b0 61 76 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65  ave FK enforceme
176c0 6e 74 0a 2a 2a 20 75 6e 63 68 61 6e 67 65 64 2e  nt.** unchanged.
176d0 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72    The second par
176e0 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e  ameter is a poin
176f0 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65  ter to an intege
17700 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20  r into which.** 
17710 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20  is written 0 or 
17720 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68  1 to indicate wh
17730 65 74 68 65 72 20 46 4b 20 65 6e 66 6f 72 63 65  ether FK enforce
17740 6d 65 6e 74 20 69 73 20 6f 66 66 20 6f 72 20 6f  ment is off or o
17750 6e 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74  n.** following t
17760 68 69 73 20 63 61 6c 6c 2e 20 20 54 68 65 20 73  his call.  The s
17770 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
17780 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f  may be a NULL po
17790 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69  inter, in.** whi
177a0 63 68 20 63 61 73 65 20 74 68 65 20 46 4b 20 65  ch case the FK e
177b0 6e 66 6f 72 63 65 6d 65 6e 74 20 73 65 74 74 69  nforcement setti
177c0 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 74  ng is not report
177d0 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a  ed back. </dd>.*
177e0 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
177f0 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f  DBCONFIG_ENABLE_
17800 54 52 49 47 47 45 52 3c 2f 64 74 3e 0a 2a 2a 20  TRIGGER</dt>.** 
17810 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f  <dd> ^This optio
17820 6e 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e 61  n is used to ena
17830 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20 5b  ble or disable [
17840 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20 7c  CREATE TRIGGER |
17850 20 74 72 69 67 67 65 72 73 5d 2e 0a 2a 2a 20 54   triggers]..** T
17860 68 65 72 65 20 73 68 6f 75 6c 64 20 62 65 20 74  here should be t
17870 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72  wo additional ar
17880 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20  guments..** The 
17890 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69  first argument i
178a0 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69  s an integer whi
178b0 63 68 20 69 73 20 30 20 74 6f 20 64 69 73 61 62  ch is 0 to disab
178c0 6c 65 20 74 72 69 67 67 65 72 73 2c 0a 2a 2a 20  le triggers,.** 
178d0 70 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62  positive to enab
178e0 6c 65 20 74 72 69 67 67 65 72 73 20 6f 72 20 6e  le triggers or n
178f0 65 67 61 74 69 76 65 20 74 6f 20 6c 65 61 76 65  egative to leave
17900 20 74 68 65 20 73 65 74 74 69 6e 67 20 75 6e 63   the setting unc
17910 68 61 6e 67 65 64 2e 0a 2a 2a 20 54 68 65 20 73  hanged..** The s
17920 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
17930 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
17940 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20  an integer into 
17950 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 74  which.** is writ
17960 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e  ten 0 or 1 to in
17970 64 69 63 61 74 65 20 77 68 65 74 68 65 72 20 74  dicate whether t
17980 72 69 67 67 65 72 73 20 61 72 65 20 64 69 73 61  riggers are disa
17990 62 6c 65 64 20 6f 72 20 65 6e 61 62 6c 65 64 0a  bled or enabled.
179a0 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69  ** following thi
179b0 73 20 63 61 6c 6c 2e 20 20 54 68 65 20 73 65 63  s call.  The sec
179c0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6d 61  ond parameter ma
179d0 79 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  y be a NULL poin
179e0 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68  ter, in.** which
179f0 20 63 61 73 65 20 74 68 65 20 74 72 69 67 67 65   case the trigge
17a00 72 20 73 65 74 74 69 6e 67 20 69 73 20 6e 6f 74  r setting is not
17a10 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 2e 20   reported back. 
17a20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
17a30 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
17a40 45 4e 41 42 4c 45 5f 46 54 53 33 5f 54 4f 4b 45  ENABLE_FTS3_TOKE
17a50 4e 49 5a 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  NIZER</dt>.** <d
17a60 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  d> ^This option 
17a70 69 73 20 75 73 65 64 20 74 6f 20 65 6e 61 62 6c  is used to enabl
17a80 65 20 6f 72 20 64 69 73 61 62 6c 65 20 74 68 65  e or disable the
17a90 20 74 77 6f 2d 61 72 67 75 6d 65 6e 74 0a 2a 2a   two-argument.**
17aa0 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20   version of the 
17ab0 5b 66 74 73 33 5f 74 6f 6b 65 6e 69 7a 65 72 28  [fts3_tokenizer(
17ac0 29 5d 20 66 75 6e 63 74 69 6f 6e 20 77 68 69 63  )] function whic
17ad0 68 20 69 73 20 70 61 72 74 20 6f 66 20 74 68 65  h is part of the
17ae0 0a 2a 2a 20 5b 46 54 53 33 5d 20 66 75 6c 6c 2d  .** [FTS3] full-
17af0 74 65 78 74 20 73 65 61 72 63 68 20 65 6e 67 69  text search engi
17b00 6e 65 20 65 78 74 65 6e 73 69 6f 6e 2e 0a 2a 2a  ne extension..**
17b10 20 54 68 65 72 65 20 73 68 6f 75 6c 64 20 62 65   There should be
17b20 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20   two additional 
17b30 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68  arguments..** Th
17b40 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
17b50 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77   is an integer w
17b60 68 69 63 68 20 69 73 20 30 20 74 6f 20 64 69 73  hich is 0 to dis
17b70 61 62 6c 65 20 66 74 73 33 5f 74 6f 6b 65 6e 69  able fts3_tokeni
17b80 7a 65 72 28 29 20 6f 72 0a 2a 2a 20 70 6f 73 69  zer() or.** posi
17b90 74 69 76 65 20 74 6f 20 65 6e 61 62 6c 65 20 66  tive to enable f
17ba0 74 73 33 5f 74 6f 6b 65 6e 69 7a 65 72 28 29 20  ts3_tokenizer() 
17bb0 6f 72 20 6e 65 67 61 74 69 76 65 20 74 6f 20 6c  or negative to l
17bc0 65 61 76 65 20 74 68 65 20 73 65 74 74 69 6e 67  eave the setting
17bd0 0a 2a 2a 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a  .** unchanged..*
17be0 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72  * The second par
17bf0 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e  ameter is a poin
17c00 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65  ter to an intege
17c10 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20  r into which.** 
17c20 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20  is written 0 or 
17c30 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68  1 to indicate wh
17c40 65 74 68 65 72 20 66 74 73 33 5f 74 6f 6b 65 6e  ether fts3_token
17c50 69 7a 65 72 20 69 73 20 64 69 73 61 62 6c 65 64  izer is disabled
17c60 20 6f 72 20 65 6e 61 62 6c 65 64 0a 2a 2a 20 66   or enabled.** f
17c70 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61  ollowing this ca
17c80 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20  ll.  The second 
17c90 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65  parameter may be
17ca0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c   a NULL pointer,
17cb0 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61 73   in.** which cas
17cc0 65 20 74 68 65 20 6e 65 77 20 73 65 74 74 69 6e  e the new settin
17cd0 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 74 65  g is not reporte
17ce0 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a  d back. </dd>.**
17cf0 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44  .** <dt>SQLITE_D
17d00 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 4c  BCONFIG_ENABLE_L
17d10 4f 41 44 5f 45 58 54 45 4e 53 49 4f 4e 3c 2f 64  OAD_EXTENSION</d
17d20 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73  t>.** <dd> ^This
17d30 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20   option is used 
17d40 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73  to enable or dis
17d50 61 62 6c 65 20 74 68 65 20 5b 73 71 6c 69 74 65  able the [sqlite
17d60 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e  3_load_extension
17d70 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  ()].** interface
17d80 20 69 6e 64 65 70 65 6e 64 65 6e 74 6c 79 20 6f   independently o
17d90 66 20 74 68 65 20 5b 6c 6f 61 64 5f 65 78 74 65  f the [load_exte
17da0 6e 73 69 6f 6e 28 29 5d 20 53 51 4c 20 66 75 6e  nsion()] SQL fun
17db0 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68 65 20 5b 73  ction..** The [s
17dc0 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 6c 6f  qlite3_enable_lo
17dd0 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20  ad_extension()] 
17de0 41 50 49 20 65 6e 61 62 6c 65 73 20 6f 72 20 64  API enables or d
17df0 69 73 61 62 6c 65 73 20 62 6f 74 68 20 74 68 65  isables both the
17e00 0a 2a 2a 20 43 2d 41 50 49 20 5b 73 71 6c 69 74  .** C-API [sqlit
17e10 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f  e3_load_extensio
17e20 6e 28 29 5d 20 61 6e 64 20 74 68 65 20 53 51 4c  n()] and the SQL
17e30 20 66 75 6e 63 74 69 6f 6e 20 5b 6c 6f 61 64 5f   function [load_
17e40 65 78 74 65 6e 73 69 6f 6e 28 29 5d 2e 0a 2a 2a  extension()]..**
17e50 20 54 68 65 72 65 20 73 68 6f 75 6c 64 20 62 65   There should be
17e60 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20   two additional 
17e70 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 57 68  arguments..** Wh
17e80 65 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67  en the first arg
17e90 75 6d 65 6e 74 20 74 6f 20 74 68 69 73 20 69 6e  ument to this in
17ea0 74 65 72 66 61 63 65 20 69 73 20 31 2c 20 74 68  terface is 1, th
17eb0 65 6e 20 6f 6e 6c 79 20 74 68 65 20 43 2d 41 50  en only the C-AP
17ec0 49 20 69 73 0a 2a 2a 20 65 6e 61 62 6c 65 64 20  I is.** enabled 
17ed0 61 6e 64 20 74 68 65 20 53 51 4c 20 66 75 6e 63  and the SQL func
17ee0 74 69 6f 6e 20 72 65 6d 61 69 6e 73 20 64 69 73  tion remains dis
17ef0 61 62 6c 65 64 2e 20 20 49 66 20 74 68 65 20 66  abled.  If the f
17f00 69 72 73 74 20 61 72 67 6d 65 6e 74 20 74 6f 0a  irst argment to.
17f10 2a 2a 20 74 68 69 73 20 69 6e 74 65 72 66 61 63  ** this interfac
17f20 65 20 69 73 20 30 2c 20 74 68 65 6e 20 62 6f 74  e is 0, then bot
17f30 68 20 74 68 65 20 43 2d 41 50 49 20 61 6e 64 20  h the C-API and 
17f40 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
17f50 20 61 72 65 20 64 69 73 61 62 6c 65 64 2e 0a 2a   are disabled..*
17f60 2a 20 49 66 20 74 68 65 20 66 69 72 73 74 20 61  * If the first a
17f70 72 67 75 6d 65 6e 74 20 69 73 20 2d 31 2c 20 74  rgument is -1, t
17f80 68 65 6e 20 6e 6f 20 63 68 61 6e 67 65 73 20 61  hen no changes a
17f90 72 65 20 6d 61 64 65 20 74 6f 20 73 74 61 74 65  re made to state
17fa0 20 6f 66 20 65 69 74 68 65 72 20 74 68 65 0a 2a   of either the.*
17fb0 2a 20 43 2d 41 50 49 20 6f 72 20 74 68 65 20 53  * C-API or the S
17fc0 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20  QL function..** 
17fd0 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
17fe0 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65  eter is a pointe
17ff0 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20  r to an integer 
18000 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73  into which.** is
18010 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20 31 20   written 0 or 1 
18020 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68 65 74  to indicate whet
18030 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 61  her [sqlite3_loa
18040 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 69  d_extension()] i
18050 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69 73 20 64  nterface.** is d
18060 69 73 61 62 6c 65 64 20 6f 72 20 65 6e 61 62 6c  isabled or enabl
18070 65 64 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69  ed following thi
18080 73 20 63 61 6c 6c 2e 20 20 54 68 65 20 73 65 63  s call.  The sec
18090 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6d 61  ond parameter ma
180a0 79 0a 2a 2a 20 62 65 20 61 20 4e 55 4c 4c 20 70  y.** be a NULL p
180b0 6f 69 6e 74 65 72 2c 20 69 6e 20 77 68 69 63 68  ointer, in which
180c0 20 63 61 73 65 20 74 68 65 20 6e 65 77 20 73 65   case the new se
180d0 74 74 69 6e 67 20 69 73 20 6e 6f 74 20 72 65 70  tting is not rep
180e0 6f 72 74 65 64 20 62 61 63 6b 2e 0a 2a 2a 20 3c  orted back..** <
180f0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e  /dd>.**.** </dl>
18100 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
18110 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  TE_DBCONFIG_LOOK
18120 41 53 49 44 45 20 20 20 20 20 20 20 20 20 20 20  ASIDE           
18130 20 20 31 30 30 31 20 2f 2a 20 76 6f 69 64 2a 20    1001 /* void* 
18140 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69  int int */.#defi
18150 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  ne SQLITE_DBCONF
18160 49 47 5f 45 4e 41 42 4c 45 5f 46 4b 45 59 20 20  IG_ENABLE_FKEY  
18170 20 20 20 20 20 20 20 20 20 31 30 30 32 20 2f 2a           1002 /*
18180 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65   int int* */.#de
18190 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f  fine SQLITE_DBCO
181a0 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47  NFIG_ENABLE_TRIG
181b0 47 45 52 20 20 20 20 20 20 20 20 31 30 30 33 20  GER        1003 
181c0 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23  /* int int* */.#
181d0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42  define SQLITE_DB
181e0 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 54  CONFIG_ENABLE_FT
181f0 53 33 5f 54 4f 4b 45 4e 49 5a 45 52 20 31 30 30  S3_TOKENIZER 100
18200 34 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f  4 /* int int* */
18210 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
18220 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f  DBCONFIG_ENABLE_
18230 4c 4f 41 44 5f 45 58 54 45 4e 53 49 4f 4e 20 31  LOAD_EXTENSION 1
18240 30 30 35 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20  005 /* int int* 
18250 2a 2f 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  */.../*.** CAPI3
18260 52 45 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44  REF: Enable Or D
18270 69 73 61 62 6c 65 20 45 78 74 65 6e 64 65 64 20  isable Extended 
18280 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20  Result Codes.** 
18290 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a  METHOD: sqlite3.
182a0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
182b0 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75  e3_extended_resu
182c0 6c 74 5f 63 6f 64 65 73 28 29 20 72 6f 75 74 69  lt_codes() routi
182d0 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69  ne enables or di
182e0 73 61 62 6c 65 73 20 74 68 65 0a 2a 2a 20 5b 65  sables the.** [e
182f0 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
18300 6f 64 65 73 5d 20 66 65 61 74 75 72 65 20 6f 66  odes] feature of
18310 20 53 51 4c 69 74 65 2e 20 5e 54 68 65 20 65 78   SQLite. ^The ex
18320 74 65 6e 64 65 64 20 72 65 73 75 6c 74 0a 2a 2a  tended result.**
18330 20 63 6f 64 65 73 20 61 72 65 20 64 69 73 61 62   codes are disab
18340 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 20 66  led by default f
18350 6f 72 20 68 69 73 74 6f 72 69 63 61 6c 20 63 6f  or historical co
18360 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2f 0a  mpatibility..*/.
18370 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 74 65  int sqlite3_exte
18380 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65  nded_result_code
18390 73 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20  s(sqlite3*, int 
183a0 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  onoff);../*.** C
183b0 41 50 49 33 52 45 46 3a 20 4c 61 73 74 20 49 6e  API3REF: Last In
183c0 73 65 72 74 20 52 6f 77 69 64 0a 2a 2a 20 4d 45  sert Rowid.** ME
183d0 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a  THOD: sqlite3.**
183e0 0a 2a 2a 20 5e 45 61 63 68 20 65 6e 74 72 79 20  .** ^Each entry 
183f0 69 6e 20 6d 6f 73 74 20 53 51 4c 69 74 65 20 74  in most SQLite t
18400 61 62 6c 65 73 20 28 65 78 63 65 70 74 20 66 6f  ables (except fo
18410 72 20 5b 57 49 54 48 4f 55 54 20 52 4f 57 49 44  r [WITHOUT ROWID
18420 5d 20 74 61 62 6c 65 73 29 0a 2a 2a 20 68 61 73  ] tables).** has
18430 20 61 20 75 6e 69 71 75 65 20 36 34 2d 62 69 74   a unique 64-bit
18440 20 73 69 67 6e 65 64 0a 2a 2a 20 69 6e 74 65 67   signed.** integ
18450 65 72 20 6b 65 79 20 63 61 6c 6c 65 64 20 74 68  er key called th
18460 65 20 5b 52 4f 57 49 44 20 7c 20 22 72 6f 77 69  e [ROWID | "rowi
18470 64 22 5d 2e 20 5e 54 68 65 20 72 6f 77 69 64 20  d"]. ^The rowid 
18480 69 73 20 61 6c 77 61 79 73 20 61 76 61 69 6c 61  is always availa
18490 62 6c 65 0a 2a 2a 20 61 73 20 61 6e 20 75 6e 64  ble.** as an und
184a0 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 20 6e  eclared column n
184b0 61 6d 65 64 20 52 4f 57 49 44 2c 20 4f 49 44 2c  amed ROWID, OID,
184c0 20 6f 72 20 5f 52 4f 57 49 44 5f 20 61 73 20 6c   or _ROWID_ as l
184d0 6f 6e 67 20 61 73 20 74 68 6f 73 65 0a 2a 2a 20  ong as those.** 
184e0 6e 61 6d 65 73 20 61 72 65 20 6e 6f 74 20 61 6c  names are not al
184f0 73 6f 20 75 73 65 64 20 62 79 20 65 78 70 6c 69  so used by expli
18500 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64 20 63  citly declared c
18510 6f 6c 75 6d 6e 73 2e 20 5e 49 66 0a 2a 2a 20 74  olumns. ^If.** t
18520 68 65 20 74 61 62 6c 65 20 68 61 73 20 61 20 63  he table has a c
18530 6f 6c 75 6d 6e 20 6f 66 20 74 79 70 65 20 5b 49  olumn of type [I
18540 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59 20 4b  NTEGER PRIMARY K
18550 45 59 5d 20 74 68 65 6e 20 74 68 61 74 20 63 6f  EY] then that co
18560 6c 75 6d 6e 0a 2a 2a 20 69 73 20 61 6e 6f 74 68  lumn.** is anoth
18570 65 72 20 61 6c 69 61 73 20 66 6f 72 20 74 68 65  er alias for the
18580 20 72 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54   rowid..**.** ^T
18590 68 65 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f  he sqlite3_last_
185a0 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 44 29 20  insert_rowid(D) 
185b0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
185c0 73 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66  s the [rowid] of
185d0 20 74 68 65 20 0a 2a 2a 20 6d 6f 73 74 20 72 65   the .** most re
185e0 63 65 6e 74 20 73 75 63 63 65 73 73 66 75 6c 20  cent successful 
185f0 5b 49 4e 53 45 52 54 5d 20 69 6e 74 6f 20 61 20  [INSERT] into a 
18600 72 6f 77 69 64 20 74 61 62 6c 65 20 6f 72 20 5b  rowid table or [
18610 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 0a 2a  virtual table].*
18620 2a 20 6f 6e 20 64 61 74 61 62 61 73 65 20 63 6f  * on database co
18630 6e 6e 65 63 74 69 6f 6e 20 44 2e 0a 2a 2a 20 5e  nnection D..** ^
18640 49 6e 73 65 72 74 73 20 69 6e 74 6f 20 5b 57 49  Inserts into [WI
18650 54 48 4f 55 54 20 52 4f 57 49 44 5d 20 74 61 62  THOUT ROWID] tab
18660 6c 65 73 20 61 72 65 20 6e 6f 74 20 72 65 63 6f  les are not reco
18670 72 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 6e 6f 20  rded..** ^If no 
18680 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45  successful [INSE
18690 52 54 5d 73 20 69 6e 74 6f 20 72 6f 77 69 64 20  RT]s into rowid 
186a0 74 61 62 6c 65 73 0a 2a 2a 20 68 61 76 65 20 65  tables.** have e
186b0 76 65 72 20 6f 63 63 75 72 72 65 64 20 6f 6e 20  ver occurred on 
186c0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
186d0 6e 65 63 74 69 6f 6e 20 44 2c 20 0a 2a 2a 20 74  nection D, .** t
186e0 68 65 6e 20 73 71 6c 69 74 65 33 5f 6c 61 73 74  hen sqlite3_last
186f0 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 44 29  _insert_rowid(D)
18700 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a   returns zero..*
18710 2a 0a 2a 2a 20 5e 28 49 66 20 61 6e 20 5b 49 4e  *.** ^(If an [IN
18720 53 45 52 54 5d 20 6f 63 63 75 72 73 20 77 69 74  SERT] occurs wit
18730 68 69 6e 20 61 20 74 72 69 67 67 65 72 20 6f 72  hin a trigger or
18740 20 77 69 74 68 69 6e 20 61 20 5b 76 69 72 74 75   within a [virtu
18750 61 6c 20 74 61 62 6c 65 5d 0a 2a 2a 20 6d 65 74  al table].** met
18760 68 6f 64 2c 20 74 68 65 6e 20 74 68 69 73 20 72  hod, then this r
18770 6f 75 74 69 6e 65 20 77 69 6c 6c 20 72 65 74 75  outine will retu
18780 72 6e 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f  rn the [rowid] o
18790 66 20 74 68 65 20 69 6e 73 65 72 74 65 64 0a 2a  f the inserted.*
187a0 2a 20 72 6f 77 20 61 73 20 6c 6f 6e 67 20 61 73  * row as long as
187b0 20 74 68 65 20 74 72 69 67 67 65 72 20 6f 72 20   the trigger or 
187c0 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 65  virtual table me
187d0 74 68 6f 64 20 69 73 20 72 75 6e 6e 69 6e 67 2e  thod is running.
187e0 0a 2a 2a 20 42 75 74 20 6f 6e 63 65 20 74 68 65  .** But once the
187f0 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 72 74   trigger or virt
18800 75 61 6c 20 74 61 62 6c 65 20 6d 65 74 68 6f 64  ual table method
18810 20 65 6e 64 73 2c 20 74 68 65 20 76 61 6c 75 65   ends, the value
18820 20 72 65 74 75 72 6e 65 64 20 0a 2a 2a 20 62 79   returned .** by
18830 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65   this routine re
18840 76 65 72 74 73 20 74 6f 20 77 68 61 74 20 69 74  verts to what it
18850 20 77 61 73 20 62 65 66 6f 72 65 20 74 68 65 20   was before the 
18860 74 72 69 67 67 65 72 20 6f 72 20 76 69 72 74 75  trigger or virtu
18870 61 6c 0a 2a 2a 20 74 61 62 6c 65 20 6d 65 74 68  al.** table meth
18880 6f 64 20 62 65 67 61 6e 2e 29 5e 0a 2a 2a 0a 2a  od began.)^.**.*
18890 2a 20 5e 41 6e 20 5b 49 4e 53 45 52 54 5d 20 74  * ^An [INSERT] t
188a0 68 61 74 20 66 61 69 6c 73 20 64 75 65 20 74 6f  hat fails due to
188b0 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69   a constraint vi
188c0 6f 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20 61  olation is not a
188d0 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 20 5b  .** successful [
188e0 49 4e 53 45 52 54 5d 20 61 6e 64 20 64 6f 65 73  INSERT] and does
188f0 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20   not change the 
18900 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62  value returned b
18910 79 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e  y this.** routin
18920 65 2e 20 20 5e 54 68 75 73 20 49 4e 53 45 52 54  e.  ^Thus INSERT
18930 20 4f 52 20 46 41 49 4c 2c 20 49 4e 53 45 52 54   OR FAIL, INSERT
18940 20 4f 52 20 49 47 4e 4f 52 45 2c 20 49 4e 53 45   OR IGNORE, INSE
18950 52 54 20 4f 52 20 52 4f 4c 4c 42 41 43 4b 2c 0a  RT OR ROLLBACK,.
18960 2a 2a 20 61 6e 64 20 49 4e 53 45 52 54 20 4f 52  ** and INSERT OR
18970 20 41 42 4f 52 54 20 6d 61 6b 65 20 6e 6f 20 63   ABORT make no c
18980 68 61 6e 67 65 73 20 74 6f 20 74 68 65 20 72 65  hanges to the re
18990 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68  turn value of th
189a0 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 77 68  is.** routine wh
189b0 65 6e 20 74 68 65 69 72 20 69 6e 73 65 72 74 69  en their inserti
189c0 6f 6e 20 66 61 69 6c 73 2e 20 20 5e 28 57 68 65  on fails.  ^(Whe
189d0 6e 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c  n INSERT OR REPL
189e0 41 43 45 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65 72  ACE.** encounter
189f0 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76  s a constraint v
18a00 69 6f 6c 61 74 69 6f 6e 2c 20 69 74 20 64 6f 65  iolation, it doe
18a10 73 20 6e 6f 74 20 66 61 69 6c 2e 20 20 54 68 65  s not fail.  The
18a20 0a 2a 2a 20 49 4e 53 45 52 54 20 63 6f 6e 74 69  .** INSERT conti
18a30 6e 75 65 73 20 74 6f 20 63 6f 6d 70 6c 65 74 69  nues to completi
18a40 6f 6e 20 61 66 74 65 72 20 64 65 6c 65 74 69 6e  on after deletin
18a50 67 20 72 6f 77 73 20 74 68 61 74 20 63 61 75 73  g rows that caus
18a60 65 64 0a 2a 2a 20 74 68 65 20 63 6f 6e 73 74 72  ed.** the constr
18a70 61 69 6e 74 20 70 72 6f 62 6c 65 6d 20 73 6f 20  aint problem so 
18a80 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43  INSERT OR REPLAC
18a90 45 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 63 68  E will always ch
18aa0 61 6e 67 65 0a 2a 2a 20 74 68 65 20 72 65 74 75  ange.** the retu
18ab0 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73  rn value of this
18ac0 20 69 6e 74 65 72 66 61 63 65 2e 29 5e 0a 2a 2a   interface.)^.**
18ad0 0a 2a 2a 20 5e 46 6f 72 20 74 68 65 20 70 75 72  .** ^For the pur
18ae0 70 6f 73 65 73 20 6f 66 20 74 68 69 73 20 72 6f  poses of this ro
18af0 75 74 69 6e 65 2c 20 61 6e 20 5b 49 4e 53 45 52  utine, an [INSER
18b00 54 5d 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64  T] is considered
18b10 20 74 6f 0a 2a 2a 20 62 65 20 73 75 63 63 65 73   to.** be succes
18b20 73 66 75 6c 20 65 76 65 6e 20 69 66 20 69 74 20  sful even if it 
18b30 69 73 20 73 75 62 73 65 71 75 65 6e 74 6c 79 20  is subsequently 
18b40 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a  rolled back..**.
18b50 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e  ** This function
18b60 20 69 73 20 61 63 63 65 73 73 69 62 6c 65 20 74   is accessible t
18b70 6f 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  o SQL statements
18b80 20 76 69 61 20 74 68 65 0a 2a 2a 20 5b 6c 61 73   via the.** [las
18b90 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29  t_insert_rowid()
18ba0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a   SQL function]..
18bb0 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72  **.** If a separ
18bc0 61 74 65 20 74 68 72 65 61 64 20 70 65 72 66 6f  ate thread perfo
18bd0 72 6d 73 20 61 20 6e 65 77 20 5b 49 4e 53 45 52  rms a new [INSER
18be0 54 5d 20 6f 6e 20 74 68 65 20 73 61 6d 65 0a 2a  T] on the same.*
18bf0 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  * database conne
18c00 63 74 69 6f 6e 20 77 68 69 6c 65 20 74 68 65 20  ction while the 
18c10 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e  [sqlite3_last_in
18c20 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 0a 2a 2a  sert_rowid()].**
18c30 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e   function is run
18c40 6e 69 6e 67 20 61 6e 64 20 74 68 75 73 20 63 68  ning and thus ch
18c50 61 6e 67 65 73 20 74 68 65 20 6c 61 73 74 20 69  anges the last i
18c60 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d 2c 0a 2a  nsert [rowid],.*
18c70 2a 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65  * then the value
18c80 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71   returned by [sq
18c90 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72  lite3_last_inser
18ca0 74 5f 72 6f 77 69 64 28 29 5d 20 69 73 0a 2a 2a  t_rowid()] is.**
18cb0 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61   unpredictable a
18cc0 6e 64 20 6d 69 67 68 74 20 6e 6f 74 20 65 71 75  nd might not equ
18cd0 61 6c 20 65 69 74 68 65 72 20 74 68 65 20 6f 6c  al either the ol
18ce0 64 20 6f 72 20 74 68 65 20 6e 65 77 0a 2a 2a 20  d or the new.** 
18cf0 6c 61 73 74 20 69 6e 73 65 72 74 20 5b 72 6f 77  last insert [row
18d00 69 64 5d 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f  id]..*/.sqlite3_
18d10 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6c 61  int64 sqlite3_la
18d20 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28  st_insert_rowid(
18d30 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a  sqlite3*);../*.*
18d40 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 75 6e  * CAPI3REF: Coun
18d50 74 20 54 68 65 20 4e 75 6d 62 65 72 20 4f 66 20  t The Number Of 
18d60 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a  Rows Modified.**
18d70 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
18d80 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e  .**.** ^This fun
18d90 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68  ction returns th
18da0 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73  e number of rows
18db0 20 6d 6f 64 69 66 69 65 64 2c 20 69 6e 73 65 72   modified, inser
18dc0 74 65 64 20 6f 72 0a 2a 2a 20 64 65 6c 65 74 65  ted or.** delete
18dd0 64 20 62 79 20 74 68 65 20 6d 6f 73 74 20 72 65  d by the most re
18de0 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64  cently completed
18df0 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20   INSERT, UPDATE 
18e00 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 73 74 61  or DELETE.** sta
18e10 74 65 6d 65 6e 74 20 6f 6e 20 74 68 65 20 64 61  tement on the da
18e20 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
18e30 6e 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74  n specified by t
18e40 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65  he only paramete
18e50 72 2e 0a 2a 2a 20 5e 45 78 65 63 75 74 69 6e 67  r..** ^Executing
18e60 20 61 6e 79 20 6f 74 68 65 72 20 74 79 70 65 20   any other type 
18e70 6f 66 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  of SQL statement
18e80 20 64 6f 65 73 20 6e 6f 74 20 6d 6f 64 69 66 79   does not modify
18e90 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65   the value.** re
18ea0 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 20 66  turned by this f
18eb0 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e  unction..**.** ^
18ec0 4f 6e 6c 79 20 63 68 61 6e 67 65 73 20 6d 61 64  Only changes mad
18ed0 65 20 64 69 72 65 63 74 6c 79 20 62 79 20 74 68  e directly by th
18ee0 65 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45  e INSERT, UPDATE
18ef0 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74 65   or DELETE state
18f00 6d 65 6e 74 20 61 72 65 0a 2a 2a 20 63 6f 6e 73  ment are.** cons
18f10 69 64 65 72 65 64 20 2d 20 61 75 78 69 6c 69 61  idered - auxilia
18f20 72 79 20 63 68 61 6e 67 65 73 20 63 61 75 73 65  ry changes cause
18f30 64 20 62 79 20 5b 43 52 45 41 54 45 20 54 52 49  d by [CREATE TRI
18f40 47 47 45 52 20 7c 20 74 72 69 67 67 65 72 73 5d  GGER | triggers]
18f50 2c 20 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b  , .** [foreign k
18f60 65 79 20 61 63 74 69 6f 6e 73 5d 20 6f 72 20 5b  ey actions] or [
18f70 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74 72 61  REPLACE] constra
18f80 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e 20 61  int resolution a
18f90 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 0a  re not counted..
18fa0 2a 2a 20 0a 2a 2a 20 43 68 61 6e 67 65 73 20 74  ** .** Changes t
18fb0 6f 20 61 20 76 69 65 77 20 74 68 61 74 20 61 72  o a view that ar
18fc0 65 20 69 6e 74 65 72 63 65 70 74 65 64 20 62 79  e intercepted by
18fd0 20 0a 2a 2a 20 5b 49 4e 53 54 45 41 44 20 4f 46   .** [INSTEAD OF
18fe0 20 74 72 69 67 67 65 72 20 7c 20 49 4e 53 54 45   trigger | INSTE
18ff0 41 44 20 4f 46 20 74 72 69 67 67 65 72 73 5d 20  AD OF triggers] 
19000 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e  are not counted.
19010 20 5e 54 68 65 20 76 61 6c 75 65 20 0a 2a 2a 20   ^The value .** 
19020 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
19030 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 69 6d  te3_changes() im
19040 6d 65 64 69 61 74 65 6c 79 20 61 66 74 65 72 20  mediately after 
19050 61 6e 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54  an INSERT, UPDAT
19060 45 20 6f 72 20 0a 2a 2a 20 44 45 4c 45 54 45 20  E or .** DELETE 
19070 73 74 61 74 65 6d 65 6e 74 20 72 75 6e 20 6f 6e  statement run on
19080 20 61 20 76 69 65 77 20 69 73 20 61 6c 77 61 79   a view is alway
19090 73 20 7a 65 72 6f 2e 20 4f 6e 6c 79 20 63 68 61  s zero. Only cha
190a0 6e 67 65 73 20 6d 61 64 65 20 74 6f 20 72 65 61  nges made to rea
190b0 6c 20 0a 2a 2a 20 74 61 62 6c 65 73 20 61 72 65  l .** tables are
190c0 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20   counted..**.** 
190d0 54 68 69 6e 67 73 20 61 72 65 20 6d 6f 72 65 20  Things are more 
190e0 63 6f 6d 70 6c 69 63 61 74 65 64 20 69 66 20 74  complicated if t
190f0 68 65 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  he sqlite3_chang
19100 65 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73  es() function is
19110 0a 2a 2a 20 65 78 65 63 75 74 65 64 20 77 68 69  .** executed whi
19120 6c 65 20 61 20 74 72 69 67 67 65 72 20 70 72 6f  le a trigger pro
19130 67 72 61 6d 20 69 73 20 72 75 6e 6e 69 6e 67 2e  gram is running.
19140 20 54 68 69 73 20 6d 61 79 20 68 61 70 70 65 6e   This may happen
19150 20 69 66 20 74 68 65 0a 2a 2a 20 70 72 6f 67 72   if the.** progr
19160 61 6d 20 75 73 65 73 20 74 68 65 20 5b 63 68 61  am uses the [cha
19170 6e 67 65 73 28 29 20 53 51 4c 20 66 75 6e 63 74  nges() SQL funct
19180 69 6f 6e 5d 2c 20 6f 72 20 69 66 20 73 6f 6d 65  ion], or if some
19190 20 6f 74 68 65 72 20 63 61 6c 6c 62 61 63 6b 0a   other callback.
191a0 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 6e 76 6f  ** function invo
191b0 6b 65 73 20 73 71 6c 69 74 65 33 5f 63 68 61 6e  kes sqlite3_chan
191c0 67 65 73 28 29 20 64 69 72 65 63 74 6c 79 2e 20  ges() directly. 
191d0 45 73 73 65 6e 74 69 61 6c 6c 79 3a 0a 2a 2a 20  Essentially:.** 
191e0 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c  .** <ul>.**   <l
191f0 69 3e 20 5e 28 42 65 66 6f 72 65 20 65 6e 74 65  i> ^(Before ente
19200 72 69 6e 67 20 61 20 74 72 69 67 67 65 72 20 70  ring a trigger p
19210 72 6f 67 72 61 6d 20 74 68 65 20 76 61 6c 75 65  rogram the value
19220 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20   returned by.** 
19230 20 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63         sqlite3_c
19240 68 61 6e 67 65 73 28 29 20 66 75 6e 63 74 69 6f  hanges() functio
19250 6e 20 69 73 20 73 61 76 65 64 2e 20 41 66 74 65  n is saved. Afte
19260 72 20 74 68 65 20 74 72 69 67 67 65 72 20 70 72  r the trigger pr
19270 6f 67 72 61 6d 20 0a 2a 2a 20 20 20 20 20 20 20  ogram .**       
19280 20 68 61 73 20 66 69 6e 69 73 68 65 64 2c 20 74   has finished, t
19290 68 65 20 6f 72 69 67 69 6e 61 6c 20 76 61 6c 75  he original valu
192a0 65 20 69 73 20 72 65 73 74 6f 72 65 64 2e 29 5e  e is restored.)^
192b0 0a 2a 2a 20 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5e  .** .**   <li> ^
192c0 28 57 69 74 68 69 6e 20 61 20 74 72 69 67 67 65  (Within a trigge
192d0 72 20 70 72 6f 67 72 61 6d 20 65 61 63 68 20 49  r program each I
192e0 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20 61 6e  NSERT, UPDATE an
192f0 64 20 44 45 4c 45 54 45 20 0a 2a 2a 20 20 20 20  d DELETE .**    
19300 20 20 20 20 73 74 61 74 65 6d 65 6e 74 20 73 65      statement se
19310 74 73 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  ts the value ret
19320 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
19330 5f 63 68 61 6e 67 65 73 28 29 20 0a 2a 2a 20 20  _changes() .**  
19340 20 20 20 20 20 20 75 70 6f 6e 20 63 6f 6d 70 6c        upon compl
19350 65 74 69 6f 6e 20 61 73 20 6e 6f 72 6d 61 6c 2e  etion as normal.
19360 20 4f 66 20 63 6f 75 72 73 65 2c 20 74 68 69 73   Of course, this
19370 20 76 61 6c 75 65 20 77 69 6c 6c 20 6e 6f 74 20   value will not 
19380 69 6e 63 6c 75 64 65 20 0a 2a 2a 20 20 20 20 20  include .**     
19390 20 20 20 61 6e 79 20 63 68 61 6e 67 65 73 20 70     any changes p
193a0 65 72 66 6f 72 6d 65 64 20 62 79 20 73 75 62 2d  erformed by sub-
193b0 74 72 69 67 67 65 72 73 2c 20 61 73 20 74 68 65  triggers, as the
193c0 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73   sqlite3_changes
193d0 28 29 20 0a 2a 2a 20 20 20 20 20 20 20 20 76 61  () .**        va
193e0 6c 75 65 20 77 69 6c 6c 20 62 65 20 73 61 76 65  lue will be save
193f0 64 20 61 6e 64 20 72 65 73 74 6f 72 65 64 20 61  d and restored a
19400 66 74 65 72 20 65 61 63 68 20 73 75 62 2d 74 72  fter each sub-tr
19410 69 67 67 65 72 20 68 61 73 20 72 75 6e 2e 29 5e  igger has run.)^
19420 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 0a 2a 2a  .** </ul>.** .**
19430 20 5e 54 68 69 73 20 6d 65 61 6e 73 20 74 68 61   ^This means tha
19440 74 20 69 66 20 74 68 65 20 63 68 61 6e 67 65 73  t if the changes
19450 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  () SQL function 
19460 28 6f 72 20 73 69 6d 69 6c 61 72 29 20 69 73 20  (or similar) is 
19470 75 73 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 66  used.** by the f
19480 69 72 73 74 20 49 4e 53 45 52 54 2c 20 55 50 44  irst INSERT, UPD
19490 41 54 45 20 6f 72 20 44 45 4c 45 54 45 20 73 74  ATE or DELETE st
194a0 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 61  atement within a
194b0 20 74 72 69 67 67 65 72 2c 20 69 74 20 0a 2a 2a   trigger, it .**
194c0 20 72 65 74 75 72 6e 73 20 74 68 65 20 76 61 6c   returns the val
194d0 75 65 20 61 73 20 73 65 74 20 77 68 65 6e 20 74  ue as set when t
194e0 68 65 20 63 61 6c 6c 69 6e 67 20 73 74 61 74 65  he calling state
194f0 6d 65 6e 74 20 62 65 67 61 6e 20 65 78 65 63 75  ment began execu
19500 74 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 69 74 20  ting..** ^If it 
19510 69 73 20 75 73 65 64 20 62 79 20 74 68 65 20 73  is used by the s
19520 65 63 6f 6e 64 20 6f 72 20 73 75 62 73 65 71 75  econd or subsequ
19530 65 6e 74 20 73 75 63 68 20 73 74 61 74 65 6d 65  ent such stateme
19540 6e 74 20 77 69 74 68 69 6e 20 61 20 74 72 69 67  nt within a trig
19550 67 65 72 20 0a 2a 2a 20 70 72 6f 67 72 61 6d 2c  ger .** program,
19560 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
19570 6e 65 64 20 72 65 66 6c 65 63 74 73 20 74 68 65  ned reflects the
19580 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20   number of rows 
19590 6d 6f 64 69 66 69 65 64 20 62 79 20 74 68 65 20  modified by the 
195a0 0a 2a 2a 20 70 72 65 76 69 6f 75 73 20 49 4e 53  .** previous INS
195b0 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20 44  ERT, UPDATE or D
195c0 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20  ELETE statement 
195d0 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20  within the same 
195e0 74 72 69 67 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 53  trigger..**.** S
195f0 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c  ee also the [sql
19600 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67  ite3_total_chang
19610 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2c  es()] interface,
19620 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63   the.** [count_c
19630 68 61 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c 20  hanges pragma], 
19640 61 6e 64 20 74 68 65 20 5b 63 68 61 6e 67 65 73  and the [changes
19650 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d  () SQL function]
19660 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70  ..**.** If a sep
19670 61 72 61 74 65 20 74 68 72 65 61 64 20 6d 61 6b  arate thread mak
19680 65 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 68  es changes on th
19690 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20  e same database 
196a0 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68  connection.** wh
196b0 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61  ile [sqlite3_cha
196c0 6e 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69  nges()] is runni
196d0 6e 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75  ng then the valu
196e0 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 69 73  e returned.** is
196f0 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61   unpredictable a
19700 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75  nd not meaningfu
19710 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  l..*/.int sqlite
19720 33 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 74 65  3_changes(sqlite
19730 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  3*);../*.** CAPI
19740 33 52 45 46 3a 20 54 6f 74 61 6c 20 4e 75 6d 62  3REF: Total Numb
19750 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66  er Of Rows Modif
19760 69 65 64 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ied.** METHOD: s
19770 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68  qlite3.**.** ^Th
19780 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  is function retu
19790 72 6e 73 20 74 68 65 20 74 6f 74 61 6c 20 6e 75  rns the total nu
197a0 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 69 6e 73  mber of rows ins
197b0 65 72 74 65 64 2c 20 6d 6f 64 69 66 69 65 64 20  erted, modified 
197c0 6f 72 0a 2a 2a 20 64 65 6c 65 74 65 64 20 62 79  or.** deleted by
197d0 20 61 6c 6c 20 5b 49 4e 53 45 52 54 5d 2c 20 5b   all [INSERT], [
197e0 55 50 44 41 54 45 5d 20 6f 72 20 5b 44 45 4c 45  UPDATE] or [DELE
197f0 54 45 5d 20 73 74 61 74 65 6d 65 6e 74 73 20 63  TE] statements c
19800 6f 6d 70 6c 65 74 65 64 0a 2a 2a 20 73 69 6e 63  ompleted.** sinc
19810 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  e the database c
19820 6f 6e 6e 65 63 74 69 6f 6e 20 77 61 73 20 6f 70  onnection was op
19830 65 6e 65 64 2c 20 69 6e 63 6c 75 64 69 6e 67 20  ened, including 
19840 74 68 6f 73 65 20 65 78 65 63 75 74 65 64 20 61  those executed a
19850 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 74 72 69  s.** part of tri
19860 67 67 65 72 20 70 72 6f 67 72 61 6d 73 2e 20 5e  gger programs. ^
19870 45 78 65 63 75 74 69 6e 67 20 61 6e 79 20 6f 74  Executing any ot
19880 68 65 72 20 74 79 70 65 20 6f 66 20 53 51 4c 20  her type of SQL 
19890 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 64 6f 65  statement.** doe
198a0 73 20 6e 6f 74 20 61 66 66 65 63 74 20 74 68 65  s not affect the
198b0 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
198c0 62 79 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c  by sqlite3_total
198d0 5f 63 68 61 6e 67 65 73 28 29 2e 0a 2a 2a 20 0a  _changes()..** .
198e0 2a 2a 20 5e 43 68 61 6e 67 65 73 20 6d 61 64 65  ** ^Changes made
198f0 20 61 73 20 70 61 72 74 20 6f 66 20 5b 66 6f 72   as part of [for
19900 65 69 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73  eign key actions
19910 5d 20 61 72 65 20 69 6e 63 6c 75 64 65 64 20 69  ] are included i
19920 6e 20 74 68 65 0a 2a 2a 20 63 6f 75 6e 74 2c 20  n the.** count, 
19930 62 75 74 20 74 68 6f 73 65 20 6d 61 64 65 20 61  but those made a
19940 73 20 70 61 72 74 20 6f 66 20 52 45 50 4c 41 43  s part of REPLAC
19950 45 20 63 6f 6e 73 74 72 61 69 6e 74 20 72 65 73  E constraint res
19960 6f 6c 75 74 69 6f 6e 20 61 72 65 0a 2a 2a 20 6e  olution are.** n
19970 6f 74 2e 20 5e 43 68 61 6e 67 65 73 20 74 6f 20  ot. ^Changes to 
19980 61 20 76 69 65 77 20 74 68 61 74 20 61 72 65 20  a view that are 
19990 69 6e 74 65 72 63 65 70 74 65 64 20 62 79 20 49  intercepted by I
199a0 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67 67 65  NSTEAD OF trigge
199b0 72 73 20 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 63  rs .** are not c
199c0 6f 75 6e 74 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 53  ounted..** .** S
199d0 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c  ee also the [sql
199e0 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20  ite3_changes()] 
199f0 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 0a 2a  interface, the.*
19a00 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73  * [count_changes
19a10 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68   pragma], and th
19a20 65 20 5b 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73  e [total_changes
19a30 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d  () SQL function]
19a40 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70  ..**.** If a sep
19a50 61 72 61 74 65 20 74 68 72 65 61 64 20 6d 61 6b  arate thread mak
19a60 65 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 68  es changes on th
19a70 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20  e same database 
19a80 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68  connection.** wh
19a90 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74  ile [sqlite3_tot
19aa0 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 73  al_changes()] is
19ab0 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68   running then th
19ac0 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72  e value.** retur
19ad0 6e 65 64 20 69 73 20 75 6e 70 72 65 64 69 63 74  ned is unpredict
19ae0 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61  able and not mea
19af0 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20  ningful..*/.int 
19b00 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68  sqlite3_total_ch
19b10 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b  anges(sqlite3*);
19b20 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
19b30 3a 20 49 6e 74 65 72 72 75 70 74 20 41 20 4c 6f  : Interrupt A Lo
19b40 6e 67 2d 52 75 6e 6e 69 6e 67 20 51 75 65 72 79  ng-Running Query
19b50 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
19b60 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  te3.**.** ^This 
19b70 66 75 6e 63 74 69 6f 6e 20 63 61 75 73 65 73 20  function causes 
19b80 61 6e 79 20 70 65 6e 64 69 6e 67 20 64 61 74 61  any pending data
19b90 62 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 20 74  base operation t
19ba0 6f 20 61 62 6f 72 74 20 61 6e 64 0a 2a 2a 20 72  o abort and.** r
19bb0 65 74 75 72 6e 20 61 74 20 69 74 73 20 65 61 72  eturn at its ear
19bc0 6c 69 65 73 74 20 6f 70 70 6f 72 74 75 6e 69 74  liest opportunit
19bd0 79 2e 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  y. This routine 
19be0 69 73 20 74 79 70 69 63 61 6c 6c 79 0a 2a 2a 20  is typically.** 
19bf0 63 61 6c 6c 65 64 20 69 6e 20 72 65 73 70 6f 6e  called in respon
19c00 73 65 20 74 6f 20 61 20 75 73 65 72 20 61 63 74  se to a user act
19c10 69 6f 6e 20 73 75 63 68 20 61 73 20 70 72 65 73  ion such as pres
19c20 73 69 6e 67 20 22 43 61 6e 63 65 6c 22 0a 2a 2a  sing "Cancel".**
19c30 20 6f 72 20 43 74 72 6c 2d 43 20 77 68 65 72 65   or Ctrl-C where
19c40 20 74 68 65 20 75 73 65 72 20 77 61 6e 74 73 20   the user wants 
19c50 61 20 6c 6f 6e 67 20 71 75 65 72 79 20 6f 70 65  a long query ope
19c60 72 61 74 69 6f 6e 20 74 6f 20 68 61 6c 74 0a 2a  ration to halt.*
19c70 2a 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a  * immediately..*
19c80 2a 0a 2a 2a 20 5e 49 74 20 69 73 20 73 61 66 65  *.** ^It is safe
19c90 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f   to call this ro
19ca0 75 74 69 6e 65 20 66 72 6f 6d 20 61 20 74 68 72  utine from a thr
19cb0 65 61 64 20 64 69 66 66 65 72 65 6e 74 20 66 72  ead different fr
19cc0 6f 6d 20 74 68 65 0a 2a 2a 20 74 68 72 65 61 64  om the.** thread
19cd0 20 74 68 61 74 20 69 73 20 63 75 72 72 65 6e 74   that is current
19ce0 6c 79 20 72 75 6e 6e 69 6e 67 20 74 68 65 20 64  ly running the d
19cf0 61 74 61 62 61 73 65 20 6f 70 65 72 61 74 69 6f  atabase operatio
19d00 6e 2e 20 20 42 75 74 20 69 74 0a 2a 2a 20 69 73  n.  But it.** is
19d10 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 63 61 6c   not safe to cal
19d20 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77  l this routine w
19d30 69 74 68 20 61 20 5b 64 61 74 61 62 61 73 65 20  ith a [database 
19d40 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74  connection] that
19d50 0a 2a 2a 20 69 73 20 63 6c 6f 73 65 64 20 6f 72  .** is closed or
19d60 20 6d 69 67 68 74 20 63 6c 6f 73 65 20 62 65 66   might close bef
19d70 6f 72 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  ore sqlite3_inte
19d80 72 72 75 70 74 28 29 20 72 65 74 75 72 6e 73 2e  rrupt() returns.
19d90 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 53 51  .**.** ^If an SQ
19da0 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 76  L operation is v
19db0 65 72 79 20 6e 65 61 72 6c 79 20 66 69 6e 69 73  ery nearly finis
19dc0 68 65 64 20 61 74 20 74 68 65 20 74 69 6d 65 20  hed at the time 
19dd0 77 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  when.** sqlite3_
19de0 69 6e 74 65 72 72 75 70 74 28 29 20 69 73 20 63  interrupt() is c
19df0 61 6c 6c 65 64 2c 20 74 68 65 6e 20 69 74 20 6d  alled, then it m
19e00 69 67 68 74 20 6e 6f 74 20 68 61 76 65 20 61 6e  ight not have an
19e10 20 6f 70 70 6f 72 74 75 6e 69 74 79 0a 2a 2a 20   opportunity.** 
19e20 74 6f 20 62 65 20 69 6e 74 65 72 72 75 70 74 65  to be interrupte
19e30 64 20 61 6e 64 20 6d 69 67 68 74 20 63 6f 6e 74  d and might cont
19e40 69 6e 75 65 20 74 6f 20 63 6f 6d 70 6c 65 74 69  inue to completi
19e50 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 53 51  on..**.** ^An SQ
19e60 4c 20 6f 70 65 72 61 74 69 6f 6e 20 74 68 61 74  L operation that
19e70 20 69 73 20 69 6e 74 65 72 72 75 70 74 65 64 20   is interrupted 
19e80 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c  will return [SQL
19e90 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2e 0a  ITE_INTERRUPT]..
19ea0 2a 2a 20 5e 49 66 20 74 68 65 20 69 6e 74 65 72  ** ^If the inter
19eb0 72 75 70 74 65 64 20 53 51 4c 20 6f 70 65 72 61  rupted SQL opera
19ec0 74 69 6f 6e 20 69 73 20 61 6e 20 49 4e 53 45 52  tion is an INSER
19ed0 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45  T, UPDATE, or DE
19ee0 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20 69 73 20  LETE.** that is 
19ef0 69 6e 73 69 64 65 20 61 6e 20 65 78 70 6c 69 63  inside an explic
19f00 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20  it transaction, 
19f10 74 68 65 6e 20 74 68 65 20 65 6e 74 69 72 65 20  then the entire 
19f20 74 72 61 6e 73 61 63 74 69 6f 6e 0a 2a 2a 20 77  transaction.** w
19f30 69 6c 6c 20 62 65 20 72 6f 6c 6c 65 64 20 62 61  ill be rolled ba
19f40 63 6b 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ck automatically
19f50 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
19f60 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 44  ite3_interrupt(D
19f70 29 20 63 61 6c 6c 20 69 73 20 69 6e 20 65 66 66  ) call is in eff
19f80 65 63 74 20 75 6e 74 69 6c 20 61 6c 6c 20 63 75  ect until all cu
19f90 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 0a  rrently running.
19fa0 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ** SQL statement
19fb0 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63  s on [database c
19fc0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 63 6f 6d  onnection] D com
19fd0 70 6c 65 74 65 2e 20 20 5e 41 6e 79 20 6e 65 77  plete.  ^Any new
19fe0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a   SQL statements.
19ff0 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74 61 72  ** that are star
1a000 74 65 64 20 61 66 74 65 72 20 74 68 65 20 73 71  ted after the sq
1a010 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
1a020 29 20 63 61 6c 6c 20 61 6e 64 20 62 65 66 6f 72  ) call and befor
1a030 65 20 74 68 65 20 0a 2a 2a 20 72 75 6e 6e 69 6e  e the .** runnin
1a040 67 20 73 74 61 74 65 6d 65 6e 74 73 20 72 65 61  g statements rea
1a050 63 68 65 73 20 7a 65 72 6f 20 61 72 65 20 69 6e  ches zero are in
1a060 74 65 72 72 75 70 74 65 64 20 61 73 20 69 66 20  terrupted as if 
1a070 74 68 65 79 20 68 61 64 20 62 65 65 6e 0a 2a 2a  they had been.**
1a080 20 72 75 6e 6e 69 6e 67 20 70 72 69 6f 72 20 74   running prior t
1a090 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e  o the sqlite3_in
1a0a0 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c 2e 20  terrupt() call. 
1a0b0 20 5e 4e 65 77 20 53 51 4c 20 73 74 61 74 65 6d   ^New SQL statem
1a0c0 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65  ents.** that are
1a0d0 20 73 74 61 72 74 65 64 20 61 66 74 65 72 20 74   started after t
1a0e0 68 65 20 72 75 6e 6e 69 6e 67 20 73 74 61 74 65  he running state
1a0f0 6d 65 6e 74 20 63 6f 75 6e 74 20 72 65 61 63 68  ment count reach
1a100 65 73 20 7a 65 72 6f 20 61 72 65 0a 2a 2a 20 6e  es zero are.** n
1a110 6f 74 20 65 66 66 65 63 74 65 64 20 62 79 20 74  ot effected by t
1a120 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  he sqlite3_inter
1a130 72 75 70 74 28 29 2e 0a 2a 2a 20 5e 41 20 63 61  rupt()..** ^A ca
1a140 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e  ll to sqlite3_in
1a150 74 65 72 72 75 70 74 28 44 29 20 74 68 61 74 20  terrupt(D) that 
1a160 6f 63 63 75 72 73 20 77 68 65 6e 20 74 68 65 72  occurs when ther
1a170 65 20 61 72 65 20 6e 6f 20 72 75 6e 6e 69 6e 67  e are no running
1a180 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  .** SQL statemen
1a190 74 73 20 69 73 20 61 20 6e 6f 2d 6f 70 20 61 6e  ts is a no-op an
1a1a0 64 20 68 61 73 20 6e 6f 20 65 66 66 65 63 74 20  d has no effect 
1a1b0 6f 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  on SQL statement
1a1c0 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74  s.** that are st
1a1d0 61 72 74 65 64 20 61 66 74 65 72 20 74 68 65 20  arted after the 
1a1e0 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
1a1f0 74 28 29 20 63 61 6c 6c 20 72 65 74 75 72 6e 73  t() call returns
1a200 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 64  ..**.** If the d
1a210 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1a220 6f 6e 20 63 6c 6f 73 65 73 20 77 68 69 6c 65 20  on closes while 
1a230 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75  [sqlite3_interru
1a240 70 74 28 29 5d 0a 2a 2a 20 69 73 20 72 75 6e 6e  pt()].** is runn
1a250 69 6e 67 20 74 68 65 6e 20 62 61 64 20 74 68 69  ing then bad thi
1a260 6e 67 73 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20  ngs will likely 
1a270 68 61 70 70 65 6e 2e 0a 2a 2f 0a 76 6f 69 64 20  happen..*/.void 
1a280 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
1a290 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a  t(sqlite3*);../*
1a2a0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
1a2b0 74 65 72 6d 69 6e 65 20 49 66 20 41 6e 20 53 51  termine If An SQ
1a2c0 4c 20 53 74 61 74 65 6d 65 6e 74 20 49 73 20 43  L Statement Is C
1a2d0 6f 6d 70 6c 65 74 65 0a 2a 2a 0a 2a 2a 20 54 68  omplete.**.** Th
1a2e0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
1a2f0 20 75 73 65 66 75 6c 20 64 75 72 69 6e 67 20 63   useful during c
1a300 6f 6d 6d 61 6e 64 2d 6c 69 6e 65 20 69 6e 70 75  ommand-line inpu
1a310 74 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 69  t to determine i
1a320 66 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74  f the.** current
1a330 6c 79 20 65 6e 74 65 72 65 64 20 74 65 78 74 20  ly entered text 
1a340 73 65 65 6d 73 20 74 6f 20 66 6f 72 6d 20 61 20  seems to form a 
1a350 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73 74 61  complete SQL sta
1a360 74 65 6d 65 6e 74 20 6f 72 0a 2a 2a 20 69 66 20  tement or.** if 
1a370 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 70 75 74  additional input
1a380 20 69 73 20 6e 65 65 64 65 64 20 62 65 66 6f 72   is needed befor
1a390 65 20 73 65 6e 64 69 6e 67 20 74 68 65 20 74 65  e sending the te
1a3a0 78 74 20 69 6e 74 6f 0a 2a 2a 20 53 51 4c 69 74  xt into.** SQLit
1a3b0 65 20 66 6f 72 20 70 61 72 73 69 6e 67 2e 20 20  e for parsing.  
1a3c0 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20  ^These routines 
1a3d0 72 65 74 75 72 6e 20 31 20 69 66 20 74 68 65 20  return 1 if the 
1a3e0 69 6e 70 75 74 20 73 74 72 69 6e 67 0a 2a 2a 20  input string.** 
1a3f0 61 70 70 65 61 72 73 20 74 6f 20 62 65 20 61 20  appears to be a 
1a400 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73 74 61  complete SQL sta
1a410 74 65 6d 65 6e 74 2e 20 20 5e 41 20 73 74 61 74  tement.  ^A stat
1a420 65 6d 65 6e 74 20 69 73 20 6a 75 64 67 65 64 20  ement is judged 
1a430 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74  to be.** complet
1a440 65 20 69 66 20 69 74 20 65 6e 64 73 20 77 69 74  e if it ends wit
1a450 68 20 61 20 73 65 6d 69 63 6f 6c 6f 6e 20 74 6f  h a semicolon to
1a460 6b 65 6e 20 61 6e 64 20 69 73 20 6e 6f 74 20 61  ken and is not a
1a470 20 70 72 65 66 69 78 20 6f 66 20 61 0a 2a 2a 20   prefix of a.** 
1a480 77 65 6c 6c 2d 66 6f 72 6d 65 64 20 43 52 45 41  well-formed CREA
1a490 54 45 20 54 52 49 47 47 45 52 20 73 74 61 74 65  TE TRIGGER state
1a4a0 6d 65 6e 74 2e 20 20 5e 53 65 6d 69 63 6f 6c 6f  ment.  ^Semicolo
1a4b0 6e 73 20 74 68 61 74 20 61 72 65 20 65 6d 62 65  ns that are embe
1a4c0 64 64 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 73  dded within.** s
1a4d0 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 73 20 6f  tring literals o
1a4e0 72 20 71 75 6f 74 65 64 20 69 64 65 6e 74 69 66  r quoted identif
1a4f0 69 65 72 20 6e 61 6d 65 73 20 6f 72 20 63 6f 6d  ier names or com
1a500 6d 65 6e 74 73 20 61 72 65 20 6e 6f 74 0a 2a 2a  ments are not.**
1a510 20 69 6e 64 65 70 65 6e 64 65 6e 74 20 74 6f 6b   independent tok
1a520 65 6e 73 20 28 74 68 65 79 20 61 72 65 20 70 61  ens (they are pa
1a530 72 74 20 6f 66 20 74 68 65 20 74 6f 6b 65 6e 20  rt of the token 
1a540 69 6e 20 77 68 69 63 68 20 74 68 65 79 20 61 72  in which they ar
1a550 65 0a 2a 2a 20 65 6d 62 65 64 64 65 64 29 20 61  e.** embedded) a
1a560 6e 64 20 74 68 75 73 20 64 6f 20 6e 6f 74 20 63  nd thus do not c
1a570 6f 75 6e 74 20 61 73 20 61 20 73 74 61 74 65 6d  ount as a statem
1a580 65 6e 74 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20  ent terminator. 
1a590 20 5e 57 68 69 74 65 73 70 61 63 65 0a 2a 2a 20   ^Whitespace.** 
1a5a0 61 6e 64 20 63 6f 6d 6d 65 6e 74 73 20 74 68 61  and comments tha
1a5b0 74 20 66 6f 6c 6c 6f 77 20 74 68 65 20 66 69 6e  t follow the fin
1a5c0 61 6c 20 73 65 6d 69 63 6f 6c 6f 6e 20 61 72 65  al semicolon are
1a5d0 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20   ignored..**.** 
1a5e0 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20  ^These routines 
1a5f0 72 65 74 75 72 6e 20 30 20 69 66 20 74 68 65 20  return 0 if the 
1a600 73 74 61 74 65 6d 65 6e 74 20 69 73 20 69 6e 63  statement is inc
1a610 6f 6d 70 6c 65 74 65 2e 20 20 5e 49 66 20 61 0a  omplete.  ^If a.
1a620 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ** memory alloca
1a630 74 69 6f 6e 20 66 61 69 6c 73 2c 20 74 68 65 6e  tion fails, then
1a640 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 69 73   SQLITE_NOMEM is
1a650 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
1a660 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73   ^These routines
1a670 20 64 6f 20 6e 6f 74 20 70 61 72 73 65 20 74 68   do not parse th
1a680 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  e SQL statements
1a690 20 74 68 75 73 0a 2a 2a 20 77 69 6c 6c 20 6e 6f   thus.** will no
1a6a0 74 20 64 65 74 65 63 74 20 73 79 6e 74 61 63 74  t detect syntact
1a6b0 69 63 61 6c 6c 79 20 69 6e 63 6f 72 72 65 63 74  ically incorrect
1a6c0 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66   SQL..**.** ^(If
1a6d0 20 53 51 4c 69 74 65 20 68 61 73 20 6e 6f 74 20   SQLite has not 
1a6e0 62 65 65 6e 20 69 6e 69 74 69 61 6c 69 7a 65 64  been initialized
1a6f0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
1a700 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 70 72  initialize()] pr
1a710 69 6f 72 20 0a 2a 2a 20 74 6f 20 69 6e 76 6f 6b  ior .** to invok
1a720 69 6e 67 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  ing sqlite3_comp
1a730 6c 65 74 65 31 36 28 29 20 74 68 65 6e 20 73 71  lete16() then sq
1a740 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
1a750 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a  () is invoked.**
1a760 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62   automatically b
1a770 79 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65  y sqlite3_comple
1a780 74 65 31 36 28 29 2e 20 20 49 66 20 74 68 61 74  te16().  If that
1a790 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20   initialization 
1a7a0 66 61 69 6c 73 2c 0a 2a 2a 20 74 68 65 6e 20 74  fails,.** then t
1a7b0 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
1a7c0 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6d  from sqlite3_com
1a7d0 70 6c 65 74 65 31 36 28 29 20 77 69 6c 6c 20 62  plete16() will b
1a7e0 65 20 6e 6f 6e 2d 7a 65 72 6f 0a 2a 2a 20 72 65  e non-zero.** re
1a7f0 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74  gardless of whet
1a800 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 69  her or not the i
1a810 6e 70 75 74 20 53 51 4c 20 69 73 20 63 6f 6d 70  nput SQL is comp
1a820 6c 65 74 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68  lete.)^.**.** Th
1a830 65 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69  e input to [sqli
1a840 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 29 5d 20  te3_complete()] 
1a850 6d 75 73 74 20 62 65 20 61 20 7a 65 72 6f 2d 74  must be a zero-t
1a860 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46  erminated.** UTF
1a870 2d 38 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a  -8 string..**.**
1a880 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20 5b 73   The input to [s
1a890 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31  qlite3_complete1
1a8a0 36 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a  6()] must be a z
1a8b0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a  ero-terminated.*
1a8c0 2a 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20  * UTF-16 string 
1a8d0 69 6e 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  in native byte o
1a8e0 72 64 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  rder..*/.int sql
1a8f0 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 63 6f  ite3_complete(co
1a900 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 29 3b 0a  nst char *sql);.
1a910 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  int sqlite3_comp
1a920 6c 65 74 65 31 36 28 63 6f 6e 73 74 20 76 6f 69  lete16(const voi
1a930 64 20 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20  d *sql);../*.** 
1a940 43 41 50 49 33 52 45 46 3a 20 52 65 67 69 73 74  CAPI3REF: Regist
1a950 65 72 20 41 20 43 61 6c 6c 62 61 63 6b 20 54 6f  er A Callback To
1a960 20 48 61 6e 64 6c 65 20 53 51 4c 49 54 45 5f 42   Handle SQLITE_B
1a970 55 53 59 20 45 72 72 6f 72 73 0a 2a 2a 20 4b 45  USY Errors.** KE
1a980 59 57 4f 52 44 53 3a 20 7b 62 75 73 79 2d 68 61  YWORDS: {busy-ha
1a990 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 7d 20  ndler callback} 
1a9a0 7b 62 75 73 79 20 68 61 6e 64 6c 65 72 7d 0a 2a  {busy handler}.*
1a9b0 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
1a9c0 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  3.**.** ^The sql
1a9d0 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65  ite3_busy_handle
1a9e0 72 28 44 2c 58 2c 50 29 20 72 6f 75 74 69 6e 65  r(D,X,P) routine
1a9f0 20 73 65 74 73 20 61 20 63 61 6c 6c 62 61 63 6b   sets a callback
1aa00 20 66 75 6e 63 74 69 6f 6e 20 58 0a 2a 2a 20 74   function X.** t
1aa10 68 61 74 20 6d 69 67 68 74 20 62 65 20 69 6e 76  hat might be inv
1aa20 6f 6b 65 64 20 77 69 74 68 20 61 72 67 75 6d 65  oked with argume
1aa30 6e 74 20 50 20 77 68 65 6e 65 76 65 72 0a 2a 2a  nt P whenever.**
1aa40 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73 20 6d   an attempt is m
1aa50 61 64 65 20 74 6f 20 61 63 63 65 73 73 20 61 20  ade to access a 
1aa60 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 20 61  database table a
1aa70 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 0a 2a  ssociated with.*
1aa80 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
1aa90 65 63 74 69 6f 6e 5d 20 44 20 77 68 65 6e 20 61  ection] D when a
1aaa0 6e 6f 74 68 65 72 20 74 68 72 65 61 64 0a 2a 2a  nother thread.**
1aab0 20 6f 72 20 70 72 6f 63 65 73 73 20 68 61 73 20   or process has 
1aac0 74 68 65 20 74 61 62 6c 65 20 6c 6f 63 6b 65 64  the table locked
1aad0 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  ..** The sqlite3
1aae0 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 20  _busy_handler() 
1aaf0 69 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 65  interface is use
1ab00 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 0a 2a  d to implement.*
1ab10 2a 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  * [sqlite3_busy_
1ab20 74 69 6d 65 6f 75 74 28 29 5d 20 61 6e 64 20 5b  timeout()] and [
1ab30 50 52 41 47 4d 41 20 62 75 73 79 5f 74 69 6d 65  PRAGMA busy_time
1ab40 6f 75 74 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  out]..**.** ^If 
1ab50 74 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63  the busy callbac
1ab60 6b 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20  k is NULL, then 
1ab70 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a 2a  [SQLITE_BUSY].**
1ab80 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 6d 6d   is returned imm
1ab90 65 64 69 61 74 65 6c 79 20 75 70 6f 6e 20 65 6e  ediately upon en
1aba0 63 6f 75 6e 74 65 72 69 6e 67 20 74 68 65 20 6c  countering the l
1abb0 6f 63 6b 2e 20 20 5e 49 66 20 74 68 65 20 62 75  ock.  ^If the bu
1abc0 73 79 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69  sy callback.** i
1abd0 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e  s not NULL, then
1abe0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 6d 69   the callback mi
1abf0 67 68 74 20 62 65 20 69 6e 76 6f 6b 65 64 20 77  ght be invoked w
1ac00 69 74 68 20 74 77 6f 20 61 72 67 75 6d 65 6e 74  ith two argument
1ac10 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69  s..**.** ^The fi
1ac20 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
1ac30 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
1ac40 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68   is a copy of th
1ac50 65 20 76 6f 69 64 2a 20 70 6f 69 6e 74 65 72 20  e void* pointer 
1ac60 77 68 69 63 68 0a 2a 2a 20 69 73 20 74 68 65 20  which.** is the 
1ac70 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74  third argument t
1ac80 6f 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68  o sqlite3_busy_h
1ac90 61 6e 64 6c 65 72 28 29 2e 20 20 5e 54 68 65 20  andler().  ^The 
1aca0 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
1acb0 74 6f 0a 2a 2a 20 74 68 65 20 62 75 73 79 20 68  to.** the busy h
1acc0 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20  andler callback 
1acd0 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  is the number of
1ace0 20 74 69 6d 65 73 20 74 68 61 74 20 74 68 65 20   times that the 
1acf0 62 75 73 79 20 68 61 6e 64 6c 65 72 20 68 61 73  busy handler has
1ad00 0a 2a 2a 20 62 65 65 6e 20 69 6e 76 6f 6b 65 64  .** been invoked
1ad10 20 70 72 65 76 69 6f 75 73 6c 79 20 66 6f 72 20   previously for 
1ad20 74 68 65 20 73 61 6d 65 20 6c 6f 63 6b 69 6e 67  the same locking
1ad30 20 65 76 65 6e 74 2e 20 20 5e 49 66 20 74 68 65   event.  ^If the
1ad40 0a 2a 2a 20 62 75 73 79 20 63 61 6c 6c 62 61 63  .** busy callbac
1ad50 6b 20 72 65 74 75 72 6e 73 20 30 2c 20 74 68 65  k returns 0, the
1ad60 6e 20 6e 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20  n no additional 
1ad70 61 74 74 65 6d 70 74 73 20 61 72 65 20 6d 61 64  attempts are mad
1ad80 65 20 74 6f 0a 2a 2a 20 61 63 63 65 73 73 20 74  e to.** access t
1ad90 68 65 20 64 61 74 61 62 61 73 65 20 61 6e 64 20  he database and 
1ada0 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 69 73  [SQLITE_BUSY] is
1adb0 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 74 6f 20   returned.** to 
1adc0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e  the application.
1add0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 63 61 6c 6c  .** ^If the call
1ade0 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e  back returns non
1adf0 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 61 6e 6f 74  -zero, then anot
1ae00 68 65 72 20 61 74 74 65 6d 70 74 0a 2a 2a 20 69  her attempt.** i
1ae10 73 20 6d 61 64 65 20 74 6f 20 61 63 63 65 73 73  s made to access
1ae20 20 74 68 65 20 64 61 74 61 62 61 73 65 20 61 6e   the database an
1ae30 64 20 74 68 65 20 63 79 63 6c 65 20 72 65 70 65  d the cycle repe
1ae40 61 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70  ats..**.** The p
1ae50 72 65 73 65 6e 63 65 20 6f 66 20 61 20 62 75 73  resence of a bus
1ae60 79 20 68 61 6e 64 6c 65 72 20 64 6f 65 73 20 6e  y handler does n
1ae70 6f 74 20 67 75 61 72 61 6e 74 65 65 20 74 68 61  ot guarantee tha
1ae80 74 20 69 74 20 77 69 6c 6c 20 62 65 20 69 6e 76  t it will be inv
1ae90 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e 20 74 68 65  oked.** when the
1aea0 72 65 20 69 73 20 6c 6f 63 6b 20 63 6f 6e 74 65  re is lock conte
1aeb0 6e 74 69 6f 6e 2e 20 5e 49 66 20 53 51 4c 69 74  ntion. ^If SQLit
1aec0 65 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68 61  e determines tha
1aed0 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62  t invoking the b
1aee0 75 73 79 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 63  usy.** handler c
1aef0 6f 75 6c 64 20 72 65 73 75 6c 74 20 69 6e 20 61  ould result in a
1af00 20 64 65 61 64 6c 6f 63 6b 2c 20 69 74 20 77 69   deadlock, it wi
1af10 6c 6c 20 67 6f 20 61 68 65 61 64 20 61 6e 64 20  ll go ahead and 
1af20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42  return [SQLITE_B
1af30 55 53 59 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 61  USY].** to the a
1af40 70 70 6c 69 63 61 74 69 6f 6e 20 69 6e 73 74 65  pplication inste
1af50 61 64 20 6f 66 20 69 6e 76 6f 6b 69 6e 67 20 74  ad of invoking t
1af60 68 65 20 0a 2a 2a 20 62 75 73 79 20 68 61 6e 64  he .** busy hand
1af70 6c 65 72 2e 0a 2a 2a 20 43 6f 6e 73 69 64 65 72  ler..** Consider
1af80 20 61 20 73 63 65 6e 61 72 69 6f 20 77 68 65 72   a scenario wher
1af90 65 20 6f 6e 65 20 70 72 6f 63 65 73 73 20 69 73  e one process is
1afa0 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 61 64 20   holding a read 
1afb0 6c 6f 63 6b 20 74 68 61 74 0a 2a 2a 20 69 74 20  lock that.** it 
1afc0 69 73 20 74 72 79 69 6e 67 20 74 6f 20 70 72 6f  is trying to pro
1afd0 6d 6f 74 65 20 74 6f 20 61 20 72 65 73 65 72 76  mote to a reserv
1afe0 65 64 20 6c 6f 63 6b 20 61 6e 64 0a 2a 2a 20 61  ed lock and.** a
1aff0 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20   second process 
1b000 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 73  is holding a res
1b010 65 72 76 65 64 20 6c 6f 63 6b 20 74 68 61 74 20  erved lock that 
1b020 69 74 20 69 73 20 74 72 79 69 6e 67 0a 2a 2a 20  it is trying.** 
1b030 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 6e  to promote to an
1b040 20 65 78 63 6c 75 73 69 76 65 20 6c 6f 63 6b 2e   exclusive lock.
1b050 20 20 54 68 65 20 66 69 72 73 74 20 70 72 6f 63    The first proc
1b060 65 73 73 20 63 61 6e 6e 6f 74 20 70 72 6f 63 65  ess cannot proce
1b070 65 64 0a 2a 2a 20 62 65 63 61 75 73 65 20 69 74  ed.** because it
1b080 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74   is blocked by t
1b090 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68  he second and th
1b0a0 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73  e second process
1b0b0 20 63 61 6e 6e 6f 74 0a 2a 2a 20 70 72 6f 63 65   cannot.** proce
1b0c0 65 64 20 62 65 63 61 75 73 65 20 69 74 20 69 73  ed because it is
1b0d0 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20   blocked by the 
1b0e0 66 69 72 73 74 2e 20 20 49 66 20 62 6f 74 68 20  first.  If both 
1b0f0 70 72 6f 63 65 73 73 65 73 0a 2a 2a 20 69 6e 76  processes.** inv
1b100 6f 6b 65 20 74 68 65 20 62 75 73 79 20 68 61 6e  oke the busy han
1b110 64 6c 65 72 73 2c 20 6e 65 69 74 68 65 72 20 77  dlers, neither w
1b120 69 6c 6c 20 6d 61 6b 65 20 61 6e 79 20 70 72 6f  ill make any pro
1b130 67 72 65 73 73 2e 20 20 54 68 65 72 65 66 6f 72  gress.  Therefor
1b140 65 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 72 65 74  e,.** SQLite ret
1b150 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 42 55 53  urns [SQLITE_BUS
1b160 59 5d 20 66 6f 72 20 74 68 65 20 66 69 72 73 74  Y] for the first
1b170 20 70 72 6f 63 65 73 73 2c 20 68 6f 70 69 6e 67   process, hoping
1b180 20 74 68 61 74 20 74 68 69 73 0a 2a 2a 20 77 69   that this.** wi
1b190 6c 6c 20 69 6e 64 75 63 65 20 74 68 65 20 66 69  ll induce the fi
1b1a0 72 73 74 20 70 72 6f 63 65 73 73 20 74 6f 20 72  rst process to r
1b1b0 65 6c 65 61 73 65 20 69 74 73 20 72 65 61 64 20  elease its read 
1b1c0 6c 6f 63 6b 20 61 6e 64 20 61 6c 6c 6f 77 0a 2a  lock and allow.*
1b1d0 2a 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f  * the second pro
1b1e0 63 65 73 73 20 74 6f 20 70 72 6f 63 65 65 64 2e  cess to proceed.
1b1f0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61  .**.** ^The defa
1b200 75 6c 74 20 62 75 73 79 20 63 61 6c 6c 62 61 63  ult busy callbac
1b210 6b 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  k is NULL..**.**
1b220 20 5e 28 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c   ^(There can onl
1b230 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75  y be a single bu
1b240 73 79 20 68 61 6e 64 6c 65 72 20 64 65 66 69 6e  sy handler defin
1b250 65 64 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 5b  ed for each.** [
1b260 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1b270 69 6f 6e 5d 2e 20 20 53 65 74 74 69 6e 67 20 61  ion].  Setting a
1b280 20 6e 65 77 20 62 75 73 79 20 68 61 6e 64 6c 65   new busy handle
1b290 72 20 63 6c 65 61 72 73 20 61 6e 79 0a 2a 2a 20  r clears any.** 
1b2a0 70 72 65 76 69 6f 75 73 6c 79 20 73 65 74 20 68  previously set h
1b2b0 61 6e 64 6c 65 72 2e 29 5e 20 20 5e 4e 6f 74 65  andler.)^  ^Note
1b2c0 20 74 68 61 74 20 63 61 6c 6c 69 6e 67 20 5b 73   that calling [s
1b2d0 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65  qlite3_busy_time
1b2e0 6f 75 74 28 29 5d 0a 2a 2a 20 6f 72 20 65 76 61  out()].** or eva
1b2f0 6c 75 61 74 69 6e 67 20 5b 50 52 41 47 4d 41 20  luating [PRAGMA 
1b300 62 75 73 79 5f 74 69 6d 65 6f 75 74 3d 4e 5d 20  busy_timeout=N] 
1b310 77 69 6c 6c 20 63 68 61 6e 67 65 20 74 68 65 0a  will change the.
1b320 2a 2a 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  ** busy handler 
1b330 61 6e 64 20 74 68 75 73 20 63 6c 65 61 72 20 61  and thus clear a
1b340 6e 79 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65  ny previously se
1b350 74 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a  t busy handler..
1b360 2a 2a 0a 2a 2a 20 54 68 65 20 62 75 73 79 20 63  **.** The busy c
1b370 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 20 6e  allback should n
1b380 6f 74 20 74 61 6b 65 20 61 6e 79 20 61 63 74 69  ot take any acti
1b390 6f 6e 73 20 77 68 69 63 68 20 6d 6f 64 69 66 79  ons which modify
1b3a0 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65   the.** database
1b3b0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74   connection that
1b3c0 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 73   invoked the bus
1b3d0 79 20 68 61 6e 64 6c 65 72 2e 20 20 49 6e 20 6f  y handler.  In o
1b3e0 74 68 65 72 20 77 6f 72 64 73 2c 0a 2a 2a 20 74  ther words,.** t
1b3f0 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  he busy handler 
1b400 69 73 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e 74  is not reentrant
1b410 2e 20 20 41 6e 79 20 73 75 63 68 20 61 63 74 69  .  Any such acti
1b420 6f 6e 73 0a 2a 2a 20 72 65 73 75 6c 74 20 69 6e  ons.** result in
1b430 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76   undefined behav
1b440 69 6f 72 2e 0a 2a 2a 20 0a 2a 2a 20 41 20 62 75  ior..** .** A bu
1b450 73 79 20 68 61 6e 64 6c 65 72 20 6d 75 73 74 20  sy handler must 
1b460 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65 20 64 61  not close the da
1b470 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1b480 6e 0a 2a 2a 20 6f 72 20 5b 70 72 65 70 61 72 65  n.** or [prepare
1b490 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61  d statement] tha
1b4a0 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75  t invoked the bu
1b4b0 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2f 0a 69  sy handler..*/.i
1b4c0 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  nt sqlite3_busy_
1b4d0 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a  handler(sqlite3*
1b4e0 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 2c 69  , int(*)(void*,i
1b4f0 6e 74 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a  nt), void*);../*
1b500 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65  .** CAPI3REF: Se
1b510 74 20 41 20 42 75 73 79 20 54 69 6d 65 6f 75 74  t A Busy Timeout
1b520 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
1b530 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  te3.**.** ^This 
1b540 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20 5b  routine sets a [
1b550 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e  sqlite3_busy_han
1b560 64 6c 65 72 20 7c 20 62 75 73 79 20 68 61 6e 64  dler | busy hand
1b570 6c 65 72 5d 20 74 68 61 74 20 73 6c 65 65 70 73  ler] that sleeps
1b580 0a 2a 2a 20 66 6f 72 20 61 20 73 70 65 63 69 66  .** for a specif
1b590 69 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 74 69  ied amount of ti
1b5a0 6d 65 20 77 68 65 6e 20 61 20 74 61 62 6c 65 20  me when a table 
1b5b0 69 73 20 6c 6f 63 6b 65 64 2e 20 20 5e 54 68 65  is locked.  ^The
1b5c0 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 69 6c 6c   handler.** will
1b5d0 20 73 6c 65 65 70 20 6d 75 6c 74 69 70 6c 65 20   sleep multiple 
1b5e0 74 69 6d 65 73 20 75 6e 74 69 6c 20 61 74 20 6c  times until at l
1b5f0 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73  east "ms" millis
1b600 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69  econds of sleepi
1b610 6e 67 0a 2a 2a 20 68 61 76 65 20 61 63 63 75 6d  ng.** have accum
1b620 75 6c 61 74 65 64 2e 20 20 5e 41 66 74 65 72 20  ulated.  ^After 
1b630 61 74 20 6c 65 61 73 74 20 22 6d 73 22 20 6d 69  at least "ms" mi
1b640 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c  lliseconds of sl
1b650 65 65 70 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 68  eeping,.** the h
1b660 61 6e 64 6c 65 72 20 72 65 74 75 72 6e 73 20 30  andler returns 0
1b670 20 77 68 69 63 68 20 63 61 75 73 65 73 20 5b 73   which causes [s
1b680 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 74  qlite3_step()] t
1b690 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c  o return.** [SQL
1b6a0 49 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a 0a 2a 2a  ITE_BUSY]..**.**
1b6b0 20 5e 43 61 6c 6c 69 6e 67 20 74 68 69 73 20 72   ^Calling this r
1b6c0 6f 75 74 69 6e 65 20 77 69 74 68 20 61 6e 20 61  outine with an a
1b6d0 72 67 75 6d 65 6e 74 20 6c 65 73 73 20 74 68 61  rgument less tha
1b6e0 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65  n or equal to ze
1b6f0 72 6f 0a 2a 2a 20 74 75 72 6e 73 20 6f 66 66 20  ro.** turns off 
1b700 61 6c 6c 20 62 75 73 79 20 68 61 6e 64 6c 65 72  all busy handler
1b710 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 65  s..**.** ^(There
1b720 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73   can only be a s
1b730 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c  ingle busy handl
1b740 65 72 20 66 6f 72 20 61 20 70 61 72 74 69 63 75  er for a particu
1b750 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  lar.** [database
1b760 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 74 20   connection] at 
1b770 61 6e 79 20 67 69 76 65 6e 20 6d 6f 6d 65 6e 74  any given moment
1b780 2e 20 20 49 66 20 61 6e 6f 74 68 65 72 20 62 75  .  If another bu
1b790 73 79 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 61  sy handler.** wa
1b7a0 73 20 64 65 66 69 6e 65 64 20 20 28 75 73 69 6e  s defined  (usin
1b7b0 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  g [sqlite3_busy_
1b7c0 68 61 6e 64 6c 65 72 28 29 5d 29 20 70 72 69 6f  handler()]) prio
1b7d0 72 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20  r to calling.** 
1b7e0 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 74 68  this routine, th
1b7f0 61 74 20 6f 74 68 65 72 20 62 75 73 79 20 68 61  at other busy ha
1b800 6e 64 6c 65 72 20 69 73 20 63 6c 65 61 72 65 64  ndler is cleared
1b810 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  .)^.**.** See al
1b820 73 6f 3a 20 20 5b 50 52 41 47 4d 41 20 62 75 73  so:  [PRAGMA bus
1b830 79 5f 74 69 6d 65 6f 75 74 5d 0a 2a 2f 0a 69 6e  y_timeout].*/.in
1b840 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74  t sqlite3_busy_t
1b850 69 6d 65 6f 75 74 28 73 71 6c 69 74 65 33 2a 2c  imeout(sqlite3*,
1b860 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a   int ms);../*.**
1b870 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 76 65   CAPI3REF: Conve
1b880 6e 69 65 6e 63 65 20 52 6f 75 74 69 6e 65 73 20  nience Routines 
1b890 46 6f 72 20 52 75 6e 6e 69 6e 67 20 51 75 65 72  For Running Quer
1b8a0 69 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ies.** METHOD: s
1b8b0 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68 69  qlite3.**.** Thi
1b8c0 73 20 69 73 20 61 20 6c 65 67 61 63 79 20 69 6e  s is a legacy in
1b8d0 74 65 72 66 61 63 65 20 74 68 61 74 20 69 73 20  terface that is 
1b8e0 70 72 65 73 65 72 76 65 64 20 66 6f 72 20 62 61  preserved for ba
1b8f0 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62  ckwards compatib
1b900 69 6c 69 74 79 2e 0a 2a 2a 20 55 73 65 20 6f 66  ility..** Use of
1b910 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   this interface 
1b920 69 73 20 6e 6f 74 20 72 65 63 6f 6d 6d 65 6e 64  is not recommend
1b930 65 64 2e 0a 2a 2a 0a 2a 2a 20 44 65 66 69 6e 69  ed..**.** Defini
1b940 74 69 6f 6e 3a 20 41 20 3c 62 3e 72 65 73 75 6c  tion: A <b>resul
1b950 74 20 74 61 62 6c 65 3c 2f 62 3e 20 69 73 20 6d  t table</b> is m
1b960 65 6d 6f 72 79 20 64 61 74 61 20 73 74 72 75 63  emory data struc
1b970 74 75 72 65 20 63 72 65 61 74 65 64 20 62 79 20  ture created by 
1b980 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
1b990 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 69 6e 74  get_table()] int
1b9a0 65 72 66 61 63 65 2e 20 20 41 20 72 65 73 75 6c  erface.  A resul
1b9b0 74 20 74 61 62 6c 65 20 72 65 63 6f 72 64 73 20  t table records 
1b9c0 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20  the.** complete 
1b9d0 71 75 65 72 79 20 72 65 73 75 6c 74 73 20 66 72  query results fr
1b9e0 6f 6d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 71  om one or more q
1b9f0 75 65 72 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  ueries..**.** Th
1ba00 65 20 74 61 62 6c 65 20 63 6f 6e 63 65 70 74 75  e table conceptu
1ba10 61 6c 6c 79 20 68 61 73 20 61 20 6e 75 6d 62 65  ally has a numbe
1ba20 72 20 6f 66 20 72 6f 77 73 20 61 6e 64 20 63 6f  r of rows and co
1ba30 6c 75 6d 6e 73 2e 20 20 42 75 74 0a 2a 2a 20 74  lumns.  But.** t
1ba40 68 65 73 65 20 6e 75 6d 62 65 72 73 20 61 72 65  hese numbers are
1ba50 20 6e 6f 74 20 70 61 72 74 20 6f 66 20 74 68 65   not part of the
1ba60 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 74   result table it
1ba70 73 65 6c 66 2e 20 20 54 68 65 73 65 0a 2a 2a 20  self.  These.** 
1ba80 6e 75 6d 62 65 72 73 20 61 72 65 20 6f 62 74 61  numbers are obta
1ba90 69 6e 65 64 20 73 65 70 61 72 61 74 65 6c 79 2e  ined separately.
1baa0 20 20 4c 65 74 20 4e 20 62 65 20 74 68 65 20 6e    Let N be the n
1bab0 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 0a 2a 2a  umber of rows.**
1bac0 20 61 6e 64 20 4d 20 62 65 20 74 68 65 20 6e 75   and M be the nu
1bad0 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 2e  mber of columns.
1bae0 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20  .**.** A result 
1baf0 74 61 62 6c 65 20 69 73 20 61 6e 20 61 72 72 61  table is an arra
1bb00 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f  y of pointers to
1bb10 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
1bb20 20 55 54 46 2d 38 20 73 74 72 69 6e 67 73 2e 0a   UTF-8 strings..
1bb30 2a 2a 20 54 68 65 72 65 20 61 72 65 20 28 4e 2b  ** There are (N+
1bb40 31 29 2a 4d 20 65 6c 65 6d 65 6e 74 73 20 69 6e  1)*M elements in
1bb50 20 74 68 65 20 61 72 72 61 79 2e 20 20 54 68 65   the array.  The
1bb60 20 66 69 72 73 74 20 4d 20 70 6f 69 6e 74 65 72   first M pointer
1bb70 73 20 70 6f 69 6e 74 0a 2a 2a 20 74 6f 20 7a 65  s point.** to ze
1bb80 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74  ro-terminated st
1bb90 72 69 6e 67 73 20 74 68 61 74 20 20 63 6f 6e 74  rings that  cont
1bba0 61 69 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f 66  ain the names of
1bbb0 20 74 68 65 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a   the columns..**
1bbc0 20 54 68 65 20 72 65 6d 61 69 6e 69 6e 67 20 65   The remaining e
1bbd0 6e 74 72 69 65 73 20 61 6c 6c 20 70 6f 69 6e 74  ntries all point
1bbe0 20 74 6f 20 71 75 65 72 79 20 72 65 73 75 6c 74   to query result
1bbf0 73 2e 20 20 4e 55 4c 4c 20 76 61 6c 75 65 73 20  s.  NULL values 
1bc00 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 20 4e 55 4c  result.** in NUL
1bc10 4c 20 70 6f 69 6e 74 65 72 73 2e 20 20 41 6c 6c  L pointers.  All
1bc20 20 6f 74 68 65 72 20 76 61 6c 75 65 73 20 61 72   other values ar
1bc30 65 20 69 6e 20 74 68 65 69 72 20 55 54 46 2d 38  e in their UTF-8
1bc40 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
1bc50 0a 2a 2a 20 73 74 72 69 6e 67 20 72 65 70 72 65  .** string repre
1bc60 73 65 6e 74 61 74 69 6f 6e 20 61 73 20 72 65 74  sentation as ret
1bc70 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65  urned by [sqlite
1bc80 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d  3_column_text()]
1bc90 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74  ..**.** A result
1bca0 20 74 61 62 6c 65 20 6d 69 67 68 74 20 63 6f 6e   table might con
1bcb0 73 69 73 74 20 6f 66 20 6f 6e 65 20 6f 72 20 6d  sist of one or m
1bcc0 6f 72 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ore memory alloc
1bcd0 61 74 69 6f 6e 73 2e 0a 2a 2a 20 49 74 20 69 73  ations..** It is
1bce0 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 70 61 73   not safe to pas
1bcf0 73 20 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65  s a result table
1bd00 20 64 69 72 65 63 74 6c 79 20 74 6f 20 5b 73 71   directly to [sq
1bd10 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a  lite3_free()]..*
1bd20 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65  * A result table
1bd30 20 73 68 6f 75 6c 64 20 62 65 20 64 65 61 6c 6c   should be deall
1bd40 6f 63 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71  ocated using [sq
1bd50 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65  lite3_free_table
1bd60 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 73 20  ()]..**.** ^(As 
1bd70 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 74 68  an example of th
1bd80 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 66  e result table f
1bd90 6f 72 6d 61 74 2c 20 73 75 70 70 6f 73 65 20 61  ormat, suppose a
1bda0 20 71 75 65 72 79 20 72 65 73 75 6c 74 0a 2a 2a   query result.**
1bdb0 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a   is as follows:.
1bdc0 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
1bdd0 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20  e><pre>.**      
1bde0 20 20 4e 61 6d 65 20 20 20 20 20 20 20 20 7c 20    Name        | 
1bdf0 41 67 65 0a 2a 2a 20 20 20 20 20 20 20 20 2d 2d  Age.**        --
1be00 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
1be10 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20 20 20 20 20 20  -----.**        
1be20 41 6c 69 63 65 20 20 20 20 20 20 20 7c 20 34 33  Alice       | 43
1be30 0a 2a 2a 20 20 20 20 20 20 20 20 42 6f 62 20 20  .**        Bob  
1be40 20 20 20 20 20 20 20 7c 20 32 38 0a 2a 2a 20 20         | 28.**  
1be50 20 20 20 20 20 20 43 69 6e 64 79 20 20 20 20 20        Cindy     
1be60 20 20 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72 65 3e    | 21.** </pre>
1be70 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
1be80 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74 77  .** There are tw
1be90 6f 20 63 6f 6c 75 6d 6e 20 28 4d 3d 3d 32 29 20  o column (M==2) 
1bea0 61 6e 64 20 74 68 72 65 65 20 72 6f 77 73 20 28  and three rows (
1beb0 4e 3d 3d 33 29 2e 20 20 54 68 75 73 20 74 68 65  N==3).  Thus the
1bec0 0a 2a 2a 20 72 65 73 75 6c 74 20 74 61 62 6c 65  .** result table
1bed0 20 68 61 73 20 38 20 65 6e 74 72 69 65 73 2e 20   has 8 entries. 
1bee0 20 53 75 70 70 6f 73 65 20 74 68 65 20 72 65 73   Suppose the res
1bef0 75 6c 74 20 74 61 62 6c 65 20 69 73 20 73 74 6f  ult table is sto
1bf00 72 65 64 0a 2a 2a 20 69 6e 20 61 6e 20 61 72 72  red.** in an arr
1bf10 61 79 20 6e 61 6d 65 73 20 61 7a 52 65 73 75 6c  ay names azResul
1bf20 74 2e 20 20 54 68 65 6e 20 61 7a 52 65 73 75 6c  t.  Then azResul
1bf30 74 20 68 6f 6c 64 73 20 74 68 69 73 20 63 6f 6e  t holds this con
1bf40 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  tent:.**.** <blo
1bf50 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
1bf60 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
1bf70 26 23 39 31 3b 30 5d 20 3d 20 22 4e 61 6d 65 22  &#91;0] = "Name"
1bf80 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
1bf90 73 75 6c 74 26 23 39 31 3b 31 5d 20 3d 20 22 41  sult&#91;1] = "A
1bfa0 67 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  ge";.**        a
1bfb0 7a 52 65 73 75 6c 74 26 23 39 31 3b 32 5d 20 3d  zResult&#91;2] =
1bfc0 20 22 41 6c 69 63 65 22 3b 0a 2a 2a 20 20 20 20   "Alice";.**    
1bfd0 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
1bfe0 3b 33 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a 20 20  ;3] = "43";.**  
1bff0 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
1c000 39 31 3b 34 5d 20 3d 20 22 42 6f 62 22 3b 0a 2a  91;4] = "Bob";.*
1c010 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
1c020 74 26 23 39 31 3b 35 5d 20 3d 20 22 32 38 22 3b  t&#91;5] = "28";
1c030 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
1c040 75 6c 74 26 23 39 31 3b 36 5d 20 3d 20 22 43 69  ult&#91;6] = "Ci
1c050 6e 64 79 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  ndy";.**        
1c060 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 37 5d 20  azResult&#91;7] 
1c070 3d 20 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72 65  = "21";.** </pre
1c080 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e  ></blockquote>)^
1c090 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
1c0a0 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20  te3_get_table() 
1c0b0 66 75 6e 63 74 69 6f 6e 20 65 76 61 6c 75 61 74  function evaluat
1c0c0 65 73 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a  es one or more.*
1c0d0 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61  * semicolon-sepa
1c0e0 72 61 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d  rated SQL statem
1c0f0 65 6e 74 73 20 69 6e 20 74 68 65 20 7a 65 72 6f  ents in the zero
1c100 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d  -terminated UTF-
1c110 38 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 66 20 69  8.** string of i
1c120 74 73 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  ts 2nd parameter
1c130 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 72   and returns a r
1c140 65 73 75 6c 74 20 74 61 62 6c 65 20 74 6f 20 74  esult table to t
1c150 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 67 69  he.** pointer gi
1c160 76 65 6e 20 69 6e 20 69 74 73 20 33 72 64 20 70  ven in its 3rd p
1c170 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  arameter..**.** 
1c180 41 66 74 65 72 20 74 68 65 20 61 70 70 6c 69 63  After the applic
1c190 61 74 69 6f 6e 20 68 61 73 20 66 69 6e 69 73 68  ation has finish
1c1a0 65 64 20 77 69 74 68 20 74 68 65 20 72 65 73 75  ed with the resu
1c1b0 6c 74 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  lt from sqlite3_
1c1c0 67 65 74 5f 74 61 62 6c 65 28 29 2c 0a 2a 2a 20  get_table(),.** 
1c1d0 69 74 20 6d 75 73 74 20 70 61 73 73 20 74 68 65  it must pass the
1c1e0 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 70 6f   result table po
1c1f0 69 6e 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  inter to sqlite3
1c200 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 20 69 6e  _free_table() in
1c210 20 6f 72 64 65 72 20 74 6f 0a 2a 2a 20 72 65 6c   order to.** rel
1c220 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20  ease the memory 
1c230 74 68 61 74 20 77 61 73 20 6d 61 6c 6c 6f 63 65  that was malloce
1c240 64 2e 20 20 42 65 63 61 75 73 65 20 6f 66 20 74  d.  Because of t
1c250 68 65 20 77 61 79 20 74 68 65 0a 2a 2a 20 5b 73  he way the.** [s
1c260 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
1c270 20 68 61 70 70 65 6e 73 20 77 69 74 68 69 6e 20   happens within 
1c280 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
1c290 65 28 29 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67  e(), the calling
1c2a0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73  .** function mus
1c2b0 74 20 6e 6f 74 20 74 72 79 20 74 6f 20 63 61 6c  t not try to cal
1c2c0 6c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  l [sqlite3_free(
1c2d0 29 5d 20 64 69 72 65 63 74 6c 79 2e 20 20 4f 6e  )] directly.  On
1c2e0 6c 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  ly.** [sqlite3_f
1c2f0 72 65 65 5f 74 61 62 6c 65 28 29 5d 20 69 73 20  ree_table()] is 
1c300 61 62 6c 65 20 74 6f 20 72 65 6c 65 61 73 65 20  able to release 
1c310 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 70 65  the memory prope
1c320 72 6c 79 20 61 6e 64 20 73 61 66 65 6c 79 2e 0a  rly and safely..
1c330 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
1c340 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 69 6e  3_get_table() in
1c350 74 65 72 66 61 63 65 20 69 73 20 69 6d 70 6c 65  terface is imple
1c360 6d 65 6e 74 65 64 20 61 73 20 61 20 77 72 61 70  mented as a wrap
1c370 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73  per around.** [s
1c380 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2e 20  qlite3_exec()]. 
1c390 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74   The sqlite3_get
1c3a0 5f 74 61 62 6c 65 28 29 20 72 6f 75 74 69 6e 65  _table() routine
1c3b0 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 61   does not have a
1c3c0 63 63 65 73 73 0a 2a 2a 20 74 6f 20 61 6e 79 20  ccess.** to any 
1c3d0 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 20 73 74  internal data st
1c3e0 72 75 63 74 75 72 65 73 20 6f 66 20 53 51 4c 69  ructures of SQLi
1c3f0 74 65 2e 20 20 49 74 20 75 73 65 73 20 6f 6e 6c  te.  It uses onl
1c400 79 20 74 68 65 20 70 75 62 6c 69 63 0a 2a 2a 20  y the public.** 
1c410 69 6e 74 65 72 66 61 63 65 20 64 65 66 69 6e 65  interface define
1c420 64 20 68 65 72 65 2e 20 20 41 73 20 61 20 63 6f  d here.  As a co
1c430 6e 73 65 71 75 65 6e 63 65 2c 20 65 72 72 6f 72  nsequence, error
1c440 73 20 74 68 61 74 20 6f 63 63 75 72 20 69 6e 20  s that occur in 
1c450 74 68 65 0a 2a 2a 20 77 72 61 70 70 65 72 20 6c  the.** wrapper l
1c460 61 79 65 72 20 6f 75 74 73 69 64 65 20 6f 66 20  ayer outside of 
1c470 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 5b 73 71  the internal [sq
1c480 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 63 61  lite3_exec()] ca
1c490 6c 6c 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 65  ll are not.** re
1c4a0 66 6c 65 63 74 65 64 20 69 6e 20 73 75 62 73 65  flected in subse
1c4b0 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b  quent calls to [
1c4c0 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28  sqlite3_errcode(
1c4d0 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  )] or.** [sqlite
1c4e0 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2f 0a  3_errmsg()]..*/.
1c4f0 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  int sqlite3_get_
1c500 74 61 62 6c 65 28 0a 20 20 73 71 6c 69 74 65 33  table(.  sqlite3
1c510 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 2f   *db,          /
1c520 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61  * An open databa
1c530 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  se */.  const ch
1c540 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 2f 2a  ar *zSql,     /*
1c550 20 53 51 4c 20 74 6f 20 62 65 20 65 76 61 6c 75   SQL to be evalu
1c560 61 74 65 64 20 2a 2f 0a 20 20 63 68 61 72 20 2a  ated */.  char *
1c570 2a 2a 70 61 7a 52 65 73 75 6c 74 2c 20 20 20 20  **pazResult,    
1c580 2f 2a 20 52 65 73 75 6c 74 73 20 6f 66 20 74 68  /* Results of th
1c590 65 20 71 75 65 72 79 20 2a 2f 0a 20 20 69 6e 74  e query */.  int
1c5a0 20 2a 70 6e 52 6f 77 2c 20 20 20 20 20 20 20 20   *pnRow,        
1c5b0 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20     /* Number of 
1c5c0 72 65 73 75 6c 74 20 72 6f 77 73 20 77 72 69 74  result rows writ
1c5d0 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 69 6e  ten here */.  in
1c5e0 74 20 2a 70 6e 43 6f 6c 75 6d 6e 2c 20 20 20 20  t *pnColumn,    
1c5f0 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66      /* Number of
1c600 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 73 20   result columns 
1c610 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a  written here */.
1c620 20 20 63 68 61 72 20 2a 2a 70 7a 45 72 72 6d 73    char **pzErrms
1c630 67 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72  g       /* Error
1c640 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68 65 72   msg written her
1c650 65 20 2a 2f 0a 29 3b 0a 76 6f 69 64 20 73 71 6c  e */.);.void sql
1c660 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28  ite3_free_table(
1c670 63 68 61 72 20 2a 2a 72 65 73 75 6c 74 29 3b 0a  char **result);.
1c680 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1c690 20 46 6f 72 6d 61 74 74 65 64 20 53 74 72 69 6e   Formatted Strin
1c6a0 67 20 50 72 69 6e 74 69 6e 67 20 46 75 6e 63 74  g Printing Funct
1c6b0 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ions.**.** These
1c6c0 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 77 6f   routines are wo
1c6d0 72 6b 2d 61 6c 69 6b 65 73 20 6f 66 20 74 68 65  rk-alikes of the
1c6e0 20 22 70 72 69 6e 74 66 28 29 22 20 66 61 6d 69   "printf()" fami
1c6f0 6c 79 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73 0a  ly of functions.
1c700 2a 2a 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e  ** from the stan
1c710 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a  dard C library..
1c720 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
1c730 73 20 75 6e 64 65 72 73 74 61 6e 64 20 6d 6f 73  s understand mos
1c740 74 20 6f 66 20 74 68 65 20 63 6f 6d 6d 6f 6e 20  t of the common 
1c750 4b 26 52 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f  K&R formatting o
1c760 70 74 69 6f 6e 73 2c 0a 2a 2a 20 70 6c 75 73 20  ptions,.** plus 
1c770 73 6f 6d 65 20 61 64 64 69 74 69 6f 6e 61 6c 20  some additional 
1c780 6e 6f 6e 2d 73 74 61 6e 64 61 72 64 20 66 6f 72  non-standard for
1c790 6d 61 74 73 2c 20 64 65 74 61 69 6c 65 64 20 62  mats, detailed b
1c7a0 65 6c 6f 77 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68  elow..** Note th
1c7b0 61 74 20 73 6f 6d 65 20 6f 66 20 74 68 65 20 6d  at some of the m
1c7c0 6f 72 65 20 6f 62 73 63 75 72 65 20 66 6f 72 6d  ore obscure form
1c7d0 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20 66  atting options f
1c7e0 72 6f 6d 20 72 65 63 65 6e 74 0a 2a 2a 20 43 2d  rom recent.** C-
1c7f0 6c 69 62 72 61 72 79 20 73 74 61 6e 64 61 72 64  library standard
1c800 73 20 61 72 65 20 6f 6d 69 74 74 65 64 20 66 72  s are omitted fr
1c810 6f 6d 20 74 68 69 73 20 69 6d 70 6c 65 6d 65 6e  om this implemen
1c820 74 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54  tation..**.** ^T
1c830 68 65 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e  he sqlite3_mprin
1c840 74 66 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  tf() and sqlite3
1c850 5f 76 6d 70 72 69 6e 74 66 28 29 20 72 6f 75 74  _vmprintf() rout
1c860 69 6e 65 73 20 77 72 69 74 65 20 74 68 65 69 72  ines write their
1c870 0a 2a 2a 20 72 65 73 75 6c 74 73 20 69 6e 74 6f  .** results into
1c880 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64   memory obtained
1c890 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d   from [sqlite3_m
1c8a0 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a 20 54 68 65  alloc()]..** The
1c8b0 20 73 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65   strings returne
1c8c0 64 20 62 79 20 74 68 65 73 65 20 74 77 6f 20 72  d by these two r
1c8d0 6f 75 74 69 6e 65 73 20 73 68 6f 75 6c 64 20 62  outines should b
1c8e0 65 0a 2a 2a 20 72 65 6c 65 61 73 65 64 20 62 79  e.** released by
1c8f0 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
1c900 5d 2e 20 20 5e 42 6f 74 68 20 72 6f 75 74 69 6e  ].  ^Both routin
1c910 65 73 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 4e  es return a.** N
1c920 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 20 5b  ULL pointer if [
1c930 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
1c940 5d 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61  ] is unable to a
1c950 6c 6c 6f 63 61 74 65 20 65 6e 6f 75 67 68 0a 2a  llocate enough.*
1c960 2a 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64  * memory to hold
1c970 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73   the resulting s
1c980 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  tring..**.** ^(T
1c990 68 65 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  he sqlite3_snpri
1c9a0 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 20 69 73  ntf() routine is
1c9b0 20 73 69 6d 69 6c 61 72 20 74 6f 20 22 73 6e 70   similar to "snp
1c9c0 72 69 6e 74 66 28 29 22 20 66 72 6f 6d 0a 2a 2a  rintf()" from.**
1c9d0 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20   the standard C 
1c9e0 6c 69 62 72 61 72 79 2e 20 20 54 68 65 20 72 65  library.  The re
1c9f0 73 75 6c 74 20 69 73 20 77 72 69 74 74 65 6e 20  sult is written 
1ca00 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 62 75 66 66  into the.** buff
1ca10 65 72 20 73 75 70 70 6c 69 65 64 20 61 73 20 74  er supplied as t
1ca20 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
1ca30 74 65 72 20 77 68 6f 73 65 20 73 69 7a 65 20 69  ter whose size i
1ca40 73 20 67 69 76 65 6e 20 62 79 0a 2a 2a 20 74 68  s given by.** th
1ca50 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
1ca60 72 2e 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65  r. Note that the
1ca70 20 6f 72 64 65 72 20 6f 66 20 74 68 65 0a 2a 2a   order of the.**
1ca80 20 66 69 72 73 74 20 74 77 6f 20 70 61 72 61 6d   first two param
1ca90 65 74 65 72 73 20 69 73 20 72 65 76 65 72 73 65  eters is reverse
1caa0 64 20 66 72 6f 6d 20 73 6e 70 72 69 6e 74 66 28  d from snprintf(
1cab0 29 2e 29 5e 20 20 54 68 69 73 20 69 73 20 61 6e  ).)^  This is an
1cac0 0a 2a 2a 20 68 69 73 74 6f 72 69 63 61 6c 20 61  .** historical a
1cad0 63 63 69 64 65 6e 74 20 74 68 61 74 20 63 61 6e  ccident that can
1cae0 6e 6f 74 20 62 65 20 66 69 78 65 64 20 77 69 74  not be fixed wit
1caf0 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 0a 2a 2a  hout breaking.**
1cb00 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61   backwards compa
1cb10 74 69 62 69 6c 69 74 79 2e 20 20 5e 28 4e 6f 74  tibility.  ^(Not
1cb20 65 20 61 6c 73 6f 20 74 68 61 74 20 73 71 6c 69  e also that sqli
1cb30 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a  te3_snprintf().*
1cb40 2a 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  * returns a poin
1cb50 74 65 72 20 74 6f 20 69 74 73 20 62 75 66 66 65  ter to its buffe
1cb60 72 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65  r instead of the
1cb70 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68   number of.** ch
1cb80 61 72 61 63 74 65 72 73 20 61 63 74 75 61 6c 6c  aracters actuall
1cb90 79 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74  y written into t
1cba0 68 65 20 62 75 66 66 65 72 2e 29 5e 20 20 57 65  he buffer.)^  We
1cbb0 20 61 64 6d 69 74 20 74 68 61 74 0a 2a 2a 20 74   admit that.** t
1cbc0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61  he number of cha
1cbd0 72 61 63 74 65 72 73 20 77 72 69 74 74 65 6e 20  racters written 
1cbe0 77 6f 75 6c 64 20 62 65 20 61 20 6d 6f 72 65 20  would be a more 
1cbf0 75 73 65 66 75 6c 20 72 65 74 75 72 6e 0a 2a 2a  useful return.**
1cc00 20 76 61 6c 75 65 20 62 75 74 20 77 65 20 63 61   value but we ca
1cc10 6e 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20  nnot change the 
1cc20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
1cc30 66 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e  f sqlite3_snprin
1cc40 74 66 28 29 0a 2a 2a 20 6e 6f 77 20 77 69 74 68  tf().** now with
1cc50 6f 75 74 20 62 72 65 61 6b 69 6e 67 20 63 6f 6d  out breaking com
1cc60 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a  patibility..**.*
1cc70 2a 20 5e 41 73 20 6c 6f 6e 67 20 61 73 20 74 68  * ^As long as th
1cc80 65 20 62 75 66 66 65 72 20 73 69 7a 65 20 69 73  e buffer size is
1cc90 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 7a 65   greater than ze
1cca0 72 6f 2c 20 73 71 6c 69 74 65 33 5f 73 6e 70 72  ro, sqlite3_snpr
1ccb0 69 6e 74 66 28 29 0a 2a 2a 20 67 75 61 72 61 6e  intf().** guaran
1ccc0 74 65 65 73 20 74 68 61 74 20 74 68 65 20 62 75  tees that the bu
1ccd0 66 66 65 72 20 69 73 20 61 6c 77 61 79 73 20 7a  ffer is always z
1cce0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20  ero-terminated. 
1ccf0 20 5e 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 70   ^The first.** p
1cd00 61 72 61 6d 65 74 65 72 20 22 6e 22 20 69 73 20  arameter "n" is 
1cd10 74 68 65 20 74 6f 74 61 6c 20 73 69 7a 65 20 6f  the total size o
1cd20 66 20 74 68 65 20 62 75 66 66 65 72 2c 20 69 6e  f the buffer, in
1cd30 63 6c 75 64 69 6e 67 20 73 70 61 63 65 20 66 6f  cluding space fo
1cd40 72 0a 2a 2a 20 74 68 65 20 7a 65 72 6f 20 74 65  r.** the zero te
1cd50 72 6d 69 6e 61 74 6f 72 2e 20 20 53 6f 20 74 68  rminator.  So th
1cd60 65 20 6c 6f 6e 67 65 73 74 20 73 74 72 69 6e 67  e longest string
1cd70 20 74 68 61 74 20 63 61 6e 20 62 65 20 63 6f 6d   that can be com
1cd80 70 6c 65 74 65 6c 79 0a 2a 2a 20 77 72 69 74 74  pletely.** writt
1cd90 65 6e 20 77 69 6c 6c 20 62 65 20 6e 2d 31 20 63  en will be n-1 c
1cda0 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a  haracters..**.**
1cdb0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 73   ^The sqlite3_vs
1cdc0 6e 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e  nprintf() routin
1cdd0 65 20 69 73 20 61 20 76 61 72 61 72 67 73 20 76  e is a varargs v
1cde0 65 72 73 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65  ersion of sqlite
1cdf0 33 5f 73 6e 70 72 69 6e 74 66 28 29 2e 0a 2a 2a  3_snprintf()..**
1ce00 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
1ce10 65 73 20 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74  es all implement
1ce20 20 73 6f 6d 65 20 61 64 64 69 74 69 6f 6e 61 6c   some additional
1ce30 20 66 6f 72 6d 61 74 74 69 6e 67 0a 2a 2a 20 6f   formatting.** o
1ce40 70 74 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20  ptions that are 
1ce50 75 73 65 66 75 6c 20 66 6f 72 20 63 6f 6e 73 74  useful for const
1ce60 72 75 63 74 69 6e 67 20 53 51 4c 20 73 74 61 74  ructing SQL stat
1ce70 65 6d 65 6e 74 73 2e 0a 2a 2a 20 41 6c 6c 20 6f  ements..** All o
1ce80 66 20 74 68 65 20 75 73 75 61 6c 20 70 72 69 6e  f the usual prin
1ce90 74 66 28 29 20 66 6f 72 6d 61 74 74 69 6e 67 20  tf() formatting 
1cea0 6f 70 74 69 6f 6e 73 20 61 70 70 6c 79 2e 20 20  options apply.  
1ceb0 49 6e 20 61 64 64 69 74 69 6f 6e 2c 20 74 68 65  In addition, the
1cec0 72 65 0a 2a 2a 20 69 73 20 61 72 65 20 22 25 71  re.** is are "%q
1ced0 22 2c 20 22 25 51 22 2c 20 22 25 77 22 20 61 6e  ", "%Q", "%w" an
1cee0 64 20 22 25 7a 22 20 6f 70 74 69 6f 6e 73 2e 0a  d "%z" options..
1cef0 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25 71 20 6f  **.** ^(The %q o
1cf00 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65  ption works like
1cf10 20 25 73 20 69 6e 20 74 68 61 74 20 69 74 20 73   %s in that it s
1cf20 75 62 73 74 69 74 75 74 65 73 20 61 20 6e 75 6c  ubstitutes a nul
1cf30 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73  -terminated.** s
1cf40 74 72 69 6e 67 20 66 72 6f 6d 20 74 68 65 20 61  tring from the a
1cf50 72 67 75 6d 65 6e 74 20 6c 69 73 74 2e 20 20 42  rgument list.  B
1cf60 75 74 20 25 71 20 61 6c 73 6f 20 64 6f 75 62 6c  ut %q also doubl
1cf70 65 73 20 65 76 65 72 79 20 27 5c 27 27 20 63 68  es every '\'' ch
1cf80 61 72 61 63 74 65 72 2e 0a 2a 2a 20 25 71 20 69  aracter..** %q i
1cf90 73 20 64 65 73 69 67 6e 65 64 20 66 6f 72 20 75  s designed for u
1cfa0 73 65 20 69 6e 73 69 64 65 20 61 20 73 74 72 69  se inside a stri
1cfb0 6e 67 20 6c 69 74 65 72 61 6c 2e 29 5e 20 20 42  ng literal.)^  B
1cfc0 79 20 64 6f 75 62 6c 69 6e 67 20 65 61 63 68 20  y doubling each 
1cfd0 27 5c 27 27 0a 2a 2a 20 63 68 61 72 61 63 74 65  '\''.** characte
1cfe0 72 20 69 74 20 65 73 63 61 70 65 73 20 74 68 61  r it escapes tha
1cff0 74 20 63 68 61 72 61 63 74 65 72 20 61 6e 64 20  t character and 
1d000 61 6c 6c 6f 77 73 20 69 74 20 74 6f 20 62 65 20  allows it to be 
1d010 69 6e 73 65 72 74 65 64 20 69 6e 74 6f 0a 2a 2a  inserted into.**
1d020 20 74 68 65 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a   the string..**.
1d030 2a 2a 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20  ** For example, 
1d040 61 73 73 75 6d 65 20 74 68 65 20 73 74 72 69 6e  assume the strin
1d050 67 20 76 61 72 69 61 62 6c 65 20 7a 54 65 78 74  g variable zText
1d060 20 63 6f 6e 74 61 69 6e 73 20 74 65 78 74 20 61   contains text a
1d070 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a  s follows:.**.**
1d080 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
1d090 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 54 65  e>.**  char *zTe
1d0a0 78 74 20 3d 20 22 49 74 27 73 20 61 20 68 61 70  xt = "It's a hap
1d0b0 70 79 20 64 61 79 21 22 3b 0a 2a 2a 20 3c 2f 70  py day!";.** </p
1d0c0 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
1d0d0 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20 63 61 6e 20 75  .**.** One can u
1d0e0 73 65 20 74 68 69 73 20 74 65 78 74 20 69 6e 20  se this text in 
1d0f0 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  an SQL statement
1d100 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a   as follows:.**.
1d110 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
1d120 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a  pre>.**  char *z
1d130 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70  SQL = sqlite3_mp
1d140 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20 49 4e  rintf("INSERT IN
1d150 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45 53 28  TO table VALUES(
1d160 27 25 71 27 29 22 2c 20 7a 54 65 78 74 29 3b 0a  '%q')", zText);.
1d170 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 78 65 63  **  sqlite3_exec
1d180 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c  (db, zSQL, 0, 0,
1d190 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33   0);.**  sqlite3
1d1a0 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20  _free(zSQL);.** 
1d1b0 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
1d1c0 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73  te>.**.** Becaus
1d1d0 65 20 74 68 65 20 25 71 20 66 6f 72 6d 61 74 20  e the %q format 
1d1e0 73 74 72 69 6e 67 20 69 73 20 75 73 65 64 2c 20  string is used, 
1d1f0 74 68 65 20 27 5c 27 27 20 63 68 61 72 61 63 74  the '\'' charact
1d200 65 72 20 69 6e 20 7a 54 65 78 74 0a 2a 2a 20 69  er in zText.** i
1d210 73 20 65 73 63 61 70 65 64 20 61 6e 64 20 74 68  s escaped and th
1d220 65 20 53 51 4c 20 67 65 6e 65 72 61 74 65 64 20  e SQL generated 
1d230 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a  is as follows:.*
1d240 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
1d250 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52  ><pre>.**  INSER
1d260 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41  T INTO table1 VA
1d270 4c 55 45 53 28 27 49 74 27 27 73 20 61 20 68 61  LUES('It''s a ha
1d280 70 70 79 20 64 61 79 21 27 29 0a 2a 2a 20 3c 2f  ppy day!').** </
1d290 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
1d2a0 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20  >.**.** This is 
1d2b0 63 6f 72 72 65 63 74 2e 20 20 48 61 64 20 77 65  correct.  Had we
1d2c0 20 75 73 65 64 20 25 73 20 69 6e 73 74 65 61 64   used %s instead
1d2d0 20 6f 66 20 25 71 2c 20 74 68 65 20 67 65 6e 65   of %q, the gene
1d2e0 72 61 74 65 64 20 53 51 4c 0a 2a 2a 20 77 6f 75  rated SQL.** wou
1d2f0 6c 64 20 68 61 76 65 20 6c 6f 6f 6b 65 64 20 6c  ld have looked l
1d300 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20  ike this:.**.** 
1d310 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
1d320 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e 54  >.**  INSERT INT
1d330 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45 53 28  O table1 VALUES(
1d340 27 49 74 27 73 20 61 20 68 61 70 70 79 20 64 61  'It's a happy da
1d350 79 21 27 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  y!');.** </pre><
1d360 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
1d370 2a 2a 20 54 68 69 73 20 73 65 63 6f 6e 64 20 65  ** This second e
1d380 78 61 6d 70 6c 65 20 69 73 20 61 6e 20 53 51 4c  xample is an SQL
1d390 20 73 79 6e 74 61 78 20 65 72 72 6f 72 2e 20 20   syntax error.  
1d3a0 41 73 20 61 20 67 65 6e 65 72 61 6c 20 72 75 6c  As a general rul
1d3b0 65 20 79 6f 75 20 73 68 6f 75 6c 64 0a 2a 2a 20  e you should.** 
1d3c0 61 6c 77 61 79 73 20 75 73 65 20 25 71 20 69 6e  always use %q in
1d3d0 73 74 65 61 64 20 6f 66 20 25 73 20 77 68 65 6e  stead of %s when
1d3e0 20 69 6e 73 65 72 74 69 6e 67 20 74 65 78 74 20   inserting text 
1d3f0 69 6e 74 6f 20 61 20 73 74 72 69 6e 67 20 6c 69  into a string li
1d400 74 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  teral..**.** ^(T
1d410 68 65 20 25 51 20 6f 70 74 69 6f 6e 20 77 6f 72  he %Q option wor
1d420 6b 73 20 6c 69 6b 65 20 25 71 20 65 78 63 65 70  ks like %q excep
1d430 74 20 69 74 20 61 6c 73 6f 20 61 64 64 73 20 73  t it also adds s
1d440 69 6e 67 6c 65 20 71 75 6f 74 65 73 20 61 72 6f  ingle quotes aro
1d450 75 6e 64 0a 2a 2a 20 74 68 65 20 6f 75 74 73 69  und.** the outsi
1d460 64 65 20 6f 66 20 74 68 65 20 74 6f 74 61 6c 20  de of the total 
1d470 73 74 72 69 6e 67 2e 20 20 41 64 64 69 74 69 6f  string.  Additio
1d480 6e 61 6c 6c 79 2c 20 69 66 20 74 68 65 20 70 61  nally, if the pa
1d490 72 61 6d 65 74 65 72 20 69 6e 20 74 68 65 0a 2a  rameter in the.*
1d4a0 2a 20 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 20  * argument list 
1d4b0 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
1d4c0 72 2c 20 25 51 20 73 75 62 73 74 69 74 75 74 65  r, %Q substitute
1d4d0 73 20 74 68 65 20 74 65 78 74 20 22 4e 55 4c 4c  s the text "NULL
1d4e0 22 20 28 77 69 74 68 6f 75 74 0a 2a 2a 20 73 69  " (without.** si
1d4f0 6e 67 6c 65 20 71 75 6f 74 65 73 29 2e 29 5e 20  ngle quotes).)^ 
1d500 20 53 6f 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65   So, for example
1d510 2c 20 6f 6e 65 20 63 6f 75 6c 64 20 73 61 79 3a  , one could say:
1d520 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
1d530 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61  te><pre>.**  cha
1d540 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65  r *zSQL = sqlite
1d550 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 45 52  3_mprintf("INSER
1d560 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c  T INTO table VAL
1d570 55 45 53 28 25 51 29 22 2c 20 7a 54 65 78 74 29  UES(%Q)", zText)
1d580 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 78  ;.**  sqlite3_ex
1d590 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20  ec(db, zSQL, 0, 
1d5a0 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74  0, 0);.**  sqlit
1d5b0 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a  e3_free(zSQL);.*
1d5c0 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
1d5d0 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  uote>.**.** The 
1d5e0 63 6f 64 65 20 61 62 6f 76 65 20 77 69 6c 6c 20  code above will 
1d5f0 72 65 6e 64 65 72 20 61 20 63 6f 72 72 65 63 74  render a correct
1d600 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69   SQL statement i
1d610 6e 20 74 68 65 20 7a 53 51 4c 0a 2a 2a 20 76 61  n the zSQL.** va
1d620 72 69 61 62 6c 65 20 65 76 65 6e 20 69 66 20 74  riable even if t
1d630 68 65 20 7a 54 65 78 74 20 76 61 72 69 61 62 6c  he zText variabl
1d640 65 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  e is a NULL poin
1d650 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ter..**.** ^(The
1d660 20 22 25 77 22 20 66 6f 72 6d 61 74 74 69 6e 67   "%w" formatting
1d670 20 6f 70 74 69 6f 6e 20 69 73 20 6c 69 6b 65 20   option is like 
1d680 22 25 71 22 20 65 78 63 65 70 74 20 74 68 61 74  "%q" except that
1d690 20 69 74 20 65 78 70 65 63 74 73 20 74 6f 0a 2a   it expects to.*
1d6a0 2a 20 62 65 20 63 6f 6e 74 61 69 6e 65 64 20 77  * be contained w
1d6b0 69 74 68 69 6e 20 64 6f 75 62 6c 65 2d 71 75 6f  ithin double-quo
1d6c0 74 65 73 20 69 6e 73 74 65 61 64 20 6f 66 20 73  tes instead of s
1d6d0 69 6e 67 6c 65 20 71 75 6f 74 65 73 2c 20 61 6e  ingle quotes, an
1d6e0 64 20 69 74 0a 2a 2a 20 65 73 63 61 70 65 73 20  d it.** escapes 
1d6f0 74 68 65 20 64 6f 75 62 6c 65 2d 71 75 6f 74 65  the double-quote
1d700 20 63 68 61 72 61 63 74 65 72 20 69 6e 73 74 65   character inste
1d710 61 64 20 6f 66 20 74 68 65 20 73 69 6e 67 6c 65  ad of the single
1d720 2d 71 75 6f 74 65 0a 2a 2a 20 63 68 61 72 61 63  -quote.** charac
1d730 74 65 72 2e 29 5e 20 20 54 68 65 20 22 25 77 22  ter.)^  The "%w"
1d740 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69   formatting opti
1d750 6f 6e 20 69 73 20 69 6e 74 65 6e 64 65 64 20 66  on is intended f
1d760 6f 72 20 73 61 66 65 6c 79 20 69 6e 73 65 72 74  or safely insert
1d770 69 6e 67 0a 2a 2a 20 74 61 62 6c 65 20 61 6e 64  ing.** table and
1d780 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 73 20 69 6e   column names in
1d790 74 6f 20 61 20 63 6f 6e 73 74 72 75 63 74 65 64  to a constructed
1d7a0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 0a   SQL statement..
1d7b0 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 22 25 7a 22  **.** ^(The "%z"
1d7c0 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69   formatting opti
1d7d0 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 22 25  on works like "%
1d7e0 73 22 20 62 75 74 20 77 69 74 68 20 74 68 65 0a  s" but with the.
1d7f0 2a 2a 20 61 64 64 69 74 69 6f 6e 20 74 68 61 74  ** addition that
1d800 20 61 66 74 65 72 20 74 68 65 20 73 74 72 69 6e   after the strin
1d810 67 20 68 61 73 20 62 65 65 6e 20 72 65 61 64 20  g has been read 
1d820 61 6e 64 20 63 6f 70 69 65 64 20 69 6e 74 6f 0a  and copied into.
1d830 2a 2a 20 74 68 65 20 72 65 73 75 6c 74 2c 20 5b  ** the result, [
1d840 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20  sqlite3_free()] 
1d850 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20 74 68 65  is called on the
1d860 20 69 6e 70 75 74 20 73 74 72 69 6e 67 2e 29 5e   input string.)^
1d870 0a 2a 2f 0a 63 68 61 72 20 2a 73 71 6c 69 74 65  .*/.char *sqlite
1d880 33 5f 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20  3_mprintf(const 
1d890 63 68 61 72 2a 2c 2e 2e 2e 29 3b 0a 63 68 61 72  char*,...);.char
1d8a0 20 2a 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e   *sqlite3_vmprin
1d8b0 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20  tf(const char*, 
1d8c0 76 61 5f 6c 69 73 74 29 3b 0a 63 68 61 72 20 2a  va_list);.char *
1d8d0 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
1d8e0 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74  (int,char*,const
1d8f0 20 63 68 61 72 2a 2c 20 2e 2e 2e 29 3b 0a 63 68   char*, ...);.ch
1d900 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 73 6e 70  ar *sqlite3_vsnp
1d910 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c  rintf(int,char*,
1d920 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76 61 5f  const char*, va_
1d930 6c 69 73 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  list);../*.** CA
1d940 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41  PI3REF: Memory A
1d950 6c 6c 6f 63 61 74 69 6f 6e 20 53 75 62 73 79 73  llocation Subsys
1d960 74 65 6d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51  tem.**.** The SQ
1d970 4c 69 74 65 20 63 6f 72 65 20 75 73 65 73 20 74  Lite core uses t
1d980 68 65 73 65 20 74 68 72 65 65 20 72 6f 75 74 69  hese three routi
1d990 6e 65 73 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69  nes for all of i
1d9a0 74 73 20 6f 77 6e 0a 2a 2a 20 69 6e 74 65 72 6e  ts own.** intern
1d9b0 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  al memory alloca
1d9c0 74 69 6f 6e 20 6e 65 65 64 73 2e 20 22 43 6f 72  tion needs. "Cor
1d9d0 65 22 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f  e" in the previo
1d9e0 75 73 20 73 65 6e 74 65 6e 63 65 0a 2a 2a 20 64  us sentence.** d
1d9f0 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20  oes not include 
1da00 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 74 65 6d  operating-system
1da10 20 73 70 65 63 69 66 69 63 20 56 46 53 20 69 6d   specific VFS im
1da20 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 54  plementation.  T
1da30 68 65 0a 2a 2a 20 57 69 6e 64 6f 77 73 20 56 46  he.** Windows VF
1da40 53 20 75 73 65 73 20 6e 61 74 69 76 65 20 6d 61  S uses native ma
1da50 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28  lloc() and free(
1da60 29 20 66 6f 72 20 73 6f 6d 65 20 6f 70 65 72 61  ) for some opera
1da70 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  tions..**.** ^Th
1da80 65 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  e sqlite3_malloc
1da90 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  () routine retur
1daa0 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
1dab0 61 20 62 6c 6f 63 6b 0a 2a 2a 20 6f 66 20 6d 65  a block.** of me
1dac0 6d 6f 72 79 20 61 74 20 6c 65 61 73 74 20 4e 20  mory at least N 
1dad0 62 79 74 65 73 20 69 6e 20 6c 65 6e 67 74 68 2c  bytes in length,
1dae0 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20   where N is the 
1daf0 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49  parameter..** ^I
1db00 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  f sqlite3_malloc
1db10 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  () is unable to 
1db20 6f 62 74 61 69 6e 20 73 75 66 66 69 63 69 65 6e  obtain sufficien
1db30 74 20 66 72 65 65 0a 2a 2a 20 6d 65 6d 6f 72 79  t free.** memory
1db40 2c 20 69 74 20 72 65 74 75 72 6e 73 20 61 20 4e  , it returns a N
1db50 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 49  ULL pointer.  ^I
1db60 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  f the parameter 
1db70 4e 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  N to.** sqlite3_
1db80 6d 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f  malloc() is zero
1db90 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 68 65   or negative the
1dba0 6e 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  n sqlite3_malloc
1dbb0 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20  () returns.** a 
1dbc0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  NULL pointer..**
1dbd0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
1dbe0 5f 6d 61 6c 6c 6f 63 36 34 28 4e 29 20 72 6f 75  _malloc64(N) rou
1dbf0 74 69 6e 65 20 77 6f 72 6b 73 20 6a 75 73 74 20  tine works just 
1dc00 6c 69 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  like.** sqlite3_
1dc10 6d 61 6c 6c 6f 63 28 4e 29 20 65 78 63 65 70 74  malloc(N) except
1dc20 20 74 68 61 74 20 4e 20 69 73 20 61 6e 20 75 6e   that N is an un
1dc30 73 69 67 6e 65 64 20 36 34 2d 62 69 74 20 69 6e  signed 64-bit in
1dc40 74 65 67 65 72 20 69 6e 73 74 65 61 64 0a 2a 2a  teger instead.**
1dc50 20 6f 66 20 61 20 73 69 67 6e 65 64 20 33 32 2d   of a signed 32-
1dc60 62 69 74 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a  bit integer..**.
1dc70 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c 69  ** ^Calling sqli
1dc80 74 65 33 5f 66 72 65 65 28 29 20 77 69 74 68 20  te3_free() with 
1dc90 61 20 70 6f 69 6e 74 65 72 20 70 72 65 76 69 6f  a pointer previo
1dca0 75 73 6c 79 20 72 65 74 75 72 6e 65 64 0a 2a 2a  usly returned.**
1dcb0 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c   by sqlite3_mall
1dcc0 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  oc() or sqlite3_
1dcd0 72 65 61 6c 6c 6f 63 28 29 20 72 65 6c 65 61 73  realloc() releas
1dce0 65 73 20 74 68 61 74 20 6d 65 6d 6f 72 79 20 73  es that memory s
1dcf0 6f 0a 2a 2a 20 74 68 61 74 20 69 74 20 6d 69 67  o.** that it mig
1dd00 68 74 20 62 65 20 72 65 75 73 65 64 2e 20 20 5e  ht be reused.  ^
1dd10 54 68 65 20 73 71 6c 69 74 65 33 5f 66 72 65 65  The sqlite3_free
1dd20 28 29 20 72 6f 75 74 69 6e 65 20 69 73 0a 2a 2a  () routine is.**
1dd30 20 61 20 6e 6f 2d 6f 70 20 69 66 20 69 73 20 63   a no-op if is c
1dd40 61 6c 6c 65 64 20 77 69 74 68 20 61 20 4e 55 4c  alled with a NUL
1dd50 4c 20 70 6f 69 6e 74 65 72 2e 20 20 50 61 73 73  L pointer.  Pass
1dd60 69 6e 67 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  ing a NULL point
1dd70 65 72 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33  er.** to sqlite3
1dd80 5f 66 72 65 65 28 29 20 69 73 20 68 61 72 6d 6c  _free() is harml
1dd90 65 73 73 2e 20 20 41 66 74 65 72 20 62 65 69 6e  ess.  After bein
1dda0 67 20 66 72 65 65 64 2c 20 6d 65 6d 6f 72 79 0a  g freed, memory.
1ddb0 2a 2a 20 73 68 6f 75 6c 64 20 6e 65 69 74 68 65  ** should neithe
1ddc0 72 20 62 65 20 72 65 61 64 20 6e 6f 72 20 77 72  r be read nor wr
1ddd0 69 74 74 65 6e 2e 20 20 45 76 65 6e 20 72 65 61  itten.  Even rea
1dde0 64 69 6e 67 20 70 72 65 76 69 6f 75 73 6c 79 20  ding previously 
1ddf0 66 72 65 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 20  freed.** memory 
1de00 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69 6e 20  might result in 
1de10 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66  a segmentation f
1de20 61 75 6c 74 20 6f 72 20 6f 74 68 65 72 20 73 65  ault or other se
1de30 76 65 72 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 4d  vere error..** M
1de40 65 6d 6f 72 79 20 63 6f 72 72 75 70 74 69 6f 6e  emory corruption
1de50 2c 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e  , a segmentation
1de60 20 66 61 75 6c 74 2c 20 6f 72 20 6f 74 68 65 72   fault, or other
1de70 20 73 65 76 65 72 65 20 65 72 72 6f 72 0a 2a 2a   severe error.**
1de80 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69 66   might result if
1de90 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20   sqlite3_free() 
1dea0 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61  is called with a
1deb0 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65   non-NULL pointe
1dec0 72 20 74 68 61 74 0a 2a 2a 20 77 61 73 20 6e 6f  r that.** was no
1ded0 74 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  t obtained from 
1dee0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
1def0 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   or sqlite3_real
1df00 6c 6f 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  loc()..**.** ^Th
1df10 65 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  e sqlite3_reallo
1df20 63 28 58 2c 4e 29 20 69 6e 74 65 72 66 61 63 65  c(X,N) interface
1df30 20 61 74 74 65 6d 70 74 73 20 74 6f 20 72 65 73   attempts to res
1df40 69 7a 65 20 61 0a 2a 2a 20 70 72 69 6f 72 20 6d  ize a.** prior m
1df50 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
1df60 20 58 20 74 6f 20 62 65 20 61 74 20 6c 65 61 73   X to be at leas
1df70 74 20 4e 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49  t N bytes..** ^I
1df80 66 20 74 68 65 20 58 20 70 61 72 61 6d 65 74 65  f the X paramete
1df90 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61  r to sqlite3_rea
1dfa0 6c 6c 6f 63 28 58 2c 4e 29 0a 2a 2a 20 69 73 20  lloc(X,N).** is 
1dfb0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74  a NULL pointer t
1dfc0 68 65 6e 20 69 74 73 20 62 65 68 61 76 69 6f 72  hen its behavior
1dfd0 20 69 73 20 69 64 65 6e 74 69 63 61 6c 20 74 6f   is identical to
1dfe0 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69   calling.** sqli
1dff0 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 2e 0a 2a  te3_malloc(N)..*
1e000 2a 20 5e 49 66 20 74 68 65 20 4e 20 70 61 72 61  * ^If the N para
1e010 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
1e020 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 69 73  _realloc(X,N) is
1e030 20 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6e 65 67 61   zero or.** nega
1e040 74 69 76 65 20 74 68 65 6e 20 74 68 65 20 62 65  tive then the be
1e050 68 61 76 69 6f 72 20 69 73 20 65 78 61 63 74 6c  havior is exactl
1e060 79 20 74 68 65 20 73 61 6d 65 20 61 73 20 63 61  y the same as ca
1e070 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33  lling.** sqlite3
1e080 5f 66 72 65 65 28 58 29 2e 0a 2a 2a 20 5e 73 71  _free(X)..** ^sq
1e090 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c  lite3_realloc(X,
1e0a0 4e 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  N) returns a poi
1e0b0 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79  nter to a memory
1e0c0 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f   allocation.** o
1e0d0 66 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74  f at least N byt
1e0e0 65 73 20 69 6e 20 73 69 7a 65 20 6f 72 20 4e 55  es in size or NU
1e0f0 4c 4c 20 69 66 20 69 6e 73 75 66 66 69 63 69 65  LL if insufficie
1e100 6e 74 20 6d 65 6d 6f 72 79 20 69 73 20 61 76 61  nt memory is ava
1e110 69 6c 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 4d  ilable..** ^If M
1e120 20 69 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20   is the size of 
1e130 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61  the prior alloca
1e140 74 69 6f 6e 2c 20 74 68 65 6e 20 6d 69 6e 28 4e  tion, then min(N
1e150 2c 4d 29 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20  ,M) bytes.** of 
1e160 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61  the prior alloca
1e170 74 69 6f 6e 20 61 72 65 20 63 6f 70 69 65 64 20  tion are copied 
1e180 69 6e 74 6f 20 74 68 65 20 62 65 67 69 6e 6e 69  into the beginni
1e190 6e 67 20 6f 66 20 62 75 66 66 65 72 20 72 65 74  ng of buffer ret
1e1a0 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69  urned.** by sqli
1e1b0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29  te3_realloc(X,N)
1e1c0 20 61 6e 64 20 74 68 65 20 70 72 69 6f 72 20 61   and the prior a
1e1d0 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20 66 72 65  llocation is fre
1e1e0 65 64 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74  ed..** ^If sqlit
1e1f0 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20  e3_realloc(X,N) 
1e200 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20 61 6e 64  returns NULL and
1e210 20 4e 20 69 73 20 70 6f 73 69 74 69 76 65 2c 20   N is positive, 
1e220 74 68 65 6e 20 74 68 65 0a 2a 2a 20 70 72 69 6f  then the.** prio
1e230 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20  r allocation is 
1e240 6e 6f 74 20 66 72 65 65 64 2e 0a 2a 2a 0a 2a 2a  not freed..**.**
1e250 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
1e260 61 6c 6c 6f 63 36 34 28 58 2c 4e 29 20 69 6e 74  alloc64(X,N) int
1e270 65 72 66 61 63 65 73 20 77 6f 72 6b 73 20 74 68  erfaces works th
1e280 65 20 73 61 6d 65 20 61 73 0a 2a 2a 20 73 71 6c  e same as.** sql
1e290 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e  ite3_realloc(X,N
1e2a0 29 20 65 78 63 65 70 74 20 74 68 61 74 20 4e 20  ) except that N 
1e2b0 69 73 20 61 20 36 34 2d 62 69 74 20 75 6e 73 69  is a 64-bit unsi
1e2c0 67 6e 65 64 20 69 6e 74 65 67 65 72 20 69 6e 73  gned integer ins
1e2d0 74 65 61 64 0a 2a 2a 20 6f 66 20 61 20 33 32 2d  tead.** of a 32-
1e2e0 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67  bit signed integ
1e2f0 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 58 20  er..**.** ^If X 
1e300 69 73 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  is a memory allo
1e310 63 61 74 69 6f 6e 20 70 72 65 76 69 6f 75 73 6c  cation previousl
1e320 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  y obtained from 
1e330 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
1e340 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c  ,.** sqlite3_mal
1e350 6c 6f 63 36 34 28 29 2c 20 73 71 6c 69 74 65 33  loc64(), sqlite3
1e360 5f 72 65 61 6c 6c 6f 63 28 29 2c 20 6f 72 20 73  _realloc(), or s
1e370 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36 34  qlite3_realloc64
1e380 28 29 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69  (), then.** sqli
1e390 74 65 33 5f 6d 73 69 7a 65 28 58 29 20 72 65 74  te3_msize(X) ret
1e3a0 75 72 6e 73 20 74 68 65 20 73 69 7a 65 20 6f 66  urns the size of
1e3b0 20 74 68 61 74 20 6d 65 6d 6f 72 79 20 61 6c 6c   that memory all
1e3c0 6f 63 61 74 69 6f 6e 20 69 6e 20 62 79 74 65 73  ocation in bytes
1e3d0 2e 0a 2a 2a 20 5e 54 68 65 20 76 61 6c 75 65 20  ..** ^The value 
1e3e0 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
1e3f0 74 65 33 5f 6d 73 69 7a 65 28 58 29 20 6d 69 67  te3_msize(X) mig
1e400 68 74 20 62 65 20 6c 61 72 67 65 72 20 74 68 61  ht be larger tha
1e410 6e 20 74 68 65 20 6e 75 6d 62 65 72 0a 2a 2a 20  n the number.** 
1e420 6f 66 20 62 79 74 65 73 20 72 65 71 75 65 73 74  of bytes request
1e430 65 64 20 77 68 65 6e 20 58 20 77 61 73 20 61 6c  ed when X was al
1e440 6c 6f 63 61 74 65 64 2e 20 20 5e 49 66 20 58 20  located.  ^If X 
1e450 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
1e460 72 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65  r then.** sqlite
1e470 33 5f 6d 73 69 7a 65 28 58 29 20 72 65 74 75 72  3_msize(X) retur
1e480 6e 73 20 7a 65 72 6f 2e 20 20 49 66 20 58 20 70  ns zero.  If X p
1e490 6f 69 6e 74 73 20 74 6f 20 73 6f 6d 65 74 68 69  oints to somethi
1e4a0 6e 67 20 74 68 61 74 20 69 73 20 6e 6f 74 0a 2a  ng that is not.*
1e4b0 2a 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20  * the beginning 
1e4c0 6f 66 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  of memory alloca
1e4d0 74 69 6f 6e 2c 20 6f 72 20 69 66 20 69 74 20 70  tion, or if it p
1e4e0 6f 69 6e 74 73 20 74 6f 20 61 20 66 6f 72 6d 65  oints to a forme
1e4f0 72 6c 79 0a 2a 2a 20 76 61 6c 69 64 20 6d 65 6d  rly.** valid mem
1e500 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74  ory allocation t
1e510 68 61 74 20 68 61 73 20 6e 6f 77 20 62 65 65 6e  hat has now been
1e520 20 66 72 65 65 64 2c 20 74 68 65 6e 20 74 68 65   freed, then the
1e530 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f 66 20   behavior.** of 
1e540 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58 29  sqlite3_msize(X)
1e550 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e   is undefined an
1e560 64 20 70 6f 73 73 69 62 6c 79 20 68 61 72 6d 66  d possibly harmf
1e570 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d  ul..**.** ^The m
1e580 65 6d 6f 72 79 20 72 65 74 75 72 6e 65 64 20 62  emory returned b
1e590 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  y sqlite3_malloc
1e5a0 28 29 2c 20 73 71 6c 69 74 65 33 5f 72 65 61 6c  (), sqlite3_real
1e5b0 6c 6f 63 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65  loc(),.** sqlite
1e5c0 33 5f 6d 61 6c 6c 6f 63 36 34 28 29 2c 20 61 6e  3_malloc64(), an
1e5d0 64 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  d sqlite3_reallo
1e5e0 63 36 34 28 29 0a 2a 2a 20 69 73 20 61 6c 77 61  c64().** is alwa
1e5f0 79 73 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 74  ys aligned to at
1e600 20 6c 65 61 73 74 20 61 6e 20 38 20 62 79 74 65   least an 8 byte
1e610 20 62 6f 75 6e 64 61 72 79 2c 20 6f 72 20 74 6f   boundary, or to
1e620 20 61 0a 2a 2a 20 34 20 62 79 74 65 20 62 6f 75   a.** 4 byte bou
1e630 6e 64 61 72 79 20 69 66 20 74 68 65 20 5b 53 51  ndary if the [SQ
1e640 4c 49 54 45 5f 34 5f 42 59 54 45 5f 41 4c 49 47  LITE_4_BYTE_ALIG
1e650 4e 45 44 5f 4d 41 4c 4c 4f 43 5d 20 63 6f 6d 70  NED_MALLOC] comp
1e660 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69  ile-time.** opti
1e670 6f 6e 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a  on is used..**.*
1e680 2a 20 49 6e 20 53 51 4c 69 74 65 20 76 65 72 73  * In SQLite vers
1e690 69 6f 6e 20 33 2e 35 2e 30 20 61 6e 64 20 33 2e  ion 3.5.0 and 3.
1e6a0 35 2e 31 2c 20 69 74 20 77 61 73 20 70 6f 73 73  5.1, it was poss
1e6b0 69 62 6c 65 20 74 6f 20 64 65 66 69 6e 65 0a 2a  ible to define.*
1e6c0 2a 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 4d 49  * the SQLITE_OMI
1e6d0 54 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f 43 41 54  T_MEMORY_ALLOCAT
1e6e0 49 4f 4e 20 77 68 69 63 68 20 77 6f 75 6c 64 20  ION which would 
1e6f0 63 61 75 73 65 20 74 68 65 20 62 75 69 6c 74 2d  cause the built-
1e700 69 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  in.** implementa
1e710 74 69 6f 6e 20 6f 66 20 74 68 65 73 65 20 72 6f  tion of these ro
1e720 75 74 69 6e 65 73 20 74 6f 20 62 65 20 6f 6d 69  utines to be omi
1e730 74 74 65 64 2e 20 20 54 68 61 74 20 63 61 70 61  tted.  That capa
1e740 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 6e 6f 20  bility.** is no 
1e750 6c 6f 6e 67 65 72 20 70 72 6f 76 69 64 65 64 2e  longer provided.
1e760 20 20 4f 6e 6c 79 20 62 75 69 6c 74 2d 69 6e 20    Only built-in 
1e770 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
1e780 73 20 63 61 6e 20 62 65 20 75 73 65 64 2e 0a 2a  s can be used..*
1e790 2a 0a 2a 2a 20 50 72 69 6f 72 20 74 6f 20 53 51  *.** Prior to SQ
1e7a0 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 37  Lite version 3.7
1e7b0 2e 31 30 2c 20 74 68 65 20 57 69 6e 64 6f 77 73  .10, the Windows
1e7c0 20 4f 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61   OS interface la
1e7d0 79 65 72 20 63 61 6c 6c 65 64 0a 2a 2a 20 74 68  yer called.** th
1e7e0 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28  e system malloc(
1e7f0 29 20 61 6e 64 20 66 72 65 65 28 29 20 64 69 72  ) and free() dir
1e800 65 63 74 6c 79 20 77 68 65 6e 20 63 6f 6e 76 65  ectly when conve
1e810 72 74 69 6e 67 0a 2a 2a 20 66 69 6c 65 6e 61 6d  rting.** filenam
1e820 65 73 20 62 65 74 77 65 65 6e 20 74 68 65 20 55  es between the U
1e830 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 75 73  TF-8 encoding us
1e840 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20  ed by SQLite.** 
1e850 61 6e 64 20 77 68 61 74 65 76 65 72 20 66 69 6c  and whatever fil
1e860 65 6e 61 6d 65 20 65 6e 63 6f 64 69 6e 67 20 69  ename encoding i
1e870 73 20 75 73 65 64 20 62 79 20 74 68 65 20 70 61  s used by the pa
1e880 72 74 69 63 75 6c 61 72 20 57 69 6e 64 6f 77 73  rticular Windows
1e890 0a 2a 2a 20 69 6e 73 74 61 6c 6c 61 74 69 6f 6e  .** installation
1e8a0 2e 20 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  .  Memory alloca
1e8b0 74 69 6f 6e 20 65 72 72 6f 72 73 20 77 65 72 65  tion errors were
1e8c0 20 64 65 74 65 63 74 65 64 2c 20 62 75 74 0a 2a   detected, but.*
1e8d0 2a 20 74 68 65 79 20 77 65 72 65 20 72 65 70 6f  * they were repo
1e8e0 72 74 65 64 20 62 61 63 6b 20 61 73 20 5b 53 51  rted back as [SQ
1e8f0 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 6f  LITE_CANTOPEN] o
1e900 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f 45  r.** [SQLITE_IOE
1e910 52 52 5d 20 72 61 74 68 65 72 20 74 68 61 6e 20  RR] rather than 
1e920 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a  [SQLITE_NOMEM]..
1e930 2a 2a 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74 65  **.** The pointe
1e940 72 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 5b  r arguments to [
1e950 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20  sqlite3_free()] 
1e960 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61  and [sqlite3_rea
1e970 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6d 75 73 74 20  lloc()].** must 
1e980 62 65 20 65 69 74 68 65 72 20 4e 55 4c 4c 20 6f  be either NULL o
1e990 72 20 65 6c 73 65 20 70 6f 69 6e 74 65 72 73 20  r else pointers 
1e9a0 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 20  obtained from a 
1e9b0 70 72 69 6f 72 0a 2a 2a 20 69 6e 76 6f 63 61 74  prior.** invocat
1e9c0 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f  ion of [sqlite3_
1e9d0 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 73 71  malloc()] or [sq
1e9e0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d  lite3_realloc()]
1e9f0 20 74 68 61 74 20 68 61 76 65 0a 2a 2a 20 6e 6f   that have.** no
1ea00 74 20 79 65 74 20 62 65 65 6e 20 72 65 6c 65 61  t yet been relea
1ea10 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61  sed..**.** The a
1ea20 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
1ea30 6e 6f 74 20 72 65 61 64 20 6f 72 20 77 72 69 74  not read or writ
1ea40 65 20 61 6e 79 20 70 61 72 74 20 6f 66 0a 2a 2a  e any part of.**
1ea50 20 61 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f   a block of memo
1ea60 72 79 20 61 66 74 65 72 20 69 74 20 68 61 73 20  ry after it has 
1ea70 62 65 65 6e 20 72 65 6c 65 61 73 65 64 20 75 73  been released us
1ea80 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
1ea90 66 72 65 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69  free()] or [sqli
1eaa0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2e 0a  te3_realloc()]..
1eab0 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  */.void *sqlite3
1eac0 5f 6d 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a 76 6f  _malloc(int);.vo
1ead0 69 64 20 2a 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  id *sqlite3_mall
1eae0 6f 63 36 34 28 73 71 6c 69 74 65 33 5f 75 69 6e  oc64(sqlite3_uin
1eaf0 74 36 34 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69  t64);.void *sqli
1eb00 74 65 33 5f 72 65 61 6c 6c 6f 63 28 76 6f 69 64  te3_realloc(void
1eb10 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 2a 73  *, int);.void *s
1eb20 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36 34  qlite3_realloc64
1eb30 28 76 6f 69 64 2a 2c 20 73 71 6c 69 74 65 33 5f  (void*, sqlite3_
1eb40 75 69 6e 74 36 34 29 3b 0a 76 6f 69 64 20 73 71  uint64);.void sq
1eb50 6c 69 74 65 33 5f 66 72 65 65 28 76 6f 69 64 2a  lite3_free(void*
1eb60 29 3b 0a 73 71 6c 69 74 65 33 5f 75 69 6e 74 36  );.sqlite3_uint6
1eb70 34 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28  4 sqlite3_msize(
1eb80 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  void*);../*.** C
1eb90 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20  API3REF: Memory 
1eba0 41 6c 6c 6f 63 61 74 6f 72 20 53 74 61 74 69 73  Allocator Statis
1ebb0 74 69 63 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  tics.**.** SQLit
1ebc0 65 20 70 72 6f 76 69 64 65 73 20 74 68 65 73 65  e provides these
1ebd0 20 74 77 6f 20 69 6e 74 65 72 66 61 63 65 73 20   two interfaces 
1ebe0 66 6f 72 20 72 65 70 6f 72 74 69 6e 67 20 6f 6e  for reporting on
1ebf0 20 74 68 65 20 73 74 61 74 75 73 0a 2a 2a 20 6f   the status.** o
1ec00 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  f the [sqlite3_m
1ec10 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71 6c 69 74  alloc()], [sqlit
1ec20 65 33 5f 66 72 65 65 28 29 5d 2c 20 61 6e 64 20  e3_free()], and 
1ec30 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  [sqlite3_realloc
1ec40 28 29 5d 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 2c  ()].** routines,
1ec50 20 77 68 69 63 68 20 66 6f 72 6d 20 74 68 65 20   which form the 
1ec60 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20  built-in memory 
1ec70 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79  allocation subsy
1ec80 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  stem..**.** ^The
1ec90 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
1eca0 5f 75 73 65 64 28 29 5d 20 72 6f 75 74 69 6e 65  _used()] routine
1ecb0 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
1ecc0 62 65 72 20 6f 66 20 62 79 74 65 73 0a 2a 2a 20  ber of bytes.** 
1ecd0 6f 66 20 6d 65 6d 6f 72 79 20 63 75 72 72 65 6e  of memory curren
1ece0 74 6c 79 20 6f 75 74 73 74 61 6e 64 69 6e 67 20  tly outstanding 
1ecf0 28 6d 61 6c 6c 6f 63 65 64 20 62 75 74 20 6e 6f  (malloced but no
1ed00 74 20 66 72 65 65 64 29 2e 0a 2a 2a 20 5e 54 68  t freed)..** ^Th
1ed10 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  e [sqlite3_memor
1ed20 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20 72  y_highwater()] r
1ed30 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74  outine returns t
1ed40 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 76 61  he maximum.** va
1ed50 6c 75 65 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f  lue of [sqlite3_
1ed60 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 73  memory_used()] s
1ed70 69 6e 63 65 20 74 68 65 20 68 69 67 68 2d 77 61  ince the high-wa
1ed80 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 77 61 73 20  ter mark.** was 
1ed90 6c 61 73 74 20 72 65 73 65 74 2e 20 20 5e 54 68  last reset.  ^Th
1eda0 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65  e values returne
1edb0 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65  d by [sqlite3_me
1edc0 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 61 6e 64  mory_used()] and
1edd0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  .** [sqlite3_mem
1ede0 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d  ory_highwater()]
1edf0 20 69 6e 63 6c 75 64 65 20 61 6e 79 20 6f 76 65   include any ove
1ee00 72 68 65 61 64 0a 2a 2a 20 61 64 64 65 64 20 62  rhead.** added b
1ee10 79 20 53 51 4c 69 74 65 20 69 6e 20 69 74 73 20  y SQLite in its 
1ee20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
1ee30 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  f [sqlite3_mallo
1ee40 63 28 29 5d 2c 0a 2a 2a 20 62 75 74 20 6e 6f 74  c()],.** but not
1ee50 20 6f 76 65 72 68 65 61 64 20 61 64 64 65 64 20   overhead added 
1ee60 62 79 20 74 68 65 20 61 6e 79 20 75 6e 64 65 72  by the any under
1ee70 6c 79 69 6e 67 20 73 79 73 74 65 6d 20 6c 69 62  lying system lib
1ee80 72 61 72 79 0a 2a 2a 20 72 6f 75 74 69 6e 65 73  rary.** routines
1ee90 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 6d   that [sqlite3_m
1eea0 61 6c 6c 6f 63 28 29 5d 20 6d 61 79 20 63 61 6c  alloc()] may cal
1eeb0 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65  l..**.** ^The me
1eec0 6d 6f 72 79 20 68 69 67 68 2d 77 61 74 65 72 20  mory high-water 
1eed0 6d 61 72 6b 20 69 73 20 72 65 73 65 74 20 74 6f  mark is reset to
1eee0 20 74 68 65 20 63 75 72 72 65 6e 74 20 76 61 6c   the current val
1eef0 75 65 20 6f 66 0a 2a 2a 20 5b 73 71 6c 69 74 65  ue of.** [sqlite
1ef00 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d  3_memory_used()]
1ef10 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20   if and only if 
1ef20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f  the parameter to
1ef30 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  .** [sqlite3_mem
1ef40 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d  ory_highwater()]
1ef50 20 69 73 20 74 72 75 65 2e 20 20 5e 54 68 65 20   is true.  ^The 
1ef60 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 0a 2a  value returned.*
1ef70 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65  * by [sqlite3_me
1ef80 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 31  mory_highwater(1
1ef90 29 5d 20 69 73 20 74 68 65 20 68 69 67 68 2d 77  )] is the high-w
1efa0 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 70 72 69  ater mark.** pri
1efb0 6f 72 20 74 6f 20 74 68 65 20 72 65 73 65 74 2e  or to the reset.
1efc0 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36  .*/.sqlite3_int6
1efd0 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79  4 sqlite3_memory
1efe0 5f 75 73 65 64 28 76 6f 69 64 29 3b 0a 73 71 6c  _used(void);.sql
1eff0 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74  ite3_int64 sqlit
1f000 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61  e3_memory_highwa
1f010 74 65 72 28 69 6e 74 20 72 65 73 65 74 46 6c 61  ter(int resetFla
1f020 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  g);../*.** CAPI3
1f030 52 45 46 3a 20 50 73 65 75 64 6f 2d 52 61 6e 64  REF: Pseudo-Rand
1f040 6f 6d 20 4e 75 6d 62 65 72 20 47 65 6e 65 72 61  om Number Genera
1f050 74 6f 72 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  tor.**.** SQLite
1f060 20 63 6f 6e 74 61 69 6e 73 20 61 20 68 69 67 68   contains a high
1f070 2d 71 75 61 6c 69 74 79 20 70 73 65 75 64 6f 2d  -quality pseudo-
1f080 72 61 6e 64 6f 6d 20 6e 75 6d 62 65 72 20 67 65  random number ge
1f090 6e 65 72 61 74 6f 72 20 28 50 52 4e 47 29 20 75  nerator (PRNG) u
1f0a0 73 65 64 20 74 6f 0a 2a 2a 20 73 65 6c 65 63 74  sed to.** select
1f0b0 20 72 61 6e 64 6f 6d 20 5b 52 4f 57 49 44 20 7c   random [ROWID |
1f0c0 20 52 4f 57 49 44 73 5d 20 77 68 65 6e 20 69 6e   ROWIDs] when in
1f0d0 73 65 72 74 69 6e 67 20 6e 65 77 20 72 65 63 6f  serting new reco
1f0e0 72 64 73 20 69 6e 74 6f 20 61 20 74 61 62 6c 65  rds into a table
1f0f0 20 74 68 61 74 0a 2a 2a 20 61 6c 72 65 61 64 79   that.** already
1f100 20 75 73 65 73 20 74 68 65 20 6c 61 72 67 65 73   uses the larges
1f110 74 20 70 6f 73 73 69 62 6c 65 20 5b 52 4f 57 49  t possible [ROWI
1f120 44 5d 2e 20 20 54 68 65 20 50 52 4e 47 20 69 73  D].  The PRNG is
1f130 20 61 6c 73 6f 20 75 73 65 64 20 66 6f 72 0a 2a   also used for.*
1f140 2a 20 74 68 65 20 62 75 69 6c 64 2d 69 6e 20 72  * the build-in r
1f150 61 6e 64 6f 6d 28 29 20 61 6e 64 20 72 61 6e 64  andom() and rand
1f160 6f 6d 62 6c 6f 62 28 29 20 53 51 4c 20 66 75 6e  omblob() SQL fun
1f170 63 74 69 6f 6e 73 2e 20 20 54 68 69 73 20 69 6e  ctions.  This in
1f180 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 0a 2a  terface allows.*
1f190 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74  * applications t
1f1a0 6f 20 61 63 63 65 73 73 20 74 68 65 20 73 61 6d  o access the sam
1f1b0 65 20 50 52 4e 47 20 66 6f 72 20 6f 74 68 65 72  e PRNG for other
1f1c0 20 70 75 72 70 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a   purposes..**.**
1f1d0 20 5e 41 20 63 61 6c 6c 20 74 6f 20 74 68 69 73   ^A call to this
1f1e0 20 72 6f 75 74 69 6e 65 20 73 74 6f 72 65 73 20   routine stores 
1f1f0 4e 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64 6f  N bytes of rando
1f200 6d 6e 65 73 73 20 69 6e 74 6f 20 62 75 66 66 65  mness into buffe
1f210 72 20 50 2e 0a 2a 2a 20 5e 54 68 65 20 50 20 70  r P..** ^The P p
1f220 61 72 61 6d 65 74 65 72 20 63 61 6e 20 62 65 20  arameter can be 
1f230 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a  a NULL pointer..
1f240 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 69 73 20 72  **.** ^If this r
1f250 6f 75 74 69 6e 65 20 68 61 73 20 6e 6f 74 20 62  outine has not b
1f260 65 65 6e 20 70 72 65 76 69 6f 75 73 6c 79 20 63  een previously c
1f270 61 6c 6c 65 64 20 6f 72 20 69 66 20 74 68 65 20  alled or if the 
1f280 70 72 65 76 69 6f 75 73 0a 2a 2a 20 63 61 6c 6c  previous.** call
1f290 20 68 61 64 20 4e 20 6c 65 73 73 20 74 68 61 6e   had N less than
1f2a0 20 6f 6e 65 20 6f 72 20 61 20 4e 55 4c 4c 20 70   one or a NULL p
1f2b0 6f 69 6e 74 65 72 20 66 6f 72 20 50 2c 20 74 68  ointer for P, th
1f2c0 65 6e 20 74 68 65 20 50 52 4e 47 20 69 73 0a 2a  en the PRNG is.*
1f2d0 2a 20 73 65 65 64 65 64 20 75 73 69 6e 67 20 72  * seeded using r
1f2e0 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e  andomness obtain
1f2f0 65 64 20 66 72 6f 6d 20 74 68 65 20 78 52 61 6e  ed from the xRan
1f300 64 6f 6d 6e 65 73 73 20 6d 65 74 68 6f 64 20 6f  domness method o
1f310 66 0a 2a 2a 20 74 68 65 20 64 65 66 61 75 6c 74  f.** the default
1f320 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f   [sqlite3_vfs] o
1f330 62 6a 65 63 74 2e 0a 2a 2a 20 5e 49 66 20 74 68  bject..** ^If th
1f340 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20  e previous call 
1f350 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  to this routine 
1f360 68 61 64 20 61 6e 20 4e 20 6f 66 20 31 20 6f 72  had an N of 1 or
1f370 20 6d 6f 72 65 20 61 6e 64 20 61 0a 2a 2a 20 6e   more and a.** n
1f380 6f 6e 2d 4e 55 4c 4c 20 50 20 74 68 65 6e 20 74  on-NULL P then t
1f390 68 65 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d  he pseudo-random
1f3a0 6e 65 73 73 20 69 73 20 67 65 6e 65 72 61 74 65  ness is generate
1f3b0 64 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 6c 79 20  d.** internally 
1f3c0 61 6e 64 20 77 69 74 68 6f 75 74 20 72 65 63 6f  and without reco
1f3d0 75 72 73 65 20 74 6f 20 74 68 65 20 5b 73 71 6c  urse to the [sql
1f3e0 69 74 65 33 5f 76 66 73 5d 20 78 52 61 6e 64 6f  ite3_vfs] xRando
1f3f0 6d 6e 65 73 73 0a 2a 2a 20 6d 65 74 68 6f 64 2e  mness.** method.
1f400 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  .*/.void sqlite3
1f410 5f 72 61 6e 64 6f 6d 6e 65 73 73 28 69 6e 74 20  _randomness(int 
1f420 4e 2c 20 76 6f 69 64 20 2a 50 29 3b 0a 0a 2f 2a  N, void *P);../*
1f430 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
1f440 6d 70 69 6c 65 2d 54 69 6d 65 20 41 75 74 68 6f  mpile-Time Autho
1f450 72 69 7a 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63  rization Callbac
1f460 6b 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  ks.** METHOD: sq
1f470 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  lite3.**.** ^Thi
1f480 73 20 72 6f 75 74 69 6e 65 20 72 65 67 69 73 74  s routine regist
1f490 65 72 73 20 61 6e 20 61 75 74 68 6f 72 69 7a 65  ers an authorize
1f4a0 72 20 63 61 6c 6c 62 61 63 6b 20 77 69 74 68 20  r callback with 
1f4b0 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20  a particular.** 
1f4c0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
1f4d0 74 69 6f 6e 5d 2c 20 73 75 70 70 6c 69 65 64 20  tion], supplied 
1f4e0 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67  in the first arg
1f4f0 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 61  ument..** ^The a
1f500 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
1f510 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 73  ck is invoked as
1f520 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
1f530 61 72 65 20 62 65 69 6e 67 20 63 6f 6d 70 69 6c  are being compil
1f540 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65  ed.** by [sqlite
1f550 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20  3_prepare()] or 
1f560 69 74 73 20 76 61 72 69 61 6e 74 73 20 5b 73 71  its variants [sq
1f570 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
1f580 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
1f590 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 61 6e  _prepare16()] an
1f5a0 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  d [sqlite3_prepa
1f5b0 72 65 31 36 5f 76 32 28 29 5d 2e 20 20 5e 41 74  re16_v2()].  ^At
1f5c0 20 76 61 72 69 6f 75 73 0a 2a 2a 20 70 6f 69 6e   various.** poin
1f5d0 74 73 20 64 75 72 69 6e 67 20 74 68 65 20 63 6f  ts during the co
1f5e0 6d 70 69 6c 61 74 69 6f 6e 20 70 72 6f 63 65 73  mpilation proces
1f5f0 73 2c 20 61 73 20 6c 6f 67 69 63 20 69 73 20 62  s, as logic is b
1f600 65 69 6e 67 20 63 72 65 61 74 65 64 0a 2a 2a 20  eing created.** 
1f610 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f  to perform vario
1f620 75 73 20 61 63 74 69 6f 6e 73 2c 20 74 68 65 20  us actions, the 
1f630 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
1f640 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 74  ack is invoked t
1f650 6f 0a 2a 2a 20 73 65 65 20 69 66 20 74 68 6f 73  o.** see if thos
1f660 65 20 61 63 74 69 6f 6e 73 20 61 72 65 20 61 6c  e actions are al
1f670 6c 6f 77 65 64 2e 20 20 5e 54 68 65 20 61 75 74  lowed.  ^The aut
1f680 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
1f690 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72   should.** retur
1f6a0 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 74 6f  n [SQLITE_OK] to
1f6b0 20 61 6c 6c 6f 77 20 74 68 65 20 61 63 74 69 6f   allow the actio
1f6c0 6e 2c 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52  n, [SQLITE_IGNOR
1f6d0 45 5d 20 74 6f 20 64 69 73 61 6c 6c 6f 77 20 74  E] to disallow t
1f6e0 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 61  he.** specific a
1f6f0 63 74 69 6f 6e 20 62 75 74 20 61 6c 6c 6f 77 20  ction but allow 
1f700 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
1f710 74 20 74 6f 20 63 6f 6e 74 69 6e 75 65 20 74 6f  t to continue to
1f720 20 62 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 2c   be.** compiled,
1f730 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59   or [SQLITE_DENY
1f740 5d 20 74 6f 20 63 61 75 73 65 20 74 68 65 20 65  ] to cause the e
1f750 6e 74 69 72 65 20 53 51 4c 20 73 74 61 74 65 6d  ntire SQL statem
1f760 65 6e 74 20 74 6f 20 62 65 0a 2a 2a 20 72 65 6a  ent to be.** rej
1f770 65 63 74 65 64 20 77 69 74 68 20 61 6e 20 65 72  ected with an er
1f780 72 6f 72 2e 20 20 5e 49 66 20 74 68 65 20 61 75  ror.  ^If the au
1f790 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
1f7a0 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79  k returns.** any
1f7b0 20 76 61 6c 75 65 20 6f 74 68 65 72 20 74 68 61   value other tha
1f7c0 6e 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  n [SQLITE_IGNORE
1f7d0 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20  ], [SQLITE_OK], 
1f7e0 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d  or [SQLITE_DENY]
1f7f0 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 5b 73 71  .** then the [sq
1f800 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
1f810 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e  ()] or equivalen
1f820 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67  t call that trig
1f830 67 65 72 65 64 0a 2a 2a 20 74 68 65 20 61 75 74  gered.** the aut
1f840 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 69  horizer will fai
1f850 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20  l with an error 
1f860 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 57  message..**.** W
1f870 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  hen the callback
1f880 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
1f890 5f 4f 4b 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73  _OK], that means
1f8a0 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a   the operation.*
1f8b0 2a 20 72 65 71 75 65 73 74 65 64 20 69 73 20 6f  * requested is o
1f8c0 6b 2e 20 20 5e 57 68 65 6e 20 74 68 65 20 63 61  k.  ^When the ca
1f8d0 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b  llback returns [
1f8e0 53 51 4c 49 54 45 5f 44 45 4e 59 5d 2c 20 74 68  SQLITE_DENY], th
1f8f0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  e.** [sqlite3_pr
1f900 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65  epare_v2()] or e
1f910 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74  quivalent call t
1f920 68 61 74 20 74 72 69 67 67 65 72 65 64 20 74 68  hat triggered th
1f930 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20  e.** authorizer 
1f940 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61  will fail with a
1f950 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20  n error message 
1f960 65 78 70 6c 61 69 6e 69 6e 67 20 74 68 61 74 0a  explaining that.
1f970 2a 2a 20 61 63 63 65 73 73 20 69 73 20 64 65 6e  ** access is den
1f980 69 65 64 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ied. .**.** ^The
1f990 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
1f9a0 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a   to the authoriz
1f9b0 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  er callback is a
1f9c0 20 63 6f 70 79 20 6f 66 20 74 68 65 20 74 68 69   copy of the thi
1f9d0 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  rd.** parameter 
1f9e0 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73  to the sqlite3_s
1f9f0 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 20  et_authorizer() 
1fa00 69 6e 74 65 72 66 61 63 65 2e 20 5e 54 68 65 20  interface. ^The 
1fa10 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
1fa20 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62  .** to the callb
1fa30 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65  ack is an intege
1fa40 72 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c  r [SQLITE_COPY |
1fa50 20 61 63 74 69 6f 6e 20 63 6f 64 65 5d 20 74 68   action code] th
1fa60 61 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20  at specifies.** 
1fa70 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 61  the particular a
1fa80 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68  ction to be auth
1fa90 6f 72 69 7a 65 64 2e 20 5e 54 68 65 20 74 68 69  orized. ^The thi
1faa0 72 64 20 74 68 72 6f 75 67 68 20 73 69 78 74 68  rd through sixth
1fab0 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74   parameters.** t
1fac0 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61  o the callback a
1fad0 72 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  re zero-terminat
1fae0 65 64 20 73 74 72 69 6e 67 73 20 74 68 61 74 20  ed strings that 
1faf0 63 6f 6e 74 61 69 6e 20 61 64 64 69 74 69 6f 6e  contain addition
1fb00 61 6c 0a 2a 2a 20 64 65 74 61 69 6c 73 20 61 62  al.** details ab
1fb10 6f 75 74 20 74 68 65 20 61 63 74 69 6f 6e 20 74  out the action t
1fb20 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e  o be authorized.
1fb30 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61  .**.** ^If the a
1fb40 63 74 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53  ction code is [S
1fb50 51 4c 49 54 45 5f 52 45 41 44 5d 0a 2a 2a 20 61  QLITE_READ].** a
1fb60 6e 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  nd the callback 
1fb70 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
1fb80 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65  IGNORE] then the
1fb90 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
1fba0 61 74 65 6d 65 6e 74 5d 20 73 74 61 74 65 6d 65  atement] stateme
1fbb0 6e 74 20 69 73 20 63 6f 6e 73 74 72 75 63 74 65  nt is constructe
1fbc0 64 20 74 6f 20 73 75 62 73 74 69 74 75 74 65 0a  d to substitute.
1fbd0 2a 2a 20 61 20 4e 55 4c 4c 20 76 61 6c 75 65 20  ** a NULL value 
1fbe0 69 6e 20 70 6c 61 63 65 20 6f 66 20 74 68 65 20  in place of the 
1fbf0 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61  table column tha
1fc00 74 20 77 6f 75 6c 64 20 68 61 76 65 0a 2a 2a 20  t would have.** 
1fc10 62 65 65 6e 20 72 65 61 64 20 69 66 20 5b 53 51  been read if [SQ
1fc20 4c 49 54 45 5f 4f 4b 5d 20 68 61 64 20 62 65 65  LITE_OK] had bee
1fc30 6e 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65  n returned.  The
1fc40 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d   [SQLITE_IGNORE]
1fc50 0a 2a 2a 20 72 65 74 75 72 6e 20 63 61 6e 20 62  .** return can b
1fc60 65 20 75 73 65 64 20 74 6f 20 64 65 6e 79 20 61  e used to deny a
1fc70 6e 20 75 6e 74 72 75 73 74 65 64 20 75 73 65 72  n untrusted user
1fc80 20 61 63 63 65 73 73 20 74 6f 20 69 6e 64 69 76   access to indiv
1fc90 69 64 75 61 6c 0a 2a 2a 20 63 6f 6c 75 6d 6e 73  idual.** columns
1fca0 20 6f 66 20 61 20 74 61 62 6c 65 2e 0a 2a 2a 20   of a table..** 
1fcb0 5e 49 66 20 74 68 65 20 61 63 74 69 6f 6e 20 63  ^If the action c
1fcc0 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 44  ode is [SQLITE_D
1fcd0 45 4c 45 54 45 5d 20 61 6e 64 20 74 68 65 20 63  ELETE] and the c
1fce0 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a  allback returns.
1fcf0 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52  ** [SQLITE_IGNOR
1fd00 45 5d 20 74 68 65 6e 20 74 68 65 20 5b 44 45 4c  E] then the [DEL
1fd10 45 54 45 5d 20 6f 70 65 72 61 74 69 6f 6e 20 70  ETE] operation p
1fd20 72 6f 63 65 65 64 73 20 62 75 74 20 74 68 65 0a  roceeds but the.
1fd30 2a 2a 20 5b 74 72 75 6e 63 61 74 65 20 6f 70 74  ** [truncate opt
1fd40 69 6d 69 7a 61 74 69 6f 6e 5d 20 69 73 20 64 69  imization] is di
1fd50 73 61 62 6c 65 64 20 61 6e 64 20 61 6c 6c 20 72  sabled and all r
1fd60 6f 77 73 20 61 72 65 20 64 65 6c 65 74 65 64 20  ows are deleted 
1fd70 69 6e 64 69 76 69 64 75 61 6c 6c 79 2e 0a 2a 2a  individually..**
1fd80 0a 2a 2a 20 41 6e 20 61 75 74 68 6f 72 69 7a 65  .** An authorize
1fd90 72 20 69 73 20 75 73 65 64 20 77 68 65 6e 20 5b  r is used when [
1fda0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20  sqlite3_prepare 
1fdb0 7c 20 70 72 65 70 61 72 69 6e 67 5d 0a 2a 2a 20  | preparing].** 
1fdc0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 66  SQL statements f
1fdd0 72 6f 6d 20 61 6e 20 75 6e 74 72 75 73 74 65 64  rom an untrusted
1fde0 20 73 6f 75 72 63 65 2c 20 74 6f 20 65 6e 73 75   source, to ensu
1fdf0 72 65 20 74 68 61 74 20 74 68 65 20 53 51 4c 20  re that the SQL 
1fe00 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 64 6f  statements.** do
1fe10 20 6e 6f 74 20 74 72 79 20 74 6f 20 61 63 63 65   not try to acce
1fe20 73 73 20 64 61 74 61 20 74 68 65 79 20 61 72 65  ss data they are
1fe30 20 6e 6f 74 20 61 6c 6c 6f 77 65 64 20 74 6f 20   not allowed to 
1fe40 73 65 65 2c 20 6f 72 20 74 68 61 74 20 74 68 65  see, or that the
1fe50 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 74 72 79 20  y do not.** try 
1fe60 74 6f 20 65 78 65 63 75 74 65 20 6d 61 6c 69 63  to execute malic
1fe70 69 6f 75 73 20 73 74 61 74 65 6d 65 6e 74 73 20  ious statements 
1fe80 74 68 61 74 20 64 61 6d 61 67 65 20 74 68 65 20  that damage the 
1fe90 64 61 74 61 62 61 73 65 2e 20 20 46 6f 72 0a 2a  database.  For.*
1fea0 2a 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70  * example, an ap
1feb0 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79 20 61 6c  plication may al
1fec0 6c 6f 77 20 61 20 75 73 65 72 20 74 6f 20 65 6e  low a user to en
1fed0 74 65 72 20 61 72 62 69 74 72 61 72 79 0a 2a 2a  ter arbitrary.**
1fee0 20 53 51 4c 20 71 75 65 72 69 65 73 20 66 6f 72   SQL queries for
1fef0 20 65 76 61 6c 75 61 74 69 6f 6e 20 62 79 20 61   evaluation by a
1ff00 20 64 61 74 61 62 61 73 65 2e 20 20 42 75 74 20   database.  But 
1ff10 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
1ff20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74  does.** not want
1ff30 20 74 68 65 20 75 73 65 72 20 74 6f 20 62 65 20   the user to be 
1ff40 61 62 6c 65 20 74 6f 20 6d 61 6b 65 20 61 72 62  able to make arb
1ff50 69 74 72 61 72 79 20 63 68 61 6e 67 65 73 20 74  itrary changes t
1ff60 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73  o the.** databas
1ff70 65 2e 20 20 41 6e 20 61 75 74 68 6f 72 69 7a 65  e.  An authorize
1ff80 72 20 63 6f 75 6c 64 20 74 68 65 6e 20 62 65 20  r could then be 
1ff90 70 75 74 20 69 6e 20 70 6c 61 63 65 20 77 68 69  put in place whi
1ffa0 6c 65 20 74 68 65 0a 2a 2a 20 75 73 65 72 2d 65  le the.** user-e
1ffb0 6e 74 65 72 65 64 20 53 51 4c 20 69 73 20 62 65  ntered SQL is be
1ffc0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  ing [sqlite3_pre
1ffd0 70 61 72 65 20 7c 20 70 72 65 70 61 72 65 64 5d  pare | prepared]
1ffe0 20 74 68 61 74 0a 2a 2a 20 64 69 73 61 6c 6c 6f   that.** disallo
1fff0 77 73 20 65 76 65 72 79 74 68 69 6e 67 20 65 78  ws everything ex
20000 63 65 70 74 20 5b 53 45 4c 45 43 54 5d 20 73 74  cept [SELECT] st
20010 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20  atements..**.** 
20020 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61  Applications tha
20030 74 20 6e 65 65 64 20 74 6f 20 70 72 6f 63 65 73  t need to proces
20040 73 20 53 51 4c 20 66 72 6f 6d 20 75 6e 74 72 75  s SQL from untru
20050 73 74 65 64 20 73 6f 75 72 63 65 73 0a 2a 2a 20  sted sources.** 
20060 6d 69 67 68 74 20 61 6c 73 6f 20 63 6f 6e 73 69  might also consi
20070 64 65 72 20 6c 6f 77 65 72 69 6e 67 20 72 65 73  der lowering res
20080 6f 75 72 63 65 20 6c 69 6d 69 74 73 20 75 73 69  ource limits usi
20090 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69  ng [sqlite3_limi
200a0 74 28 29 5d 0a 2a 2a 20 61 6e 64 20 6c 69 6d 69  t()].** and limi
200b0 74 69 6e 67 20 64 61 74 61 62 61 73 65 20 73 69  ting database si
200c0 7a 65 20 75 73 69 6e 67 20 74 68 65 20 5b 6d 61  ze using the [ma
200d0 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50  x_page_count] [P
200e0 52 41 47 4d 41 5d 0a 2a 2a 20 69 6e 20 61 64 64  RAGMA].** in add
200f0 69 74 69 6f 6e 20 74 6f 20 75 73 69 6e 67 20 61  ition to using a
20100 6e 20 61 75 74 68 6f 72 69 7a 65 72 2e 0a 2a 2a  n authorizer..**
20110 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 61 20 73 69 6e  .** ^(Only a sin
20120 67 6c 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  gle authorizer c
20130 61 6e 20 62 65 20 69 6e 20 70 6c 61 63 65 20 6f  an be in place o
20140 6e 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e  n a database con
20150 6e 65 63 74 69 6f 6e 0a 2a 2a 20 61 74 20 61 20  nection.** at a 
20160 74 69 6d 65 2e 20 20 45 61 63 68 20 63 61 6c 6c  time.  Each call
20170 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65 74 5f   to sqlite3_set_
20180 61 75 74 68 6f 72 69 7a 65 72 20 6f 76 65 72 72  authorizer overr
20190 69 64 65 73 20 74 68 65 0a 2a 2a 20 70 72 65 76  ides the.** prev
201a0 69 6f 75 73 20 63 61 6c 6c 2e 29 5e 20 20 5e 44  ious call.)^  ^D
201b0 69 73 61 62 6c 65 20 74 68 65 20 61 75 74 68 6f  isable the autho
201c0 72 69 7a 65 72 20 62 79 20 69 6e 73 74 61 6c 6c  rizer by install
201d0 69 6e 67 20 61 20 4e 55 4c 4c 20 63 61 6c 6c 62  ing a NULL callb
201e0 61 63 6b 2e 0a 2a 2a 20 54 68 65 20 61 75 74 68  ack..** The auth
201f0 6f 72 69 7a 65 72 20 69 73 20 64 69 73 61 62 6c  orizer is disabl
20200 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a  ed by default..*
20210 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 69  *.** The authori
20220 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73  zer callback mus
20230 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e  t not do anythin
20240 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69  g that will modi
20250 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61  fy.** the databa
20260 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68  se connection th
20270 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 61  at invoked the a
20280 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
20290 63 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  ck..** Note that
202a0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
202b0 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c  e_v2()] and [sql
202c0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74  ite3_step()] bot
202d0 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a  h modify their.*
202e0 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  * database conne
202f0 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d  ctions for the m
20300 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66  eaning of "modif
20310 79 22 20 69 6e 20 74 68 69 73 20 70 61 72 61 67  y" in this parag
20320 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65  raph..**.** ^Whe
20330 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  n [sqlite3_prepa
20340 72 65 5f 76 32 28 29 5d 20 69 73 20 75 73 65 64  re_v2()] is used
20350 20 74 6f 20 70 72 65 70 61 72 65 20 61 20 73 74   to prepare a st
20360 61 74 65 6d 65 6e 74 2c 20 74 68 65 0a 2a 2a 20  atement, the.** 
20370 73 74 61 74 65 6d 65 6e 74 20 6d 69 67 68 74 20  statement might 
20380 62 65 20 72 65 2d 70 72 65 70 61 72 65 64 20 64  be re-prepared d
20390 75 72 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73  uring [sqlite3_s
203a0 74 65 70 28 29 5d 20 64 75 65 20 74 6f 20 61 20  tep()] due to a 
203b0 0a 2a 2a 20 73 63 68 65 6d 61 20 63 68 61 6e 67  .** schema chang
203c0 65 2e 20 20 48 65 6e 63 65 2c 20 74 68 65 20 61  e.  Hence, the a
203d0 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c  pplication shoul
203e0 64 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68  d ensure that th
203f0 65 0a 2a 2a 20 63 6f 72 72 65 63 74 20 61 75 74  e.** correct aut
20400 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
20410 20 72 65 6d 61 69 6e 73 20 69 6e 20 70 6c 61 63   remains in plac
20420 65 20 64 75 72 69 6e 67 20 74 68 65 20 5b 73 71  e during the [sq
20430 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a  lite3_step()]..*
20440 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74 68 61 74 20  *.** ^Note that 
20450 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
20460 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
20470 65 64 20 6f 6e 6c 79 20 64 75 72 69 6e 67 0a 2a  ed only during.*
20480 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
20490 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72  re()] or its var
204a0 69 61 6e 74 73 2e 20 20 41 75 74 68 6f 72 69 7a  iants.  Authoriz
204b0 61 74 69 6f 6e 20 69 73 20 6e 6f 74 0a 2a 2a 20  ation is not.** 
204c0 70 65 72 66 6f 72 6d 65 64 20 64 75 72 69 6e 67  performed during
204d0 20 73 74 61 74 65 6d 65 6e 74 20 65 76 61 6c 75   statement evalu
204e0 61 74 69 6f 6e 20 69 6e 20 5b 73 71 6c 69 74 65  ation in [sqlite
204f0 33 5f 73 74 65 70 28 29 5d 2c 20 75 6e 6c 65 73  3_step()], unles
20500 73 0a 2a 2a 20 61 73 20 73 74 61 74 65 64 20 69  s.** as stated i
20510 6e 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 70  n the previous p
20520 61 72 61 67 72 61 70 68 2c 20 73 71 6c 69 74 65  aragraph, sqlite
20530 33 5f 73 74 65 70 28 29 20 69 6e 76 6f 6b 65 73  3_step() invokes
20540 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 65 70  .** sqlite3_prep
20550 61 72 65 5f 76 32 28 29 20 74 6f 20 72 65 70 72  are_v2() to repr
20560 65 70 61 72 65 20 61 20 73 74 61 74 65 6d 65 6e  epare a statemen
20570 74 20 61 66 74 65 72 20 61 20 73 63 68 65 6d 61  t after a schema
20580 20 63 68 61 6e 67 65 2e 0a 2a 2f 0a 69 6e 74 20   change..*/.int 
20590 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
205a0 6f 72 69 7a 65 72 28 0a 20 20 73 71 6c 69 74 65  orizer(.  sqlite
205b0 33 2a 2c 0a 20 20 69 6e 74 20 28 2a 78 41 75 74  3*,.  int (*xAut
205c0 68 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e  h)(void*,int,con
205d0 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63  st char*,const c
205e0 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  har*,const char*
205f0 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 0a 20  ,const char*),. 
20600 20 76 6f 69 64 20 2a 70 55 73 65 72 44 61 74 61   void *pUserData
20610 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
20620 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20  REF: Authorizer 
20630 52 65 74 75 72 6e 20 43 6f 64 65 73 0a 2a 2a 0a  Return Codes.**.
20640 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** The [sqlite3_
20650 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c  set_authorizer |
20660 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
20670 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 5d 20 6d  back function] m
20680 75 73 74 0a 2a 2a 20 72 65 74 75 72 6e 20 65 69  ust.** return ei
20690 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  ther [SQLITE_OK]
206a0 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 73 65   or one of these
206b0 20 74 77 6f 20 63 6f 6e 73 74 61 6e 74 73 20 69   two constants i
206c0 6e 20 6f 72 64 65 72 0a 2a 2a 20 74 6f 20 73 69  n order.** to si
206d0 67 6e 61 6c 20 53 51 4c 69 74 65 20 77 68 65 74  gnal SQLite whet
206e0 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 61  her or not the a
206f0 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74  ction is permitt
20700 65 64 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a 20  ed.  See the.** 
20710 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74  [sqlite3_set_aut
20720 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72  horizer | author
20730 69 7a 65 72 20 64 6f 63 75 6d 65 6e 74 61 74 69  izer documentati
20740 6f 6e 5d 20 66 6f 72 20 61 64 64 69 74 69 6f 6e  on] for addition
20750 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  al.** informatio
20760 6e 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68  n..**.** Note th
20770 61 74 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  at SQLITE_IGNORE
20780 20 69 73 20 61 6c 73 6f 20 75 73 65 64 20 61 73   is also used as
20790 20 61 20 5b 63 6f 6e 66 6c 69 63 74 20 72 65 73   a [conflict res
207a0 6f 6c 75 74 69 6f 6e 20 6d 6f 64 65 5d 0a 2a 2a  olution mode].**
207b0 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 74   returned from t
207c0 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 74 61 62  he [sqlite3_vtab
207d0 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 74 28 29 5d 20  _on_conflict()] 
207e0 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2f 0a 23 64  interface..*/.#d
207f0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4e  efine SQLITE_DEN
20800 59 20 20 20 31 20 20 20 2f 2a 20 41 62 6f 72 74  Y   1   /* Abort
20810 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
20820 6e 74 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72  nt with an error
20830 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
20840 54 45 5f 49 47 4e 4f 52 45 20 32 20 20 20 2f 2a  TE_IGNORE 2   /*
20850 20 44 6f 6e 27 74 20 61 6c 6c 6f 77 20 61 63 63   Don't allow acc
20860 65 73 73 2c 20 62 75 74 20 64 6f 6e 27 74 20 67  ess, but don't g
20870 65 6e 65 72 61 74 65 20 61 6e 20 65 72 72 6f 72  enerate an error
20880 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   */../*.** CAPI3
20890 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20  REF: Authorizer 
208a0 41 63 74 69 6f 6e 20 43 6f 64 65 73 0a 2a 2a 0a  Action Codes.**.
208b0 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** The [sqlite3_
208c0 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29  set_authorizer()
208d0 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69  ] interface regi
208e0 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b  sters a callback
208f0 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74 68 61   function.** tha
20900 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 20  t is invoked to 
20910 61 75 74 68 6f 72 69 7a 65 20 63 65 72 74 61 69  authorize certai
20920 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  n SQL statement 
20930 61 63 74 69 6f 6e 73 2e 20 20 54 68 65 0a 2a 2a  actions.  The.**
20940 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
20950 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63  r to the callbac
20960 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  k is an integer 
20970 63 6f 64 65 20 74 68 61 74 20 73 70 65 63 69 66  code that specif
20980 69 65 73 0a 2a 2a 20 77 68 61 74 20 61 63 74 69  ies.** what acti
20990 6f 6e 20 69 73 20 62 65 69 6e 67 20 61 75 74 68  on is being auth
209a0 6f 72 69 7a 65 64 2e 20 20 54 68 65 73 65 20 61  orized.  These a
209b0 72 65 20 74 68 65 20 69 6e 74 65 67 65 72 20 61  re the integer a
209c0 63 74 69 6f 6e 20 63 6f 64 65 73 20 74 68 61 74  ction codes that
209d0 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a  .** the authoriz
209e0 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 61 79 20  er callback may 
209f0 62 65 20 70 61 73 73 65 64 2e 0a 2a 2a 0a 2a 2a  be passed..**.**
20a00 20 54 68 65 73 65 20 61 63 74 69 6f 6e 20 63 6f   These action co
20a10 64 65 20 76 61 6c 75 65 73 20 73 69 67 6e 69 66  de values signif
20a20 79 20 77 68 61 74 20 6b 69 6e 64 20 6f 66 20 6f  y what kind of o
20a30 70 65 72 61 74 69 6f 6e 20 69 73 20 74 6f 20 62  peration is to b
20a40 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 64 2e  e.** authorized.
20a50 20 20 54 68 65 20 33 72 64 20 61 6e 64 20 34 74    The 3rd and 4t
20a60 68 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20  h parameters to 
20a70 74 68 65 20 61 75 74 68 6f 72 69 7a 61 74 69 6f  the authorizatio
20a80 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75  n.** callback fu
20a90 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 62 65 20 70  nction will be p
20aa0 61 72 61 6d 65 74 65 72 73 20 6f 72 20 4e 55 4c  arameters or NUL
20ab0 4c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 77  L depending on w
20ac0 68 69 63 68 20 6f 66 20 74 68 65 73 65 0a 2a 2a  hich of these.**
20ad0 20 63 6f 64 65 73 20 69 73 20 75 73 65 64 20 61   codes is used a
20ae0 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72  s the second par
20af0 61 6d 65 74 65 72 2e 20 20 5e 28 54 68 65 20 35  ameter.  ^(The 5
20b00 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
20b10 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65  the.** authorize
20b20 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68  r callback is th
20b30 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61  e name of the da
20b40 74 61 62 61 73 65 20 28 22 6d 61 69 6e 22 2c 20  tabase ("main", 
20b50 22 74 65 6d 70 22 2c 0a 2a 2a 20 65 74 63 2e 29  "temp",.** etc.)
20b60 20 69 66 20 61 70 70 6c 69 63 61 62 6c 65 2e 29   if applicable.)
20b70 5e 20 20 5e 54 68 65 20 36 74 68 20 70 61 72 61  ^  ^The 6th para
20b80 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 75 74  meter to the aut
20b90 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
20ba0 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d 65 20  .** is the name 
20bb0 6f 66 20 74 68 65 20 69 6e 6e 65 72 2d 6d 6f 73  of the inner-mos
20bc0 74 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 65  t trigger or vie
20bd0 77 20 74 68 61 74 20 69 73 20 72 65 73 70 6f 6e  w that is respon
20be0 73 69 62 6c 65 20 66 6f 72 0a 2a 2a 20 74 68 65  sible for.** the
20bf0 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 74 20   access attempt 
20c00 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 69 73 20  or NULL if this 
20c10 61 63 63 65 73 73 20 61 74 74 65 6d 70 74 20 69  access attempt i
20c20 73 20 64 69 72 65 63 74 6c 79 20 66 72 6f 6d 0a  s directly from.
20c30 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c 20 53 51 4c  ** top-level SQL
20c40 20 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a   code..*/./*****
20c50 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
20c60 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
20c70 2a 2a 2a 2a 2a 2a 20 33 72 64 20 2a 2a 2a 2a 2a  ****** 3rd *****
20c80 2a 2a 2a 2a 2a 2a 2a 20 34 74 68 20 2a 2a 2a 2a  ******* 4th ****
20c90 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 69 6e 65  *******/.#define
20ca0 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 49   SQLITE_CREATE_I
20cb0 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 31 20  NDEX          1 
20cc0 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20    /* Index Name 
20cd0 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20       Table Name 
20ce0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
20cf0 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 41  SQLITE_CREATE_TA
20d00 42 4c 45 20 20 20 20 20 20 20 20 20 20 32 20 20  BLE          2  
20d10 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
20d20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
20d30 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
20d40 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d  QLITE_CREATE_TEM
20d50 50 5f 49 4e 44 45 58 20 20 20 20 20 33 20 20 20  P_INDEX     3   
20d60 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20  /* Index Name   
20d70 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
20d80 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
20d90 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50  LITE_CREATE_TEMP
20da0 5f 54 41 42 4c 45 20 20 20 20 20 34 20 20 20 2f  _TABLE     4   /
20db0 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
20dc0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
20dd0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
20de0 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f  ITE_CREATE_TEMP_
20df0 54 52 49 47 47 45 52 20 20 20 35 20 20 20 2f 2a  TRIGGER   5   /*
20e00 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20   Trigger Name   
20e10 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
20e20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
20e30 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 56  TE_CREATE_TEMP_V
20e40 49 45 57 20 20 20 20 20 20 36 20 20 20 2f 2a 20  IEW      6   /* 
20e50 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20  View Name       
20e60 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
20e70 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
20e80 45 5f 43 52 45 41 54 45 5f 54 52 49 47 47 45 52  E_CREATE_TRIGGER
20e90 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 54          7   /* T
20ea0 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54  rigger Name    T
20eb0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
20ec0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
20ed0 5f 43 52 45 41 54 45 5f 56 49 45 57 20 20 20 20  _CREATE_VIEW    
20ee0 20 20 20 20 20 20 20 38 20 20 20 2f 2a 20 56 69         8   /* Vi
20ef0 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55  ew Name       NU
20f00 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
20f10 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
20f20 44 45 4c 45 54 45 20 20 20 20 20 20 20 20 20 20  DELETE          
20f30 20 20 20 20 20 20 39 20 20 20 2f 2a 20 54 61 62        9   /* Tab
20f40 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
20f50 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
20f60 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
20f70 52 4f 50 5f 49 4e 44 45 58 20 20 20 20 20 20 20  ROP_INDEX       
20f80 20 20 20 20 31 30 20 20 20 2f 2a 20 49 6e 64 65      10   /* Inde
20f90 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c  x Name      Tabl
20fa0 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
20fb0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
20fc0 4f 50 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20  OP_TABLE        
20fd0 20 20 20 31 31 20 20 20 2f 2a 20 54 61 62 6c 65     11   /* Table
20fe0 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
20ff0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
21000 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
21010 50 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20  P_TEMP_INDEX    
21020 20 20 31 32 20 20 20 2f 2a 20 49 6e 64 65 78 20    12   /* Index 
21030 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20  Name      Table 
21040 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
21050 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
21060 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20  _TEMP_TABLE     
21070 20 31 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   13   /* Table N
21080 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
21090 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
210a0 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
210b0 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20 20  TEMP_TRIGGER    
210c0 31 34 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20  14   /* Trigger 
210d0 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61  Name    Table Na
210e0 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
210f0 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54  ne SQLITE_DROP_T
21100 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20 20 31  EMP_VIEW       1
21110 35 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65  5   /* View Name
21120 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
21130 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
21140 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 52  e SQLITE_DROP_TR
21150 49 47 47 45 52 20 20 20 20 20 20 20 20 20 31 36  IGGER         16
21160 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61     /* Trigger Na
21170 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65  me    Table Name
21180 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
21190 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 49 45   SQLITE_DROP_VIE
211a0 57 20 20 20 20 20 20 20 20 20 20 20 20 31 37 20  W            17 
211b0 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20    /* View Name  
211c0 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
211d0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
211e0 53 51 4c 49 54 45 5f 49 4e 53 45 52 54 20 20 20  SQLITE_INSERT   
211f0 20 20 20 20 20 20 20 20 20 20 20 20 31 38 20 20              18  
21200 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
21210 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
21220 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
21230 51 4c 49 54 45 5f 50 52 41 47 4d 41 20 20 20 20  QLITE_PRAGMA    
21240 20 20 20 20 20 20 20 20 20 20 20 31 39 20 20 20             19   
21250 2f 2a 20 50 72 61 67 6d 61 20 4e 61 6d 65 20 20  /* Pragma Name  
21260 20 20 20 31 73 74 20 61 72 67 20 6f 72 20 4e 55     1st arg or NU
21270 4c 4c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  LL */.#define SQ
21280 4c 49 54 45 5f 52 45 41 44 20 20 20 20 20 20 20  LITE_READ       
21290 20 20 20 20 20 20 20 20 20 20 32 30 20 20 20 2f            20   /
212a0 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
212b0 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20    Column Name   
212c0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
212d0 49 54 45 5f 53 45 4c 45 43 54 20 20 20 20 20 20  ITE_SELECT      
212e0 20 20 20 20 20 20 20 20 20 32 31 20 20 20 2f 2a           21   /*
212f0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
21300 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
21310 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
21320 54 45 5f 54 52 41 4e 53 41 43 54 49 4f 4e 20 20  TE_TRANSACTION  
21330 20 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a 20          22   /* 
21340 4f 70 65 72 61 74 69 6f 6e 20 20 20 20 20 20 20  Operation       
21350 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
21360 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
21370 45 5f 55 50 44 41 54 45 20 20 20 20 20 20 20 20  E_UPDATE        
21380 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20 54         23   /* T
21390 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43  able Name      C
213a0 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a  olumn Name     *
213b0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
213c0 5f 41 54 54 41 43 48 20 20 20 20 20 20 20 20 20  _ATTACH         
213d0 20 20 20 20 20 20 32 34 20 20 20 2f 2a 20 46 69        24   /* Fi
213e0 6c 65 6e 61 6d 65 20 20 20 20 20 20 20 20 4e 55  lename        NU
213f0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
21400 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
21410 44 45 54 41 43 48 20 20 20 20 20 20 20 20 20 20  DETACH          
21420 20 20 20 20 20 32 35 20 20 20 2f 2a 20 44 61 74       25   /* Dat
21430 61 62 61 73 65 20 4e 61 6d 65 20 20 20 4e 55 4c  abase Name   NUL
21440 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
21450 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
21460 4c 54 45 52 5f 54 41 42 4c 45 20 20 20 20 20 20  LTER_TABLE      
21470 20 20 20 20 32 36 20 20 20 2f 2a 20 44 61 74 61      26   /* Data
21480 62 61 73 65 20 4e 61 6d 65 20 20 20 54 61 62 6c  base Name   Tabl
21490 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
214a0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45  define SQLITE_RE
214b0 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 20  INDEX           
214c0 20 20 20 32 37 20 20 20 2f 2a 20 49 6e 64 65 78     27   /* Index
214d0 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
214e0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
214f0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 41  efine SQLITE_ANA
21500 4c 59 5a 45 20 20 20 20 20 20 20 20 20 20 20 20  LYZE            
21510 20 20 32 38 20 20 20 2f 2a 20 54 61 62 6c 65 20    28   /* Table 
21520 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
21530 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
21540 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
21550 54 45 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20  TE_VTABLE       
21560 20 32 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   29   /* Table N
21570 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20  ame      Module 
21580 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66  Name     */.#def
21590 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
215a0 56 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20  VTABLE          
215b0 33 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  30   /* Table Na
215c0 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e  me      Module N
215d0 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  ame     */.#defi
215e0 6e 65 20 53 51 4c 49 54 45 5f 46 55 4e 43 54 49  ne SQLITE_FUNCTI
215f0 4f 4e 20 20 20 20 20 20 20 20 20 20 20 20 20 33  ON             3
21600 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20  1   /* NULL     
21610 20 20 20 20 20 20 20 46 75 6e 63 74 69 6f 6e 20         Function 
21620 4e 61 6d 65 20 20 20 2a 2f 0a 23 64 65 66 69 6e  Name   */.#defin
21630 65 20 53 51 4c 49 54 45 5f 53 41 56 45 50 4f 49  e SQLITE_SAVEPOI
21640 4e 54 20 20 20 20 20 20 20 20 20 20 20 20 33 32  NT            32
21650 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20     /* Operation 
21660 20 20 20 20 20 20 53 61 76 65 70 6f 69 6e 74 20        Savepoint 
21670 4e 61 6d 65 20 20 2a 2f 0a 23 64 65 66 69 6e 65  Name  */.#define
21680 20 53 51 4c 49 54 45 5f 43 4f 50 59 20 20 20 20   SQLITE_COPY    
21690 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 20                0 
216a0 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 75    /* No longer u
216b0 73 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  sed */.#define S
216c0 51 4c 49 54 45 5f 52 45 43 55 52 53 49 56 45 20  QLITE_RECURSIVE 
216d0 20 20 20 20 20 20 20 20 20 20 20 33 33 20 20 20             33   
216e0 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20  /* NULL         
216f0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
21700 20 20 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50     */../*.** CAP
21710 49 33 52 45 46 3a 20 54 72 61 63 69 6e 67 20 41  I3REF: Tracing A
21720 6e 64 20 50 72 6f 66 69 6c 69 6e 67 20 46 75 6e  nd Profiling Fun
21730 63 74 69 6f 6e 73 0a 2a 2a 20 4d 45 54 48 4f 44  ctions.** METHOD
21740 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20  : sqlite3.**.** 
21750 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
21760 72 65 20 64 65 70 72 65 63 61 74 65 64 2e 20 55  re deprecated. U
21770 73 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  se the [sqlite3_
21780 74 72 61 63 65 5f 76 32 28 29 5d 20 69 6e 74 65  trace_v2()] inte
21790 72 66 61 63 65 0a 2a 2a 20 69 6e 73 74 65 61 64  rface.** instead
217a0 20 6f 66 20 74 68 65 20 72 6f 75 74 69 6e 65 73   of the routines
217b0 20 64 65 73 63 72 69 62 65 64 20 68 65 72 65 2e   described here.
217c0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
217d0 74 69 6e 65 73 20 72 65 67 69 73 74 65 72 20 63  tines register c
217e0 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
217f0 73 20 74 68 61 74 20 63 61 6e 20 62 65 20 75 73  s that can be us
21800 65 64 20 66 6f 72 0a 2a 2a 20 74 72 61 63 69 6e  ed for.** tracin
21810 67 20 61 6e 64 20 70 72 6f 66 69 6c 69 6e 67 20  g and profiling 
21820 74 68 65 20 65 78 65 63 75 74 69 6f 6e 20 6f 66  the execution of
21830 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e   SQL statements.
21840 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c  .**.** ^The call
21850 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65  back function re
21860 67 69 73 74 65 72 65 64 20 62 79 20 73 71 6c 69  gistered by sqli
21870 74 65 33 5f 74 72 61 63 65 28 29 20 69 73 20 69  te3_trace() is i
21880 6e 76 6f 6b 65 64 20 61 74 0a 2a 2a 20 76 61 72  nvoked at.** var
21890 69 6f 75 73 20 74 69 6d 65 73 20 77 68 65 6e 20  ious times when 
218a0 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  an SQL statement
218b0 20 69 73 20 62 65 69 6e 67 20 72 75 6e 20 62 79   is being run by
218c0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
218d0 5d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  ]..** ^The sqlit
218e0 65 33 5f 74 72 61 63 65 28 29 20 63 61 6c 6c 62  e3_trace() callb
218f0 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77  ack is invoked w
21900 69 74 68 20 61 20 55 54 46 2d 38 20 72 65 6e 64  ith a UTF-8 rend
21910 65 72 69 6e 67 20 6f 66 20 74 68 65 0a 2a 2a 20  ering of the.** 
21920 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65  SQL statement te
21930 78 74 20 61 73 20 74 68 65 20 73 74 61 74 65 6d  xt as the statem
21940 65 6e 74 20 66 69 72 73 74 20 62 65 67 69 6e 73  ent first begins
21950 20 65 78 65 63 75 74 69 6e 67 2e 0a 2a 2a 20 5e   executing..** ^
21960 28 41 64 64 69 74 69 6f 6e 61 6c 20 73 71 6c 69  (Additional sqli
21970 74 65 33 5f 74 72 61 63 65 28 29 20 63 61 6c 6c  te3_trace() call
21980 62 61 63 6b 73 20 6d 69 67 68 74 20 6f 63 63 75  backs might occu
21990 72 0a 2a 2a 20 61 73 20 65 61 63 68 20 74 72 69  r.** as each tri
219a0 67 67 65 72 65 64 20 73 75 62 70 72 6f 67 72 61  ggered subprogra
219b0 6d 20 69 73 20 65 6e 74 65 72 65 64 2e 20 20 54  m is entered.  T
219c0 68 65 20 63 61 6c 6c 62 61 63 6b 73 20 66 6f 72  he callbacks for
219d0 20 74 72 69 67 67 65 72 73 0a 2a 2a 20 63 6f 6e   triggers.** con
219e0 74 61 69 6e 20 61 20 55 54 46 2d 38 20 53 51 4c  tain a UTF-8 SQL
219f0 20 63 6f 6d 6d 65 6e 74 20 74 68 61 74 20 69 64   comment that id
21a00 65 6e 74 69 66 69 65 73 20 74 68 65 20 74 72 69  entifies the tri
21a10 67 67 65 72 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68  gger.)^.**.** Th
21a20 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5f  e [SQLITE_TRACE_
21a30 53 49 5a 45 5f 4c 49 4d 49 54 5d 20 63 6f 6d 70  SIZE_LIMIT] comp
21a40 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
21a50 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6c  can be used to l
21a60 69 6d 69 74 0a 2a 2a 20 74 68 65 20 6c 65 6e 67  imit.** the leng
21a70 74 68 20 6f 66 20 5b 62 6f 75 6e 64 20 70 61 72  th of [bound par
21a80 61 6d 65 74 65 72 5d 20 65 78 70 61 6e 73 69 6f  ameter] expansio
21a90 6e 20 69 6e 20 74 68 65 20 6f 75 74 70 75 74 20  n in the output 
21aa0 6f 66 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65  of sqlite3_trace
21ab0 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63  ()..**.** ^The c
21ac0 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
21ad0 20 72 65 67 69 73 74 65 72 65 64 20 62 79 20 73   registered by s
21ae0 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29  qlite3_profile()
21af0 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61   is invoked.** a
21b00 73 20 65 61 63 68 20 53 51 4c 20 73 74 61 74 65  s each SQL state
21b10 6d 65 6e 74 20 66 69 6e 69 73 68 65 73 2e 20 20  ment finishes.  
21b20 5e 54 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c  ^The profile cal
21b30 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e 73 0a 2a  lback contains.*
21b40 2a 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73  * the original s
21b50 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 61 6e  tatement text an
21b60 64 20 61 6e 20 65 73 74 69 6d 61 74 65 20 6f 66  d an estimate of
21b70 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d 65   wall-clock time
21b80 0a 2a 2a 20 6f 66 20 68 6f 77 20 6c 6f 6e 67 20  .** of how long 
21b90 74 68 61 74 20 73 74 61 74 65 6d 65 6e 74 20 74  that statement t
21ba0 6f 6f 6b 20 74 6f 20 72 75 6e 2e 20 20 5e 54 68  ook to run.  ^Th
21bb0 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61  e profile callba
21bc0 63 6b 0a 2a 2a 20 74 69 6d 65 20 69 73 20 69 6e  ck.** time is in
21bd0 20 75 6e 69 74 73 20 6f 66 20 6e 61 6e 6f 73 65   units of nanose
21be0 63 6f 6e 64 73 2c 20 68 6f 77 65 76 65 72 20 74  conds, however t
21bf0 68 65 20 63 75 72 72 65 6e 74 20 69 6d 70 6c 65  he current imple
21c00 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 69 73 20  mentation.** is 
21c10 6f 6e 6c 79 20 63 61 70 61 62 6c 65 20 6f 66 20  only capable of 
21c20 6d 69 6c 6c 69 73 65 63 6f 6e 64 20 72 65 73 6f  millisecond reso
21c30 6c 75 74 69 6f 6e 20 73 6f 20 74 68 65 20 73 69  lution so the si
21c40 78 20 6c 65 61 73 74 20 73 69 67 6e 69 66 69 63  x least signific
21c50 61 6e 74 0a 2a 2a 20 64 69 67 69 74 73 20 69 6e  ant.** digits in
21c60 20 74 68 65 20 74 69 6d 65 20 61 72 65 20 6d 65   the time are me
21c70 61 6e 69 6e 67 6c 65 73 73 2e 20 20 46 75 74 75  aningless.  Futu
21c80 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  re versions of S
21c90 51 4c 69 74 65 0a 2a 2a 20 6d 69 67 68 74 20 70  QLite.** might p
21ca0 72 6f 76 69 64 65 20 67 72 65 61 74 65 72 20 72  rovide greater r
21cb0 65 73 6f 6c 75 74 69 6f 6e 20 6f 6e 20 74 68 65  esolution on the
21cc0 20 70 72 6f 66 69 6c 65 72 20 63 61 6c 6c 62 61   profiler callba
21cd0 63 6b 2e 20 20 54 68 65 0a 2a 2a 20 73 71 6c 69  ck.  The.** sqli
21ce0 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 20 66 75  te3_profile() fu
21cf0 6e 63 74 69 6f 6e 20 69 73 20 63 6f 6e 73 69 64  nction is consid
21d00 65 72 65 64 20 65 78 70 65 72 69 6d 65 6e 74 61  ered experimenta
21d10 6c 20 61 6e 64 20 69 73 0a 2a 2a 20 73 75 62 6a  l and is.** subj
21d20 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 69 6e  ect to change in
21d30 20 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73   future versions
21d40 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 53   of SQLite..*/.S
21d50 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44  QLITE_DEPRECATED
21d60 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 74   void *sqlite3_t
21d70 72 61 63 65 28 73 71 6c 69 74 65 33 2a 2c 0a 20  race(sqlite3*,. 
21d80 20 20 76 6f 69 64 28 2a 78 54 72 61 63 65 29 28    void(*xTrace)(
21d90 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72  void*,const char
21da0 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 53 51 4c 49  *), void*);.SQLI
21db0 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 76 6f  TE_DEPRECATED vo
21dc0 69 64 20 2a 73 71 6c 69 74 65 33 5f 70 72 6f 66  id *sqlite3_prof
21dd0 69 6c 65 28 73 71 6c 69 74 65 33 2a 2c 0a 20 20  ile(sqlite3*,.  
21de0 20 76 6f 69 64 28 2a 78 50 72 6f 66 69 6c 65 29   void(*xProfile)
21df0 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61  (void*,const cha
21e00 72 2a 2c 73 71 6c 69 74 65 33 5f 75 69 6e 74 36  r*,sqlite3_uint6
21e10 34 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a  4), void*);../*.
21e20 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c  ** CAPI3REF: SQL
21e30 20 54 72 61 63 65 20 45 76 65 6e 74 20 43 6f 64   Trace Event Cod
21e40 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  es.** KEYWORDS: 
21e50 53 51 4c 49 54 45 5f 54 52 41 43 45 0a 2a 2a 0a  SQLITE_TRACE.**.
21e60 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e  ** These constan
21e70 74 73 20 69 64 65 6e 74 69 66 79 20 63 6c 61 73  ts identify clas
21e80 73 65 73 20 6f 66 20 65 76 65 6e 74 73 20 74 68  ses of events th
21e90 61 74 20 63 61 6e 20 62 65 20 6d 6f 6e 69 74 6f  at can be monito
21ea0 72 65 64 0a 2a 2a 20 75 73 69 6e 67 20 74 68 65  red.** using the
21eb0 20 5b 73 71 6c 69 74 65 33 5f 74 72 61 63 65 5f   [sqlite3_trace_
21ec0 76 32 28 29 5d 20 74 72 61 63 69 6e 67 20 6c 6f  v2()] tracing lo
21ed0 67 69 63 2e 20 20 54 68 65 20 74 68 69 72 64 20  gic.  The third 
21ee0 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 5b  argument.** to [
21ef0 73 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 32  sqlite3_trace_v2
21f00 28 29 5d 20 69 73 20 61 6e 20 4f 52 2d 65 64 20  ()] is an OR-ed 
21f10 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 20 6f  combination of o
21f20 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66 0a 2a 2a  ne or more of.**
21f30 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63   the following c
21f40 6f 6e 73 74 61 6e 74 73 2e 20 20 5e 54 68 65 20  onstants.  ^The 
21f50 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
21f60 6f 20 74 68 65 20 74 72 61 63 65 20 63 61 6c 6c  o the trace call
21f70 62 61 63 6b 0a 2a 2a 20 69 73 20 6f 6e 65 20 6f  back.** is one o
21f80 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  f the following 
21f90 63 6f 6e 73 74 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a  constants..**.**
21fa0 20 4e 65 77 20 74 72 61 63 69 6e 67 20 63 6f 6e   New tracing con
21fb0 73 74 61 6e 74 73 20 6d 61 79 20 62 65 20 61 64  stants may be ad
21fc0 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65  ded in future re
21fd0 6c 65 61 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41  leases..**.** ^A
21fe0 20 74 72 61 63 65 20 63 61 6c 6c 62 61 63 6b 20   trace callback 
21ff0 68 61 73 20 66 6f 75 72 20 61 72 67 75 6d 65 6e  has four argumen
22000 74 73 3a 20 78 43 61 6c 6c 62 61 63 6b 28 54 2c  ts: xCallback(T,
22010 43 2c 50 2c 58 29 2e 0a 2a 2a 20 5e 54 68 65 20  C,P,X)..** ^The 
22020 54 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e  T argument is on
22030 65 20 6f 66 20 74 68 65 20 69 6e 74 65 67 65 72  e of the integer
22040 20 74 79 70 65 20 63 6f 64 65 73 20 61 62 6f 76   type codes abov
22050 65 2e 0a 2a 2a 20 5e 54 68 65 20 43 20 61 72 67  e..** ^The C arg
22060 75 6d 65 6e 74 20 69 73 20 61 20 63 6f 70 79 20  ument is a copy 
22070 6f 66 20 74 68 65 20 63 6f 6e 74 65 78 74 20 70  of the context p
22080 6f 69 6e 74 65 72 20 70 61 73 73 65 64 20 69 6e  ointer passed in
22090 20 61 73 20 74 68 65 0a 2a 2a 20 66 6f 75 72 74   as the.** fourt
220a0 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73  h argument to [s
220b0 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28  qlite3_trace_v2(
220c0 29 5d 2e 0a 2a 2a 20 54 68 65 20 50 20 61 6e 64  )]..** The P and
220d0 20 58 20 61 72 67 75 6d 65 6e 74 73 20 61 72 65   X arguments are
220e0 20 70 6f 69 6e 74 65 72 73 20 77 68 6f 73 65 20   pointers whose 
220f0 6d 65 61 6e 69 6e 67 73 20 64 65 70 65 6e 64 20  meanings depend 
22100 6f 6e 20 54 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e  on T..**.** <dl>
22110 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 54 52 41  .** [[SQLITE_TRA
22120 43 45 5f 53 54 4d 54 5d 5d 20 3c 64 74 3e 53 51  CE_STMT]] <dt>SQ
22130 4c 49 54 45 5f 54 52 41 43 45 5f 53 54 4d 54 3c  LITE_TRACE_STMT<
22140 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 5e 41 6e 20  /dt>.** <dd>^An 
22150 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 53 54 4d  SQLITE_TRACE_STM
22160 54 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  T callback is in
22170 76 6f 6b 65 64 20 77 68 65 6e 20 61 20 70 72 65  voked when a pre
22180 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a  pared statement.
22190 2a 2a 20 66 69 72 73 74 20 62 65 67 69 6e 73 20  ** first begins 
221a0 72 75 6e 6e 69 6e 67 20 61 6e 64 20 70 6f 73 73  running and poss
221b0 69 62 6c 79 20 61 74 20 6f 74 68 65 72 20 74 69  ibly at other ti
221c0 6d 65 73 20 64 75 72 69 6e 67 20 74 68 65 0a 2a  mes during the.*
221d0 2a 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 74  * execution of t
221e0 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74  he prepared stat
221f0 65 6d 65 6e 74 2c 20 73 75 63 68 20 61 73 20 61  ement, such as a
22200 74 20 74 68 65 20 73 74 61 72 74 20 6f 66 20 65  t the start of e
22210 61 63 68 0a 2a 2a 20 74 72 69 67 67 65 72 20 73  ach.** trigger s
22220 75 62 70 72 6f 67 72 61 6d 2e 20 5e 54 68 65 20  ubprogram. ^The 
22230 50 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20  P argument is a 
22240 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a  pointer to the.*
22250 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  * [prepared stat
22260 65 6d 65 6e 74 5d 2e 20 5e 54 68 65 20 58 20 61  ement]. ^The X a
22270 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69  rgument is a poi
22280 6e 74 65 72 20 74 6f 20 61 20 73 74 72 69 6e 67  nter to a string
22290 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 74 68 65   which.** is the
222a0 20 65 78 70 61 6e 64 65 64 20 53 51 4c 20 74 65   expanded SQL te
222b0 78 74 20 6f 66 20 74 68 65 20 70 72 65 70 61 72  xt of the prepar
222c0 65 64 20 73 74 61 74 65 6d 65 6e 74 20 6f 72 20  ed statement or 
222d0 61 20 63 6f 6d 6d 65 6e 74 20 74 68 61 74 0a 2a  a comment that.*
222e0 2a 20 69 6e 64 69 63 61 74 65 73 20 74 68 65 20  * indicates the 
222f0 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 61 20  invocation of a 
22300 74 72 69 67 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 5b  trigger..**.** [
22310 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 50 52  [SQLITE_TRACE_PR
22320 4f 46 49 4c 45 5d 5d 20 3c 64 74 3e 53 51 4c 49  OFILE]] <dt>SQLI
22330 54 45 5f 54 52 41 43 45 5f 50 52 4f 46 49 4c 45  TE_TRACE_PROFILE
22340 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 5e 41 6e  </dt>.** <dd>^An
22350 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 50 52   SQLITE_TRACE_PR
22360 4f 46 49 4c 45 20 63 61 6c 6c 62 61 63 6b 20 70  OFILE callback p
22370 72 6f 76 69 64 65 73 20 61 70 70 72 6f 78 69 6d  rovides approxim
22380 61 74 65 6c 79 20 74 68 65 20 73 61 6d 65 0a 2a  ately the same.*
22390 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 73  * information as
223a0 20 69 73 20 70 72 6f 76 69 64 65 64 20 62 79 20   is provided by 
223b0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 6f  the [sqlite3_pro
223c0 66 69 6c 65 28 29 5d 20 63 61 6c 6c 62 61 63 6b  file()] callback
223d0 2e 0a 2a 2a 20 5e 54 68 65 20 50 20 61 72 67 75  ..** ^The P argu
223e0 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65  ment is a pointe
223f0 72 20 74 6f 20 74 68 65 20 5b 70 72 65 70 61 72  r to the [prepar
22400 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 6e  ed statement] an
22410 64 20 74 68 65 0a 2a 2a 20 5e 58 20 61 72 67 75  d the.** ^X argu
22420 6d 65 6e 74 20 70 6f 69 6e 74 73 20 74 6f 20 61  ment points to a
22430 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72 20   64-bit integer 
22440 77 68 69 63 68 20 69 73 20 74 68 65 20 65 73 74  which is the est
22450 69 6d 61 74 65 64 20 6f 66 0a 2a 2a 20 74 68 65  imated of.** the
22460 20 6e 75 6d 62 65 72 20 6f 66 20 6e 61 6e 6f 73   number of nanos
22470 65 63 6f 6e 64 20 74 68 61 74 20 74 68 65 20 70  econd that the p
22480 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
22490 74 20 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e 0a 2a  t took to run..*
224a0 2a 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 54 52  * ^The SQLITE_TR
224b0 41 43 45 5f 50 52 4f 46 49 4c 45 20 63 61 6c 6c  ACE_PROFILE call
224c0 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20  back is invoked 
224d0 77 68 65 6e 20 74 68 65 20 73 74 61 74 65 6d 65  when the stateme
224e0 6e 74 20 66 69 6e 69 73 68 65 73 2e 0a 2a 2a 0a  nt finishes..**.
224f0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 54 52 41 43  ** [[SQLITE_TRAC
22500 45 5f 52 4f 57 5d 5d 20 3c 64 74 3e 53 51 4c 49  E_ROW]] <dt>SQLI
22510 54 45 5f 54 52 41 43 45 5f 52 4f 57 3c 2f 64 74  TE_TRACE_ROW</dt
22520 3e 0a 2a 2a 20 3c 64 64 3e 5e 41 6e 20 53 51 4c  >.** <dd>^An SQL
22530 49 54 45 5f 54 52 41 43 45 5f 52 4f 57 20 63 61  ITE_TRACE_ROW ca
22540 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
22550 64 20 77 68 65 6e 65 76 65 72 20 61 20 70 72 65  d whenever a pre
22560 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65  pared.** stateme
22570 6e 74 20 67 65 6e 65 72 61 74 65 73 20 61 20 73  nt generates a s
22580 69 6e 67 6c 65 20 72 6f 77 20 6f 66 20 72 65 73  ingle row of res
22590 75 6c 74 2e 20 20 0a 2a 2a 20 5e 54 68 65 20 50  ult.  .** ^The P
225a0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70   argument is a p
225b0 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 70  ointer to the [p
225c0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
225d0 74 5d 20 61 6e 64 20 74 68 65 0a 2a 2a 20 58 20  t] and the.** X 
225e0 61 72 67 75 6d 65 6e 74 20 69 73 20 75 6e 75 73  argument is unus
225f0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  ed..**.** [[SQLI
22600 54 45 5f 54 52 41 43 45 5f 43 4c 4f 53 45 5d 5d  TE_TRACE_CLOSE]]
22610 20 3c 64 74 3e 53 51 4c 49 54 45 5f 54 52 41 43   <dt>SQLITE_TRAC
22620 45 5f 43 4c 4f 53 45 3c 2f 64 74 3e 0a 2a 2a 20  E_CLOSE</dt>.** 
22630 3c 64 64 3e 5e 41 6e 20 53 51 4c 49 54 45 5f 54  <dd>^An SQLITE_T
22640 52 41 43 45 5f 43 4c 4f 53 45 20 63 61 6c 6c 62  RACE_CLOSE callb
22650 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77  ack is invoked w
22660 68 65 6e 20 61 20 64 61 74 61 62 61 73 65 0a 2a  hen a database.*
22670 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f  * connection clo
22680 73 65 73 2e 0a 2a 2a 20 5e 54 68 65 20 50 20 61  ses..** ^The P a
22690 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69  rgument is a poi
226a0 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 64 61 74  nter to the [dat
226b0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
226c0 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 61 6e 64 20  ] object.** and 
226d0 74 68 65 20 58 20 61 72 67 75 6d 65 6e 74 20 69  the X argument i
226e0 73 20 75 6e 75 73 65 64 2e 0a 2a 2a 20 3c 2f 64  s unused..** </d
226f0 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  l>.*/.#define SQ
22700 4c 49 54 45 5f 54 52 41 43 45 5f 53 54 4d 54 20  LITE_TRACE_STMT 
22710 20 20 20 20 20 20 30 78 30 31 0a 23 64 65 66 69        0x01.#defi
22720 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f  ne SQLITE_TRACE_
22730 50 52 4f 46 49 4c 45 20 20 20 20 30 78 30 32 0a  PROFILE    0x02.
22740 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54  #define SQLITE_T
22750 52 41 43 45 5f 52 4f 57 20 20 20 20 20 20 20 20  RACE_ROW        
22760 30 78 30 34 0a 23 64 65 66 69 6e 65 20 53 51 4c  0x04.#define SQL
22770 49 54 45 5f 54 52 41 43 45 5f 43 4c 4f 53 45 20  ITE_TRACE_CLOSE 
22780 20 20 20 20 20 30 78 30 38 0a 0a 2f 2a 0a 2a 2a       0x08../*.**
22790 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20 54   CAPI3REF: SQL T
227a0 72 61 63 65 20 48 6f 6f 6b 0a 2a 2a 20 4d 45 54  race Hook.** MET
227b0 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a  HOD: sqlite3.**.
227c0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
227d0 74 72 61 63 65 5f 76 32 28 44 2c 4d 2c 58 2c 50  trace_v2(D,M,X,P
227e0 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69  ) interface regi
227f0 73 74 65 72 73 20 61 20 74 72 61 63 65 20 63 61  sters a trace ca
22800 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69  llback.** functi
22810 6f 6e 20 58 20 61 67 61 69 6e 73 74 20 5b 64 61  on X against [da
22820 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
22830 6e 5d 20 44 2c 20 75 73 69 6e 67 20 70 72 6f 70  n] D, using prop
22840 65 72 74 79 20 6d 61 73 6b 20 4d 0a 2a 2a 20 61  erty mask M.** a
22850 6e 64 20 63 6f 6e 74 65 78 74 20 70 6f 69 6e 74  nd context point
22860 65 72 20 50 2e 20 20 5e 49 66 20 74 68 65 20 58  er P.  ^If the X
22870 20 63 61 6c 6c 62 61 63 6b 20 69 73 0a 2a 2a 20   callback is.** 
22880 4e 55 4c 4c 20 6f 72 20 69 66 20 74 68 65 20 4d  NULL or if the M
22890 20 6d 61 73 6b 20 69 73 20 7a 65 72 6f 2c 20 74   mask is zero, t
228a0 68 65 6e 20 74 72 61 63 69 6e 67 20 69 73 20 64  hen tracing is d
228b0 69 73 61 62 6c 65 64 2e 20 20 54 68 65 0a 2a 2a  isabled.  The.**
228c0 20 4d 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74   M argument must
228d0 20 62 65 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20   be one or more 
228e0 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54  of the [SQLITE_T
228f0 52 41 43 45 5d 0a 2a 2a 20 63 6f 6e 73 74 61 6e  RACE].** constan
22900 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 45 61 63 68 20  ts..**.** ^Each 
22910 63 61 6c 6c 20 74 6f 20 65 69 74 68 65 72 20 73  call to either s
22920 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 6f  qlite3_trace() o
22930 72 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 5f  r sqlite3_trace_
22940 76 32 28 29 20 6f 76 65 72 72 69 64 65 73 20 0a  v2() overrides .
22950 2a 2a 20 28 63 61 6e 63 65 6c 73 29 20 61 6e 79  ** (cancels) any
22960 20 70 72 69 6f 72 20 63 61 6c 6c 73 20 74 6f 20   prior calls to 
22970 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20  sqlite3_trace() 
22980 6f 72 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65  or sqlite3_trace
22990 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  _v2()..**.** ^Th
229a0 65 20 58 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  e X callback is 
229b0 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72  invoked whenever
229c0 20 61 6e 79 20 6f 66 20 74 68 65 20 65 76 65 6e   any of the even
229d0 74 73 20 69 64 65 6e 74 69 66 69 65 64 20 62 79  ts identified by
229e0 20 0a 2a 2a 20 6d 61 73 6b 20 4d 20 6f 63 63 75   .** mask M occu
229f0 72 2e 20 20 5e 54 68 65 20 69 6e 74 65 67 65 72  r.  ^The integer
22a00 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72   return value fr
22a10 6f 6d 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  om the callback 
22a20 69 73 20 63 75 72 72 65 6e 74 6c 79 0a 2a 2a 20  is currently.** 
22a30 69 67 6e 6f 72 65 64 2c 20 74 68 6f 75 67 68 20  ignored, though 
22a40 74 68 69 73 20 6d 61 79 20 63 68 61 6e 67 65 20  this may change 
22a50 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  in future releas
22a60 65 73 2e 20 20 43 61 6c 6c 62 61 63 6b 0a 2a 2a  es.  Callback.**
22a70 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
22a80 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 7a   should return z
22a90 65 72 6f 20 74 6f 20 65 6e 73 75 72 65 20 66 75  ero to ensure fu
22aa0 74 75 72 65 20 63 6f 6d 70 61 74 69 62 69 6c 69  ture compatibili
22ab0 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 74 72 61  ty..**.** ^A tra
22ac0 63 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  ce callback is i
22ad0 6e 76 6f 6b 65 64 20 77 69 74 68 20 66 6f 75 72  nvoked with four
22ae0 20 61 72 67 75 6d 65 6e 74 73 3a 20 63 61 6c 6c   arguments: call
22af0 62 61 63 6b 28 54 2c 43 2c 50 2c 58 29 2e 0a 2a  back(T,C,P,X)..*
22b00 2a 20 5e 54 68 65 20 54 20 61 72 67 75 6d 65 6e  * ^The T argumen
22b10 74 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 20  t is one of the 
22b20 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5d 0a 2a  [SQLITE_TRACE].*
22b30 2a 20 63 6f 6e 73 74 61 6e 74 73 20 74 6f 20 69  * constants to i
22b40 6e 64 69 63 61 74 65 20 77 68 79 20 74 68 65 20  ndicate why the 
22b50 63 61 6c 6c 62 61 63 6b 20 77 61 73 20 69 6e 76  callback was inv
22b60 6f 6b 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 43 20  oked..** ^The C 
22b70 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 63 6f  argument is a co
22b80 70 79 20 6f 66 20 74 68 65 20 63 6f 6e 74 65 78  py of the contex
22b90 74 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 20 54 68  t pointer..** Th
22ba0 65 20 50 20 61 6e 64 20 58 20 61 72 67 75 6d 65  e P and X argume
22bb0 6e 74 73 20 61 72 65 20 70 6f 69 6e 74 65 72 73  nts are pointers
22bc0 20 77 68 6f 73 65 20 6d 65 61 6e 69 6e 67 73 20   whose meanings 
22bd0 64 65 70 65 6e 64 20 6f 6e 20 54 2e 0a 2a 2a 0a  depend on T..**.
22be0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 74  ** The sqlite3_t
22bf0 72 61 63 65 5f 76 32 28 29 20 69 6e 74 65 72 66  race_v2() interf
22c00 61 63 65 20 69 73 20 69 6e 74 65 6e 64 65 64 20  ace is intended 
22c10 74 6f 20 72 65 70 6c 61 63 65 20 74 68 65 20 6c  to replace the l
22c20 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61  egacy.** interfa
22c30 63 65 73 20 5b 73 71 6c 69 74 65 33 5f 74 72 61  ces [sqlite3_tra
22c40 63 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  ce()] and [sqlit
22c50 65 33 5f 70 72 6f 66 69 6c 65 28 29 5d 2c 20 62  e3_profile()], b
22c60 6f 74 68 20 6f 66 20 77 68 69 63 68 0a 2a 2a 20  oth of which.** 
22c70 61 72 65 20 64 65 70 72 65 63 61 74 65 64 2e 0a  are deprecated..
22c80 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 74  */.int sqlite3_t
22c90 72 61 63 65 5f 76 32 28 0a 20 20 73 71 6c 69 74  race_v2(.  sqlit
22ca0 65 33 2a 2c 0a 20 20 75 6e 73 69 67 6e 65 64 20  e3*,.  unsigned 
22cb0 75 4d 61 73 6b 2c 0a 20 20 69 6e 74 28 2a 78 43  uMask,.  int(*xC
22cc0 61 6c 6c 62 61 63 6b 29 28 75 6e 73 69 67 6e 65  allback)(unsigne
22cd0 64 2c 76 6f 69 64 2a 2c 76 6f 69 64 2a 2c 76 6f  d,void*,void*,vo
22ce0 69 64 2a 29 2c 0a 20 20 76 6f 69 64 20 2a 70 43  id*),.  void *pC
22cf0 74 78 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tx.);../*.** CAP
22d00 49 33 52 45 46 3a 20 51 75 65 72 79 20 50 72 6f  I3REF: Query Pro
22d10 67 72 65 73 73 20 43 61 6c 6c 62 61 63 6b 73 0a  gress Callbacks.
22d20 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
22d30 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  e3.**.** ^The sq
22d40 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68  lite3_progress_h
22d50 61 6e 64 6c 65 72 28 44 2c 4e 2c 58 2c 50 29 20  andler(D,N,X,P) 
22d60 69 6e 74 65 72 66 61 63 65 20 63 61 75 73 65 73  interface causes
22d70 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a   the callback.**
22d80 20 66 75 6e 63 74 69 6f 6e 20 58 20 74 6f 20 62   function X to b
22d90 65 20 69 6e 76 6f 6b 65 64 20 70 65 72 69 6f 64  e invoked period
22da0 69 63 61 6c 6c 79 20 64 75 72 69 6e 67 20 6c 6f  ically during lo
22db0 6e 67 20 72 75 6e 6e 69 6e 67 20 63 61 6c 6c 73  ng running calls
22dc0 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
22dd0 65 78 65 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65  exec()], [sqlite
22de0 33 5f 73 74 65 70 28 29 5d 20 61 6e 64 20 5b 73  3_step()] and [s
22df0 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
22e00 28 29 5d 20 66 6f 72 0a 2a 2a 20 64 61 74 61 62  ()] for.** datab
22e10 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44  ase connection D
22e20 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 75 73  .  An example us
22e30 65 20 66 6f 72 20 74 68 69 73 0a 2a 2a 20 69 6e  e for this.** in
22e40 74 65 72 66 61 63 65 20 69 73 20 74 6f 20 6b 65  terface is to ke
22e50 65 70 20 61 20 47 55 49 20 75 70 64 61 74 65 64  ep a GUI updated
22e60 20 64 75 72 69 6e 67 20 61 20 6c 61 72 67 65 20   during a large 
22e70 71 75 65 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  query..**.** ^Th
22e80 65 20 70 61 72 61 6d 65 74 65 72 20 50 20 69 73  e parameter P is
22e90 20 70 61 73 73 65 64 20 74 68 72 6f 75 67 68 20   passed through 
22ea0 61 73 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 61  as the only para
22eb0 6d 65 74 65 72 20 74 6f 20 74 68 65 20 0a 2a 2a  meter to the .**
22ec0 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
22ed0 6f 6e 20 58 2e 20 20 5e 54 68 65 20 70 61 72 61  on X.  ^The para
22ee0 6d 65 74 65 72 20 4e 20 69 73 20 74 68 65 20 61  meter N is the a
22ef0 70 70 72 6f 78 69 6d 61 74 65 20 6e 75 6d 62 65  pproximate numbe
22f00 72 20 6f 66 20 0a 2a 2a 20 5b 76 69 72 74 75 61  r of .** [virtua
22f10 6c 20 6d 61 63 68 69 6e 65 20 69 6e 73 74 72 75  l machine instru
22f20 63 74 69 6f 6e 73 5d 20 74 68 61 74 20 61 72 65  ctions] that are
22f30 20 65 76 61 6c 75 61 74 65 64 20 62 65 74 77 65   evaluated betwe
22f40 65 6e 20 73 75 63 63 65 73 73 69 76 65 0a 2a 2a  en successive.**
22f50 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20   invocations of 
22f60 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 58 2e 20  the callback X. 
22f70 20 5e 49 66 20 4e 20 69 73 20 6c 65 73 73 20 74   ^If N is less t
22f80 68 61 6e 20 6f 6e 65 20 74 68 65 6e 20 74 68 65  han one then the
22f90 20 70 72 6f 67 72 65 73 73 0a 2a 2a 20 68 61 6e   progress.** han
22fa0 64 6c 65 72 20 69 73 20 64 69 73 61 62 6c 65 64  dler is disabled
22fb0 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 61 20  ..**.** ^Only a 
22fc0 73 69 6e 67 6c 65 20 70 72 6f 67 72 65 73 73 20  single progress 
22fd0 68 61 6e 64 6c 65 72 20 6d 61 79 20 62 65 20 64  handler may be d
22fe0 65 66 69 6e 65 64 20 61 74 20 6f 6e 65 20 74 69  efined at one ti
22ff0 6d 65 20 70 65 72 0a 2a 2a 20 5b 64 61 74 61 62  me per.** [datab
23000 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 3b  ase connection];
23010 20 73 65 74 74 69 6e 67 20 61 20 6e 65 77 20 70   setting a new p
23020 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20  rogress handler 
23030 63 61 6e 63 65 6c 73 20 74 68 65 0a 2a 2a 20 6f  cancels the.** o
23040 6c 64 20 6f 6e 65 2e 20 20 5e 53 65 74 74 69 6e  ld one.  ^Settin
23050 67 20 70 61 72 61 6d 65 74 65 72 20 58 20 74 6f  g parameter X to
23060 20 4e 55 4c 4c 20 64 69 73 61 62 6c 65 73 20 74   NULL disables t
23070 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64  he progress hand
23080 6c 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 70 72 6f  ler..** ^The pro
23090 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 69 73  gress handler is
230a0 20 61 6c 73 6f 20 64 69 73 61 62 6c 65 64 20 62   also disabled b
230b0 79 20 73 65 74 74 69 6e 67 20 4e 20 74 6f 20 61  y setting N to a
230c0 20 76 61 6c 75 65 20 6c 65 73 73 0a 2a 2a 20 74   value less.** t
230d0 68 61 6e 20 31 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  han 1..**.** ^If
230e0 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 63 61   the progress ca
230f0 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e  llback returns n
23100 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 6f 70 65  on-zero, the ope
23110 72 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 69 6e 74  ration is.** int
23120 65 72 72 75 70 74 65 64 2e 20 20 54 68 69 73 20  errupted.  This 
23130 66 65 61 74 75 72 65 20 63 61 6e 20 62 65 20 75  feature can be u
23140 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74  sed to implement
23150 20 61 0a 2a 2a 20 22 43 61 6e 63 65 6c 22 20 62   a.** "Cancel" b
23160 75 74 74 6f 6e 20 6f 6e 20 61 20 47 55 49 20 70  utton on a GUI p
23170 72 6f 67 72 65 73 73 20 64 69 61 6c 6f 67 20 62  rogress dialog b
23180 6f 78 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72  ox..**.** The pr
23190 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 63  ogress handler c
231a0 61 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74  allback must not
231b0 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61   do anything tha
231c0 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a  t will modify.**
231d0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
231e0 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e  nnection that in
231f0 76 6f 6b 65 64 20 74 68 65 20 70 72 6f 67 72 65  voked the progre
23200 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 4e  ss handler..** N
23210 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65  ote that [sqlite
23220 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
23230 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  and [sqlite3_ste
23240 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79  p()] both modify
23250 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61   their.** databa
23260 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66  se connections f
23270 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f  or the meaning o
23280 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68  f "modify" in th
23290 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a  is paragraph..**
232a0 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  .*/.void sqlite3
232b0 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65  _progress_handle
232c0 72 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 2c  r(sqlite3*, int,
232d0 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20   int(*)(void*), 
232e0 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  void*);../*.** C
232f0 41 50 49 33 52 45 46 3a 20 4f 70 65 6e 69 6e 67  API3REF: Opening
23300 20 41 20 4e 65 77 20 44 61 74 61 62 61 73 65 20   A New Database 
23310 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 43 4f  Connection.** CO
23320 4e 53 54 52 55 43 54 4f 52 3a 20 73 71 6c 69 74  NSTRUCTOR: sqlit
23330 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  e3.**.** ^These 
23340 72 6f 75 74 69 6e 65 73 20 6f 70 65 6e 20 61 6e  routines open an
23350 20 53 51 4c 69 74 65 20 64 61 74 61 62 61 73 65   SQLite database
23360 20 66 69 6c 65 20 61 73 20 73 70 65 63 69 66 69   file as specifi
23370 65 64 20 62 79 20 74 68 65 20 0a 2a 2a 20 66 69  ed by the .** fi
23380 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 2e  lename argument.
23390 20 5e 54 68 65 20 66 69 6c 65 6e 61 6d 65 20 61   ^The filename a
233a0 72 67 75 6d 65 6e 74 20 69 73 20 69 6e 74 65 72  rgument is inter
233b0 70 72 65 74 65 64 20 61 73 20 55 54 46 2d 38 20  preted as UTF-8 
233c0 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f  for.** sqlite3_o
233d0 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65  pen() and sqlite
233e0 33 5f 6f 70 65 6e 5f 76 32 28 29 20 61 6e 64 20  3_open_v2() and 
233f0 61 73 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65  as UTF-16 in the
23400 20 6e 61 74 69 76 65 20 62 79 74 65 0a 2a 2a 20   native byte.** 
23410 6f 72 64 65 72 20 66 6f 72 20 73 71 6c 69 74 65  order for sqlite
23420 33 5f 6f 70 65 6e 31 36 28 29 2e 20 5e 28 41 20  3_open16(). ^(A 
23430 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
23440 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 69 73 20  tion] handle is 
23450 75 73 75 61 6c 6c 79 0a 2a 2a 20 72 65 74 75 72  usually.** retur
23460 6e 65 64 20 69 6e 20 2a 70 70 44 62 2c 20 65 76  ned in *ppDb, ev
23470 65 6e 20 69 66 20 61 6e 20 65 72 72 6f 72 20 6f  en if an error o
23480 63 63 75 72 73 2e 20 20 54 68 65 20 6f 6e 6c 79  ccurs.  The only
23490 20 65 78 63 65 70 74 69 6f 6e 20 69 73 20 74 68   exception is th
234a0 61 74 0a 2a 2a 20 69 66 20 53 51 4c 69 74 65 20  at.** if SQLite 
234b0 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c  is unable to all
234c0 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20  ocate memory to 
234d0 68 6f 6c 64 20 74 68 65 20 5b 73 71 6c 69 74 65  hold the [sqlite
234e0 33 5d 20 6f 62 6a 65 63 74 2c 0a 2a 2a 20 61 20  3] object,.** a 
234f0 4e 55 4c 4c 20 77 69 6c 6c 20 62 65 20 77 72 69  NULL will be wri
23500 74 74 65 6e 20 69 6e 74 6f 20 2a 70 70 44 62 20  tten into *ppDb 
23510 69 6e 73 74 65 61 64 20 6f 66 20 61 20 70 6f 69  instead of a poi
23520 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c  nter to the [sql
23530 69 74 65 33 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2e  ite3].** object.
23540 29 5e 20 5e 28 49 66 20 74 68 65 20 64 61 74 61  )^ ^(If the data
23550 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 28  base is opened (
23560 61 6e 64 2f 6f 72 20 63 72 65 61 74 65 64 29 20  and/or created) 
23570 73 75 63 63 65 73 73 66 75 6c 6c 79 2c 20 74 68  successfully, th
23580 65 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b  en.** [SQLITE_OK
23590 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20  ] is returned.  
235a0 4f 74 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72  Otherwise an [er
235b0 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74  ror code] is ret
235c0 75 72 6e 65 64 2e 29 5e 20 5e 54 68 65 0a 2a 2a  urned.)^ ^The.**
235d0 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
235e0 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
235f0 65 72 72 6d 73 67 31 36 28 29 5d 20 72 6f 75 74  errmsg16()] rout
23600 69 6e 65 73 20 63 61 6e 20 62 65 20 75 73 65 64  ines can be used
23610 20 74 6f 20 6f 62 74 61 69 6e 0a 2a 2a 20 61 6e   to obtain.** an
23620 20 45 6e 67 6c 69 73 68 20 6c 61 6e 67 75 61 67   English languag
23630 65 20 64 65 73 63 72 69 70 74 69 6f 6e 20 6f 66  e description of
23640 20 74 68 65 20 65 72 72 6f 72 20 66 6f 6c 6c 6f   the error follo
23650 77 69 6e 67 20 61 20 66 61 69 6c 75 72 65 20 6f  wing a failure o
23660 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 20  f any.** of the 
23670 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 72  sqlite3_open() r
23680 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e  outines..**.** ^
23690 54 68 65 20 64 65 66 61 75 6c 74 20 65 6e 63 6f  The default enco
236a0 64 69 6e 67 20 77 69 6c 6c 20 62 65 20 55 54 46  ding will be UTF
236b0 2d 38 20 66 6f 72 20 64 61 74 61 62 61 73 65 73  -8 for databases
236c0 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 0a 2a   created using.*
236d0 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  * sqlite3_open()
236e0 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   or sqlite3_open
236f0 5f 76 32 28 29 2e 20 20 5e 54 68 65 20 64 65 66  _v2().  ^The def
23700 61 75 6c 74 20 65 6e 63 6f 64 69 6e 67 20 66 6f  ault encoding fo
23710 72 20 64 61 74 61 62 61 73 65 73 0a 2a 2a 20 63  r databases.** c
23720 72 65 61 74 65 64 20 75 73 69 6e 67 20 73 71 6c  reated using sql
23730 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 20 77 69  ite3_open16() wi
23740 6c 6c 20 62 65 20 55 54 46 2d 31 36 20 69 6e 20  ll be UTF-16 in 
23750 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 20  the native byte 
23760 6f 72 64 65 72 2e 0a 2a 2a 0a 2a 2a 20 57 68 65  order..**.** Whe
23770 74 68 65 72 20 6f 72 20 6e 6f 74 20 61 6e 20 65  ther or not an e
23780 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68 65 6e  rror occurs when
23790 20 69 74 20 69 73 20 6f 70 65 6e 65 64 2c 20 72   it is opened, r
237a0 65 73 6f 75 72 63 65 73 0a 2a 2a 20 61 73 73 6f  esources.** asso
237b0 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20  ciated with the 
237c0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
237d0 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 73 68 6f  tion] handle sho
237e0 75 6c 64 20 62 65 20 72 65 6c 65 61 73 65 64 20  uld be released 
237f0 62 79 0a 2a 2a 20 70 61 73 73 69 6e 67 20 69 74  by.** passing it
23800 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f   to [sqlite3_clo
23810 73 65 28 29 5d 20 77 68 65 6e 20 69 74 20 69 73  se()] when it is
23820 20 6e 6f 20 6c 6f 6e 67 65 72 20 72 65 71 75 69   no longer requi
23830 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  red..**.** The s
23840 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
23850 20 69 6e 74 65 72 66 61 63 65 20 77 6f 72 6b 73   interface works
23860 20 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f 6f 70   like sqlite3_op
23870 65 6e 28 29 0a 2a 2a 20 65 78 63 65 70 74 20 74  en().** except t
23880 68 61 74 20 69 74 20 61 63 63 65 70 74 73 20 74  hat it accepts t
23890 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 70 61  wo additional pa
238a0 72 61 6d 65 74 65 72 73 20 66 6f 72 20 61 64 64  rameters for add
238b0 69 74 69 6f 6e 61 6c 20 63 6f 6e 74 72 6f 6c 0a  itional control.
238c0 2a 2a 20 6f 76 65 72 20 74 68 65 20 6e 65 77 20  ** over the new 
238d0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
238e0 69 6f 6e 2e 20 20 5e 28 54 68 65 20 66 6c 61 67  ion.  ^(The flag
238f0 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a  s parameter to.*
23900 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  * sqlite3_open_v
23910 32 28 29 20 63 61 6e 20 74 61 6b 65 20 6f 6e 65  2() can take one
23920 20 6f 66 0a 2a 2a 20 74 68 65 20 66 6f 6c 6c 6f   of.** the follo
23930 77 69 6e 67 20 74 68 72 65 65 20 76 61 6c 75 65  wing three value
23940 73 2c 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f  s, optionally co
23950 6d 62 69 6e 65 64 20 77 69 74 68 20 74 68 65 20  mbined with the 
23960 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  .** [SQLITE_OPEN
23970 5f 4e 4f 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49  _NOMUTEX], [SQLI
23980 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45  TE_OPEN_FULLMUTE
23990 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  X], [SQLITE_OPEN
239a0 5f 53 48 41 52 45 44 43 41 43 48 45 5d 2c 0a 2a  _SHAREDCACHE],.*
239b0 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50  * [SQLITE_OPEN_P
239c0 52 49 56 41 54 45 43 41 43 48 45 5d 2c 20 61 6e  RIVATECACHE], an
239d0 64 2f 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45  d/or [SQLITE_OPE
239e0 4e 5f 55 52 49 5d 20 66 6c 61 67 73 3a 29 5e 0a  N_URI] flags:)^.
239f0 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5e 28  **.** <dl>.** ^(
23a00 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  <dt>[SQLITE_OPEN
23a10 5f 52 45 41 44 4f 4e 4c 59 5d 3c 2f 64 74 3e 0a  _READONLY]</dt>.
23a20 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62  ** <dd>The datab
23a30 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 69 6e  ase is opened in
23a40 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 6f 64 65 2e   read-only mode.
23a50 20 20 49 66 20 74 68 65 20 64 61 74 61 62 61 73    If the databas
23a60 65 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 61 6c  e does not.** al
23a70 72 65 61 64 79 20 65 78 69 73 74 2c 20 61 6e 20  ready exist, an 
23a80 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65  error is returne
23a90 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  d.</dd>)^.**.** 
23aa0 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50  ^(<dt>[SQLITE_OP
23ab0 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 3c 2f 64  EN_READWRITE]</d
23ac0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61  t>.** <dd>The da
23ad0 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64  tabase is opened
23ae0 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64   for reading and
23af0 20 77 72 69 74 69 6e 67 20 69 66 20 70 6f 73 73   writing if poss
23b00 69 62 6c 65 2c 20 6f 72 20 72 65 61 64 69 6e 67  ible, or reading
23b10 0a 2a 2a 20 6f 6e 6c 79 20 69 66 20 74 68 65 20  .** only if the 
23b20 66 69 6c 65 20 69 73 20 77 72 69 74 65 20 70 72  file is write pr
23b30 6f 74 65 63 74 65 64 20 62 79 20 74 68 65 20 6f  otected by the o
23b40 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e  perating system.
23b50 20 20 49 6e 20 65 69 74 68 65 72 0a 2a 2a 20 63    In either.** c
23b60 61 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65  ase the database
23b70 20 6d 75 73 74 20 61 6c 72 65 61 64 79 20 65 78   must already ex
23b80 69 73 74 2c 20 6f 74 68 65 72 77 69 73 65 20 61  ist, otherwise a
23b90 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72  n error is retur
23ba0 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  ned.</dd>)^.**.*
23bb0 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f  * ^(<dt>[SQLITE_
23bc0 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20  OPEN_READWRITE] 
23bd0 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43  | [SQLITE_OPEN_C
23be0 52 45 41 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c  REATE]</dt>.** <
23bf0 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 20  dd>The database 
23c00 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65  is opened for re
23c10 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e  ading and writin
23c20 67 2c 20 61 6e 64 20 69 73 20 63 72 65 61 74 65  g, and is create
23c30 64 20 69 66 0a 2a 2a 20 69 74 20 64 6f 65 73 20  d if.** it does 
23c40 6e 6f 74 20 61 6c 72 65 61 64 79 20 65 78 69 73  not already exis
23c50 74 2e 20 54 68 69 73 20 69 73 20 74 68 65 20 62  t. This is the b
23c60 65 68 61 76 69 6f 72 20 74 68 61 74 20 69 73 20  ehavior that is 
23c70 61 6c 77 61 79 73 20 75 73 65 64 20 66 6f 72 0a  always used for.
23c80 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  ** sqlite3_open(
23c90 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70  ) and sqlite3_op
23ca0 65 6e 31 36 28 29 2e 3c 2f 64 64 3e 29 5e 0a 2a  en16().</dd>)^.*
23cb0 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66  * </dl>.**.** If
23cc0 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74   the 3rd paramet
23cd0 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70  er to sqlite3_op
23ce0 65 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74 20 6f  en_v2() is not o
23cf0 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 63 6f 6d  ne of the.** com
23d00 62 69 6e 61 74 69 6f 6e 73 20 73 68 6f 77 6e 20  binations shown 
23d10 61 62 6f 76 65 20 6f 70 74 69 6f 6e 61 6c 6c 79  above optionally
23d20 20 63 6f 6d 62 69 6e 65 64 20 77 69 74 68 20 6f   combined with o
23d30 74 68 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ther.** [SQLITE_
23d40 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 7c 20  OPEN_READONLY | 
23d50 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 2a 20 62 69  SQLITE_OPEN_* bi
23d60 74 73 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  ts].** then the 
23d70 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65  behavior is unde
23d80 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  fined..**.** ^If
23d90 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45   the [SQLITE_OPE
23da0 4e 5f 4e 4f 4d 55 54 45 58 5d 20 66 6c 61 67 20  N_NOMUTEX] flag 
23db0 69 73 20 73 65 74 2c 20 74 68 65 6e 20 74 68 65  is set, then the
23dc0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
23dd0 74 69 6f 6e 0a 2a 2a 20 6f 70 65 6e 73 20 69 6e  tion.** opens in
23de0 20 74 68 65 20 6d 75 6c 74 69 2d 74 68 72 65 61   the multi-threa
23df0 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  d [threading mod
23e00 65 5d 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68  e] as long as th
23e10 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 0a  e single-thread.
23e20 2a 2a 20 6d 6f 64 65 20 68 61 73 20 6e 6f 74 20  ** mode has not 
23e30 62 65 65 6e 20 73 65 74 20 61 74 20 63 6f 6d 70  been set at comp
23e40 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74 61 72  ile-time or star
23e50 74 2d 74 69 6d 65 2e 20 20 5e 49 66 20 74 68 65  t-time.  ^If the
23e60 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  .** [SQLITE_OPEN
23e70 5f 46 55 4c 4c 4d 55 54 45 58 5d 20 66 6c 61 67  _FULLMUTEX] flag
23e80 20 69 73 20 73 65 74 20 74 68 65 6e 20 74 68 65   is set then the
23e90 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
23ea0 74 69 6f 6e 20 6f 70 65 6e 73 0a 2a 2a 20 69 6e  tion opens.** in
23eb0 20 74 68 65 20 73 65 72 69 61 6c 69 7a 65 64 20   the serialized 
23ec0 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
23ed0 20 75 6e 6c 65 73 73 20 73 69 6e 67 6c 65 2d 74   unless single-t
23ee0 68 72 65 61 64 20 77 61 73 0a 2a 2a 20 70 72 65  hread was.** pre
23ef0 76 69 6f 75 73 6c 79 20 73 65 6c 65 63 74 65 64  viously selected
23f00 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65   at compile-time
23f10 20 6f 72 20 73 74 61 72 74 2d 74 69 6d 65 2e 0a   or start-time..
23f20 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  ** ^The [SQLITE_
23f30 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45  OPEN_SHAREDCACHE
23f40 5d 20 66 6c 61 67 20 63 61 75 73 65 73 20 74 68  ] flag causes th
23f50 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
23f60 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 65  ction to be.** e
23f70 6c 69 67 69 62 6c 65 20 74 6f 20 75 73 65 20 5b  ligible to use [
23f80 73 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64  shared cache mod
23f90 65 5d 2c 20 72 65 67 61 72 64 6c 65 73 73 20 6f  e], regardless o
23fa0 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  f whether or not
23fb0 20 73 68 61 72 65 64 0a 2a 2a 20 63 61 63 68 65   shared.** cache
23fc0 20 69 73 20 65 6e 61 62 6c 65 64 20 75 73 69 6e   is enabled usin
23fd0 67 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c  g [sqlite3_enabl
23fe0 65 5f 73 68 61 72 65 64 5f 63 61 63 68 65 28 29  e_shared_cache()
23ff0 5d 2e 20 20 5e 54 68 65 0a 2a 2a 20 5b 53 51 4c  ].  ^The.** [SQL
24000 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45  ITE_OPEN_PRIVATE
24010 43 41 43 48 45 5d 20 66 6c 61 67 20 63 61 75 73  CACHE] flag caus
24020 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  es the database 
24030 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 6e 6f  connection to no
24040 74 0a 2a 2a 20 70 61 72 74 69 63 69 70 61 74 65  t.** participate
24050 20 69 6e 20 5b 73 68 61 72 65 64 20 63 61 63 68   in [shared cach
24060 65 20 6d 6f 64 65 5d 20 65 76 65 6e 20 69 66 20  e mode] even if 
24070 69 74 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a  it is enabled..*
24080 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68  *.** ^The fourth
24090 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
240a0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
240b0 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  is the name of t
240c0 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76  he.** [sqlite3_v
240d0 66 73 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 20  fs] object that 
240e0 64 65 66 69 6e 65 73 20 74 68 65 20 6f 70 65 72  defines the oper
240f0 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69 6e 74  ating system int
24100 65 72 66 61 63 65 20 74 68 61 74 0a 2a 2a 20 74  erface that.** t
24110 68 65 20 6e 65 77 20 64 61 74 61 62 61 73 65 20  he new database 
24120 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 68 6f 75 6c  connection shoul
24130 64 20 75 73 65 2e 20 20 5e 49 66 20 74 68 65 20  d use.  ^If the 
24140 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
24150 20 69 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f   is.** a NULL po
24160 69 6e 74 65 72 20 74 68 65 6e 20 74 68 65 20 64  inter then the d
24170 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f  efault [sqlite3_
24180 76 66 73 5d 20 6f 62 6a 65 63 74 20 69 73 20 75  vfs] object is u
24190 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  sed..**.** ^If t
241a0 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 22  he filename is "
241b0 3a 6d 65 6d 6f 72 79 3a 22 2c 20 74 68 65 6e 20  :memory:", then 
241c0 61 20 70 72 69 76 61 74 65 2c 20 74 65 6d 70 6f  a private, tempo
241d0 72 61 72 79 20 69 6e 2d 6d 65 6d 6f 72 79 20 64  rary in-memory d
241e0 61 74 61 62 61 73 65 0a 2a 2a 20 69 73 20 63 72  atabase.** is cr
241f0 65 61 74 65 64 20 66 6f 72 20 74 68 65 20 63 6f  eated for the co
24200 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 54 68 69 73  nnection.  ^This
24210 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62   in-memory datab
24220 61 73 65 20 77 69 6c 6c 20 76 61 6e 69 73 68 20  ase will vanish 
24230 77 68 65 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61  when.** the data
24240 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
24250 69 73 20 63 6c 6f 73 65 64 2e 20 20 46 75 74 75  is closed.  Futu
24260 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  re versions of S
24270 51 4c 69 74 65 20 6d 69 67 68 74 0a 2a 2a 20 6d  QLite might.** m
24280 61 6b 65 20 75 73 65 20 6f 66 20 61 64 64 69 74  ake use of addit
24290 69 6f 6e 61 6c 20 73 70 65 63 69 61 6c 20 66 69  ional special fi
242a0 6c 65 6e 61 6d 65 73 20 74 68 61 74 20 62 65 67  lenames that beg
242b0 69 6e 20 77 69 74 68 20 74 68 65 20 22 3a 22 20  in with the ":" 
242c0 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 49 74  character..** It
242d0 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20   is recommended 
242e0 74 68 61 74 20 77 68 65 6e 20 61 20 64 61 74 61  that when a data
242f0 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 61 63  base filename ac
24300 74 75 61 6c 6c 79 20 64 6f 65 73 20 62 65 67 69  tually does begi
24310 6e 20 77 69 74 68 0a 2a 2a 20 61 20 22 3a 22 20  n with.** a ":" 
24320 63 68 61 72 61 63 74 65 72 20 79 6f 75 20 73 68  character you sh
24330 6f 75 6c 64 20 70 72 65 66 69 78 20 74 68 65 20  ould prefix the 
24340 66 69 6c 65 6e 61 6d 65 20 77 69 74 68 20 61 20  filename with a 
24350 70 61 74 68 6e 61 6d 65 20 73 75 63 68 20 61 73  pathname such as
24360 0a 2a 2a 20 22 2e 2f 22 20 74 6f 20 61 76 6f 69  .** "./" to avoi
24370 64 20 61 6d 62 69 67 75 69 74 79 2e 0a 2a 2a 0a  d ambiguity..**.
24380 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 6c 65 6e  ** ^If the filen
24390 61 6d 65 20 69 73 20 61 6e 20 65 6d 70 74 79 20  ame is an empty 
243a0 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 61 20 70  string, then a p
243b0 72 69 76 61 74 65 2c 20 74 65 6d 70 6f 72 61 72  rivate, temporar
243c0 79 0a 2a 2a 20 6f 6e 2d 64 69 73 6b 20 64 61 74  y.** on-disk dat
243d0 61 62 61 73 65 20 77 69 6c 6c 20 62 65 20 63 72  abase will be cr
243e0 65 61 74 65 64 2e 20 20 5e 54 68 69 73 20 70 72  eated.  ^This pr
243f0 69 76 61 74 65 20 64 61 74 61 62 61 73 65 20 77  ivate database w
24400 69 6c 6c 20 62 65 0a 2a 2a 20 61 75 74 6f 6d 61  ill be.** automa
24410 74 69 63 61 6c 6c 79 20 64 65 6c 65 74 65 64 20  tically deleted 
24420 61 73 20 73 6f 6f 6e 20 61 73 20 74 68 65 20 64  as soon as the d
24430 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
24440 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a  on is closed..**
24450 0a 2a 2a 20 5b 5b 55 52 49 20 66 69 6c 65 6e 61  .** [[URI filena
24460 6d 65 73 20 69 6e 20 73 71 6c 69 74 65 33 5f 6f  mes in sqlite3_o
24470 70 65 6e 28 29 5d 5d 20 3c 68 33 3e 55 52 49 20  pen()]] <h3>URI 
24480 46 69 6c 65 6e 61 6d 65 73 3c 2f 68 33 3e 0a 2a  Filenames</h3>.*
24490 2a 0a 2a 2a 20 5e 49 66 20 5b 55 52 49 20 66 69  *.** ^If [URI fi
244a0 6c 65 6e 61 6d 65 5d 20 69 6e 74 65 72 70 72 65  lename] interpre
244b0 74 61 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65  tation is enable
244c0 64 2c 20 61 6e 64 20 74 68 65 20 66 69 6c 65 6e  d, and the filen
244d0 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  ame argument.** 
244e0 62 65 67 69 6e 73 20 77 69 74 68 20 22 66 69 6c  begins with "fil
244f0 65 3a 22 2c 20 74 68 65 6e 20 74 68 65 20 66 69  e:", then the fi
24500 6c 65 6e 61 6d 65 20 69 73 20 69 6e 74 65 72 70  lename is interp
24510 72 65 74 65 64 20 61 73 20 61 20 55 52 49 2e 20  reted as a URI. 
24520 5e 55 52 49 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65  ^URI.** filename
24530 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20   interpretation 
24540 69 73 20 65 6e 61 62 6c 65 64 20 69 66 20 74 68  is enabled if th
24550 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55  e [SQLITE_OPEN_U
24560 52 49 5d 20 66 6c 61 67 20 69 73 0a 2a 2a 20 73  RI] flag is.** s
24570 65 74 20 69 6e 20 74 68 65 20 66 6f 75 72 74 68  et in the fourth
24580 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
24590 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2c 20  ite3_open_v2(), 
245a0 6f 72 20 69 66 20 69 74 20 68 61 73 0a 2a 2a 20  or if it has.** 
245b0 62 65 65 6e 20 65 6e 61 62 6c 65 64 20 67 6c 6f  been enabled glo
245c0 62 61 6c 6c 79 20 75 73 69 6e 67 20 74 68 65 20  bally using the 
245d0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55  [SQLITE_CONFIG_U
245e0 52 49 5d 20 6f 70 74 69 6f 6e 20 77 69 74 68 20  RI] option with 
245f0 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
24600 63 6f 6e 66 69 67 28 29 5d 20 6d 65 74 68 6f 64  config()] method
24610 20 6f 72 20 62 79 20 74 68 65 20 5b 53 51 4c 49   or by the [SQLI
24620 54 45 5f 55 53 45 5f 55 52 49 5d 20 63 6f 6d 70  TE_USE_URI] comp
24630 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e  ile-time option.
24640 0a 2a 2a 20 41 73 20 6f 66 20 53 51 4c 69 74 65  .** As of SQLite
24650 20 76 65 72 73 69 6f 6e 20 33 2e 37 2e 37 2c 20   version 3.7.7, 
24660 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 69 6e 74  URI filename int
24670 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20 74  erpretation is t
24680 75 72 6e 65 64 20 6f 66 66 0a 2a 2a 20 62 79 20  urned off.** by 
24690 64 65 66 61 75 6c 74 2c 20 62 75 74 20 66 75 74  default, but fut
246a0 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20  ure releases of 
246b0 53 51 4c 69 74 65 20 6d 69 67 68 74 20 65 6e 61  SQLite might ena
246c0 62 6c 65 20 55 52 49 20 66 69 6c 65 6e 61 6d 65  ble URI filename
246d0 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74 61 74 69  .** interpretati
246e0 6f 6e 20 62 79 20 64 65 66 61 75 6c 74 2e 20 20  on by default.  
246f0 53 65 65 20 22 5b 55 52 49 20 66 69 6c 65 6e 61  See "[URI filena
24700 6d 65 73 5d 22 20 66 6f 72 20 61 64 64 69 74 69  mes]" for additi
24710 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74  onal.** informat
24720 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 55 52 49 20 66  ion..**.** URI f
24730 69 6c 65 6e 61 6d 65 73 20 61 72 65 20 70 61 72  ilenames are par
24740 73 65 64 20 61 63 63 6f 72 64 69 6e 67 20 74 6f  sed according to
24750 20 52 46 43 20 33 39 38 36 2e 20 5e 49 66 20 74   RFC 3986. ^If t
24760 68 65 20 55 52 49 20 63 6f 6e 74 61 69 6e 73 20  he URI contains 
24770 61 6e 0a 2a 2a 20 61 75 74 68 6f 72 69 74 79 2c  an.** authority,
24780 20 74 68 65 6e 20 69 74 20 6d 75 73 74 20 62 65   then it must be
24790 20 65 69 74 68 65 72 20 61 6e 20 65 6d 70 74 79   either an empty
247a0 20 73 74 72 69 6e 67 20 6f 72 20 74 68 65 20 73   string or the s
247b0 74 72 69 6e 67 20 0a 2a 2a 20 22 6c 6f 63 61 6c  tring .** "local
247c0 68 6f 73 74 22 2e 20 5e 49 66 20 74 68 65 20 61  host". ^If the a
247d0 75 74 68 6f 72 69 74 79 20 69 73 20 6e 6f 74 20  uthority is not 
247e0 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20  an empty string 
247f0 6f 72 20 22 6c 6f 63 61 6c 68 6f 73 74 22 2c 20  or "localhost", 
24800 61 6e 20 0a 2a 2a 20 65 72 72 6f 72 20 69 73 20  an .** error is 
24810 72 65 74 75 72 6e 65 64 20 74 6f 20 74 68 65 20  returned to the 
24820 63 61 6c 6c 65 72 2e 20 5e 54 68 65 20 66 72 61  caller. ^The fra
24830 67 6d 65 6e 74 20 63 6f 6d 70 6f 6e 65 6e 74 20  gment component 
24840 6f 66 20 61 20 55 52 49 2c 20 69 66 20 0a 2a 2a  of a URI, if .**
24850 20 70 72 65 73 65 6e 74 2c 20 69 73 20 69 67 6e   present, is ign
24860 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c  ored..**.** ^SQL
24870 69 74 65 20 75 73 65 73 20 74 68 65 20 70 61 74  ite uses the pat
24880 68 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 74  h component of t
24890 68 65 20 55 52 49 20 61 73 20 74 68 65 20 6e 61  he URI as the na
248a0 6d 65 20 6f 66 20 74 68 65 20 64 69 73 6b 20 66  me of the disk f
248b0 69 6c 65 0a 2a 2a 20 77 68 69 63 68 20 63 6f 6e  ile.** which con
248c0 74 61 69 6e 73 20 74 68 65 20 64 61 74 61 62 61  tains the databa
248d0 73 65 2e 20 5e 49 66 20 74 68 65 20 70 61 74 68  se. ^If the path
248e0 20 62 65 67 69 6e 73 20 77 69 74 68 20 61 20 27   begins with a '
248f0 2f 27 20 63 68 61 72 61 63 74 65 72 2c 20 0a 2a  /' character, .*
24900 2a 20 74 68 65 6e 20 69 74 20 69 73 20 69 6e 74  * then it is int
24910 65 72 70 72 65 74 65 64 20 61 73 20 61 6e 20 61  erpreted as an a
24920 62 73 6f 6c 75 74 65 20 70 61 74 68 2e 20 5e 49  bsolute path. ^I
24930 66 20 74 68 65 20 70 61 74 68 20 64 6f 65 73 20  f the path does 
24940 6e 6f 74 20 62 65 67 69 6e 20 0a 2a 2a 20 77 69  not begin .** wi
24950 74 68 20 61 20 27 2f 27 20 28 6d 65 61 6e 69 6e  th a '/' (meanin
24960 67 20 74 68 61 74 20 74 68 65 20 61 75 74 68 6f  g that the autho
24970 72 69 74 79 20 73 65 63 74 69 6f 6e 20 69 73 20  rity section is 
24980 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65  omitted from the
24990 20 55 52 49 29 0a 2a 2a 20 74 68 65 6e 20 74 68   URI).** then th
249a0 65 20 70 61 74 68 20 69 73 20 69 6e 74 65 72 70  e path is interp
249b0 72 65 74 65 64 20 61 73 20 61 20 72 65 6c 61 74  reted as a relat
249c0 69 76 65 20 70 61 74 68 2e 20 0a 2a 2a 20 5e 28  ive path. .** ^(
249d0 4f 6e 20 77 69 6e 64 6f 77 73 2c 20 74 68 65 20  On windows, the 
249e0 66 69 72 73 74 20 63 6f 6d 70 6f 6e 65 6e 74 20  first component 
249f0 6f 66 20 61 6e 20 61 62 73 6f 6c 75 74 65 20 70  of an absolute p
24a00 61 74 68 20 0a 2a 2a 20 69 73 20 61 20 64 72 69  ath .** is a dri
24a10 76 65 20 73 70 65 63 69 66 69 63 61 74 69 6f 6e  ve specification
24a20 20 28 65 2e 67 2e 20 22 43 3a 22 29 2e 29 5e 0a   (e.g. "C:").)^.
24a30 2a 2a 0a 2a 2a 20 5b 5b 63 6f 72 65 20 55 52 49  **.** [[core URI
24a40 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72   query parameter
24a50 73 5d 5d 0a 2a 2a 20 54 68 65 20 71 75 65 72 79  s]].** The query
24a60 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20   component of a 
24a70 55 52 49 20 6d 61 79 20 63 6f 6e 74 61 69 6e 20  URI may contain 
24a80 70 61 72 61 6d 65 74 65 72 73 20 74 68 61 74 20  parameters that 
24a90 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64 0a  are interpreted.
24aa0 2a 2a 20 65 69 74 68 65 72 20 62 79 20 53 51 4c  ** either by SQL
24ab0 69 74 65 20 69 74 73 65 6c 66 2c 20 6f 72 20 62  ite itself, or b
24ac0 79 20 61 20 5b 56 46 53 20 7c 20 63 75 73 74 6f  y a [VFS | custo
24ad0 6d 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61  m VFS implementa
24ae0 74 69 6f 6e 5d 2e 0a 2a 2a 20 53 51 4c 69 74 65  tion]..** SQLite
24af0 20 61 6e 64 20 69 74 73 20 62 75 69 6c 74 2d 69   and its built-i
24b00 6e 20 5b 56 46 53 65 73 5d 20 69 6e 74 65 72 70  n [VFSes] interp
24b10 72 65 74 20 74 68 65 0a 2a 2a 20 66 6f 6c 6c 6f  ret the.** follo
24b20 77 69 6e 67 20 71 75 65 72 79 20 70 61 72 61 6d  wing query param
24b30 65 74 65 72 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  eters:.**.** <ul
24b40 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 76  >.**   <li> <b>v
24b50 66 73 3c 2f 62 3e 3a 20 5e 54 68 65 20 22 76 66  fs</b>: ^The "vf
24b60 73 22 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79  s" parameter may
24b70 20 62 65 20 75 73 65 64 20 74 6f 20 73 70 65 63   be used to spec
24b80 69 66 79 20 74 68 65 20 6e 61 6d 65 20 6f 66 0a  ify the name of.
24b90 2a 2a 20 20 20 20 20 61 20 56 46 53 20 6f 62 6a  **     a VFS obj
24ba0 65 63 74 20 74 68 61 74 20 70 72 6f 76 69 64 65  ect that provide
24bb0 73 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20  s the operating 
24bc0 73 79 73 74 65 6d 20 69 6e 74 65 72 66 61 63 65  system interface
24bd0 20 74 68 61 74 20 73 68 6f 75 6c 64 0a 2a 2a 20   that should.** 
24be0 20 20 20 20 62 65 20 75 73 65 64 20 74 6f 20 61      be used to a
24bf0 63 63 65 73 73 20 74 68 65 20 64 61 74 61 62 61  ccess the databa
24c00 73 65 20 66 69 6c 65 20 6f 6e 20 64 69 73 6b 2e  se file on disk.
24c10 20 5e 49 66 20 74 68 69 73 20 6f 70 74 69 6f 6e   ^If this option
24c20 20 69 73 20 73 65 74 20 74 6f 0a 2a 2a 20 20 20   is set to.**   
24c30 20 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e    an empty strin
24c40 67 20 74 68 65 20 64 65 66 61 75 6c 74 20 56 46  g the default VF
24c50 53 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64  S object is used
24c60 2e 20 5e 53 70 65 63 69 66 79 69 6e 67 20 61 6e  . ^Specifying an
24c70 20 75 6e 6b 6e 6f 77 6e 0a 2a 2a 20 20 20 20 20   unknown.**     
24c80 56 46 53 20 69 73 20 61 6e 20 65 72 72 6f 72 2e  VFS is an error.
24c90 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f 70 65   ^If sqlite3_ope
24ca0 6e 5f 76 32 28 29 20 69 73 20 75 73 65 64 20 61  n_v2() is used a
24cb0 6e 64 20 74 68 65 20 76 66 73 20 6f 70 74 69 6f  nd the vfs optio
24cc0 6e 20 69 73 0a 2a 2a 20 20 20 20 20 70 72 65 73  n is.**     pres
24cd0 65 6e 74 2c 20 74 68 65 6e 20 74 68 65 20 56 46  ent, then the VF
24ce0 53 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74  S specified by t
24cf0 68 65 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  he option takes 
24d00 70 72 65 63 65 64 65 6e 63 65 20 6f 76 65 72 0a  precedence over.
24d10 2a 2a 20 20 20 20 20 74 68 65 20 76 61 6c 75 65  **     the value
24d20 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66   passed as the f
24d30 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
24d40 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  to sqlite3_open_
24d50 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c  v2()..**.**   <l
24d60 69 3e 20 3c 62 3e 6d 6f 64 65 3c 2f 62 3e 3a 20  i> <b>mode</b>: 
24d70 5e 28 54 68 65 20 6d 6f 64 65 20 70 61 72 61 6d  ^(The mode param
24d80 65 74 65 72 20 6d 61 79 20 62 65 20 73 65 74 20  eter may be set 
24d90 74 6f 20 65 69 74 68 65 72 20 22 72 6f 22 2c 20  to either "ro", 
24da0 22 72 77 22 2c 0a 2a 2a 20 20 20 20 20 22 72 77  "rw",.**     "rw
24db0 63 22 2c 20 6f 72 20 22 6d 65 6d 6f 72 79 22 2e  c", or "memory".
24dc0 20 41 74 74 65 6d 70 74 69 6e 67 20 74 6f 20 73   Attempting to s
24dd0 65 74 20 69 74 20 74 6f 20 61 6e 79 20 6f 74 68  et it to any oth
24de0 65 72 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20 20  er value is.**  
24df0 20 20 20 61 6e 20 65 72 72 6f 72 29 5e 2e 20 0a     an error)^. .
24e00 2a 2a 20 20 20 20 20 5e 49 66 20 22 72 6f 22 20  **     ^If "ro" 
24e10 69 73 20 73 70 65 63 69 66 69 65 64 2c 20 74 68  is specified, th
24e20 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
24e30 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65  is opened for re
24e40 61 64 2d 6f 6e 6c 79 20 0a 2a 2a 20 20 20 20 20  ad-only .**     
24e50 61 63 63 65 73 73 2c 20 6a 75 73 74 20 61 73 20  access, just as 
24e60 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  if the [SQLITE_O
24e70 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 20 66 6c  PEN_READONLY] fl
24e80 61 67 20 68 61 64 20 62 65 65 6e 20 73 65 74 20  ag had been set 
24e90 69 6e 20 74 68 65 20 0a 2a 2a 20 20 20 20 20 74  in the .**     t
24ea0 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  hird argument to
24eb0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
24ec0 28 29 2e 20 5e 49 66 20 74 68 65 20 6d 6f 64 65  (). ^If the mode
24ed0 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 20 74   option is set t
24ee0 6f 20 0a 2a 2a 20 20 20 20 20 22 72 77 22 2c 20  o .**     "rw", 
24ef0 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  then the databas
24f00 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20  e is opened for 
24f10 72 65 61 64 2d 77 72 69 74 65 20 28 62 75 74 20  read-write (but 
24f20 6e 6f 74 20 63 72 65 61 74 65 29 20 0a 2a 2a 20  not create) .** 
24f30 20 20 20 20 61 63 63 65 73 73 2c 20 61 73 20 69      access, as i
24f40 66 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45  f SQLITE_OPEN_RE
24f50 41 44 57 52 49 54 45 20 28 62 75 74 20 6e 6f 74  ADWRITE (but not
24f60 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45   SQLITE_OPEN_CRE
24f70 41 54 45 29 20 68 61 64 20 0a 2a 2a 20 20 20 20  ATE) had .**    
24f80 20 62 65 65 6e 20 73 65 74 2e 20 5e 56 61 6c 75   been set. ^Valu
24f90 65 20 22 72 77 63 22 20 69 73 20 65 71 75 69 76  e "rwc" is equiv
24fa0 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67  alent to setting
24fb0 20 62 6f 74 68 20 0a 2a 2a 20 20 20 20 20 53 51   both .**     SQ
24fc0 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52  LITE_OPEN_READWR
24fd0 49 54 45 20 61 6e 64 20 53 51 4c 49 54 45 5f 4f  ITE and SQLITE_O
24fe0 50 45 4e 5f 43 52 45 41 54 45 2e 20 20 5e 49 66  PEN_CREATE.  ^If
24ff0 20 74 68 65 20 6d 6f 64 65 20 6f 70 74 69 6f 6e   the mode option
25000 20 69 73 0a 2a 2a 20 20 20 20 20 73 65 74 20 74   is.**     set t
25010 6f 20 22 6d 65 6d 6f 72 79 22 20 74 68 65 6e 20  o "memory" then 
25020 61 20 70 75 72 65 20 5b 69 6e 2d 6d 65 6d 6f 72  a pure [in-memor
25030 79 20 64 61 74 61 62 61 73 65 5d 20 74 68 61 74  y database] that
25040 20 6e 65 76 65 72 20 72 65 61 64 73 0a 2a 2a 20   never reads.** 
25050 20 20 20 20 6f 72 20 77 72 69 74 65 73 20 66 72      or writes fr
25060 6f 6d 20 64 69 73 6b 20 69 73 20 75 73 65 64 2e  om disk is used.
25070 20 5e 49 74 20 69 73 20 61 6e 20 65 72 72 6f 72   ^It is an error
25080 20 74 6f 20 73 70 65 63 69 66 79 20 61 20 76 61   to specify a va
25090 6c 75 65 20 66 6f 72 0a 2a 2a 20 20 20 20 20 74  lue for.**     t
250a0 68 65 20 6d 6f 64 65 20 70 61 72 61 6d 65 74 65  he mode paramete
250b0 72 20 74 68 61 74 20 69 73 20 6c 65 73 73 20 72  r that is less r
250c0 65 73 74 72 69 63 74 69 76 65 20 74 68 61 6e 20  estrictive than 
250d0 74 68 61 74 20 73 70 65 63 69 66 69 65 64 20 62  that specified b
250e0 79 0a 2a 2a 20 20 20 20 20 74 68 65 20 66 6c 61  y.**     the fla
250f0 67 73 20 70 61 73 73 65 64 20 69 6e 20 74 68 65  gs passed in the
25100 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
25110 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   to sqlite3_open
25120 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c  _v2()..**.**   <
25130 6c 69 3e 20 3c 62 3e 63 61 63 68 65 3c 2f 62 3e  li> <b>cache</b>
25140 3a 20 5e 54 68 65 20 63 61 63 68 65 20 70 61 72  : ^The cache par
25150 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 73 65  ameter may be se
25160 74 20 74 6f 20 65 69 74 68 65 72 20 22 73 68 61  t to either "sha
25170 72 65 64 22 20 6f 72 0a 2a 2a 20 20 20 20 20 22  red" or.**     "
25180 70 72 69 76 61 74 65 22 2e 20 5e 53 65 74 74 69  private". ^Setti
25190 6e 67 20 69 74 20 74 6f 20 22 73 68 61 72 65 64  ng it to "shared
251a0 22 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20  " is equivalent 
251b0 74 6f 20 73 65 74 74 69 6e 67 20 74 68 65 0a 2a  to setting the.*
251c0 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45  *     SQLITE_OPE
251d0 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20 62 69  N_SHAREDCACHE bi
251e0 74 20 69 6e 20 74 68 65 20 66 6c 61 67 73 20 61  t in the flags a
251f0 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20 74  rgument passed t
25200 6f 0a 2a 2a 20 20 20 20 20 73 71 6c 69 74 65 33  o.**     sqlite3
25210 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 5e 53 65 74  _open_v2(). ^Set
25220 74 69 6e 67 20 74 68 65 20 63 61 63 68 65 20 70  ting the cache p
25230 61 72 61 6d 65 74 65 72 20 74 6f 20 22 70 72 69  arameter to "pri
25240 76 61 74 65 22 20 69 73 20 0a 2a 2a 20 20 20 20  vate" is .**    
25250 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73   equivalent to s
25260 65 74 74 69 6e 67 20 74 68 65 20 53 51 4c 49 54  etting the SQLIT
25270 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41  E_OPEN_PRIVATECA
25280 43 48 45 20 62 69 74 2e 0a 2a 2a 20 20 20 20 20  CHE bit..**     
25290 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ^If sqlite3_open
252a0 5f 76 32 28 29 20 69 73 20 75 73 65 64 20 61 6e  _v2() is used an
252b0 64 20 74 68 65 20 22 63 61 63 68 65 22 20 70 61  d the "cache" pa
252c0 72 61 6d 65 74 65 72 20 69 73 20 70 72 65 73 65  rameter is prese
252d0 6e 74 20 69 6e 0a 2a 2a 20 20 20 20 20 61 20 55  nt in.**     a U
252e0 52 49 20 66 69 6c 65 6e 61 6d 65 2c 20 69 74 73  RI filename, its
252f0 20 76 61 6c 75 65 20 6f 76 65 72 72 69 64 65 73   value overrides
25300 20 61 6e 79 20 62 65 68 61 76 69 6f 72 20 72 65   any behavior re
25310 71 75 65 73 74 65 64 20 62 79 20 73 65 74 74 69  quested by setti
25320 6e 67 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45  ng.**     SQLITE
25330 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43  _OPEN_PRIVATECAC
25340 48 45 20 6f 72 20 53 51 4c 49 54 45 5f 4f 50 45  HE or SQLITE_OPE
25350 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20 66 6c  N_SHAREDCACHE fl
25360 61 67 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20  ag..**.**  <li> 
25370 3c 62 3e 70 73 6f 77 3c 2f 62 3e 3a 20 5e 54 68  <b>psow</b>: ^Th
25380 65 20 70 73 6f 77 20 70 61 72 61 6d 65 74 65 72  e psow parameter
25390 20 69 6e 64 69 63 61 74 65 73 20 77 68 65 74 68   indicates wheth
253a0 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 0a 2a 2a  er or not the.**
253b0 20 20 20 20 20 5b 70 6f 77 65 72 73 61 66 65 20       [powersafe 
253c0 6f 76 65 72 77 72 69 74 65 5d 20 70 72 6f 70 65  overwrite] prope
253d0 72 74 79 20 64 6f 65 73 20 6f 72 20 64 6f 65 73  rty does or does
253e0 20 6e 6f 74 20 61 70 70 6c 79 20 74 6f 20 74 68   not apply to th
253f0 65 0a 2a 2a 20 20 20 20 20 73 74 6f 72 61 67 65  e.**     storage
25400 20 6d 65 64 69 61 20 6f 6e 20 77 68 69 63 68 20   media on which 
25410 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
25420 65 20 72 65 73 69 64 65 73 2e 0a 2a 2a 0a 2a 2a  e resides..**.**
25430 20 20 3c 6c 69 3e 20 3c 62 3e 6e 6f 6c 6f 63 6b    <li> <b>nolock
25440 3c 2f 62 3e 3a 20 5e 54 68 65 20 6e 6f 6c 6f 63  </b>: ^The noloc
25450 6b 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  k parameter is a
25460 20 62 6f 6f 6c 65 61 6e 20 71 75 65 72 79 20 70   boolean query p
25470 61 72 61 6d 65 74 65 72 0a 2a 2a 20 20 20 20 20  arameter.**     
25480 77 68 69 63 68 20 69 66 20 73 65 74 20 64 69 73  which if set dis
25490 61 62 6c 65 73 20 66 69 6c 65 20 6c 6f 63 6b 69  ables file locki
254a0 6e 67 20 69 6e 20 72 6f 6c 6c 62 61 63 6b 20 6a  ng in rollback j
254b0 6f 75 72 6e 61 6c 20 6d 6f 64 65 73 2e 20 20 54  ournal modes.  T
254c0 68 69 73 0a 2a 2a 20 20 20 20 20 69 73 20 75 73  his.**     is us
254d0 65 66 75 6c 20 66 6f 72 20 61 63 63 65 73 73 69  eful for accessi
254e0 6e 67 20 61 20 64 61 74 61 62 61 73 65 20 6f 6e  ng a database on
254f0 20 61 20 66 69 6c 65 73 79 73 74 65 6d 20 74 68   a filesystem th
25500 61 74 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 20  at does not.**  
25510 20 20 20 73 75 70 70 6f 72 74 20 6c 6f 63 6b 69     support locki
25520 6e 67 2e 20 20 43 61 75 74 69 6f 6e 3a 20 20 44  ng.  Caution:  D
25530 61 74 61 62 61 73 65 20 63 6f 72 72 75 70 74 69  atabase corrupti
25540 6f 6e 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20  on might result 
25550 69 66 20 74 77 6f 0a 2a 2a 20 20 20 20 20 6f 72  if two.**     or
25560 20 6d 6f 72 65 20 70 72 6f 63 65 73 73 65 73 20   more processes 
25570 77 72 69 74 65 20 74 6f 20 74 68 65 20 73 61 6d  write to the sam
25580 65 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 61  e database and a
25590 6e 79 20 6f 6e 65 20 6f 66 20 74 68 6f 73 65 0a  ny one of those.
255a0 2a 2a 20 20 20 20 20 70 72 6f 63 65 73 73 65 73  **     processes
255b0 20 75 73 65 73 20 6e 6f 6c 6f 63 6b 3d 31 2e 0a   uses nolock=1..
255c0 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e 69  **.**  <li> <b>i
255d0 6d 6d 75 74 61 62 6c 65 3c 2f 62 3e 3a 20 5e 54  mmutable</b>: ^T
255e0 68 65 20 69 6d 6d 75 74 61 62 6c 65 20 70 61 72  he immutable par
255f0 61 6d 65 74 65 72 20 69 73 20 61 20 62 6f 6f 6c  ameter is a bool
25600 65 61 6e 20 71 75 65 72 79 0a 2a 2a 20 20 20 20  ean query.**    
25610 20 70 61 72 61 6d 65 74 65 72 20 74 68 61 74 20   parameter that 
25620 69 6e 64 69 63 61 74 65 73 20 74 68 61 74 20 74  indicates that t
25630 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
25640 20 69 73 20 73 74 6f 72 65 64 20 6f 6e 0a 2a 2a   is stored on.**
25650 20 20 20 20 20 72 65 61 64 2d 6f 6e 6c 79 20 6d       read-only m
25660 65 64 69 61 2e 20 20 5e 57 68 65 6e 20 69 6d 6d  edia.  ^When imm
25670 75 74 61 62 6c 65 20 69 73 20 73 65 74 2c 20 53  utable is set, S
25680 51 4c 69 74 65 20 61 73 73 75 6d 65 73 20 74 68  QLite assumes th
25690 61 74 20 74 68 65 0a 2a 2a 20 20 20 20 20 64 61  at the.**     da
256a0 74 61 62 61 73 65 20 66 69 6c 65 20 63 61 6e 6e  tabase file cann
256b0 6f 74 20 62 65 20 63 68 61 6e 67 65 64 2c 20 65  ot be changed, e
256c0 76 65 6e 20 62 79 20 61 20 70 72 6f 63 65 73 73  ven by a process
256d0 20 77 69 74 68 20 68 69 67 68 65 72 0a 2a 2a 20   with higher.** 
256e0 20 20 20 20 70 72 69 76 69 6c 65 67 65 2c 20 61      privilege, a
256f0 6e 64 20 73 6f 20 74 68 65 20 64 61 74 61 62 61  nd so the databa
25700 73 65 20 69 73 20 6f 70 65 6e 65 64 20 72 65 61  se is opened rea
25710 64 2d 6f 6e 6c 79 20 61 6e 64 20 61 6c 6c 20 6c  d-only and all l
25720 6f 63 6b 69 6e 67 0a 2a 2a 20 20 20 20 20 61 6e  ocking.**     an
25730 64 20 63 68 61 6e 67 65 20 64 65 74 65 63 74 69  d change detecti
25740 6f 6e 20 69 73 20 64 69 73 61 62 6c 65 64 2e 20  on is disabled. 
25750 20 43 61 75 74 69 6f 6e 3a 20 53 65 74 74 69 6e   Caution: Settin
25760 67 20 74 68 65 20 69 6d 6d 75 74 61 62 6c 65 0a  g the immutable.
25770 2a 2a 20 20 20 20 20 70 72 6f 70 65 72 74 79 20  **     property 
25780 6f 6e 20 61 20 64 61 74 61 62 61 73 65 20 66 69  on a database fi
25790 6c 65 20 74 68 61 74 20 64 6f 65 73 20 69 6e 20  le that does in 
257a0 66 61 63 74 20 63 68 61 6e 67 65 20 63 61 6e 20  fact change can 
257b0 72 65 73 75 6c 74 0a 2a 2a 20 20 20 20 20 69 6e  result.**     in
257c0 20 69 6e 63 6f 72 72 65 63 74 20 71 75 65 72 79   incorrect query
257d0 20 72 65 73 75 6c 74 73 20 61 6e 64 2f 6f 72 20   results and/or 
257e0 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d  [SQLITE_CORRUPT]
257f0 20 65 72 72 6f 72 73 2e 0a 2a 2a 20 20 20 20 20   errors..**     
25800 53 65 65 20 61 6c 73 6f 3a 20 5b 53 51 4c 49 54  See also: [SQLIT
25810 45 5f 49 4f 43 41 50 5f 49 4d 4d 55 54 41 42 4c  E_IOCAP_IMMUTABL
25820 45 5d 2e 0a 2a 2a 20 20 20 20 20 20 20 0a 2a 2a  E]..**       .**
25830 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 53 70   </ul>.**.** ^Sp
25840 65 63 69 66 79 69 6e 67 20 61 6e 20 75 6e 6b 6e  ecifying an unkn
25850 6f 77 6e 20 70 61 72 61 6d 65 74 65 72 20 69 6e  own parameter in
25860 20 74 68 65 20 71 75 65 72 79 20 63 6f 6d 70 6f   the query compo
25870 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 20 69 73  nent of a URI is
25880 20 6e 6f 74 20 61 6e 0a 2a 2a 20 65 72 72 6f 72   not an.** error
25890 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f  .  Future versio
258a0 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67  ns of SQLite mig
258b0 68 74 20 75 6e 64 65 72 73 74 61 6e 64 20 61 64  ht understand ad
258c0 64 69 74 69 6f 6e 61 6c 20 71 75 65 72 79 0a 2a  ditional query.*
258d0 2a 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20 53  * parameters.  S
258e0 65 65 20 22 5b 71 75 65 72 79 20 70 61 72 61 6d  ee "[query param
258f0 65 74 65 72 73 20 77 69 74 68 20 73 70 65 63 69  eters with speci
25900 61 6c 20 6d 65 61 6e 69 6e 67 20 74 6f 20 53 51  al meaning to SQ
25910 4c 69 74 65 5d 22 20 66 6f 72 0a 2a 2a 20 61 64  Lite]" for.** ad
25920 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61  ditional informa
25930 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52  tion..**.** [[UR
25940 49 20 66 69 6c 65 6e 61 6d 65 20 65 78 61 6d 70  I filename examp
25950 6c 65 73 5d 5d 20 3c 68 33 3e 55 52 49 20 66 69  les]] <h3>URI fi
25960 6c 65 6e 61 6d 65 20 65 78 61 6d 70 6c 65 73 3c  lename examples<
25970 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 3c 74 61 62 6c  /h3>.**.** <tabl
25980 65 20 62 6f 72 64 65 72 3d 22 31 22 20 61 6c 69  e border="1" ali
25990 67 6e 3d 63 65 6e 74 65 72 20 63 65 6c 6c 70 61  gn=center cellpa
259a0 64 64 69 6e 67 3d 35 3e 0a 2a 2a 20 3c 74 72 3e  dding=5>.** <tr>
259b0 3c 74 68 3e 20 55 52 49 20 66 69 6c 65 6e 61 6d  <th> URI filenam
259c0 65 73 20 3c 74 68 3e 20 52 65 73 75 6c 74 73 0a  es <th> Results.
259d0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65  ** <tr><td> file
259e0 3a 64 61 74 61 2e 64 62 20 3c 74 64 3e 20 0a 2a  :data.db <td> .*
259f0 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20  *          Open 
25a00 74 68 65 20 66 69 6c 65 20 22 64 61 74 61 2e 64  the file "data.d
25a10 62 22 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e  b" in the curren
25a20 74 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 20  t directory..** 
25a30 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 68  <tr><td> file:/h
25a40 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62  ome/fred/data.db
25a50 3c 62 72 3e 0a 2a 2a 20 20 20 20 20 20 20 20 20  <br>.**         
25a60 20 66 69 6c 65 3a 2f 2f 2f 68 6f 6d 65 2f 66 72   file:///home/fr
25a70 65 64 2f 64 61 74 61 2e 64 62 20 3c 62 72 3e 20  ed/data.db <br> 
25a80 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c  .**          fil
25a90 65 3a 2f 2f 6c 6f 63 61 6c 68 6f 73 74 2f 68 6f  e://localhost/ho
25aa0 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 20  me/fred/data.db 
25ab0 3c 62 72 3e 20 3c 74 64 3e 20 0a 2a 2a 20 20 20  <br> <td> .**   
25ac0 20 20 20 20 20 20 20 4f 70 65 6e 20 74 68 65 20         Open the 
25ad0 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 22 2f  database file "/
25ae0 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64  home/fred/data.d
25af0 62 22 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  b"..** <tr><td> 
25b00 66 69 6c 65 3a 2f 2f 64 61 72 6b 73 74 61 72 2f  file://darkstar/
25b10 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64  home/fred/data.d
25b20 62 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20  b <td> .**      
25b30 20 20 20 20 41 6e 20 65 72 72 6f 72 2e 20 22 64      An error. "d
25b40 61 72 6b 73 74 61 72 22 20 69 73 20 6e 6f 74 20  arkstar" is not 
25b50 61 20 72 65 63 6f 67 6e 69 7a 65 64 20 61 75 74  a recognized aut
25b60 68 6f 72 69 74 79 2e 0a 2a 2a 20 3c 74 72 3e 3c  hority..** <tr><
25b70 74 64 20 73 74 79 6c 65 3d 22 77 68 69 74 65 2d  td style="white-
25b80 73 70 61 63 65 3a 6e 6f 77 72 61 70 22 3e 20 0a  space:nowrap"> .
25b90 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c 65  **          file
25ba0 3a 2f 2f 2f 43 3a 2f 44 6f 63 75 6d 65 6e 74 73  :///C:/Documents
25bb0 25 32 30 61 6e 64 25 32 30 53 65 74 74 69 6e 67  %20and%20Setting
25bc0 73 2f 66 72 65 64 2f 44 65 73 6b 74 6f 70 2f 64  s/fred/Desktop/d
25bd0 61 74 61 2e 64 62 0a 2a 2a 20 20 20 20 20 3c 74  ata.db.**     <t
25be0 64 3e 20 57 69 6e 64 6f 77 73 20 6f 6e 6c 79 3a  d> Windows only:
25bf0 20 4f 70 65 6e 20 74 68 65 20 66 69 6c 65 20 22   Open the file "
25c00 64 61 74 61 2e 64 62 22 20 6f 6e 20 66 72 65 64  data.db" on fred
25c10 27 73 20 64 65 73 6b 74 6f 70 20 6f 6e 20 64 72  's desktop on dr
25c20 69 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ive.**          
25c30 43 3a 2e 20 4e 6f 74 65 20 74 68 61 74 20 74 68  C:. Note that th
25c40 65 20 25 32 30 20 65 73 63 61 70 69 6e 67 20 69  e %20 escaping i
25c50 6e 20 74 68 69 73 20 65 78 61 6d 70 6c 65 20 69  n this example i
25c60 73 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 0a  s not strictly .
25c70 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 65 63 65  **          nece
25c80 73 73 61 72 79 20 2d 20 73 70 61 63 65 20 63 68  ssary - space ch
25c90 61 72 61 63 74 65 72 73 20 63 61 6e 20 62 65 20  aracters can be 
25ca0 75 73 65 64 20 6c 69 74 65 72 61 6c 6c 79 0a 2a  used literally.*
25cb0 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20 55 52  *          in UR
25cc0 49 20 66 69 6c 65 6e 61 6d 65 73 2e 0a 2a 2a 20  I filenames..** 
25cd0 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61  <tr><td> file:da
25ce0 74 61 2e 64 62 3f 6d 6f 64 65 3d 72 6f 26 63 61  ta.db?mode=ro&ca
25cf0 63 68 65 3d 70 72 69 76 61 74 65 20 3c 74 64 3e  che=private <td>
25d00 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70   .**          Op
25d10 65 6e 20 66 69 6c 65 20 22 64 61 74 61 2e 64 62  en file "data.db
25d20 22 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74  " in the current
25d30 20 64 69 72 65 63 74 6f 72 79 20 66 6f 72 20 72   directory for r
25d40 65 61 64 2d 6f 6e 6c 79 20 61 63 63 65 73 73 2e  ead-only access.
25d50 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 52 65 67  .**          Reg
25d60 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68  ardless of wheth
25d70 65 72 20 6f 72 20 6e 6f 74 20 73 68 61 72 65 64  er or not shared
25d80 2d 63 61 63 68 65 20 6d 6f 64 65 20 69 73 20 65  -cache mode is e
25d90 6e 61 62 6c 65 64 20 62 79 0a 2a 2a 20 20 20 20  nabled by.**    
25da0 20 20 20 20 20 20 64 65 66 61 75 6c 74 2c 20 75        default, u
25db0 73 65 20 61 20 70 72 69 76 61 74 65 20 63 61 63  se a private cac
25dc0 68 65 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  he..** <tr><td> 
25dd0 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f  file:/home/fred/
25de0 64 61 74 61 2e 64 62 3f 76 66 73 3d 75 6e 69 78  data.db?vfs=unix
25df0 2d 64 6f 74 66 69 6c 65 20 3c 74 64 3e 0a 2a 2a  -dotfile <td>.**
25e00 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20 66            Open f
25e10 69 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65 64 2f  ile "/home/fred/
25e20 64 61 74 61 2e 64 62 22 2e 20 55 73 65 20 74 68  data.db". Use th
25e30 65 20 73 70 65 63 69 61 6c 20 56 46 53 20 22 75  e special VFS "u
25e40 6e 69 78 2d 64 6f 74 66 69 6c 65 22 0a 2a 2a 20  nix-dotfile".** 
25e50 20 20 20 20 20 20 20 20 20 74 68 61 74 20 75 73           that us
25e60 65 73 20 64 6f 74 2d 66 69 6c 65 73 20 69 6e 20  es dot-files in 
25e70 70 6c 61 63 65 20 6f 66 20 70 6f 73 69 78 20 61  place of posix a
25e80 64 76 69 73 6f 72 79 20 6c 6f 63 6b 69 6e 67 2e  dvisory locking.
25e90 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c  .** <tr><td> fil
25ea0 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64 65 3d 72  e:data.db?mode=r
25eb0 65 61 64 6f 6e 6c 79 20 3c 74 64 3e 20 0a 2a 2a  eadonly <td> .**
25ec0 20 20 20 20 20 20 20 20 20 20 41 6e 20 65 72 72            An err
25ed0 6f 72 2e 20 22 72 65 61 64 6f 6e 6c 79 22 20 69  or. "readonly" i
25ee0 73 20 6e 6f 74 20 61 20 76 61 6c 69 64 20 6f 70  s not a valid op
25ef0 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 22 6d 6f  tion for the "mo
25f00 64 65 22 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  de" parameter..*
25f10 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 0a 2a 2a  * </table>.**.**
25f20 20 5e 55 52 49 20 68 65 78 61 64 65 63 69 6d 61   ^URI hexadecima
25f30 6c 20 65 73 63 61 70 65 20 73 65 71 75 65 6e 63  l escape sequenc
25f40 65 73 20 28 25 48 48 29 20 61 72 65 20 73 75 70  es (%HH) are sup
25f50 70 6f 72 74 65 64 20 77 69 74 68 69 6e 20 74 68  ported within th
25f60 65 20 70 61 74 68 20 61 6e 64 0a 2a 2a 20 71 75  e path and.** qu
25f70 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f  ery components o
25f80 66 20 61 20 55 52 49 2e 20 41 20 68 65 78 61 64  f a URI. A hexad
25f90 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73 65  ecimal escape se
25fa0 71 75 65 6e 63 65 20 63 6f 6e 73 69 73 74 73 20  quence consists 
25fb0 6f 66 20 61 0a 2a 2a 20 70 65 72 63 65 6e 74 20  of a.** percent 
25fc0 73 69 67 6e 20 2d 20 22 25 22 20 2d 20 66 6f 6c  sign - "%" - fol
25fd0 6c 6f 77 65 64 20 62 79 20 65 78 61 63 74 6c 79  lowed by exactly
25fe0 20 74 77 6f 20 68 65 78 61 64 65 63 69 6d 61 6c   two hexadecimal
25ff0 20 64 69 67 69 74 73 20 0a 2a 2a 20 73 70 65 63   digits .** spec
26000 69 66 79 69 6e 67 20 61 6e 20 6f 63 74 65 74 20  ifying an octet 
26010 76 61 6c 75 65 2e 20 5e 42 65 66 6f 72 65 20 74  value. ^Before t
26020 68 65 20 70 61 74 68 20 6f 72 20 71 75 65 72 79  he path or query
26030 20 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66 20 61   components of a
26040 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d 65  .** URI filename
26050 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64   are interpreted
26060 2c 20 74 68 65 79 20 61 72 65 20 65 6e 63 6f 64  , they are encod
26070 65 64 20 75 73 69 6e 67 20 55 54 46 2d 38 20 61  ed using UTF-8 a
26080 6e 64 20 61 6c 6c 20 0a 2a 2a 20 68 65 78 61 64  nd all .** hexad
26090 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73 65  ecimal escape se
260a0 71 75 65 6e 63 65 73 20 72 65 70 6c 61 63 65 64  quences replaced
260b0 20 62 79 20 61 20 73 69 6e 67 6c 65 20 62 79 74   by a single byt
260c0 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65  e containing the
260d0 0a 2a 2a 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  .** correspondin
260e0 67 20 6f 63 74 65 74 2e 20 49 66 20 74 68 69 73  g octet. If this
260f0 20 70 72 6f 63 65 73 73 20 67 65 6e 65 72 61 74   process generat
26100 65 73 20 61 6e 20 69 6e 76 61 6c 69 64 20 55 54  es an invalid UT
26110 46 2d 38 20 65 6e 63 6f 64 69 6e 67 2c 0a 2a 2a  F-8 encoding,.**
26120 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65   the results are
26130 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
26140 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e  * <b>Note to Win
26150 64 6f 77 73 20 75 73 65 72 73 3a 3c 2f 62 3e 20  dows users:</b> 
26160 20 54 68 65 20 65 6e 63 6f 64 69 6e 67 20 75 73   The encoding us
26170 65 64 20 66 6f 72 20 74 68 65 20 66 69 6c 65 6e  ed for the filen
26180 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  ame argument.** 
26190 6f 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  of sqlite3_open(
261a0 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70  ) and sqlite3_op
261b0 65 6e 5f 76 32 28 29 20 6d 75 73 74 20 62 65 20  en_v2() must be 
261c0 55 54 46 2d 38 2c 20 6e 6f 74 20 77 68 61 74 65  UTF-8, not whate
261d0 76 65 72 0a 2a 2a 20 63 6f 64 65 70 61 67 65 20  ver.** codepage 
261e0 69 73 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66  is currently def
261f0 69 6e 65 64 2e 20 20 46 69 6c 65 6e 61 6d 65 73  ined.  Filenames
26200 20 63 6f 6e 74 61 69 6e 69 6e 67 20 69 6e 74 65   containing inte
26210 72 6e 61 74 69 6f 6e 61 6c 0a 2a 2a 20 63 68 61  rnational.** cha
26220 72 61 63 74 65 72 73 20 6d 75 73 74 20 62 65 20  racters must be 
26230 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 55 54 46  converted to UTF
26240 2d 38 20 70 72 69 6f 72 20 74 6f 20 70 61 73 73  -8 prior to pass
26250 69 6e 67 20 74 68 65 6d 20 69 6e 74 6f 0a 2a 2a  ing them into.**
26260 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20   sqlite3_open() 
26270 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  or sqlite3_open_
26280 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e  v2()..**.** <b>N
26290 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77 73 20 52  ote to Windows R
262a0 75 6e 74 69 6d 65 20 75 73 65 72 73 3a 3c 2f 62  untime users:</b
262b0 3e 20 20 54 68 65 20 74 65 6d 70 6f 72 61 72 79  >  The temporary
262c0 20 64 69 72 65 63 74 6f 72 79 20 6d 75 73 74 20   directory must 
262d0 62 65 20 73 65 74 0a 2a 2a 20 70 72 69 6f 72 20  be set.** prior 
262e0 74 6f 20 63 61 6c 6c 69 6e 67 20 73 71 6c 69 74  to calling sqlit
262f0 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c  e3_open() or sql
26300 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20  ite3_open_v2(). 
26310 20 4f 74 68 65 72 77 69 73 65 2c 20 76 61 72 69   Otherwise, vari
26320 6f 75 73 0a 2a 2a 20 66 65 61 74 75 72 65 73 20  ous.** features 
26330 74 68 61 74 20 72 65 71 75 69 72 65 20 74 68 65  that require the
26340 20 75 73 65 20 6f 66 20 74 65 6d 70 6f 72 61 72   use of temporar
26350 79 20 66 69 6c 65 73 20 6d 61 79 20 66 61 69 6c  y files may fail
26360 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
26370 3a 20 5b 73 71 6c 69 74 65 33 5f 74 65 6d 70 5f  : [sqlite3_temp_
26380 64 69 72 65 63 74 6f 72 79 5d 0a 2a 2f 0a 69 6e  directory].*/.in
26390 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 0a  t sqlite3_open(.
263a0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69    const char *fi
263b0 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74  lename,   /* Dat
263c0 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28  abase filename (
263d0 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69  UTF-8) */.  sqli
263e0 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20  te3 **ppDb      
263f0 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69      /* OUT: SQLi
26400 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a  te db handle */.
26410 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f  );.int sqlite3_o
26420 70 65 6e 31 36 28 0a 20 20 63 6f 6e 73 74 20 76  pen16(.  const v
26430 6f 69 64 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20  oid *filename,  
26440 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c   /* Database fil
26450 65 6e 61 6d 65 20 28 55 54 46 2d 31 36 29 20 2a  ename (UTF-16) *
26460 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70  /.  sqlite3 **pp
26470 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f  Db          /* O
26480 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61  UT: SQLite db ha
26490 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73  ndle */.);.int s
264a0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 0a  qlite3_open_v2(.
264b0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69    const char *fi
264c0 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74  lename,   /* Dat
264d0 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28  abase filename (
264e0 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69  UTF-8) */.  sqli
264f0 74 65 33 20 2a 2a 70 70 44 62 2c 20 20 20 20 20  te3 **ppDb,     
26500 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69      /* OUT: SQLi
26510 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a  te db handle */.
26520 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 20 20 20    int flags,    
26530 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46 6c 61            /* Fla
26540 67 73 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  gs */.  const ch
26550 61 72 20 2a 7a 56 66 73 20 20 20 20 20 20 20 20  ar *zVfs        
26560 2f 2a 20 4e 61 6d 65 20 6f 66 20 56 46 53 20 6d  /* Name of VFS m
26570 6f 64 75 6c 65 20 74 6f 20 75 73 65 20 2a 2f 0a  odule to use */.
26580 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
26590 45 46 3a 20 4f 62 74 61 69 6e 20 56 61 6c 75 65  EF: Obtain Value
265a0 73 20 46 6f 72 20 55 52 49 20 50 61 72 61 6d 65  s For URI Parame
265b0 74 65 72 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ters.**.** These
265c0 20 61 72 65 20 75 74 69 6c 69 74 79 20 72 6f 75   are utility rou
265d0 74 69 6e 65 73 2c 20 75 73 65 66 75 6c 20 74 6f  tines, useful to
265e0 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74   VFS implementat
265f0 69 6f 6e 73 2c 20 74 68 61 74 20 63 68 65 63 6b  ions, that check
26600 0a 2a 2a 20 74 6f 20 73 65 65 20 69 66 20 61 20  .** to see if a 
26610 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 61  database file wa
26620 73 20 61 20 55 52 49 20 74 68 61 74 20 63 6f 6e  s a URI that con
26630 74 61 69 6e 65 64 20 61 20 73 70 65 63 69 66 69  tained a specifi
26640 63 20 71 75 65 72 79 20 0a 2a 2a 20 70 61 72 61  c query .** para
26650 6d 65 74 65 72 2c 20 61 6e 64 20 69 66 20 73 6f  meter, and if so
26660 20 6f 62 74 61 69 6e 73 20 74 68 65 20 76 61 6c   obtains the val
26670 75 65 20 6f 66 20 74 68 61 74 20 71 75 65 72 79  ue of that query
26680 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a   parameter..**.*
26690 2a 20 49 66 20 46 20 69 73 20 74 68 65 20 64 61  * If F is the da
266a0 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20  tabase filename 
266b0 70 6f 69 6e 74 65 72 20 70 61 73 73 65 64 20 69  pointer passed i
266c0 6e 74 6f 20 74 68 65 20 78 4f 70 65 6e 28 29 20  nto the xOpen() 
266d0 6d 65 74 68 6f 64 20 6f 66 20 0a 2a 2a 20 61 20  method of .** a 
266e0 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  VFS implementati
266f0 6f 6e 20 77 68 65 6e 20 74 68 65 20 66 6c 61 67  on when the flag
26700 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78  s parameter to x
26710 4f 70 65 6e 28 29 20 68 61 73 20 6f 6e 65 20 6f  Open() has one o
26720 72 20 0a 2a 2a 20 6d 6f 72 65 20 6f 66 20 74 68  r .** more of th
26730 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55  e [SQLITE_OPEN_U
26740 52 49 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4f  RI] or [SQLITE_O
26750 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 20 62 69 74  PEN_MAIN_DB] bit
26760 73 20 73 65 74 20 61 6e 64 0a 2a 2a 20 50 20 69  s set and.** P i
26770 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
26780 65 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65  e query paramete
26790 72 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74  r, then.** sqlit
267a0 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72  e3_uri_parameter
267b0 28 46 2c 50 29 20 72 65 74 75 72 6e 73 20 74 68  (F,P) returns th
267c0 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 50  e value of the P
267d0 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 69 66  .** parameter if
267e0 20 69 74 20 65 78 69 73 74 73 20 6f 72 20 61 20   it exists or a 
267f0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 20  NULL pointer if 
26800 50 20 64 6f 65 73 20 6e 6f 74 20 61 70 70 65 61  P does not appea
26810 72 20 61 73 20 61 20 0a 2a 2a 20 71 75 65 72 79  r as a .** query
26820 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 46 2e   parameter on F.
26830 20 20 49 66 20 50 20 69 73 20 61 20 71 75 65 72    If P is a quer
26840 79 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 46  y parameter of F
26850 0a 2a 2a 20 68 61 73 20 6e 6f 20 65 78 70 6c 69  .** has no expli
26860 63 69 74 20 76 61 6c 75 65 2c 20 74 68 65 6e 20  cit value, then 
26870 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61  sqlite3_uri_para
26880 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74 75 72  meter(F,P) retur
26890 6e 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20  ns.** a pointer 
268a0 74 6f 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69  to an empty stri
268b0 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ng..**.** The sq
268c0 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61  lite3_uri_boolea
268d0 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65  n(F,P,B) routine
268e0 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 50 20   assumes that P 
268f0 69 73 20 61 20 62 6f 6f 6c 65 61 6e 0a 2a 2a 20  is a boolean.** 
26900 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20 72 65  parameter and re
26910 74 75 72 6e 73 20 74 72 75 65 20 28 31 29 20 6f  turns true (1) o
26920 72 20 66 61 6c 73 65 20 28 30 29 20 61 63 63 6f  r false (0) acco
26930 72 64 69 6e 67 20 74 6f 20 74 68 65 20 76 61 6c  rding to the val
26940 75 65 0a 2a 2a 20 6f 66 20 50 2e 20 20 54 68 65  ue.** of P.  The
26950 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f   sqlite3_uri_boo
26960 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74  lean(F,P,B) rout
26970 69 6e 65 20 72 65 74 75 72 6e 73 20 74 72 75 65  ine returns true
26980 20 28 31 29 20 69 66 20 74 68 65 0a 2a 2a 20 76   (1) if the.** v
26990 61 6c 75 65 20 6f 66 20 71 75 65 72 79 20 70 61  alue of query pa
269a0 72 61 6d 65 74 65 72 20 50 20 69 73 20 6f 6e 65  rameter P is one
269b0 20 6f 66 20 22 79 65 73 22 2c 20 22 74 72 75 65   of "yes", "true
269c0 22 2c 20 6f 72 20 22 6f 6e 22 20 69 6e 20 61 6e  ", or "on" in an
269d0 79 0a 2a 2a 20 63 61 73 65 20 6f 72 20 69 66 20  y.** case or if 
269e0 74 68 65 20 76 61 6c 75 65 20 62 65 67 69 6e 73  the value begins
269f0 20 77 69 74 68 20 61 20 6e 6f 6e 2d 7a 65 72 6f   with a non-zero
26a00 20 6e 75 6d 62 65 72 2e 20 20 54 68 65 20 0a 2a   number.  The .*
26a10 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f  * sqlite3_uri_bo
26a20 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75  olean(F,P,B) rou
26a30 74 69 6e 65 73 20 72 65 74 75 72 6e 73 20 66 61  tines returns fa
26a40 6c 73 65 20 28 30 29 20 69 66 20 74 68 65 20 76  lse (0) if the v
26a50 61 6c 75 65 20 6f 66 0a 2a 2a 20 71 75 65 72 79  alue of.** query
26a60 20 70 61 72 61 6d 65 74 65 72 20 50 20 69 73 20   parameter P is 
26a70 6f 6e 65 20 6f 66 20 22 6e 6f 22 2c 20 22 66 61  one of "no", "fa
26a80 6c 73 65 22 2c 20 6f 72 20 22 6f 66 66 22 20 69  lse", or "off" i
26a90 6e 20 61 6e 79 20 63 61 73 65 20 6f 72 0a 2a 2a  n any case or.**
26aa0 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 62 65   if the value be
26ab0 67 69 6e 73 20 77 69 74 68 20 61 20 6e 75 6d 65  gins with a nume
26ac0 72 69 63 20 7a 65 72 6f 2e 20 20 49 66 20 50 20  ric zero.  If P 
26ad0 69 73 20 6e 6f 74 20 61 20 71 75 65 72 79 0a 2a  is not a query.*
26ae0 2a 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 46  * parameter on F
26af0 20 6f 72 20 69 66 20 74 68 65 20 76 61 6c 75 65   or if the value
26b00 20 6f 66 20 50 20 69 73 20 64 6f 65 73 20 6e 6f   of P is does no
26b10 74 20 6d 61 74 63 68 20 61 6e 79 20 6f 66 20 74  t match any of t
26b20 68 65 0a 2a 2a 20 61 62 6f 76 65 2c 20 74 68 65  he.** above, the
26b30 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f  n sqlite3_uri_bo
26b40 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 65 74  olean(F,P,B) ret
26b50 75 72 6e 73 20 28 42 21 3d 30 29 2e 0a 2a 2a 0a  urns (B!=0)..**.
26b60 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75  ** The sqlite3_u
26b70 72 69 5f 69 6e 74 36 34 28 46 2c 50 2c 44 29 20  ri_int64(F,P,D) 
26b80 72 6f 75 74 69 6e 65 20 63 6f 6e 76 65 72 74 73  routine converts
26b90 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20   the value of P 
26ba0 69 6e 74 6f 20 61 0a 2a 2a 20 36 34 2d 62 69 74  into a.** 64-bit
26bb0 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20   signed integer 
26bc0 61 6e 64 20 72 65 74 75 72 6e 73 20 74 68 61 74  and returns that
26bd0 20 69 6e 74 65 67 65 72 2c 20 6f 72 20 44 20 69   integer, or D i
26be0 66 20 50 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20  f P does not.** 
26bf0 65 78 69 73 74 2e 20 20 49 66 20 74 68 65 20 76  exist.  If the v
26c00 61 6c 75 65 20 6f 66 20 50 20 69 73 20 73 6f 6d  alue of P is som
26c10 65 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61  ething other tha
26c20 6e 20 61 6e 20 69 6e 74 65 67 65 72 2c 20 74 68  n an integer, th
26c30 65 6e 0a 2a 2a 20 7a 65 72 6f 20 69 73 20 72 65  en.** zero is re
26c40 74 75 72 6e 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 49  turned..** .** I
26c50 66 20 46 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  f F is a NULL po
26c60 69 6e 74 65 72 2c 20 74 68 65 6e 20 73 71 6c 69  inter, then sqli
26c70 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65  te3_uri_paramete
26c80 72 28 46 2c 50 29 20 72 65 74 75 72 6e 73 20 4e  r(F,P) returns N
26c90 55 4c 4c 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74  ULL and.** sqlit
26ca0 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46  e3_uri_boolean(F
26cb0 2c 50 2c 42 29 20 72 65 74 75 72 6e 73 20 42 2e  ,P,B) returns B.
26cc0 20 20 49 66 20 46 20 69 73 20 6e 6f 74 20 61 20    If F is not a 
26cd0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 61 6e 64  NULL pointer and
26ce0 0a 2a 2a 20 69 73 20 6e 6f 74 20 61 20 64 61 74  .** is not a dat
26cf0 61 62 61 73 65 20 66 69 6c 65 20 70 61 74 68 6e  abase file pathn
26d00 61 6d 65 20 70 6f 69 6e 74 65 72 20 74 68 61 74  ame pointer that
26d10 20 53 51 4c 69 74 65 20 70 61 73 73 65 64 20 69   SQLite passed i
26d20 6e 74 6f 20 74 68 65 20 78 4f 70 65 6e 0a 2a 2a  nto the xOpen.**
26d30 20 56 46 53 20 6d 65 74 68 6f 64 2c 20 74 68 65   VFS method, the
26d40 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f  n the behavior o
26d50 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69  f this routine i
26d60 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20  s undefined and 
26d70 70 72 6f 62 61 62 6c 79 0a 2a 2a 20 75 6e 64 65  probably.** unde
26d80 73 69 72 61 62 6c 65 2e 0a 2a 2f 0a 63 6f 6e 73  sirable..*/.cons
26d90 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
26da0 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28 63 6f  uri_parameter(co
26db0 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e  nst char *zFilen
26dc0 61 6d 65 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  ame, const char 
26dd0 2a 7a 50 61 72 61 6d 29 3b 0a 69 6e 74 20 73 71  *zParam);.int sq
26de0 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61  lite3_uri_boolea
26df0 6e 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46  n(const char *zF
26e00 69 6c 65 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  ile, const char 
26e10 2a 7a 50 61 72 61 6d 2c 20 69 6e 74 20 62 44 65  *zParam, int bDe
26e20 66 61 75 6c 74 29 3b 0a 73 71 6c 69 74 65 33 5f  fault);.sqlite3_
26e30 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 75 72  int64 sqlite3_ur
26e40 69 5f 69 6e 74 36 34 28 63 6f 6e 73 74 20 63 68  i_int64(const ch
26e50 61 72 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a  ar*, const char*
26e60 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29  , sqlite3_int64)
26e70 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  ;.../*.** CAPI3R
26e80 45 46 3a 20 45 72 72 6f 72 20 43 6f 64 65 73 20  EF: Error Codes 
26e90 41 6e 64 20 4d 65 73 73 61 67 65 73 0a 2a 2a 20  And Messages.** 
26ea0 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a  METHOD: sqlite3.
26eb0 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f  **.** ^If the mo
26ec0 73 74 20 72 65 63 65 6e 74 20 73 71 6c 69 74 65  st recent sqlite
26ed0 33 5f 2a 20 41 50 49 20 63 61 6c 6c 20 61 73 73  3_* API call ass
26ee0 6f 63 69 61 74 65 64 20 77 69 74 68 20 0a 2a 2a  ociated with .**
26ef0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
26f00 63 74 69 6f 6e 5d 20 44 20 66 61 69 6c 65 64 2c  ction] D failed,
26f10 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65   then the sqlite
26f20 33 5f 65 72 72 63 6f 64 65 28 44 29 20 69 6e 74  3_errcode(D) int
26f30 65 72 66 61 63 65 0a 2a 2a 20 72 65 74 75 72 6e  erface.** return
26f40 73 20 74 68 65 20 6e 75 6d 65 72 69 63 20 5b 72  s the numeric [r
26f50 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 20 5b  esult code] or [
26f60 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
26f70 63 6f 64 65 5d 20 66 6f 72 20 74 68 61 74 0a 2a  code] for that.*
26f80 2a 20 41 50 49 20 63 61 6c 6c 2e 0a 2a 2a 20 49  * API call..** I
26f90 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  f the most recen
26fa0 74 20 41 50 49 20 63 61 6c 6c 20 77 61 73 20 73  t API call was s
26fb0 75 63 63 65 73 73 66 75 6c 2c 0a 2a 2a 20 74 68  uccessful,.** th
26fc0 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  en the return va
26fd0 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  lue from sqlite3
26fe0 5f 65 72 72 63 6f 64 65 28 29 20 69 73 20 75 6e  _errcode() is un
26ff0 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 5e 54 68 65  defined..** ^The
27000 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65   sqlite3_extende
27010 64 5f 65 72 72 63 6f 64 65 28 29 0a 2a 2a 20 69  d_errcode().** i
27020 6e 74 65 72 66 61 63 65 20 69 73 20 74 68 65 20  nterface is the 
27030 73 61 6d 65 20 65 78 63 65 70 74 20 74 68 61 74  same except that
27040 20 69 74 20 61 6c 77 61 79 73 20 72 65 74 75 72   it always retur
27050 6e 73 20 74 68 65 20 0a 2a 2a 20 5b 65 78 74 65  ns the .** [exte
27060 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
27070 5d 20 65 76 65 6e 20 77 68 65 6e 20 65 78 74 65  ] even when exte
27080 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
27090 73 20 61 72 65 0a 2a 2a 20 64 69 73 61 62 6c 65  s are.** disable
270a0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  d..**.** ^The sq
270b0 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 20 61  lite3_errmsg() a
270c0 6e 64 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  nd sqlite3_errms
270d0 67 31 36 28 29 20 72 65 74 75 72 6e 20 45 6e 67  g16() return Eng
270e0 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65 0a 2a 2a  lish-language.**
270f0 20 74 65 78 74 20 74 68 61 74 20 64 65 73 63 72   text that descr
27100 69 62 65 73 20 74 68 65 20 65 72 72 6f 72 2c 20  ibes the error, 
27110 61 73 20 65 69 74 68 65 72 20 55 54 46 2d 38 20  as either UTF-8 
27120 6f 72 20 55 54 46 2d 31 36 20 72 65 73 70 65 63  or UTF-16 respec
27130 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e 28 4d 65 6d  tively..** ^(Mem
27140 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20  ory to hold the 
27150 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74  error message st
27160 72 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 64 20  ring is managed 
27170 69 6e 74 65 72 6e 61 6c 6c 79 2e 0a 2a 2a 20 54  internally..** T
27180 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  he application d
27190 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20  oes not need to 
271a0 77 6f 72 72 79 20 61 62 6f 75 74 20 66 72 65 65  worry about free
271b0 69 6e 67 20 74 68 65 20 72 65 73 75 6c 74 2e 0a  ing the result..
271c0 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74 68 65 20  ** However, the 
271d0 65 72 72 6f 72 20 73 74 72 69 6e 67 20 6d 69 67  error string mig
271e0 68 74 20 62 65 20 6f 76 65 72 77 72 69 74 74 65  ht be overwritte
271f0 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 65 64  n or deallocated
27200 20 62 79 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e   by.** subsequen
27210 74 20 63 61 6c 6c 73 20 74 6f 20 6f 74 68 65 72  t calls to other
27220 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
27230 65 20 66 75 6e 63 74 69 6f 6e 73 2e 29 5e 0a 2a  e functions.)^.*
27240 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
27250 33 5f 65 72 72 73 74 72 28 29 20 69 6e 74 65 72  3_errstr() inter
27260 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65  face returns the
27270 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67   English-languag
27280 65 20 74 65 78 74 0a 2a 2a 20 74 68 61 74 20 64  e text.** that d
27290 65 73 63 72 69 62 65 73 20 74 68 65 20 5b 72 65  escribes the [re
272a0 73 75 6c 74 20 63 6f 64 65 5d 2c 20 61 73 20 55  sult code], as U
272b0 54 46 2d 38 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72  TF-8..** ^(Memor
272c0 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 65 72  y to hold the er
272d0 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72 69  ror message stri
272e0 6e 67 20 69 73 20 6d 61 6e 61 67 65 64 20 69 6e  ng is managed in
272f0 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 61 6e 64 20  ternally.** and 
27300 6d 75 73 74 20 6e 6f 74 20 62 65 20 66 72 65 65  must not be free
27310 64 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 61  d by the applica
27320 74 69 6f 6e 29 5e 2e 0a 2a 2a 0a 2a 2a 20 57 68  tion)^..**.** Wh
27330 65 6e 20 74 68 65 20 73 65 72 69 61 6c 69 7a 65  en the serialize
27340 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  d [threading mod
27350 65 5d 20 69 73 20 69 6e 20 75 73 65 2c 20 69 74  e] is in use, it
27360 20 6d 69 67 68 74 20 62 65 20 74 68 65 0a 2a 2a   might be the.**
27370 20 63 61 73 65 20 74 68 61 74 20 61 20 73 65 63   case that a sec
27380 6f 6e 64 20 65 72 72 6f 72 20 6f 63 63 75 72 73  ond error occurs
27390 20 6f 6e 20 61 20 73 65 70 61 72 61 74 65 20 74   on a separate t
273a0 68 72 65 61 64 20 69 6e 20 62 65 74 77 65 65 6e  hread in between
273b0 0a 2a 2a 20 74 68 65 20 74 69 6d 65 20 6f 66 20  .** the time of 
273c0 74 68 65 20 66 69 72 73 74 20 65 72 72 6f 72 20  the first error 
273d0 61 6e 64 20 74 68 65 20 63 61 6c 6c 20 74 6f 20  and the call to 
273e0 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73  these interfaces
273f0 2e 0a 2a 2a 20 57 68 65 6e 20 74 68 61 74 20 68  ..** When that h
27400 61 70 70 65 6e 73 2c 20 74 68 65 20 73 65 63 6f  appens, the seco
27410 6e 64 20 65 72 72 6f 72 20 77 69 6c 6c 20 62 65  nd error will be
27420 20 72 65 70 6f 72 74 65 64 20 73 69 6e 63 65 20   reported since 
27430 74 68 65 73 65 0a 2a 2a 20 69 6e 74 65 72 66 61  these.** interfa
27440 63 65 73 20 61 6c 77 61 79 73 20 72 65 70 6f 72  ces always repor
27450 74 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  t the most recen
27460 74 20 72 65 73 75 6c 74 2e 20 20 54 6f 20 61 76  t result.  To av
27470 6f 69 64 0a 2a 2a 20 74 68 69 73 2c 20 65 61 63  oid.** this, eac
27480 68 20 74 68 72 65 61 64 20 63 61 6e 20 6f 62 74  h thread can obt
27490 61 69 6e 20 65 78 63 6c 75 73 69 76 65 20 75 73  ain exclusive us
274a0 65 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61  e of the [databa
274b0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44  se connection] D
274c0 0a 2a 2a 20 62 79 20 69 6e 76 6f 6b 69 6e 67 20  .** by invoking 
274d0 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65  [sqlite3_mutex_e
274e0 6e 74 65 72 5d 28 5b 73 71 6c 69 74 65 33 5f 64  nter]([sqlite3_d
274f0 62 5f 6d 75 74 65 78 5d 28 44 29 29 20 62 65 66  b_mutex](D)) bef
27500 6f 72 65 20 62 65 67 69 6e 6e 69 6e 67 0a 2a 2a  ore beginning.**
27510 20 74 6f 20 75 73 65 20 44 20 61 6e 64 20 69 6e   to use D and in
27520 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  voking [sqlite3_
27530 6d 75 74 65 78 5f 6c 65 61 76 65 5d 28 5b 73 71  mutex_leave]([sq
27540 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28  lite3_db_mutex](
27550 44 29 29 20 61 66 74 65 72 0a 2a 2a 20 61 6c 6c  D)) after.** all
27560 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 69 6e   calls to the in
27570 74 65 72 66 61 63 65 73 20 6c 69 73 74 65 64 20  terfaces listed 
27580 68 65 72 65 20 61 72 65 20 63 6f 6d 70 6c 65 74  here are complet
27590 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20  ed..**.** If an 
275a0 69 6e 74 65 72 66 61 63 65 20 66 61 69 6c 73 20  interface fails 
275b0 77 69 74 68 20 53 51 4c 49 54 45 5f 4d 49 53 55  with SQLITE_MISU
275c0 53 45 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74  SE, that means t
275d0 68 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  he interface.** 
275e0 77 61 73 20 69 6e 76 6f 6b 65 64 20 69 6e 63 6f  was invoked inco
275f0 72 72 65 63 74 6c 79 20 62 79 20 74 68 65 20 61  rrectly by the a
27600 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 49 6e 20  pplication.  In 
27610 74 68 61 74 20 63 61 73 65 2c 20 74 68 65 0a 2a  that case, the.*
27620 2a 20 65 72 72 6f 72 20 63 6f 64 65 20 61 6e 64  * error code and
27630 20 6d 65 73 73 61 67 65 20 6d 61 79 20 6f 72 20   message may or 
27640 6d 61 79 20 6e 6f 74 20 62 65 20 73 65 74 2e 0a  may not be set..
27650 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65  */.int sqlite3_e
27660 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20 2a  rrcode(sqlite3 *
27670 64 62 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  db);.int sqlite3
27680 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64  _extended_errcod
27690 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a  e(sqlite3 *db);.
276a0 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
276b0 74 65 33 5f 65 72 72 6d 73 67 28 73 71 6c 69 74  te3_errmsg(sqlit
276c0 65 33 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  e3*);.const void
276d0 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   *sqlite3_errmsg
276e0 31 36 28 73 71 6c 69 74 65 33 2a 29 3b 0a 63 6f  16(sqlite3*);.co
276f0 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
27700 33 5f 65 72 72 73 74 72 28 69 6e 74 29 3b 0a 0a  3_errstr(int);..
27710 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
27720 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65  Prepared Stateme
27730 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59  nt Object.** KEY
27740 57 4f 52 44 53 3a 20 7b 70 72 65 70 61 72 65 64  WORDS: {prepared
27750 20 73 74 61 74 65 6d 65 6e 74 7d 20 7b 70 72 65   statement} {pre
27760 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73  pared statements
27770 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61  }.**.** An insta
27780 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65  nce of this obje
27790 63 74 20 72 65 70 72 65 73 65 6e 74 73 20 61 20  ct represents a 
277a0 73 69 6e 67 6c 65 20 53 51 4c 20 73 74 61 74 65  single SQL state
277b0 6d 65 6e 74 20 74 68 61 74 0a 2a 2a 20 68 61 73  ment that.** has
277c0 20 62 65 65 6e 20 63 6f 6d 70 69 6c 65 64 20 69   been compiled i
277d0 6e 74 6f 20 62 69 6e 61 72 79 20 66 6f 72 6d 20  nto binary form 
277e0 61 6e 64 20 69 73 20 72 65 61 64 79 20 74 6f 20  and is ready to 
277f0 62 65 20 65 76 61 6c 75 61 74 65 64 2e 0a 2a 2a  be evaluated..**
27800 0a 2a 2a 20 54 68 69 6e 6b 20 6f 66 20 65 61 63  .** Think of eac
27810 68 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  h SQL statement 
27820 61 73 20 61 20 73 65 70 61 72 61 74 65 20 63 6f  as a separate co
27830 6d 70 75 74 65 72 20 70 72 6f 67 72 61 6d 2e 20  mputer program. 
27840 20 54 68 65 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c   The.** original
27850 20 53 51 4c 20 74 65 78 74 20 69 73 20 73 6f 75   SQL text is sou
27860 72 63 65 20 63 6f 64 65 2e 20 20 41 20 70 72 65  rce code.  A pre
27870 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
27880 6f 62 6a 65 63 74 20 0a 2a 2a 20 69 73 20 74 68  object .** is th
27890 65 20 63 6f 6d 70 69 6c 65 64 20 6f 62 6a 65 63  e compiled objec
278a0 74 20 63 6f 64 65 2e 20 20 41 6c 6c 20 53 51 4c  t code.  All SQL
278b0 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74   must be convert
278c0 65 64 20 69 6e 74 6f 20 61 0a 2a 2a 20 70 72 65  ed into a.** pre
278d0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
278e0 62 65 66 6f 72 65 20 69 74 20 63 61 6e 20 62 65  before it can be
278f0 20 72 75 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20   run..**.** The 
27900 6c 69 66 65 2d 63 79 63 6c 65 20 6f 66 20 61 20  life-cycle of a 
27910 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
27920 6e 74 20 6f 62 6a 65 63 74 20 75 73 75 61 6c 6c  nt object usuall
27930 79 20 67 6f 65 73 20 6c 69 6b 65 20 74 68 69 73  y goes like this
27940 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20  :.**.** <ol>.** 
27950 3c 6c 69 3e 20 43 72 65 61 74 65 20 74 68 65 20  <li> Create the 
27960 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
27970 6e 74 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20  nt object using 
27980 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
27990 5f 76 32 28 29 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20  _v2()]..** <li> 
279a0 42 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 5b  Bind values to [
279b0 70 61 72 61 6d 65 74 65 72 73 5d 20 75 73 69 6e  parameters] usin
279c0 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69  g the sqlite3_bi
279d0 6e 64 5f 2a 28 29 0a 2a 2a 20 20 20 20 20 20 69  nd_*().**      i
279e0 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 3c 6c  nterfaces..** <l
279f0 69 3e 20 52 75 6e 20 74 68 65 20 53 51 4c 20 62  i> Run the SQL b
27a00 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74  y calling [sqlit
27a10 65 33 5f 73 74 65 70 28 29 5d 20 6f 6e 65 20 6f  e3_step()] one o
27a20 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a  r more times..**
27a30 20 3c 6c 69 3e 20 52 65 73 65 74 20 74 68 65 20   <li> Reset the 
27a40 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
27a50 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  nt using [sqlite
27a60 33 5f 72 65 73 65 74 28 29 5d 20 74 68 65 6e 20  3_reset()] then 
27a70 67 6f 20 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20  go back.**      
27a80 74 6f 20 73 74 65 70 20 32 2e 20 20 44 6f 20 74  to step 2.  Do t
27a90 68 69 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65  his zero or more
27aa0 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20   times..** <li> 
27ab0 44 65 73 74 72 6f 79 20 74 68 65 20 6f 62 6a 65  Destroy the obje
27ac0 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ct using [sqlite
27ad0 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a  3_finalize()]..*
27ae0 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 74 79 70 65 64  * </ol>.*/.typed
27af0 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
27b00 33 5f 73 74 6d 74 20 73 71 6c 69 74 65 33 5f 73  3_stmt sqlite3_s
27b10 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  tmt;../*.** CAPI
27b20 33 52 45 46 3a 20 52 75 6e 2d 74 69 6d 65 20 4c  3REF: Run-time L
27b30 69 6d 69 74 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a  imits.** METHOD:
27b40 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e   sqlite3.**.** ^
27b50 28 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20  (This interface 
27b60 61 6c 6c 6f 77 73 20 74 68 65 20 73 69 7a 65 20  allows the size 
27b70 6f 66 20 76 61 72 69 6f 75 73 20 63 6f 6e 73 74  of various const
27b80 72 75 63 74 73 20 74 6f 20 62 65 20 6c 69 6d 69  ructs to be limi
27b90 74 65 64 0a 2a 2a 20 6f 6e 20 61 20 63 6f 6e 6e  ted.** on a conn
27ba0 65 63 74 69 6f 6e 20 62 79 20 63 6f 6e 6e 65 63  ection by connec
27bb0 74 69 6f 6e 20 62 61 73 69 73 2e 20 20 54 68 65  tion basis.  The
27bc0 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
27bd0 20 69 73 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61   is the.** [data
27be0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
27bf0 20 77 68 6f 73 65 20 6c 69 6d 69 74 20 69 73 20   whose limit is 
27c00 74 6f 20 62 65 20 73 65 74 20 6f 72 20 71 75 65  to be set or que
27c10 72 69 65 64 2e 20 20 54 68 65 0a 2a 2a 20 73 65  ried.  The.** se
27c20 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69  cond parameter i
27c30 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 5b 6c 69  s one of the [li
27c40 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 5d 20  mit categories] 
27c50 74 68 61 74 20 64 65 66 69 6e 65 20 61 0a 2a 2a  that define a.**
27c60 20 63 6c 61 73 73 20 6f 66 20 63 6f 6e 73 74 72   class of constr
27c70 75 63 74 73 20 74 6f 20 62 65 20 73 69 7a 65 20  ucts to be size 
27c80 6c 69 6d 69 74 65 64 2e 20 20 54 68 65 20 74 68  limited.  The th
27c90 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ird parameter is
27ca0 20 74 68 65 0a 2a 2a 20 6e 65 77 20 6c 69 6d 69   the.** new limi
27cb0 74 20 66 6f 72 20 74 68 61 74 20 63 6f 6e 73 74  t for that const
27cc0 72 75 63 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49  ruct.)^.**.** ^I
27cd0 66 20 74 68 65 20 6e 65 77 20 6c 69 6d 69 74 20  f the new limit 
27ce0 69 73 20 61 20 6e 65 67 61 74 69 76 65 20 6e 75  is a negative nu
27cf0 6d 62 65 72 2c 20 74 68 65 20 6c 69 6d 69 74 20  mber, the limit 
27d00 69 73 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a  is unchanged..**
27d10 20 5e 28 46 6f 72 20 65 61 63 68 20 6c 69 6d 69   ^(For each limi
27d20 74 20 63 61 74 65 67 6f 72 79 20 53 51 4c 49 54  t category SQLIT
27d30 45 5f 4c 49 4d 49 54 5f 3c 69 3e 4e 41 4d 45 3c  E_LIMIT_<i>NAME<
27d40 2f 69 3e 20 74 68 65 72 65 20 69 73 20 61 20 0a  /i> there is a .
27d50 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 68 61 72  ** [limits | har
27d60 64 20 75 70 70 65 72 20 62 6f 75 6e 64 5d 0a 2a  d upper bound].*
27d70 2a 20 73 65 74 20 61 74 20 63 6f 6d 70 69 6c 65  * set at compile
27d80 2d 74 69 6d 65 20 62 79 20 61 20 43 20 70 72 65  -time by a C pre
27d90 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20  processor macro 
27da0 63 61 6c 6c 65 64 0a 2a 2a 20 5b 6c 69 6d 69 74  called.** [limit
27db0 73 20 7c 20 53 51 4c 49 54 45 5f 4d 41 58 5f 3c  s | SQLITE_MAX_<
27dc0 69 3e 4e 41 4d 45 3c 2f 69 3e 5d 2e 0a 2a 2a 20  i>NAME</i>]..** 
27dd0 28 54 68 65 20 22 5f 4c 49 4d 49 54 5f 22 20 69  (The "_LIMIT_" i
27de0 6e 20 74 68 65 20 6e 61 6d 65 20 69 73 20 63 68  n the name is ch
27df0 61 6e 67 65 64 20 74 6f 20 22 5f 4d 41 58 5f 22  anged to "_MAX_"
27e00 2e 29 29 5e 0a 2a 2a 20 5e 41 74 74 65 6d 70 74  .))^.** ^Attempt
27e10 73 20 74 6f 20 69 6e 63 72 65 61 73 65 20 61 20  s to increase a 
27e20 6c 69 6d 69 74 20 61 62 6f 76 65 20 69 74 73 20  limit above its 
27e30 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64  hard upper bound
27e40 20 61 72 65 0a 2a 2a 20 73 69 6c 65 6e 74 6c 79   are.** silently
27e50 20 74 72 75 6e 63 61 74 65 64 20 74 6f 20 74 68   truncated to th
27e60 65 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75  e hard upper bou
27e70 6e 64 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65 67 61 72  nd..**.** ^Regar
27e80 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72  dless of whether
27e90 20 6f 72 20 6e 6f 74 20 74 68 65 20 6c 69 6d 69   or not the limi
27ea0 74 20 77 61 73 20 63 68 61 6e 67 65 64 2c 20 74  t was changed, t
27eb0 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  he .** [sqlite3_
27ec0 6c 69 6d 69 74 28 29 5d 20 69 6e 74 65 72 66 61  limit()] interfa
27ed0 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 70  ce returns the p
27ee0 72 69 6f 72 20 76 61 6c 75 65 20 6f 66 20 74 68  rior value of th
27ef0 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 48 65 6e  e limit..** ^Hen
27f00 63 65 2c 20 74 6f 20 66 69 6e 64 20 74 68 65 20  ce, to find the 
27f10 63 75 72 72 65 6e 74 20 76 61 6c 75 65 20 6f 66  current value of
27f20 20 61 20 6c 69 6d 69 74 20 77 69 74 68 6f 75 74   a limit without
27f30 20 63 68 61 6e 67 69 6e 67 20 69 74 2c 0a 2a 2a   changing it,.**
27f40 20 73 69 6d 70 6c 79 20 69 6e 76 6f 6b 65 20 74   simply invoke t
27f50 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 77 69  his interface wi
27f60 74 68 20 74 68 65 20 74 68 69 72 64 20 70 61 72  th the third par
27f70 61 6d 65 74 65 72 20 73 65 74 20 74 6f 20 2d 31  ameter set to -1
27f80 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e 2d 74 69 6d 65  ..**.** Run-time
27f90 20 6c 69 6d 69 74 73 20 61 72 65 20 69 6e 74 65   limits are inte
27fa0 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e 20  nded for use in 
27fb0 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61  applications tha
27fc0 74 20 6d 61 6e 61 67 65 0a 2a 2a 20 62 6f 74 68  t manage.** both
27fd0 20 74 68 65 69 72 20 6f 77 6e 20 69 6e 74 65 72   their own inter
27fe0 6e 61 6c 20 64 61 74 61 62 61 73 65 20 61 6e 64  nal database and
27ff0 20 61 6c 73 6f 20 64 61 74 61 62 61 73 65 73 20   also databases 
28000 74 68 61 74 20 61 72 65 20 63 6f 6e 74 72 6f 6c  that are control
28010 6c 65 64 0a 2a 2a 20 62 79 20 75 6e 74 72 75 73  led.** by untrus
28020 74 65 64 20 65 78 74 65 72 6e 61 6c 20 73 6f 75  ted external sou
28030 72 63 65 73 2e 20 20 41 6e 20 65 78 61 6d 70 6c  rces.  An exampl
28040 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 69  e application mi
28050 67 68 74 20 62 65 20 61 0a 2a 2a 20 77 65 62 20  ght be a.** web 
28060 62 72 6f 77 73 65 72 20 74 68 61 74 20 68 61 73  browser that has
28070 20 69 74 73 20 6f 77 6e 20 64 61 74 61 62 61 73   its own databas
28080 65 73 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 68  es for storing h
28090 69 73 74 6f 72 79 20 61 6e 64 0a 2a 2a 20 73 65  istory and.** se
280a0 70 61 72 61 74 65 20 64 61 74 61 62 61 73 65 73  parate databases
280b0 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62 79 20 4a   controlled by J
280c0 61 76 61 53 63 72 69 70 74 20 61 70 70 6c 69 63  avaScript applic
280d0 61 74 69 6f 6e 73 20 64 6f 77 6e 6c 6f 61 64 65  ations downloade
280e0 64 0a 2a 2a 20 6f 66 66 20 74 68 65 20 49 6e 74  d.** off the Int
280f0 65 72 6e 65 74 2e 20 20 54 68 65 20 69 6e 74 65  ernet.  The inte
28100 72 6e 61 6c 20 64 61 74 61 62 61 73 65 73 20 63  rnal databases c
28110 61 6e 20 62 65 20 67 69 76 65 6e 20 74 68 65 0a  an be given the.
28120 2a 2a 20 6c 61 72 67 65 2c 20 64 65 66 61 75 6c  ** large, defaul
28130 74 20 6c 69 6d 69 74 73 2e 20 20 44 61 74 61 62  t limits.  Datab
28140 61 73 65 73 20 6d 61 6e 61 67 65 64 20 62 79 20  ases managed by 
28150 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63 65 73  external sources
28160 20 63 61 6e 0a 2a 2a 20 62 65 20 67 69 76 65 6e   can.** be given
28170 20 6d 75 63 68 20 73 6d 61 6c 6c 65 72 20 6c 69   much smaller li
28180 6d 69 74 73 20 64 65 73 69 67 6e 65 64 20 74 6f  mits designed to
28190 20 70 72 65 76 65 6e 74 20 61 20 64 65 6e 69 61   prevent a denia
281a0 6c 20 6f 66 20 73 65 72 76 69 63 65 0a 2a 2a 20  l of service.** 
281b0 61 74 74 61 63 6b 2e 20 20 44 65 76 65 6c 6f 70  attack.  Develop
281c0 65 72 73 20 6d 69 67 68 74 20 61 6c 73 6f 20 77  ers might also w
281d0 61 6e 74 20 74 6f 20 75 73 65 20 74 68 65 20 5b  ant to use the [
281e0 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
281f0 6f 72 69 7a 65 72 28 29 5d 0a 2a 2a 20 69 6e 74  orizer()].** int
28200 65 72 66 61 63 65 20 74 6f 20 66 75 72 74 68 65  erface to furthe
28210 72 20 63 6f 6e 74 72 6f 6c 20 75 6e 74 72 75 73  r control untrus
28220 74 65 64 20 53 51 4c 2e 20 20 54 68 65 20 73 69  ted SQL.  The si
28230 7a 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  ze of the databa
28240 73 65 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 79  se.** created by
28250 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 73 63   an untrusted sc
28260 72 69 70 74 20 63 61 6e 20 62 65 20 63 6f 6e 74  ript can be cont
28270 61 69 6e 65 64 20 75 73 69 6e 67 20 74 68 65 0a  ained using the.
28280 2a 2a 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75  ** [max_page_cou
28290 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 2e 0a 2a 2a  nt] [PRAGMA]..**
282a0 0a 2a 2a 20 4e 65 77 20 72 75 6e 2d 74 69 6d 65  .** New run-time
282b0 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65   limit categorie
282c0 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69  s may be added i
282d0 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  n future release
282e0 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  s..*/.int sqlite
282f0 33 5f 6c 69 6d 69 74 28 73 71 6c 69 74 65 33 2a  3_limit(sqlite3*
28300 2c 20 69 6e 74 20 69 64 2c 20 69 6e 74 20 6e 65  , int id, int ne
28310 77 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  wVal);../*.** CA
28320 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65  PI3REF: Run-Time
28330 20 4c 69 6d 69 74 20 43 61 74 65 67 6f 72 69 65   Limit Categorie
28340 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  s.** KEYWORDS: {
28350 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79 7d 20  limit category} 
28360 7b 2a 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69  {*limit categori
28370 65 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  es}.**.** These 
28380 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65  constants define
28390 20 76 61 72 69 6f 75 73 20 70 65 72 66 6f 72 6d   various perform
283a0 61 6e 63 65 20 6c 69 6d 69 74 73 0a 2a 2a 20 74  ance limits.** t
283b0 68 61 74 20 63 61 6e 20 62 65 20 6c 6f 77 65 72  hat can be lower
283c0 65 64 20 61 74 20 72 75 6e 2d 74 69 6d 65 20 75  ed at run-time u
283d0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69  sing [sqlite3_li
283e0 6d 69 74 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73  mit()]..** The s
283f0 79 6e 6f 70 73 69 73 20 6f 66 20 74 68 65 20 6d  ynopsis of the m
28400 65 61 6e 69 6e 67 73 20 6f 66 20 74 68 65 20 76  eanings of the v
28410 61 72 69 6f 75 73 20 6c 69 6d 69 74 73 20 69 73  arious limits is
28420 20 73 68 6f 77 6e 20 62 65 6c 6f 77 2e 0a 2a 2a   shown below..**
28430 20 41 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f   Additional info
28440 72 6d 61 74 69 6f 6e 20 69 73 20 61 76 61 69 6c  rmation is avail
28450 61 62 6c 65 20 61 74 20 5b 6c 69 6d 69 74 73 20  able at [limits 
28460 7c 20 4c 69 6d 69 74 73 20 69 6e 20 53 51 4c 69  | Limits in SQLi
28470 74 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a  te]..**.** <dl>.
28480 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
28490 54 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74  T_LENGTH]] ^(<dt
284a0 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45  >SQLITE_LIMIT_LE
284b0 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  NGTH</dt>.** <dd
284c0 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a  >The maximum siz
284d0 65 20 6f 66 20 61 6e 79 20 73 74 72 69 6e 67 20  e of any string 
284e0 6f 72 20 42 4c 4f 42 20 6f 72 20 74 61 62 6c 65  or BLOB or table
284f0 20 72 6f 77 2c 20 69 6e 20 62 79 74 65 73 2e 3c   row, in bytes.<
28500 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  dd>)^.**.** [[SQ
28510 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c  LITE_LIMIT_SQL_L
28520 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51  ENGTH]] ^(<dt>SQ
28530 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c  LITE_LIMIT_SQL_L
28540 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ENGTH</dt>.** <d
28550 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65  d>The maximum le
28560 6e 67 74 68 20 6f 66 20 61 6e 20 53 51 4c 20 73  ngth of an SQL s
28570 74 61 74 65 6d 65 6e 74 2c 20 69 6e 20 62 79 74  tatement, in byt
28580 65 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  es.</dd>)^.**.**
28590 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
285a0 43 4f 4c 55 4d 4e 5d 5d 20 5e 28 3c 64 74 3e 53  COLUMN]] ^(<dt>S
285b0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55  QLITE_LIMIT_COLU
285c0 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  MN</dt>.** <dd>T
285d0 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
285e0 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20  r of columns in 
285f0 61 20 74 61 62 6c 65 20 64 65 66 69 6e 69 74 69  a table definiti
28600 6f 6e 20 6f 72 20 69 6e 20 74 68 65 0a 2a 2a 20  on or in the.** 
28610 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20  result set of a 
28620 5b 53 45 4c 45 43 54 5d 20 6f 72 20 74 68 65 20  [SELECT] or the 
28630 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
28640 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 6e 20  f columns in an 
28650 69 6e 64 65 78 0a 2a 2a 20 6f 72 20 69 6e 20 61  index.** or in a
28660 6e 20 4f 52 44 45 52 20 42 59 20 6f 72 20 47 52  n ORDER BY or GR
28670 4f 55 50 20 42 59 20 63 6c 61 75 73 65 2e 3c 2f  OUP BY clause.</
28680 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  dd>)^.**.** [[SQ
28690 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f  LITE_LIMIT_EXPR_
286a0 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51  DEPTH]] ^(<dt>SQ
286b0 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f  LITE_LIMIT_EXPR_
286c0 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  DEPTH</dt>.** <d
286d0 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 65  d>The maximum de
286e0 70 74 68 20 6f 66 20 74 68 65 20 70 61 72 73 65  pth of the parse
286f0 20 74 72 65 65 20 6f 6e 20 61 6e 79 20 65 78 70   tree on any exp
28700 72 65 73 73 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a  ression.</dd>)^.
28710 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  **.** [[SQLITE_L
28720 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45  IMIT_COMPOUND_SE
28730 4c 45 43 54 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c  LECT]] ^(<dt>SQL
28740 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55  ITE_LIMIT_COMPOU
28750 4e 44 5f 53 45 4c 45 43 54 3c 2f 64 74 3e 0a 2a  ND_SELECT</dt>.*
28760 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
28770 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74 65 72 6d  m number of term
28780 73 20 69 6e 20 61 20 63 6f 6d 70 6f 75 6e 64 20  s in a compound 
28790 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74  SELECT statement
287a0 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  .</dd>)^.**.** [
287b0 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44  [SQLITE_LIMIT_VD
287c0 42 45 5f 4f 50 5d 5d 20 5e 28 3c 64 74 3e 53 51  BE_OP]] ^(<dt>SQ
287d0 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f  LITE_LIMIT_VDBE_
287e0 4f 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  OP</dt>.** <dd>T
287f0 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
28800 72 20 6f 66 20 69 6e 73 74 72 75 63 74 69 6f 6e  r of instruction
28810 73 20 69 6e 20 61 20 76 69 72 74 75 61 6c 20 6d  s in a virtual m
28820 61 63 68 69 6e 65 20 70 72 6f 67 72 61 6d 0a 2a  achine program.*
28830 2a 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d  * used to implem
28840 65 6e 74 20 61 6e 20 53 51 4c 20 73 74 61 74 65  ent an SQL state
28850 6d 65 6e 74 2e 20 20 54 68 69 73 20 6c 69 6d 69  ment.  This limi
28860 74 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74  t is not current
28870 6c 79 0a 2a 2a 20 65 6e 66 6f 72 63 65 64 2c 20  ly.** enforced, 
28880 74 68 6f 75 67 68 20 74 68 61 74 20 6d 69 67 68  though that migh
28890 74 20 62 65 20 61 64 64 65 64 20 69 6e 20 73 6f  t be added in so
288a0 6d 65 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  me future releas
288b0 65 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 3c  e of.** SQLite.<
288c0 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  /dd>)^.**.** [[S
288d0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43  QLITE_LIMIT_FUNC
288e0 54 49 4f 4e 5f 41 52 47 5d 5d 20 5e 28 3c 64 74  TION_ARG]] ^(<dt
288f0 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55  >SQLITE_LIMIT_FU
28900 4e 43 54 49 4f 4e 5f 41 52 47 3c 2f 64 74 3e 0a  NCTION_ARG</dt>.
28910 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
28920 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67  um number of arg
28930 75 6d 65 6e 74 73 20 6f 6e 20 61 20 66 75 6e 63  uments on a func
28940 74 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  tion.</dd>)^.**.
28950 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
28960 54 5f 41 54 54 41 43 48 45 44 5d 5d 20 5e 28 3c  T_ATTACHED]] ^(<
28970 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
28980 41 54 54 41 43 48 45 44 3c 2f 64 74 3e 0a 2a 2a  ATTACHED</dt>.**
28990 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
289a0 20 6e 75 6d 62 65 72 20 6f 66 20 5b 41 54 54 41   number of [ATTA
289b0 43 48 20 7c 20 61 74 74 61 63 68 65 64 20 64 61  CH | attached da
289c0 74 61 62 61 73 65 73 5d 2e 29 5e 3c 2f 64 64 3e  tabases].)^</dd>
289d0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
289e0 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45  LIMIT_LIKE_PATTE
289f0 52 4e 5f 4c 45 4e 47 54 48 5d 5d 0a 2a 2a 20 5e  RN_LENGTH]].** ^
28a00 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
28a10 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c  T_LIKE_PATTERN_L
28a20 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ENGTH</dt>.** <d
28a30 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65  d>The maximum le
28a40 6e 67 74 68 20 6f 66 20 74 68 65 20 70 61 74 74  ngth of the patt
28a50 65 72 6e 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ern argument to 
28a60 74 68 65 20 5b 4c 49 4b 45 5d 20 6f 72 0a 2a 2a  the [LIKE] or.**
28a70 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72   [GLOB] operator
28a80 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  s.</dd>)^.**.** 
28a90 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56  [[SQLITE_LIMIT_V
28aa0 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 5d  ARIABLE_NUMBER]]
28ab0 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  .** ^(<dt>SQLITE
28ac0 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f  _LIMIT_VARIABLE_
28ad0 4e 55 4d 42 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c  NUMBER</dt>.** <
28ae0 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 69  dd>The maximum i
28af0 6e 64 65 78 20 6e 75 6d 62 65 72 20 6f 66 20 61  ndex number of a
28b00 6e 79 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 69  ny [parameter] i
28b10 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  n an SQL stateme
28b20 6e 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  nt.)^.**.** [[SQ
28b30 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47  LITE_LIMIT_TRIGG
28b40 45 52 5f 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74  ER_DEPTH]] ^(<dt
28b50 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52  >SQLITE_LIMIT_TR
28b60 49 47 47 45 52 5f 44 45 50 54 48 3c 2f 64 74 3e  IGGER_DEPTH</dt>
28b70 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
28b80 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 72 65 63  mum depth of rec
28b90 75 72 73 69 6f 6e 20 66 6f 72 20 74 72 69 67 67  ursion for trigg
28ba0 65 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  ers.</dd>)^.**.*
28bb0 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
28bc0 5f 57 4f 52 4b 45 52 5f 54 48 52 45 41 44 53 5d  _WORKER_THREADS]
28bd0 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  ] ^(<dt>SQLITE_L
28be0 49 4d 49 54 5f 57 4f 52 4b 45 52 5f 54 48 52 45  IMIT_WORKER_THRE
28bf0 41 44 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  ADS</dt>.** <dd>
28c00 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  The maximum numb
28c10 65 72 20 6f 66 20 61 75 78 69 6c 69 61 72 79 20  er of auxiliary 
28c20 77 6f 72 6b 65 72 20 74 68 72 65 61 64 73 20 74  worker threads t
28c30 68 61 74 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20  hat a single.** 
28c40 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
28c50 65 6e 74 5d 20 6d 61 79 20 73 74 61 72 74 2e 3c  ent] may start.<
28c60 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a  /dd>)^.** </dl>.
28c70 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
28c80 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 20 20  E_LIMIT_LENGTH  
28c90 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
28ca0 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    0.#define SQLI
28cb0 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e  TE_LIMIT_SQL_LEN
28cc0 47 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20  GTH             
28cd0 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c     1.#define SQL
28ce0 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e  ITE_LIMIT_COLUMN
28cf0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
28d00 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51      2.#define SQ
28d10 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f  LITE_LIMIT_EXPR_
28d20 44 45 50 54 48 20 20 20 20 20 20 20 20 20 20 20  DEPTH           
28d30 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53       3.#define S
28d40 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50  QLITE_LIMIT_COMP
28d50 4f 55 4e 44 5f 53 45 4c 45 43 54 20 20 20 20 20  OUND_SELECT     
28d60 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20        4.#define 
28d70 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42  SQLITE_LIMIT_VDB
28d80 45 5f 4f 50 20 20 20 20 20 20 20 20 20 20 20 20  E_OP            
28d90 20 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e 65         5.#define
28da0 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55   SQLITE_LIMIT_FU
28db0 4e 43 54 49 4f 4e 5f 41 52 47 20 20 20 20 20 20  NCTION_ARG      
28dc0 20 20 20 20 20 20 20 20 36 0a 23 64 65 66 69 6e          6.#defin
28dd0 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41  e SQLITE_LIMIT_A
28de0 54 54 41 43 48 45 44 20 20 20 20 20 20 20 20 20  TTACHED         
28df0 20 20 20 20 20 20 20 20 20 37 0a 23 64 65 66 69           7.#defi
28e00 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
28e10 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e  LIKE_PATTERN_LEN
28e20 47 54 48 20 20 20 20 20 20 20 38 0a 23 64 65 66  GTH       8.#def
28e30 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
28e40 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52  _VARIABLE_NUMBER
28e50 20 20 20 20 20 20 20 20 20 20 20 39 0a 23 64 65             9.#de
28e60 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
28e70 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48 20  T_TRIGGER_DEPTH 
28e80 20 20 20 20 20 20 20 20 20 20 20 31 30 0a 23 64             10.#d
28e90 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
28ea0 49 54 5f 57 4f 52 4b 45 52 5f 54 48 52 45 41 44  IT_WORKER_THREAD
28eb0 53 20 20 20 20 20 20 20 20 20 20 20 31 31 0a 0a  S           11..
28ec0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
28ed0 43 6f 6d 70 69 6c 69 6e 67 20 41 6e 20 53 51 4c  Compiling An SQL
28ee0 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 4b 45   Statement.** KE
28ef0 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 73 74 61  YWORDS: {SQL sta
28f00 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 72 7d  tement compiler}
28f10 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
28f20 74 65 33 0a 2a 2a 20 43 4f 4e 53 54 52 55 43 54  te3.** CONSTRUCT
28f30 4f 52 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  OR: sqlite3_stmt
28f40 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65 63 75 74  .**.** To execut
28f50 65 20 61 6e 20 53 51 4c 20 71 75 65 72 79 2c 20  e an SQL query, 
28f60 69 74 20 6d 75 73 74 20 66 69 72 73 74 20 62 65  it must first be
28f70 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20 61   compiled into a
28f80 20 62 79 74 65 2d 63 6f 64 65 0a 2a 2a 20 70 72   byte-code.** pr
28f90 6f 67 72 61 6d 20 75 73 69 6e 67 20 6f 6e 65 20  ogram using one 
28fa0 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
28fb0 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72  s..**.** The fir
28fc0 73 74 20 61 72 67 75 6d 65 6e 74 2c 20 22 64 62  st argument, "db
28fd0 22 2c 20 69 73 20 61 20 5b 64 61 74 61 62 61 73  ", is a [databas
28fe0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62  e connection] ob
28ff0 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 0a 2a 2a  tained from a.**
29000 20 70 72 69 6f 72 20 73 75 63 63 65 73 73 66 75   prior successfu
29010 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  l call to [sqlit
29020 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c  e3_open()], [sql
29030 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20  ite3_open_v2()] 
29040 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f  or.** [sqlite3_o
29050 70 65 6e 31 36 28 29 5d 2e 20 20 54 68 65 20 64  pen16()].  The d
29060 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
29070 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 68 61 76 65  on must not have
29080 20 62 65 65 6e 20 63 6c 6f 73 65 64 2e 0a 2a 2a   been closed..**
29090 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61  .** The second a
290a0 72 67 75 6d 65 6e 74 2c 20 22 7a 53 71 6c 22 2c  rgument, "zSql",
290b0 20 69 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e   is the statemen
290c0 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64  t to be compiled
290d0 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a 20 61 73 20  , encoded.** as 
290e0 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20  either UTF-8 or 
290f0 55 54 46 2d 31 36 2e 20 20 54 68 65 20 73 71 6c  UTF-16.  The sql
29100 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 20 61  ite3_prepare() a
29110 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nd sqlite3_prepa
29120 72 65 5f 76 32 28 29 0a 2a 2a 20 69 6e 74 65 72  re_v2().** inter
29130 66 61 63 65 73 20 75 73 65 20 55 54 46 2d 38 2c  faces use UTF-8,
29140 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65   and sqlite3_pre
29150 70 61 72 65 31 36 28 29 20 61 6e 64 20 73 71 6c  pare16() and sql
29160 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
29170 32 28 29 0a 2a 2a 20 75 73 65 20 55 54 46 2d 31  2().** use UTF-1
29180 36 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  6..**.** ^If the
29190 20 6e 42 79 74 65 20 61 72 67 75 6d 65 6e 74 20   nByte argument 
291a0 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65  is negative, the
291b0 6e 20 7a 53 71 6c 20 69 73 20 72 65 61 64 20 75  n zSql is read u
291c0 70 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 72 73  p to the.** firs
291d0 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f  t zero terminato
291e0 72 2e 20 5e 49 66 20 6e 42 79 74 65 20 69 73 20  r. ^If nByte is 
291f0 70 6f 73 69 74 69 76 65 2c 20 74 68 65 6e 20 69  positive, then i
29200 74 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62  t is the.** numb
29210 65 72 20 6f 66 20 62 79 74 65 73 20 72 65 61 64  er of bytes read
29220 20 66 72 6f 6d 20 7a 53 71 6c 2e 20 20 5e 49 66   from zSql.  ^If
29230 20 6e 42 79 74 65 20 69 73 20 7a 65 72 6f 2c 20   nByte is zero, 
29240 74 68 65 6e 20 6e 6f 20 70 72 65 70 61 72 65 64  then no prepared
29250 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 69 73  .** statement is
29260 20 67 65 6e 65 72 61 74 65 64 2e 0a 2a 2a 20 49   generated..** I
29270 66 20 74 68 65 20 63 61 6c 6c 65 72 20 6b 6e 6f  f the caller kno
29280 77 73 20 74 68 61 74 20 74 68 65 20 73 75 70 70  ws that the supp
29290 6c 69 65 64 20 73 74 72 69 6e 67 20 69 73 20 6e  lied string is n
292a0 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 2c 20 74  ul-terminated, t
292b0 68 65 6e 0a 2a 2a 20 74 68 65 72 65 20 69 73 20  hen.** there is 
292c0 61 20 73 6d 61 6c 6c 20 70 65 72 66 6f 72 6d 61  a small performa
292d0 6e 63 65 20 61 64 76 61 6e 74 61 67 65 20 74 6f  nce advantage to
292e0 20 70 61 73 73 69 6e 67 20 61 6e 20 6e 42 79 74   passing an nByt
292f0 65 20 70 61 72 61 6d 65 74 65 72 20 74 68 61 74  e parameter that
29300 0a 2a 2a 20 69 73 20 74 68 65 20 6e 75 6d 62 65  .** is the numbe
29310 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
29320 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 20 3c  e input string <
29330 69 3e 69 6e 63 6c 75 64 69 6e 67 3c 2f 69 3e 0a  i>including</i>.
29340 2a 2a 20 74 68 65 20 6e 75 6c 2d 74 65 72 6d 69  ** the nul-termi
29350 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  nator..**.** ^If
29360 20 70 7a 54 61 69 6c 20 69 73 20 6e 6f 74 20 4e   pzTail is not N
29370 55 4c 4c 20 74 68 65 6e 20 2a 70 7a 54 61 69 6c  ULL then *pzTail
29380 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e   is made to poin
29390 74 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 62  t to the first b
293a0 79 74 65 0a 2a 2a 20 70 61 73 74 20 74 68 65 20  yte.** past the 
293b0 65 6e 64 20 6f 66 20 74 68 65 20 66 69 72 73 74  end of the first
293c0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69   SQL statement i
293d0 6e 20 7a 53 71 6c 2e 20 20 54 68 65 73 65 20 72  n zSql.  These r
293e0 6f 75 74 69 6e 65 73 20 6f 6e 6c 79 0a 2a 2a 20  outines only.** 
293f0 63 6f 6d 70 69 6c 65 20 74 68 65 20 66 69 72 73  compile the firs
29400 74 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a  t statement in z
29410 53 71 6c 2c 20 73 6f 20 2a 70 7a 54 61 69 6c 20  Sql, so *pzTail 
29420 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67  is left pointing
29430 20 74 6f 0a 2a 2a 20 77 68 61 74 20 72 65 6d 61   to.** what rema
29440 69 6e 73 20 75 6e 63 6f 6d 70 69 6c 65 64 2e 0a  ins uncompiled..
29450 2a 2a 0a 2a 2a 20 5e 2a 70 70 53 74 6d 74 20 69  **.** ^*ppStmt i
29460 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20  s left pointing 
29470 74 6f 20 61 20 63 6f 6d 70 69 6c 65 64 20 5b 70  to a compiled [p
29480 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
29490 74 5d 20 74 68 61 74 20 63 61 6e 20 62 65 0a 2a  t] that can be.*
294a0 2a 20 65 78 65 63 75 74 65 64 20 75 73 69 6e 67  * executed using
294b0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
294c0 5d 2e 20 20 5e 49 66 20 74 68 65 72 65 20 69 73  ].  ^If there is
294d0 20 61 6e 20 65 72 72 6f 72 2c 20 2a 70 70 53 74   an error, *ppSt
294e0 6d 74 20 69 73 20 73 65 74 0a 2a 2a 20 74 6f 20  mt is set.** to 
294f0 4e 55 4c 4c 2e 20 20 5e 49 66 20 74 68 65 20 69  NULL.  ^If the i
29500 6e 70 75 74 20 74 65 78 74 20 63 6f 6e 74 61 69  nput text contai
29510 6e 73 20 6e 6f 20 53 51 4c 20 28 69 66 20 74 68  ns no SQL (if th
29520 65 20 69 6e 70 75 74 20 69 73 20 61 6e 20 65 6d  e input is an em
29530 70 74 79 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 72  pty.** string or
29540 20 61 20 63 6f 6d 6d 65 6e 74 29 20 74 68 65 6e   a comment) then
29550 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74 20   *ppStmt is set 
29560 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 54 68 65 20  to NULL..** The 
29570 63 61 6c 6c 69 6e 67 20 70 72 6f 63 65 64 75 72  calling procedur
29580 65 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65  e is responsible
29590 20 66 6f 72 20 64 65 6c 65 74 69 6e 67 20 74 68   for deleting th
295a0 65 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 53 51  e compiled.** SQ
295b0 4c 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e  L statement usin
295c0 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  g [sqlite3_final
295d0 69 7a 65 28 29 5d 20 61 66 74 65 72 20 69 74 20  ize()] after it 
295e0 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74  has finished wit
295f0 68 20 69 74 2e 0a 2a 2a 20 70 70 53 74 6d 74 20  h it..** ppStmt 
29600 6d 61 79 20 6e 6f 74 20 62 65 20 4e 55 4c 4c 2e  may not be NULL.
29610 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 20 73 75 63 63 65  .**.** ^On succe
29620 73 73 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ss, the sqlite3_
29630 70 72 65 70 61 72 65 28 29 20 66 61 6d 69 6c 79  prepare() family
29640 20 6f 66 20 72 6f 75 74 69 6e 65 73 20 72 65 74   of routines ret
29650 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 3b  urn [SQLITE_OK];
29660 0a 2a 2a 20 6f 74 68 65 72 77 69 73 65 20 61 6e  .** otherwise an
29670 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73   [error code] is
29680 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
29690 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65   The sqlite3_pre
296a0 70 61 72 65 5f 76 32 28 29 20 61 6e 64 20 73 71  pare_v2() and sq
296b0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
296c0 76 32 28 29 20 69 6e 74 65 72 66 61 63 65 73 20  v2() interfaces 
296d0 61 72 65 0a 2a 2a 20 72 65 63 6f 6d 6d 65 6e 64  are.** recommend
296e0 65 64 20 66 6f 72 20 61 6c 6c 20 6e 65 77 20 70  ed for all new p
296f0 72 6f 67 72 61 6d 73 2e 20 54 68 65 20 74 77 6f  rograms. The two
29700 20 6f 6c 64 65 72 20 69 6e 74 65 72 66 61 63 65   older interface
29710 73 20 61 72 65 20 72 65 74 61 69 6e 65 64 0a 2a  s are retained.*
29720 2a 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20  * for backwards 
29730 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2c 20 62  compatibility, b
29740 75 74 20 74 68 65 69 72 20 75 73 65 20 69 73 20  ut their use is 
29750 64 69 73 63 6f 75 72 61 67 65 64 2e 0a 2a 2a 20  discouraged..** 
29760 5e 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74  ^In the "v2" int
29770 65 72 66 61 63 65 73 2c 20 74 68 65 20 70 72 65  erfaces, the pre
29780 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a  pared statement.
29790 2a 2a 20 74 68 61 74 20 69 73 20 72 65 74 75 72  ** that is retur
297a0 6e 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65  ned (the [sqlite
297b0 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 29 20  3_stmt] object) 
297c0 63 6f 6e 74 61 69 6e 73 20 61 20 63 6f 70 79 20  contains a copy 
297d0 6f 66 20 74 68 65 0a 2a 2a 20 6f 72 69 67 69 6e  of the.** origin
297e0 61 6c 20 53 51 4c 20 74 65 78 74 2e 20 54 68 69  al SQL text. Thi
297f0 73 20 63 61 75 73 65 73 20 74 68 65 20 5b 73 71  s causes the [sq
29800 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 69 6e  lite3_step()] in
29810 74 65 72 66 61 63 65 20 74 6f 0a 2a 2a 20 62 65  terface to.** be
29820 68 61 76 65 20 64 69 66 66 65 72 65 6e 74 6c 79  have differently
29830 20 69 6e 20 74 68 72 65 65 20 77 61 79 73 3a 0a   in three ways:.
29840 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c  **.** <ol>.** <l
29850 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 64 61  i>.** ^If the da
29860 74 61 62 61 73 65 20 73 63 68 65 6d 61 20 63 68  tabase schema ch
29870 61 6e 67 65 73 2c 20 69 6e 73 74 65 61 64 20 6f  anges, instead o
29880 66 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c  f returning [SQL
29890 49 54 45 5f 53 43 48 45 4d 41 5d 20 61 73 20 69  ITE_SCHEMA] as i
298a0 74 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 64  t.** always used
298b0 20 74 6f 20 64 6f 2c 20 5b 73 71 6c 69 74 65 33   to do, [sqlite3
298c0 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 61 75  _step()] will au
298d0 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 63 6f  tomatically reco
298e0 6d 70 69 6c 65 20 74 68 65 20 53 51 4c 0a 2a 2a  mpile the SQL.**
298f0 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74   statement and t
29900 72 79 20 74 6f 20 72 75 6e 20 69 74 20 61 67 61  ry to run it aga
29910 69 6e 2e 20 41 73 20 6d 61 6e 79 20 61 73 20 5b  in. As many as [
29920 53 51 4c 49 54 45 5f 4d 41 58 5f 53 43 48 45 4d  SQLITE_MAX_SCHEM
29930 41 5f 52 45 54 52 59 5d 0a 2a 2a 20 72 65 74 72  A_RETRY].** retr
29940 69 65 73 20 77 69 6c 6c 20 6f 63 63 75 72 20 62  ies will occur b
29950 65 66 6f 72 65 20 73 71 6c 69 74 65 33 5f 73 74  efore sqlite3_st
29960 65 70 28 29 20 67 69 76 65 73 20 75 70 20 61 6e  ep() gives up an
29970 64 20 72 65 74 75 72 6e 73 20 61 6e 20 65 72 72  d returns an err
29980 6f 72 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a  or..** </li>.**.
29990 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 57 68 65 6e  ** <li>.** ^When
299a0 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73   an error occurs
299b0 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  , [sqlite3_step(
299c0 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 6f  )] will return o
299d0 6e 65 20 6f 66 20 74 68 65 20 64 65 74 61 69 6c  ne of the detail
299e0 65 64 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64  ed.** [error cod
299f0 65 73 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65 64  es] or [extended
29a00 20 65 72 72 6f 72 20 63 6f 64 65 73 5d 2e 20 20   error codes].  
29a10 5e 54 68 65 20 6c 65 67 61 63 79 20 62 65 68 61  ^The legacy beha
29a20 76 69 6f 72 20 77 61 73 20 74 68 61 74 0a 2a 2a  vior was that.**
29a30 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
29a40 5d 20 77 6f 75 6c 64 20 6f 6e 6c 79 20 72 65 74  ] would only ret
29a50 75 72 6e 20 61 20 67 65 6e 65 72 69 63 20 5b 53  urn a generic [S
29a60 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 72 65 73  QLITE_ERROR] res
29a70 75 6c 74 20 63 6f 64 65 0a 2a 2a 20 61 6e 64 20  ult code.** and 
29a80 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
29a90 77 6f 75 6c 64 20 68 61 76 65 20 74 6f 20 6d 61  would have to ma
29aa0 6b 65 20 61 20 73 65 63 6f 6e 64 20 63 61 6c 6c  ke a second call
29ab0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73   to [sqlite3_res
29ac0 65 74 28 29 5d 0a 2a 2a 20 69 6e 20 6f 72 64 65  et()].** in orde
29ad0 72 20 74 6f 20 66 69 6e 64 20 74 68 65 20 75 6e  r to find the un
29ae0 64 65 72 6c 79 69 6e 67 20 63 61 75 73 65 20 6f  derlying cause o
29af0 66 20 74 68 65 20 70 72 6f 62 6c 65 6d 2e 20 57  f the problem. W
29b00 69 74 68 20 74 68 65 20 22 76 32 22 20 70 72 65  ith the "v2" pre
29b10 70 61 72 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63  pare.** interfac
29b20 65 73 2c 20 74 68 65 20 75 6e 64 65 72 6c 79 69  es, the underlyi
29b30 6e 67 20 72 65 61 73 6f 6e 20 66 6f 72 20 74 68  ng reason for th
29b40 65 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72  e error is retur
29b50 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e  ned immediately.
29b60 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20  .** </li>.**.** 
29b70 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  <li>.** ^If the 
29b80 73 70 65 63 69 66 69 63 20 76 61 6c 75 65 20 62  specific value b
29b90 6f 75 6e 64 20 74 6f 20 5b 70 61 72 61 6d 65 74  ound to [paramet
29ba0 65 72 20 7c 20 68 6f 73 74 20 70 61 72 61 6d 65  er | host parame
29bb0 74 65 72 5d 20 69 6e 20 74 68 65 20 0a 2a 2a 20  ter] in the .** 
29bc0 57 48 45 52 45 20 63 6c 61 75 73 65 20 6d 69 67  WHERE clause mig
29bd0 68 74 20 69 6e 66 6c 75 65 6e 63 65 20 74 68 65  ht influence the
29be0 20 63 68 6f 69 63 65 20 6f 66 20 71 75 65 72 79   choice of query
29bf0 20 70 6c 61 6e 20 66 6f 72 20 61 20 73 74 61 74   plan for a stat
29c00 65 6d 65 6e 74 2c 0a 2a 2a 20 74 68 65 6e 20 74  ement,.** then t
29c10 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77 69 6c  he statement wil
29c20 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61 6c  l be automatical
29c30 6c 79 20 72 65 63 6f 6d 70 69 6c 65 64 2c 20 61  ly recompiled, a
29c40 73 20 69 66 20 74 68 65 72 65 20 68 61 64 20 62  s if there had b
29c50 65 65 6e 20 0a 2a 2a 20 61 20 73 63 68 65 6d 61  een .** a schema
29c60 20 63 68 61 6e 67 65 2c 20 6f 6e 20 74 68 65 20   change, on the 
29c70 66 69 72 73 74 20 20 5b 73 71 6c 69 74 65 33 5f  first  [sqlite3_
29c80 73 74 65 70 28 29 5d 20 63 61 6c 6c 20 66 6f 6c  step()] call fol
29c90 6c 6f 77 69 6e 67 20 61 6e 79 20 63 68 61 6e 67  lowing any chang
29ca0 65 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c  e.** to the [sql
29cb0 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 20 7c  ite3_bind_text |
29cc0 20 62 69 6e 64 69 6e 67 73 5d 20 6f 66 20 74 68   bindings] of th
29cd0 61 74 20 5b 70 61 72 61 6d 65 74 65 72 5d 2e 20  at [parameter]. 
29ce0 0a 2a 2a 20 5e 54 68 65 20 73 70 65 63 69 66 69  .** ^The specifi
29cf0 63 20 76 61 6c 75 65 20 6f 66 20 57 48 45 52 45  c value of WHERE
29d00 2d 63 6c 61 75 73 65 20 5b 70 61 72 61 6d 65 74  -clause [paramet
29d10 65 72 5d 20 6d 69 67 68 74 20 69 6e 66 6c 75 65  er] might influe
29d20 6e 63 65 20 74 68 65 20 0a 2a 2a 20 63 68 6f 69  nce the .** choi
29d30 63 65 20 6f 66 20 71 75 65 72 79 20 70 6c 61 6e  ce of query plan
29d40 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65   if the paramete
29d50 72 20 69 73 20 74 68 65 20 6c 65 66 74 2d 68 61  r is the left-ha
29d60 6e 64 20 73 69 64 65 20 6f 66 20 61 20 5b 4c 49  nd side of a [LI
29d70 4b 45 5d 0a 2a 2a 20 6f 72 20 5b 47 4c 4f 42 5d  KE].** or [GLOB]
29d80 20 6f 70 65 72 61 74 6f 72 20 6f 72 20 69 66 20   operator or if 
29d90 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 73  the parameter is
29da0 20 63 6f 6d 70 61 72 65 64 20 74 6f 20 61 6e 20   compared to an 
29db0 69 6e 64 65 78 65 64 20 63 6f 6c 75 6d 6e 0a 2a  indexed column.*
29dc0 2a 20 61 6e 64 20 74 68 65 20 5b 53 51 4c 49 54  * and the [SQLIT
29dd0 45 5f 45 4e 41 42 4c 45 5f 53 54 41 54 33 5d 20  E_ENABLE_STAT3] 
29de0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
29df0 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a  ion is enabled..
29e00 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 6f 6c  ** </li>.** </ol
29e10 3e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  >.*/.int sqlite3
29e20 5f 70 72 65 70 61 72 65 28 0a 20 20 73 71 6c 69  _prepare(.  sqli
29e30 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
29e40 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20      /* Database 
29e50 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
29e60 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20  t char *zSql,   
29e70 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65      /* SQL state
29e80 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f  ment, UTF-8 enco
29e90 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79  ded */.  int nBy
29ea0 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  te,             
29eb0 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67   /* Maximum leng
29ec0 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79  th of zSql in by
29ed0 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65  tes. */.  sqlite
29ee0 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c  3_stmt **ppStmt,
29ef0 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d    /* OUT: Statem
29f00 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ent handle */.  
29f10 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54  const char **pzT
29f20 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20  ail     /* OUT: 
29f30 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65  Pointer to unuse
29f40 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71  d portion of zSq
29f50 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69  l */.);.int sqli
29f60 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 0a  te3_prepare_v2(.
29f70 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
29f80 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74            /* Dat
29f90 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a  abase handle */.
29fa0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53    const char *zS
29fb0 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c  ql,       /* SQL
29fc0 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d   statement, UTF-
29fd0 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69  8 encoded */.  i
29fe0 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20  nt nByte,       
29ff0 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75         /* Maximu
2a000 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c  m length of zSql
2a010 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20   in bytes. */.  
2a020 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70  sqlite3_stmt **p
2a030 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20  pStmt,  /* OUT: 
2a040 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65  Statement handle
2a050 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
2a060 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a   **pzTail     /*
2a070 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f   OUT: Pointer to
2a080 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20   unused portion 
2a090 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e  of zSql */.);.in
2a0a0 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  t sqlite3_prepar
2a0b0 65 31 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  e16(.  sqlite3 *
2a0c0 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f  db,            /
2a0d0 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c  * Database handl
2a0e0 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69  e */.  const voi
2a0f0 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f  d *zSql,       /
2a100 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c  * SQL statement,
2a110 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20   UTF-16 encoded 
2a120 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20  */.  int nByte, 
2a130 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
2a140 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  Maximum length o
2a150 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e  f zSql in bytes.
2a160 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74   */.  sqlite3_st
2a170 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a  mt **ppStmt,  /*
2a180 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20   OUT: Statement 
2a190 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
2a1a0 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20  t void **pzTail 
2a1b0 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e      /* OUT: Poin
2a1c0 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f  ter to unused po
2a1d0 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f  rtion of zSql */
2a1e0 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
2a1f0 70 72 65 70 61 72 65 31 36 5f 76 32 28 0a 20 20  prepare16_v2(.  
2a200 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
2a210 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62          /* Datab
2a220 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ase handle */.  
2a230 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c  const void *zSql
2a240 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73  ,       /* SQL s
2a250 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36  tatement, UTF-16
2a260 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e   encoded */.  in
2a270 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20  t nByte,        
2a280 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d        /* Maximum
2a290 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20   length of zSql 
2a2a0 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73  in bytes. */.  s
2a2b0 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70  qlite3_stmt **pp
2a2c0 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53  Stmt,  /* OUT: S
2a2d0 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20  tatement handle 
2a2e0 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
2a2f0 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20  **pzTail     /* 
2a300 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20  OUT: Pointer to 
2a310 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f  unused portion o
2a320 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a  f zSql */.);../*
2a330 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
2a340 74 72 69 65 76 69 6e 67 20 53 74 61 74 65 6d 65  trieving Stateme
2a350 6e 74 20 53 51 4c 0a 2a 2a 20 4d 45 54 48 4f 44  nt SQL.** METHOD
2a360 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a  : sqlite3_stmt.*
2a370 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
2a380 33 5f 73 71 6c 28 50 29 20 69 6e 74 65 72 66 61  3_sql(P) interfa
2a390 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  ce returns a poi
2a3a0 6e 74 65 72 20 74 6f 20 61 20 63 6f 70 79 20 6f  nter to a copy o
2a3b0 66 20 74 68 65 20 55 54 46 2d 38 0a 2a 2a 20 53  f the UTF-8.** S
2a3c0 51 4c 20 74 65 78 74 20 75 73 65 64 20 74 6f 20  QL text used to 
2a3d0 63 72 65 61 74 65 20 5b 70 72 65 70 61 72 65 64  create [prepared
2a3e0 20 73 74 61 74 65 6d 65 6e 74 5d 20 50 20 69 66   statement] P if
2a3f0 20 50 20 77 61 73 0a 2a 2a 20 63 72 65 61 74 65   P was.** create
2a400 64 20 62 79 20 65 69 74 68 65 72 20 5b 73 71 6c  d by either [sql
2a410 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
2a420 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70  )] or [sqlite3_p
2a430 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a  repare16_v2()]..
2a440 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2a450 65 78 70 61 6e 64 65 64 5f 73 71 6c 28 50 29 20  expanded_sql(P) 
2a460 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
2a470 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
2a480 20 55 54 46 2d 38 0a 2a 2a 20 73 74 72 69 6e 67   UTF-8.** string
2a490 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20   containing the 
2a4a0 53 51 4c 20 74 65 78 74 20 6f 66 20 70 72 65 70  SQL text of prep
2a4b0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 50  ared statement P
2a4c0 20 77 69 74 68 0a 2a 2a 20 5b 62 6f 75 6e 64 20   with.** [bound 
2a4d0 70 61 72 61 6d 65 74 65 72 73 5d 20 65 78 70 61  parameters] expa
2a4e0 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 46 6f  nded..**.** ^(Fo
2a4f0 72 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 61 20  r example, if a 
2a500 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2a510 6e 74 20 69 73 20 63 72 65 61 74 65 64 20 75 73  nt is created us
2a520 69 6e 67 20 74 68 65 20 53 51 4c 0a 2a 2a 20 74  ing the SQL.** t
2a530 65 78 74 20 22 53 45 4c 45 43 54 20 24 61 62 63  ext "SELECT $abc
2a540 2c 3a 78 79 7a 22 20 61 6e 64 20 69 66 20 70 61  ,:xyz" and if pa
2a550 72 61 6d 65 74 65 72 20 24 61 62 63 20 69 73 20  rameter $abc is 
2a560 62 6f 75 6e 64 20 74 6f 20 69 6e 74 65 67 65 72  bound to integer
2a570 20 32 33 34 35 0a 2a 2a 20 61 6e 64 20 70 61 72   2345.** and par
2a580 61 6d 65 74 65 72 20 3a 78 79 7a 20 69 73 20 75  ameter :xyz is u
2a590 6e 62 6f 75 6e 64 2c 20 74 68 65 6e 20 73 71 6c  nbound, then sql
2a5a0 69 74 65 33 5f 73 71 6c 28 29 20 77 69 6c 6c 20  ite3_sql() will 
2a5b0 72 65 74 75 72 6e 0a 2a 2a 20 74 68 65 20 6f 72  return.** the or
2a5c0 69 67 69 6e 61 6c 20 73 74 72 69 6e 67 2c 20 22  iginal string, "
2a5d0 53 45 4c 45 43 54 20 24 61 62 63 2c 3a 78 79 7a  SELECT $abc,:xyz
2a5e0 22 20 62 75 74 20 73 71 6c 69 74 65 33 5f 65 78  " but sqlite3_ex
2a5f0 70 61 6e 64 65 64 5f 73 71 6c 28 29 0a 2a 2a 20  panded_sql().** 
2a600 77 69 6c 6c 20 72 65 74 75 72 6e 20 22 53 45 4c  will return "SEL
2a610 45 43 54 20 32 33 34 35 2c 4e 55 4c 4c 22 2e 29  ECT 2345,NULL".)
2a620 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51  ^.**.** ^The [SQ
2a630 4c 49 54 45 5f 54 52 41 43 45 5f 53 49 5a 45 5f  LITE_TRACE_SIZE_
2a640 4c 49 4d 49 54 5d 20 73 65 74 74 69 6e 67 20 6c  LIMIT] setting l
2a650 69 6d 69 74 73 20 74 68 65 20 73 69 7a 65 20 6f  imits the size o
2a660 66 20 61 20 0a 2a 2a 20 62 6f 75 6e 64 20 70 61  f a .** bound pa
2a670 72 61 6d 65 74 65 72 20 65 78 70 61 6e 73 69 6f  rameter expansio
2a680 6e 2e 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69  n.  ^If SQLite i
2a690 73 20 62 75 69 6c 74 20 77 69 74 68 20 74 68 65  s built with the
2a6a0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54  .** [SQLITE_OMIT
2a6b0 5f 54 52 41 43 45 5d 20 63 6f 6d 70 69 6c 65 2d  _TRACE] compile-
2a6c0 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e  time option then
2a6d0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65 78 70   the sqlite3_exp
2a6e0 61 6e 64 65 64 5f 73 71 6c 28 29 0a 2a 2a 20 69  anded_sql().** i
2a6f0 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f 6e 2d  nterface is non-
2a700 66 75 6e 63 74 69 6f 6e 61 6c 20 61 6e 64 20 61  functional and a
2a710 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 4e 55  lways returns NU
2a720 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  LL..**.** ^The s
2a730 74 72 69 6e 67 20 72 65 74 75 72 6e 65 64 20 62  tring returned b
2a740 79 20 73 71 6c 69 74 65 33 5f 73 71 6c 28 50 29  y sqlite3_sql(P)
2a750 20 69 73 20 6d 61 6e 61 67 65 64 20 62 79 20 53   is managed by S
2a760 51 4c 69 74 65 20 61 6e 64 20 69 73 0a 2a 2a 20  QLite and is.** 
2a770 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 66 72  automatically fr
2a780 65 65 64 20 77 68 65 6e 20 74 68 65 20 70 72 65  eed when the pre
2a790 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
2a7a0 69 73 20 66 69 6e 61 6c 69 7a 65 64 2e 0a 2a 2a  is finalized..**
2a7b0 20 5e 54 68 65 20 73 74 72 69 6e 67 20 72 65 74   ^The string ret
2a7c0 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
2a7d0 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c 28 50 29  _expanded_sql(P)
2a7e0 2c 20 6f 6e 20 74 68 65 20 6f 74 68 65 72 20 68  , on the other h
2a7f0 61 6e 64 2c 0a 2a 2a 20 69 73 20 6f 62 74 61 69  and,.** is obtai
2a800 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ned from [sqlite
2a810 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e 64 20  3_malloc()] and 
2a820 6d 75 73 74 20 62 65 20 66 72 65 65 20 62 79 20  must be free by 
2a830 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a  the application.
2a840 2a 2a 20 62 79 20 70 61 73 73 69 6e 67 20 69 74  ** by passing it
2a850 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65   to [sqlite3_fre
2a860 65 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63  e()]..*/.const c
2a870 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 71 6c  har *sqlite3_sql
2a880 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70  (sqlite3_stmt *p
2a890 53 74 6d 74 29 3b 0a 63 68 61 72 20 2a 73 71 6c  Stmt);.char *sql
2a8a0 69 74 65 33 5f 65 78 70 61 6e 64 65 64 5f 73 71  ite3_expanded_sq
2a8b0 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  l(sqlite3_stmt *
2a8c0 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pStmt);../*.** C
2a8d0 41 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69  API3REF: Determi
2a8e0 6e 65 20 49 66 20 41 6e 20 53 51 4c 20 53 74 61  ne If An SQL Sta
2a8f0 74 65 6d 65 6e 74 20 57 72 69 74 65 73 20 54 68  tement Writes Th
2a900 65 20 44 61 74 61 62 61 73 65 0a 2a 2a 20 4d 45  e Database.** ME
2a910 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74  THOD: sqlite3_st
2a920 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  mt.**.** ^The sq
2a930 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f  lite3_stmt_reado
2a940 6e 6c 79 28 58 29 20 69 6e 74 65 72 66 61 63 65  nly(X) interface
2a950 20 72 65 74 75 72 6e 73 20 74 72 75 65 20 28 6e   returns true (n
2a960 6f 6e 2d 7a 65 72 6f 29 20 69 66 0a 2a 2a 20 61  on-zero) if.** a
2a970 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 5b  nd only if the [
2a980 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2a990 6e 74 5d 20 58 20 6d 61 6b 65 73 20 6e 6f 20 64  nt] X makes no d
2a9a0 69 72 65 63 74 20 63 68 61 6e 67 65 73 20 74 6f  irect changes to
2a9b0 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20  .** the content 
2a9c0 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  of the database 
2a9d0 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65  file..**.** Note
2a9e0 20 74 68 61 74 20 5b 61 70 70 6c 69 63 61 74 69   that [applicati
2a9f0 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66  on-defined SQL f
2aa00 75 6e 63 74 69 6f 6e 73 5d 20 6f 72 0a 2a 2a 20  unctions] or.** 
2aa10 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 5d  [virtual tables]
2aa20 20 6d 69 67 68 74 20 63 68 61 6e 67 65 20 74 68   might change th
2aa30 65 20 64 61 74 61 62 61 73 65 20 69 6e 64 69 72  e database indir
2aa40 65 63 74 6c 79 20 61 73 20 61 20 73 69 64 65 20  ectly as a side 
2aa50 65 66 66 65 63 74 2e 20 20 0a 2a 2a 20 5e 28 46  effect.  .** ^(F
2aa60 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 61  or example, if a
2aa70 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65  n application de
2aa80 66 69 6e 65 73 20 61 20 66 75 6e 63 74 69 6f 6e  fines a function
2aa90 20 22 65 76 61 6c 28 29 22 20 74 68 61 74 20 0a   "eval()" that .
2aaa0 2a 2a 20 63 61 6c 6c 73 20 5b 73 71 6c 69 74 65  ** calls [sqlite
2aab0 33 5f 65 78 65 63 28 29 5d 2c 20 74 68 65 6e 20  3_exec()], then 
2aac0 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51  the following SQ
2aad0 4c 20 73 74 61 74 65 6d 65 6e 74 20 77 6f 75 6c  L statement woul
2aae0 64 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20  d.** change the 
2aaf0 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 74 68  database file th
2ab00 72 6f 75 67 68 20 73 69 64 65 2d 65 66 66 65 63  rough side-effec
2ab10 74 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ts:.**.** <block
2ab20 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
2ab30 20 20 53 45 4c 45 43 54 20 65 76 61 6c 28 27 44    SELECT eval('D
2ab40 45 4c 45 54 45 20 46 52 4f 4d 20 74 31 27 29 20  ELETE FROM t1') 
2ab50 46 52 4f 4d 20 74 32 3b 0a 2a 2a 20 3c 2f 70 72  FROM t2;.** </pr
2ab60 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  e></blockquote>.
2ab70 2a 2a 0a 2a 2a 20 42 75 74 20 62 65 63 61 75 73  **.** But becaus
2ab80 65 20 74 68 65 20 5b 53 45 4c 45 43 54 5d 20 73  e the [SELECT] s
2ab90 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f  tatement does no
2aba0 74 20 63 68 61 6e 67 65 20 74 68 65 20 64 61 74  t change the dat
2abb0 61 62 61 73 65 20 66 69 6c 65 0a 2a 2a 20 64 69  abase file.** di
2abc0 72 65 63 74 6c 79 2c 20 73 71 6c 69 74 65 33 5f  rectly, sqlite3_
2abd0 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20  stmt_readonly() 
2abe0 77 6f 75 6c 64 20 73 74 69 6c 6c 20 72 65 74 75  would still retu
2abf0 72 6e 20 74 72 75 65 2e 29 5e 0a 2a 2a 0a 2a 2a  rn true.)^.**.**
2ac00 20 5e 54 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f   ^Transaction co
2ac10 6e 74 72 6f 6c 20 73 74 61 74 65 6d 65 6e 74 73  ntrol statements
2ac20 20 73 75 63 68 20 61 73 20 5b 42 45 47 49 4e 5d   such as [BEGIN]
2ac30 2c 20 5b 43 4f 4d 4d 49 54 5d 2c 20 5b 52 4f 4c  , [COMMIT], [ROL
2ac40 4c 42 41 43 4b 5d 2c 0a 2a 2a 20 5b 53 41 56 45  LBACK],.** [SAVE
2ac50 50 4f 49 4e 54 5d 2c 20 61 6e 64 20 5b 52 45 4c  POINT], and [REL
2ac60 45 41 53 45 5d 20 63 61 75 73 65 20 73 71 6c 69  EASE] cause sqli
2ac70 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c  te3_stmt_readonl
2ac80 79 28 29 20 74 6f 20 72 65 74 75 72 6e 20 74 72  y() to return tr
2ac90 75 65 2c 0a 2a 2a 20 73 69 6e 63 65 20 74 68 65  ue,.** since the
2aca0 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 65 6d   statements them
2acb0 73 65 6c 76 65 73 20 64 6f 20 6e 6f 74 20 61 63  selves do not ac
2acc0 74 75 61 6c 6c 79 20 6d 6f 64 69 66 79 20 74 68  tually modify th
2acd0 65 20 64 61 74 61 62 61 73 65 20 62 75 74 0a 2a  e database but.*
2ace0 2a 20 72 61 74 68 65 72 20 74 68 65 79 20 63 6f  * rather they co
2acf0 6e 74 72 6f 6c 20 74 68 65 20 74 69 6d 69 6e 67  ntrol the timing
2ad00 20 6f 66 20 77 68 65 6e 20 6f 74 68 65 72 20 73   of when other s
2ad10 74 61 74 65 6d 65 6e 74 73 20 6d 6f 64 69 66 79  tatements modify
2ad20 20 74 68 65 20 0a 2a 2a 20 64 61 74 61 62 61 73   the .** databas
2ad30 65 2e 20 20 5e 54 68 65 20 5b 41 54 54 41 43 48  e.  ^The [ATTACH
2ad40 5d 20 61 6e 64 20 5b 44 45 54 41 43 48 5d 20 73  ] and [DETACH] s
2ad50 74 61 74 65 6d 65 6e 74 73 20 61 6c 73 6f 20 63  tatements also c
2ad60 61 75 73 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ause.** sqlite3_
2ad70 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20  stmt_readonly() 
2ad80 74 6f 20 72 65 74 75 72 6e 20 74 72 75 65 20 73  to return true s
2ad90 69 6e 63 65 2c 20 77 68 69 6c 65 20 74 68 6f 73  ince, while thos
2ada0 65 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20  e statements.** 
2adb0 63 68 61 6e 67 65 20 74 68 65 20 63 6f 6e 66 69  change the confi
2adc0 67 75 72 61 74 69 6f 6e 20 6f 66 20 61 20 64 61  guration of a da
2add0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2ade0 6e 2c 20 74 68 65 79 20 64 6f 20 6e 6f 74 20 6d  n, they do not m
2adf0 61 6b 65 20 0a 2a 2a 20 63 68 61 6e 67 65 73 20  ake .** changes 
2ae00 74 6f 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f  to the content o
2ae10 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  f the database f
2ae20 69 6c 65 73 20 6f 6e 20 64 69 73 6b 2e 0a 2a 2f  iles on disk..*/
2ae30 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 6d  .int sqlite3_stm
2ae40 74 5f 72 65 61 64 6f 6e 6c 79 28 73 71 6c 69 74  t_readonly(sqlit
2ae50 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
2ae60 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2ae70 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41  : Determine If A
2ae80 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d   Prepared Statem
2ae90 65 6e 74 20 48 61 73 20 42 65 65 6e 20 52 65 73  ent Has Been Res
2aea0 65 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  et.** METHOD: sq
2aeb0 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a  lite3_stmt.**.**
2aec0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 74   ^The sqlite3_st
2aed0 6d 74 5f 62 75 73 79 28 53 29 20 69 6e 74 65 72  mt_busy(S) inter
2aee0 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 72 75  face returns tru
2aef0 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66 20  e (non-zero) if 
2af00 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  the.** [prepared
2af10 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 68 61   statement] S ha
2af20 73 20 62 65 65 6e 20 73 74 65 70 70 65 64 20 61  s been stepped a
2af30 74 20 6c 65 61 73 74 20 6f 6e 63 65 20 75 73 69  t least once usi
2af40 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ng .** [sqlite3_
2af50 73 74 65 70 28 53 29 5d 20 62 75 74 20 68 61 73  step(S)] but has
2af60 20 6e 65 69 74 68 65 72 20 72 75 6e 20 74 6f 20   neither run to 
2af70 63 6f 6d 70 6c 65 74 69 6f 6e 20 28 72 65 74 75  completion (retu
2af80 72 6e 65 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  rned.** [SQLITE_
2af90 44 4f 4e 45 5d 20 66 72 6f 6d 20 5b 73 71 6c 69  DONE] from [sqli
2afa0 74 65 33 5f 73 74 65 70 28 53 29 5d 29 20 6e 6f  te3_step(S)]) no
2afb0 72 0a 2a 2a 20 62 65 65 6e 20 72 65 73 65 74 20  r.** been reset 
2afc0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72  using [sqlite3_r
2afd0 65 73 65 74 28 53 29 5d 2e 20 20 5e 54 68 65 20  eset(S)].  ^The 
2afe0 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73  sqlite3_stmt_bus
2aff0 79 28 53 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63  y(S).** interfac
2b000 65 20 72 65 74 75 72 6e 73 20 66 61 6c 73 65 20  e returns false 
2b010 69 66 20 53 20 69 73 20 61 20 4e 55 4c 4c 20 70  if S is a NULL p
2b020 6f 69 6e 74 65 72 2e 20 20 49 66 20 53 20 69 73  ointer.  If S is
2b030 20 6e 6f 74 20 61 20 0a 2a 2a 20 4e 55 4c 4c 20   not a .** NULL 
2b040 70 6f 69 6e 74 65 72 20 61 6e 64 20 69 73 20 6e  pointer and is n
2b050 6f 74 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ot a pointer to 
2b060 61 20 76 61 6c 69 64 20 5b 70 72 65 70 61 72 65  a valid [prepare
2b070 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20  d statement].** 
2b080 6f 62 6a 65 63 74 2c 20 74 68 65 6e 20 74 68 65  object, then the
2b090 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64   behavior is und
2b0a0 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61  efined and proba
2b0b0 62 6c 79 20 75 6e 64 65 73 69 72 61 62 6c 65 2e  bly undesirable.
2b0c0 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65  .**.** This inte
2b0d0 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 73 65  rface can be use
2b0e0 64 20 69 6e 20 63 6f 6d 62 69 6e 61 74 69 6f 6e  d in combination
2b0f0 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73   [sqlite3_next_s
2b100 74 6d 74 28 29 5d 0a 2a 2a 20 74 6f 20 6c 6f 63  tmt()].** to loc
2b110 61 74 65 20 61 6c 6c 20 70 72 65 70 61 72 65 64  ate all prepared
2b120 20 73 74 61 74 65 6d 65 6e 74 73 20 61 73 73 6f   statements asso
2b130 63 69 61 74 65 64 20 77 69 74 68 20 61 20 64 61  ciated with a da
2b140 74 61 62 61 73 65 20 0a 2a 2a 20 63 6f 6e 6e 65  tabase .** conne
2b150 63 74 69 6f 6e 20 74 68 61 74 20 61 72 65 20 69  ction that are i
2b160 6e 20 6e 65 65 64 20 6f 66 20 62 65 69 6e 67 20  n need of being 
2b170 72 65 73 65 74 2e 20 20 54 68 69 73 20 63 61 6e  reset.  This can
2b180 20 62 65 20 75 73 65 64 2c 0a 2a 2a 20 66 6f 72   be used,.** for
2b190 20 65 78 61 6d 70 6c 65 2c 20 69 6e 20 64 69 61   example, in dia
2b1a0 67 6e 6f 73 74 69 63 20 72 6f 75 74 69 6e 65 73  gnostic routines
2b1b0 20 74 6f 20 73 65 61 72 63 68 20 66 6f 72 20 70   to search for p
2b1c0 72 65 70 61 72 65 64 20 0a 2a 2a 20 73 74 61 74  repared .** stat
2b1d0 65 6d 65 6e 74 73 20 74 68 61 74 20 61 72 65 20  ements that are 
2b1e0 68 6f 6c 64 69 6e 67 20 61 20 74 72 61 6e 73 61  holding a transa
2b1f0 63 74 69 6f 6e 20 6f 70 65 6e 2e 0a 2a 2f 0a 69  ction open..*/.i
2b200 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f  nt sqlite3_stmt_
2b210 62 75 73 79 28 73 71 6c 69 74 65 33 5f 73 74 6d  busy(sqlite3_stm
2b220 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  t*);../*.** CAPI
2b230 33 52 45 46 3a 20 44 79 6e 61 6d 69 63 61 6c 6c  3REF: Dynamicall
2b240 79 20 54 79 70 65 64 20 56 61 6c 75 65 20 4f 62  y Typed Value Ob
2b250 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ject.** KEYWORDS
2b260 3a 20 7b 70 72 6f 74 65 63 74 65 64 20 73 71 6c  : {protected sql
2b270 69 74 65 33 5f 76 61 6c 75 65 7d 20 7b 75 6e 70  ite3_value} {unp
2b280 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
2b290 5f 76 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 51  _value}.**.** SQ
2b2a0 4c 69 74 65 20 75 73 65 73 20 74 68 65 20 73 71  Lite uses the sq
2b2b0 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
2b2c0 63 74 20 74 6f 20 72 65 70 72 65 73 65 6e 74 20  ct to represent 
2b2d0 61 6c 6c 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68  all values.** th
2b2e0 61 74 20 63 61 6e 20 62 65 20 73 74 6f 72 65 64  at can be stored
2b2f0 20 69 6e 20 61 20 64 61 74 61 62 61 73 65 20 74   in a database t
2b300 61 62 6c 65 2e 20 53 51 4c 69 74 65 20 75 73 65  able. SQLite use
2b310 73 20 64 79 6e 61 6d 69 63 20 74 79 70 69 6e 67  s dynamic typing
2b320 0a 2a 2a 20 66 6f 72 20 74 68 65 20 76 61 6c 75  .** for the valu
2b330 65 73 20 69 74 20 73 74 6f 72 65 73 2e 20 20 5e  es it stores.  ^
2b340 56 61 6c 75 65 73 20 73 74 6f 72 65 64 20 69 6e  Values stored in
2b350 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
2b360 62 6a 65 63 74 73 0a 2a 2a 20 63 61 6e 20 62 65  bjects.** can be
2b370 20 69 6e 74 65 67 65 72 73 2c 20 66 6c 6f 61 74   integers, float
2b380 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 73  ing point values
2b390 2c 20 73 74 72 69 6e 67 73 2c 20 42 4c 4f 42 73  , strings, BLOBs
2b3a0 2c 20 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  , or NULL..**.**
2b3b0 20 41 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75   An sqlite3_valu
2b3c0 65 20 6f 62 6a 65 63 74 20 6d 61 79 20 62 65 20  e object may be 
2b3d0 65 69 74 68 65 72 20 22 70 72 6f 74 65 63 74 65  either "protecte
2b3e0 64 22 20 6f 72 20 22 75 6e 70 72 6f 74 65 63 74  d" or "unprotect
2b3f0 65 64 22 2e 0a 2a 2a 20 53 6f 6d 65 20 69 6e 74  ed"..** Some int
2b400 65 72 66 61 63 65 73 20 72 65 71 75 69 72 65 20  erfaces require 
2b410 61 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  a protected sqli
2b420 74 65 33 5f 76 61 6c 75 65 2e 20 20 4f 74 68 65  te3_value.  Othe
2b430 72 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  r interfaces.** 
2b440 77 69 6c 6c 20 61 63 63 65 70 74 20 65 69 74 68  will accept eith
2b450 65 72 20 61 20 70 72 6f 74 65 63 74 65 64 20 6f  er a protected o
2b460 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64  r an unprotected
2b470 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a   sqlite3_value..
2b480 2a 2a 20 45 76 65 72 79 20 69 6e 74 65 72 66 61  ** Every interfa
2b490 63 65 20 74 68 61 74 20 61 63 63 65 70 74 73 20  ce that accepts 
2b4a0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 61 72  sqlite3_value ar
2b4b0 67 75 6d 65 6e 74 73 20 73 70 65 63 69 66 69 65  guments specifie
2b4c0 73 0a 2a 2a 20 77 68 65 74 68 65 72 20 6f 72 20  s.** whether or 
2b4d0 6e 6f 74 20 69 74 20 72 65 71 75 69 72 65 73 20  not it requires 
2b4e0 61 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  a protected sqli
2b4f0 74 65 33 5f 76 61 6c 75 65 2e 20 20 54 68 65 0a  te3_value.  The.
2b500 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ** [sqlite3_valu
2b510 65 5f 64 75 70 28 29 5d 20 69 6e 74 65 72 66 61  e_dup()] interfa
2b520 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  ce can be used t
2b530 6f 20 63 6f 6e 73 74 72 75 63 74 20 61 20 6e 65  o construct a ne
2b540 77 20 0a 2a 2a 20 70 72 6f 74 65 63 74 65 64 20  w .** protected 
2b550 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 66 72  sqlite3_value fr
2b560 6f 6d 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65  om an unprotecte
2b570 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e  d sqlite3_value.
2b580 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 65 72 6d 73  .**.** The terms
2b590 20 22 70 72 6f 74 65 63 74 65 64 22 20 61 6e 64   "protected" and
2b5a0 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22 20 72   "unprotected" r
2b5b0 65 66 65 72 20 74 6f 20 77 68 65 74 68 65 72 20  efer to whether 
2b5c0 6f 72 20 6e 6f 74 0a 2a 2a 20 61 20 6d 75 74 65  or not.** a mute
2b5d0 78 20 69 73 20 68 65 6c 64 2e 20 20 41 6e 20 69  x is held.  An i
2b5e0 6e 74 65 72 6e 61 6c 20 6d 75 74 65 78 20 69 73  nternal mutex is
2b5f0 20 68 65 6c 64 20 66 6f 72 20 61 20 70 72 6f 74   held for a prot
2b600 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33  ected.** sqlite3
2b610 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 62 75  _value object bu
2b620 74 20 6e 6f 20 6d 75 74 65 78 20 69 73 20 68 65  t no mutex is he
2b630 6c 64 20 66 6f 72 20 61 6e 20 75 6e 70 72 6f 74  ld for an unprot
2b640 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33  ected.** sqlite3
2b650 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 2e 20 20  _value object.  
2b660 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
2b670 70 69 6c 65 64 20 74 6f 20 62 65 20 73 69 6e 67  piled to be sing
2b680 6c 65 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 28  le-threaded.** (
2b690 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 54 48 52  with [SQLITE_THR
2b6a0 45 41 44 53 41 46 45 3d 30 5d 20 61 6e 64 20 77  EADSAFE=0] and w
2b6b0 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 74 68 72  ith [sqlite3_thr
2b6c0 65 61 64 73 61 66 65 28 29 5d 20 72 65 74 75 72  eadsafe()] retur
2b6d0 6e 69 6e 67 20 30 29 0a 2a 2a 20 6f 72 20 69 66  ning 0).** or if
2b6e0 20 53 51 4c 69 74 65 20 69 73 20 72 75 6e 20 69   SQLite is run i
2b6f0 6e 20 6f 6e 65 20 6f 66 20 72 65 64 75 63 65 64  n one of reduced
2b700 20 6d 75 74 65 78 20 6d 6f 64 65 73 20 0a 2a 2a   mutex modes .**
2b710 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
2b720 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 20 6f 72  SINGLETHREAD] or
2b730 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
2b740 4d 55 4c 54 49 54 48 52 45 41 44 5d 0a 2a 2a 20  MULTITHREAD].** 
2b750 74 68 65 6e 20 74 68 65 72 65 20 69 73 20 6e 6f  then there is no
2b760 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74   distinction bet
2b770 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61  ween protected a
2b780 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a  nd unprotected.*
2b790 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  * sqlite3_value 
2b7a0 6f 62 6a 65 63 74 73 20 61 6e 64 20 74 68 65 79  objects and they
2b7b0 20 63 61 6e 20 62 65 20 75 73 65 64 20 69 6e 74   can be used int
2b7c0 65 72 63 68 61 6e 67 65 61 62 6c 79 2e 20 20 48  erchangeably.  H
2b7d0 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 6f 72 20 6d  owever,.** for m
2b7e0 61 78 69 6d 75 6d 20 63 6f 64 65 20 70 6f 72 74  aximum code port
2b7f0 61 62 69 6c 69 74 79 20 69 74 20 69 73 20 72 65  ability it is re
2b800 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61  commended that a
2b810 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73  pplications.** s
2b820 74 69 6c 6c 20 6d 61 6b 65 20 74 68 65 20 64 69  till make the di
2b830 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65  stinction betwee
2b840 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20  n protected and 
2b850 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73  unprotected.** s
2b860 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
2b870 65 63 74 73 20 65 76 65 6e 20 77 68 65 6e 20 6e  ects even when n
2b880 6f 74 20 73 74 72 69 63 74 6c 79 20 72 65 71 75  ot strictly requ
2b890 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ired..**.** ^The
2b8a0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
2b8b0 62 6a 65 63 74 73 20 74 68 61 74 20 61 72 65 20  bjects that are 
2b8c0 70 61 73 73 65 64 20 61 73 20 70 61 72 61 6d 65  passed as parame
2b8d0 74 65 72 73 20 69 6e 74 6f 20 74 68 65 0a 2a 2a  ters into the.**
2b8e0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
2b8f0 6f 66 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d  of [application-
2b900 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
2b910 74 69 6f 6e 73 5d 20 61 72 65 20 70 72 6f 74 65  tions] are prote
2b920 63 74 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 71  cted..** ^The sq
2b930 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
2b940 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a  ct returned by.*
2b950 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  * [sqlite3_colum
2b960 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75 6e  n_value()] is un
2b970 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 55 6e  protected..** Un
2b980 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
2b990 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20  3_value objects 
2b9a0 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64  may only be used
2b9b0 20 77 69 74 68 0a 2a 2a 20 5b 73 71 6c 69 74 65   with.** [sqlite
2b9c0 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29  3_result_value()
2b9d0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62  ] and [sqlite3_b
2b9e0 69 6e 64 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a  ind_value()]..**
2b9f0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   The [sqlite3_va
2ba00 6c 75 65 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74  lue_blob | sqlit
2ba10 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 29 5d  e3_value_type()]
2ba20 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 69 6e   family of.** in
2ba30 74 65 72 66 61 63 65 73 20 72 65 71 75 69 72 65  terfaces require
2ba40 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74   protected sqlit
2ba50 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73  e3_value objects
2ba60 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
2ba70 75 63 74 20 4d 65 6d 20 73 71 6c 69 74 65 33 5f  uct Mem sqlite3_
2ba80 76 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  value;../*.** CA
2ba90 50 49 33 52 45 46 3a 20 53 51 4c 20 46 75 6e 63  PI3REF: SQL Func
2baa0 74 69 6f 6e 20 43 6f 6e 74 65 78 74 20 4f 62 6a  tion Context Obj
2bab0 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f  ect.**.** The co
2bac0 6e 74 65 78 74 20 69 6e 20 77 68 69 63 68 20 61  ntext in which a
2bad0 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 65  n SQL function e
2bae0 78 65 63 75 74 65 73 20 69 73 20 73 74 6f 72 65  xecutes is store
2baf0 64 20 69 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74  d in an.** sqlit
2bb00 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63  e3_context objec
2bb10 74 2e 20 20 5e 41 20 70 6f 69 6e 74 65 72 20 74  t.  ^A pointer t
2bb20 6f 20 61 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6e  o an sqlite3_con
2bb30 74 65 78 74 20 6f 62 6a 65 63 74 0a 2a 2a 20 69  text object.** i
2bb40 73 20 61 6c 77 61 79 73 20 66 69 72 73 74 20 70  s always first p
2bb50 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 61 70 70  arameter to [app
2bb60 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
2bb70 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 2e   SQL functions].
2bb80 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74  .** The applicat
2bb90 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20  ion-defined SQL 
2bba0 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65  function impleme
2bbb0 6e 74 61 74 69 6f 6e 20 77 69 6c 6c 20 70 61 73  ntation will pas
2bbc0 73 20 74 68 69 73 0a 2a 2a 20 70 6f 69 6e 74 65  s this.** pointe
2bbd0 72 20 74 68 72 6f 75 67 68 20 69 6e 74 6f 20 63  r through into c
2bbe0 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
2bbf0 5f 72 65 73 75 6c 74 5f 69 6e 74 20 7c 20 73 71  _result_int | sq
2bc00 6c 69 74 65 33 5f 72 65 73 75 6c 74 28 29 5d 2c  lite3_result()],
2bc10 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 61 67 67  .** [sqlite3_agg
2bc20 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29  regate_context()
2bc30 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72  ], [sqlite3_user
2bc40 5f 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 5b 73 71  _data()],.** [sq
2bc50 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62  lite3_context_db
2bc60 5f 68 61 6e 64 6c 65 28 29 5d 2c 20 5b 73 71 6c  _handle()], [sql
2bc70 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61  ite3_get_auxdata
2bc80 28 29 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b  ()],.** and/or [
2bc90 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
2bca0 61 74 61 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64  ata()]..*/.typed
2bcb0 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
2bcc0 33 5f 63 6f 6e 74 65 78 74 20 73 71 6c 69 74 65  3_context sqlite
2bcd0 33 5f 63 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a  3_context;../*.*
2bce0 2a 20 43 41 50 49 33 52 45 46 3a 20 42 69 6e 64  * CAPI3REF: Bind
2bcf0 69 6e 67 20 56 61 6c 75 65 73 20 54 6f 20 50 72  ing Values To Pr
2bd00 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74  epared Statement
2bd10 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  s.** KEYWORDS: {
2bd20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 7d 20  host parameter} 
2bd30 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73  {host parameters
2bd40 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65  } {host paramete
2bd50 72 20 6e 61 6d 65 7d 0a 2a 2a 20 4b 45 59 57 4f  r name}.** KEYWO
2bd60 52 44 53 3a 20 7b 53 51 4c 20 70 61 72 61 6d 65  RDS: {SQL parame
2bd70 74 65 72 7d 20 7b 53 51 4c 20 70 61 72 61 6d 65  ter} {SQL parame
2bd80 74 65 72 73 7d 20 7b 70 61 72 61 6d 65 74 65 72  ters} {parameter
2bd90 20 62 69 6e 64 69 6e 67 7d 0a 2a 2a 20 4d 45 54   binding}.** MET
2bda0 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d  HOD: sqlite3_stm
2bdb0 74 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 65  t.**.** ^(In the
2bdc0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74   SQL statement t
2bdd0 65 78 74 20 69 6e 70 75 74 20 74 6f 20 5b 73 71  ext input to [sq
2bde0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
2bdf0 28 29 5d 20 61 6e 64 20 69 74 73 20 76 61 72 69  ()] and its vari
2be00 61 6e 74 73 2c 0a 2a 2a 20 6c 69 74 65 72 61 6c  ants,.** literal
2be10 73 20 6d 61 79 20 62 65 20 72 65 70 6c 61 63 65  s may be replace
2be20 64 20 62 79 20 61 20 5b 70 61 72 61 6d 65 74 65  d by a [paramete
2be30 72 5d 20 74 68 61 74 20 6d 61 74 63 68 65 73 20  r] that matches 
2be40 6f 6e 65 20 6f 66 20 66 6f 6c 6c 6f 77 69 6e 67  one of following
2be50 0a 2a 2a 20 74 65 6d 70 6c 61 74 65 73 3a 0a 2a  .** templates:.*
2be60 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
2be70 3e 20 20 3f 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e  >  ?.** <li>  ?N
2be80 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20 20 3a 56 56 56  NN.** <li>  :VVV
2be90 0a 2a 2a 20 3c 6c 69 3e 20 20 40 56 56 56 0a 2a  .** <li>  @VVV.*
2bea0 2a 20 3c 6c 69 3e 20 20 24 56 56 56 0a 2a 2a 20  * <li>  $VVV.** 
2beb0 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74  </ul>.**.** In t
2bec0 68 65 20 74 65 6d 70 6c 61 74 65 73 20 61 62 6f  he templates abo
2bed0 76 65 2c 20 4e 4e 4e 20 72 65 70 72 65 73 65 6e  ve, NNN represen
2bee0 74 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6c 69  ts an integer li
2bef0 74 65 72 61 6c 2c 0a 2a 2a 20 61 6e 64 20 56 56  teral,.** and VV
2bf00 56 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20  V represents an 
2bf10 61 6c 70 68 61 6e 75 6d 65 72 69 63 20 69 64 65  alphanumeric ide
2bf20 6e 74 69 66 69 65 72 2e 29 5e 20 20 5e 54 68 65  ntifier.)^  ^The
2bf30 20 76 61 6c 75 65 73 20 6f 66 20 74 68 65 73 65   values of these
2bf40 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 20 28  .** parameters (
2bf50 61 6c 73 6f 20 63 61 6c 6c 65 64 20 22 68 6f 73  also called "hos
2bf60 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65  t parameter name
2bf70 73 22 20 6f 72 20 22 53 51 4c 20 70 61 72 61 6d  s" or "SQL param
2bf80 65 74 65 72 73 22 29 0a 2a 2a 20 63 61 6e 20 62  eters").** can b
2bf90 65 20 73 65 74 20 75 73 69 6e 67 20 74 68 65 20  e set using the 
2bfa0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29  sqlite3_bind_*()
2bfb0 20 72 6f 75 74 69 6e 65 73 20 64 65 66 69 6e 65   routines define
2bfc0 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54  d here..**.** ^T
2bfd0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
2bfe0 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  t to the sqlite3
2bff0 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e  _bind_*() routin
2c000 65 73 20 69 73 20 61 6c 77 61 79 73 0a 2a 2a 20  es is always.** 
2c010 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
2c020 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20   [sqlite3_stmt] 
2c030 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20  object returned 
2c040 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  from.** [sqlite3
2c050 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
2c060 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e 0a  r its variants..
2c070 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e  **.** ^The secon
2c080 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68  d argument is th
2c090 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 53  e index of the S
2c0a0 51 4c 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  QL parameter to 
2c0b0 62 65 20 73 65 74 2e 0a 2a 2a 20 5e 54 68 65 20  be set..** ^The 
2c0c0 6c 65 66 74 6d 6f 73 74 20 53 51 4c 20 70 61 72  leftmost SQL par
2c0d0 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e  ameter has an in
2c0e0 64 65 78 20 6f 66 20 31 2e 20 20 5e 57 68 65 6e  dex of 1.  ^When
2c0f0 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 64 0a   the same named.
2c100 2a 2a 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  ** SQL parameter
2c110 20 69 73 20 75 73 65 64 20 6d 6f 72 65 20 74 68   is used more th
2c120 61 6e 20 6f 6e 63 65 2c 20 73 65 63 6f 6e 64 20  an once, second 
2c130 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74 0a 2a  and subsequent.*
2c140 2a 20 6f 63 63 75 72 72 65 6e 63 65 73 20 68 61  * occurrences ha
2c150 76 65 20 74 68 65 20 73 61 6d 65 20 69 6e 64 65  ve the same inde
2c160 78 20 61 73 20 74 68 65 20 66 69 72 73 74 20 6f  x as the first o
2c170 63 63 75 72 72 65 6e 63 65 2e 0a 2a 2a 20 5e 54  ccurrence..** ^T
2c180 68 65 20 69 6e 64 65 78 20 66 6f 72 20 6e 61 6d  he index for nam
2c190 65 64 20 70 61 72 61 6d 65 74 65 72 73 20 63 61  ed parameters ca
2c1a0 6e 20 62 65 20 6c 6f 6f 6b 65 64 20 75 70 20 75  n be looked up u
2c1b0 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  sing the.** [sql
2c1c0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
2c1d0 74 65 72 5f 69 6e 64 65 78 28 29 5d 20 41 50 49  ter_index()] API
2c1e0 20 69 66 20 64 65 73 69 72 65 64 2e 20 20 5e 54   if desired.  ^T
2c1f0 68 65 20 69 6e 64 65 78 0a 2a 2a 20 66 6f 72 20  he index.** for 
2c200 22 3f 4e 4e 4e 22 20 70 61 72 61 6d 65 74 65 72  "?NNN" parameter
2c210 73 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f  s is the value o
2c220 66 20 4e 4e 4e 2e 0a 2a 2a 20 5e 54 68 65 20 4e  f NNN..** ^The N
2c230 4e 4e 20 76 61 6c 75 65 20 6d 75 73 74 20 62 65  NN value must be
2c240 20 62 65 74 77 65 65 6e 20 31 20 61 6e 64 20 74   between 1 and t
2c250 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69  he [sqlite3_limi
2c260 74 28 29 5d 0a 2a 2a 20 70 61 72 61 6d 65 74 65  t()].** paramete
2c270 72 20 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  r [SQLITE_LIMIT_
2c280 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d  VARIABLE_NUMBER]
2c290 20 28 64 65 66 61 75 6c 74 20 76 61 6c 75 65 3a   (default value:
2c2a0 20 39 39 39 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68   999)..**.** ^Th
2c2b0 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  e third argument
2c2c0 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 74 6f   is the value to
2c2d0 20 62 69 6e 64 20 74 6f 20 74 68 65 20 70 61 72   bind to the par
2c2e0 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74  ameter..** ^If t
2c2f0 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
2c300 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69  er to sqlite3_bi
2c310 6e 64 5f 74 65 78 74 28 29 20 6f 72 20 73 71 6c  nd_text() or sql
2c320 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36  ite3_bind_text16
2c330 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33  ().** or sqlite3
2c340 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 20 69 73 20  _bind_blob() is 
2c350 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74  a NULL pointer t
2c360 68 65 6e 20 74 68 65 20 66 6f 75 72 74 68 20 70  hen the fourth p
2c370 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69 73 20 69  arameter.** is i
2c380 67 6e 6f 72 65 64 20 61 6e 64 20 74 68 65 20 65  gnored and the e
2c390 6e 64 20 72 65 73 75 6c 74 20 69 73 20 74 68 65  nd result is the
2c3a0 20 73 61 6d 65 20 61 73 20 73 71 6c 69 74 65 33   same as sqlite3
2c3b0 5f 62 69 6e 64 5f 6e 75 6c 6c 28 29 2e 0a 2a 2a  _bind_null()..**
2c3c0 0a 2a 2a 20 5e 28 49 6e 20 74 68 6f 73 65 20 72  .** ^(In those r
2c3d0 6f 75 74 69 6e 65 73 20 74 68 61 74 20 68 61 76  outines that hav
2c3e0 65 20 61 20 66 6f 75 72 74 68 20 61 72 67 75 6d  e a fourth argum
2c3f0 65 6e 74 2c 20 69 74 73 20 76 61 6c 75 65 20 69  ent, its value i
2c400 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20  s the.** number 
2c410 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20  of bytes in the 
2c420 70 61 72 61 6d 65 74 65 72 2e 20 20 54 6f 20 62  parameter.  To b
2c430 65 20 63 6c 65 61 72 3a 20 74 68 65 20 76 61 6c  e clear: the val
2c440 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d  ue is the.** num
2c450 62 65 72 20 6f 66 20 3c 75 3e 62 79 74 65 73 3c  ber of <u>bytes<
2c460 2f 75 3e 20 69 6e 20 74 68 65 20 76 61 6c 75 65  /u> in the value
2c470 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72  , not the number
2c480 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e 29   of characters.)
2c490 5e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 6f 75  ^.** ^If the fou
2c4a0 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rth parameter to
2c4b0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
2c4c0 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  xt() or sqlite3_
2c4d0 62 69 6e 64 5f 74 65 78 74 31 36 28 29 0a 2a 2a  bind_text16().**
2c4e0 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68   is negative, th
2c4f0 65 6e 20 74 68 65 20 6c 65 6e 67 74 68 20 6f 66  en the length of
2c500 20 74 68 65 20 73 74 72 69 6e 67 20 69 73 0a 2a   the string is.*
2c510 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  * the number of 
2c520 62 79 74 65 73 20 75 70 20 74 6f 20 74 68 65 20  bytes up to the 
2c530 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69  first zero termi
2c540 6e 61 74 6f 72 2e 0a 2a 2a 20 49 66 20 74 68 65  nator..** If the
2c550 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
2c560 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e  r to sqlite3_bin
2c570 64 5f 62 6c 6f 62 28 29 20 69 73 20 6e 65 67 61  d_blob() is nega
2c580 74 69 76 65 2c 20 74 68 65 6e 0a 2a 2a 20 74 68  tive, then.** th
2c590 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e  e behavior is un
2c5a0 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 61  defined..** If a
2c5b0 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20 66 6f   non-negative fo
2c5c0 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  urth parameter i
2c5d0 73 20 70 72 6f 76 69 64 65 64 20 74 6f 20 73 71  s provided to sq
2c5e0 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28  lite3_bind_text(
2c5f0 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f  ).** or sqlite3_
2c600 62 69 6e 64 5f 74 65 78 74 31 36 28 29 20 6f 72  bind_text16() or
2c610 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
2c620 78 74 36 34 28 29 20 74 68 65 6e 0a 2a 2a 20 74  xt64() then.** t
2c630 68 61 74 20 70 61 72 61 6d 65 74 65 72 20 6d 75  hat parameter mu
2c640 73 74 20 62 65 20 74 68 65 20 62 79 74 65 20 6f  st be the byte o
2c650 66 66 73 65 74 0a 2a 2a 20 77 68 65 72 65 20 74  ffset.** where t
2c660 68 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74 6f  he NUL terminato
2c670 72 20 77 6f 75 6c 64 20 6f 63 63 75 72 20 61 73  r would occur as
2c680 73 75 6d 69 6e 67 20 74 68 65 20 73 74 72 69 6e  suming the strin
2c690 67 20 77 65 72 65 20 4e 55 4c 0a 2a 2a 20 74 65  g were NUL.** te
2c6a0 72 6d 69 6e 61 74 65 64 2e 20 20 49 66 20 61 6e  rminated.  If an
2c6b0 79 20 4e 55 4c 20 63 68 61 72 61 63 74 65 72 73  y NUL characters
2c6c0 20 6f 63 63 75 72 20 61 74 20 62 79 74 65 20 6f   occur at byte o
2c6d0 66 66 73 65 74 73 20 6c 65 73 73 20 74 68 61 6e  ffsets less than
2c6e0 20 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 6f   .** the value o
2c6f0 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72  f the fourth par
2c700 61 6d 65 74 65 72 20 74 68 65 6e 20 74 68 65 20  ameter then the 
2c710 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67  resulting string
2c720 20 76 61 6c 75 65 20 77 69 6c 6c 0a 2a 2a 20 63   value will.** c
2c730 6f 6e 74 61 69 6e 20 65 6d 62 65 64 64 65 64 20  ontain embedded 
2c740 4e 55 4c 73 2e 20 20 54 68 65 20 72 65 73 75 6c  NULs.  The resul
2c750 74 20 6f 66 20 65 78 70 72 65 73 73 69 6f 6e 73  t of expressions
2c760 20 69 6e 76 6f 6c 76 69 6e 67 20 73 74 72 69 6e   involving strin
2c770 67 73 0a 2a 2a 20 77 69 74 68 20 65 6d 62 65 64  gs.** with embed
2c780 64 65 64 20 4e 55 4c 73 20 69 73 20 75 6e 64 65  ded NULs is unde
2c790 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  fined..**.** ^Th
2c7a0 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74  e fifth argument
2c7b0 20 74 6f 20 74 68 65 20 42 4c 4f 42 20 61 6e 64   to the BLOB and
2c7c0 20 73 74 72 69 6e 67 20 62 69 6e 64 69 6e 67 20   string binding 
2c7d0 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69 73  interfaces.** is
2c7e0 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 75 73   a destructor us
2c7f0 65 64 20 74 6f 20 64 69 73 70 6f 73 65 20 6f 66  ed to dispose of
2c800 20 74 68 65 20 42 4c 4f 42 20 6f 72 0a 2a 2a 20   the BLOB or.** 
2c810 73 74 72 69 6e 67 20 61 66 74 65 72 20 53 51 4c  string after SQL
2c820 69 74 65 20 68 61 73 20 66 69 6e 69 73 68 65 64  ite has finished
2c830 20 77 69 74 68 20 69 74 2e 20 20 5e 54 68 65 20   with it.  ^The 
2c840 64 65 73 74 72 75 63 74 6f 72 20 69 73 20 63 61  destructor is ca
2c850 6c 6c 65 64 0a 2a 2a 20 74 6f 20 64 69 73 70 6f  lled.** to dispo
2c860 73 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f  se of the BLOB o
2c870 72 20 73 74 72 69 6e 67 20 65 76 65 6e 20 69 66  r string even if
2c880 20 74 68 65 20 63 61 6c 6c 20 74 6f 20 62 69 6e   the call to bin
2c890 64 20 41 50 49 20 66 61 69 6c 73 2e 0a 2a 2a 20  d API fails..** 
2c8a0 5e 49 66 20 74 68 65 20 66 69 66 74 68 20 61 72  ^If the fifth ar
2c8b0 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 74 68 65  gument is.** the
2c8c0 20 73 70 65 63 69 61 6c 20 76 61 6c 75 65 20 5b   special value [
2c8d0 53 51 4c 49 54 45 5f 53 54 41 54 49 43 5d 2c 20  SQLITE_STATIC], 
2c8e0 74 68 65 6e 20 53 51 4c 69 74 65 20 61 73 73 75  then SQLite assu
2c8f0 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20  mes that the.** 
2c900 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 69  information is i
2c910 6e 20 73 74 61 74 69 63 2c 20 75 6e 6d 61 6e 61  n static, unmana
2c920 67 65 64 20 73 70 61 63 65 20 61 6e 64 20 64 6f  ged space and do
2c930 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62  es not need to b
2c940 65 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20  e freed..** ^If 
2c950 74 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65  the fifth argume
2c960 6e 74 20 68 61 73 20 74 68 65 20 76 61 6c 75 65  nt has the value
2c970 20 5b 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45   [SQLITE_TRANSIE
2c980 4e 54 5d 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c  NT], then.** SQL
2c990 69 74 65 20 6d 61 6b 65 73 20 69 74 73 20 6f 77  ite makes its ow
2c9a0 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f  n private copy o
2c9b0 66 20 74 68 65 20 64 61 74 61 20 69 6d 6d 65 64  f the data immed
2c9c0 69 61 74 65 6c 79 2c 20 62 65 66 6f 72 65 0a 2a  iately, before.*
2c9d0 2a 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69  * the sqlite3_bi
2c9e0 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 20 72  nd_*() routine r
2c9f0 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  eturns..**.** ^T
2ca00 68 65 20 73 69 78 74 68 20 61 72 67 75 6d 65 6e  he sixth argumen
2ca10 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e  t to sqlite3_bin
2ca20 64 5f 74 65 78 74 36 34 28 29 20 6d 75 73 74 20  d_text64() must 
2ca30 62 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 5b 53 51  be one of.** [SQ
2ca40 4c 49 54 45 5f 55 54 46 38 5d 2c 20 5b 53 51 4c  LITE_UTF8], [SQL
2ca50 49 54 45 5f 55 54 46 31 36 5d 2c 20 5b 53 51 4c  ITE_UTF16], [SQL
2ca60 49 54 45 5f 55 54 46 31 36 42 45 5d 2c 20 6f 72  ITE_UTF16BE], or
2ca70 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45   [SQLITE_UTF16LE
2ca80 5d 0a 2a 2a 20 74 6f 20 73 70 65 63 69 66 79 20  ].** to specify 
2ca90 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 6f 66 20  the encoding of 
2caa0 74 68 65 20 74 65 78 74 20 69 6e 20 74 68 65 20  the text in the 
2cab0 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 2e  third parameter.
2cac0 20 20 49 66 0a 2a 2a 20 74 68 65 20 73 69 78 74    If.** the sixt
2cad0 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71  h argument to sq
2cae0 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 36  lite3_bind_text6
2caf0 34 28 29 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f  4() is not one o
2cb00 66 20 74 68 65 0a 2a 2a 20 61 6c 6c 6f 77 65 64  f the.** allowed
2cb10 20 76 61 6c 75 65 73 20 73 68 6f 77 6e 20 61 62   values shown ab
2cb20 6f 76 65 2c 20 6f 72 20 69 66 20 74 68 65 20 74  ove, or if the t
2cb30 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 69 73 20  ext encoding is 
2cb40 64 69 66 66 65 72 65 6e 74 0a 2a 2a 20 66 72 6f  different.** fro
2cb50 6d 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 73  m the encoding s
2cb60 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20  pecified by the 
2cb70 73 69 78 74 68 20 70 61 72 61 6d 65 74 65 72 2c  sixth parameter,
2cb80 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69   then the behavi
2cb90 6f 72 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e  or.** is undefin
2cba0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ed..**.** ^The s
2cbb0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f  qlite3_bind_zero
2cbc0 62 6c 6f 62 28 29 20 72 6f 75 74 69 6e 65 20 62  blob() routine b
2cbd0 69 6e 64 73 20 61 20 42 4c 4f 42 20 6f 66 20 6c  inds a BLOB of l
2cbe0 65 6e 67 74 68 20 4e 20 74 68 61 74 0a 2a 2a 20  ength N that.** 
2cbf0 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 7a  is filled with z
2cc00 65 72 6f 65 73 2e 20 20 5e 41 20 7a 65 72 6f 62  eroes.  ^A zerob
2cc10 6c 6f 62 20 75 73 65 73 20 61 20 66 69 78 65 64  lob uses a fixed
2cc20 20 61 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f 72   amount of memor
2cc30 79 0a 2a 2a 20 28 6a 75 73 74 20 61 6e 20 69 6e  y.** (just an in
2cc40 74 65 67 65 72 20 74 6f 20 68 6f 6c 64 20 69 74  teger to hold it
2cc50 73 20 73 69 7a 65 29 20 77 68 69 6c 65 20 69 74  s size) while it
2cc60 20 69 73 20 62 65 69 6e 67 20 70 72 6f 63 65 73   is being proces
2cc70 73 65 64 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62  sed..** Zeroblob
2cc80 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 74  s are intended t
2cc90 6f 20 73 65 72 76 65 20 61 73 20 70 6c 61 63 65  o serve as place
2cca0 68 6f 6c 64 65 72 73 20 66 6f 72 20 42 4c 4f 42  holders for BLOB
2ccb0 73 20 77 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65  s whose.** conte
2ccc0 6e 74 20 69 73 20 6c 61 74 65 72 20 77 72 69 74  nt is later writ
2ccd0 74 65 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71  ten using.** [sq
2cce0 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20  lite3_blob_open 
2ccf0 7c 20 69 6e 63 72 65 6d 65 6e 74 61 6c 20 42 4c  | incremental BL
2cd00 4f 42 20 49 2f 4f 5d 20 72 6f 75 74 69 6e 65 73  OB I/O] routines
2cd10 2e 0a 2a 2a 20 5e 41 20 6e 65 67 61 74 69 76 65  ..** ^A negative
2cd20 20 76 61 6c 75 65 20 66 6f 72 20 74 68 65 20 7a   value for the z
2cd30 65 72 6f 62 6c 6f 62 20 72 65 73 75 6c 74 73 20  eroblob results 
2cd40 69 6e 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68  in a zero-length
2cd50 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66   BLOB..**.** ^If
2cd60 20 61 6e 79 20 6f 66 20 74 68 65 20 73 71 6c 69   any of the sqli
2cd70 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75  te3_bind_*() rou
2cd80 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64  tines are called
2cd90 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69   with a NULL poi
2cda0 6e 74 65 72 0a 2a 2a 20 66 6f 72 20 74 68 65 20  nter.** for the 
2cdb0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2cdc0 65 6e 74 5d 20 6f 72 20 77 69 74 68 20 61 20 70  ent] or with a p
2cdd0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2cde0 74 20 66 6f 72 20 77 68 69 63 68 0a 2a 2a 20 5b  t for which.** [
2cdf0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
2ce00 68 61 73 20 62 65 65 6e 20 63 61 6c 6c 65 64 20  has been called 
2ce10 6d 6f 72 65 20 72 65 63 65 6e 74 6c 79 20 74 68  more recently th
2ce20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  an [sqlite3_rese
2ce30 74 28 29 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68  t()],.** then th
2ce40 65 20 63 61 6c 6c 20 77 69 6c 6c 20 72 65 74 75  e call will retu
2ce50 72 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53  rn [SQLITE_MISUS
2ce60 45 5d 2e 20 20 49 66 20 61 6e 79 20 73 71 6c 69  E].  If any sqli
2ce70 74 65 33 5f 62 69 6e 64 5f 28 29 0a 2a 2a 20 72  te3_bind_().** r
2ce80 6f 75 74 69 6e 65 20 69 73 20 70 61 73 73 65 64  outine is passed
2ce90 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
2cea0 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 68 61 73  tement] that has
2ceb0 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2c   been finalized,
2cec0 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 69   the.** result i
2ced0 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20  s undefined and 
2cee0 70 72 6f 62 61 62 6c 79 20 68 61 72 6d 66 75 6c  probably harmful
2cef0 2e 0a 2a 2a 0a 2a 2a 20 5e 42 69 6e 64 69 6e 67  ..**.** ^Binding
2cf00 73 20 61 72 65 20 6e 6f 74 20 63 6c 65 61 72 65  s are not cleare
2cf10 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65  d by the [sqlite
2cf20 33 5f 72 65 73 65 74 28 29 5d 20 72 6f 75 74 69  3_reset()] routi
2cf30 6e 65 2e 0a 2a 2a 20 5e 55 6e 62 6f 75 6e 64 20  ne..** ^Unbound 
2cf40 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 69  parameters are i
2cf50 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 4e 55  nterpreted as NU
2cf60 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  LL..**.** ^The s
2cf70 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 20 72 6f  qlite3_bind_* ro
2cf80 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 5b 53  utines return [S
2cf90 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63  QLITE_OK] on suc
2cfa0 63 65 73 73 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65  cess or an.** [e
2cfb0 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 6e  rror code] if an
2cfc0 79 74 68 69 6e 67 20 67 6f 65 73 20 77 72 6f 6e  ything goes wron
2cfd0 67 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 54  g..** ^[SQLITE_T
2cfe0 4f 4f 42 49 47 5d 20 6d 69 67 68 74 20 62 65 20  OOBIG] might be 
2cff0 72 65 74 75 72 6e 65 64 20 69 66 20 74 68 65 20  returned if the 
2d000 73 69 7a 65 20 6f 66 20 61 20 73 74 72 69 6e 67  size of a string
2d010 20 6f 72 20 42 4c 4f 42 0a 2a 2a 20 65 78 63 65   or BLOB.** exce
2d020 65 64 73 20 6c 69 6d 69 74 73 20 69 6d 70 6f 73  eds limits impos
2d030 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c  ed by [sqlite3_l
2d040 69 6d 69 74 5d 28 5b 53 51 4c 49 54 45 5f 4c 49  imit]([SQLITE_LI
2d050 4d 49 54 5f 4c 45 4e 47 54 48 5d 29 20 6f 72 0a  MIT_LENGTH]) or.
2d060 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 41 58 5f 4c  ** [SQLITE_MAX_L
2d070 45 4e 47 54 48 5d 2e 0a 2a 2a 20 5e 5b 53 51 4c  ENGTH]..** ^[SQL
2d080 49 54 45 5f 52 41 4e 47 45 5d 20 69 73 20 72 65  ITE_RANGE] is re
2d090 74 75 72 6e 65 64 20 69 66 20 74 68 65 20 70 61  turned if the pa
2d0a0 72 61 6d 65 74 65 72 0a 2a 2a 20 69 6e 64 65 78  rameter.** index
2d0b0 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65   is out of range
2d0c0 2e 20 20 5e 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45  .  ^[SQLITE_NOME
2d0d0 4d 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 69  M] is returned i
2d0e0 66 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73  f malloc() fails
2d0f0 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
2d100 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  : [sqlite3_bind_
2d110 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28  parameter_count(
2d120 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
2d130 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e  bind_parameter_n
2d140 61 6d 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c  ame()], and [sql
2d150 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
2d160 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f  ter_index()]..*/
2d170 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
2d180 64 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73  d_blob(sqlite3_s
2d190 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74  tmt*, int, const
2d1a0 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 2c 20 76   void*, int n, v
2d1b0 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
2d1c0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
2d1d0 5f 62 6c 6f 62 36 34 28 73 71 6c 69 74 65 33 5f  _blob64(sqlite3_
2d1e0 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73  stmt*, int, cons
2d1f0 74 20 76 6f 69 64 2a 2c 20 73 71 6c 69 74 65 33  t void*, sqlite3
2d200 5f 75 69 6e 74 36 34 2c 0a 20 20 20 20 20 20 20  _uint64,.       
2d210 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2d220 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29   void(*)(void*))
2d230 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
2d240 6e 64 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65  nd_double(sqlite
2d250 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 64 6f  3_stmt*, int, do
2d260 75 62 6c 65 29 3b 0a 69 6e 74 20 73 71 6c 69 74  uble);.int sqlit
2d270 65 33 5f 62 69 6e 64 5f 69 6e 74 28 73 71 6c 69  e3_bind_int(sqli
2d280 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
2d290 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  int);.int sqlite
2d2a0 33 5f 62 69 6e 64 5f 69 6e 74 36 34 28 73 71 6c  3_bind_int64(sql
2d2b0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
2d2c0 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b   sqlite3_int64);
2d2d0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
2d2e0 64 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 73  d_null(sqlite3_s
2d2f0 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 69 6e 74 20  tmt*, int);.int 
2d300 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
2d310 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  t(sqlite3_stmt*,
2d320 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c  int,const char*,
2d330 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64  int,void(*)(void
2d340 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  *));.int sqlite3
2d350 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 73 71 6c  _bind_text16(sql
2d360 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
2d370 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e   const void*, in
2d380 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  t, void(*)(void*
2d390 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  ));.int sqlite3_
2d3a0 62 69 6e 64 5f 74 65 78 74 36 34 28 73 71 6c 69  bind_text64(sqli
2d3b0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
2d3c0 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 73 71 6c  const char*, sql
2d3d0 69 74 65 33 5f 75 69 6e 74 36 34 2c 0a 20 20 20  ite3_uint64,.   
2d3e0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2d3f0 20 20 20 20 20 20 76 6f 69 64 28 2a 29 28 76 6f        void(*)(vo
2d400 69 64 2a 29 2c 20 75 6e 73 69 67 6e 65 64 20 63  id*), unsigned c
2d410 68 61 72 20 65 6e 63 6f 64 69 6e 67 29 3b 0a 69  har encoding);.i
2d420 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
2d430 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74  value(sqlite3_st
2d440 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20  mt*, int, const 
2d450 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
2d460 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
2d470 64 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74  d_zeroblob(sqlit
2d480 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69  e3_stmt*, int, i
2d490 6e 74 20 6e 29 3b 0a 69 6e 74 20 73 71 6c 69 74  nt n);.int sqlit
2d4a0 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62  e3_bind_zeroblob
2d4b0 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  64(sqlite3_stmt*
2d4c0 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f 75  , int, sqlite3_u
2d4d0 69 6e 74 36 34 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  int64);../*.** C
2d4e0 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20  API3REF: Number 
2d4f0 4f 66 20 53 51 4c 20 50 61 72 61 6d 65 74 65 72  Of SQL Parameter
2d500 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  s.** METHOD: sql
2d510 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20  ite3_stmt.**.** 
2d520 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 63 61  ^This routine ca
2d530 6e 20 62 65 20 75 73 65 64 20 74 6f 20 66 69 6e  n be used to fin
2d540 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  d the number of 
2d550 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 5d  [SQL parameters]
2d560 0a 2a 2a 20 69 6e 20 61 20 5b 70 72 65 70 61 72  .** in a [prepar
2d570 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20  ed statement].  
2d580 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20 61  SQL parameters a
2d590 72 65 20 74 6f 6b 65 6e 73 20 6f 66 20 74 68 65  re tokens of the
2d5a0 0a 2a 2a 20 66 6f 72 6d 20 22 3f 22 2c 20 22 3f  .** form "?", "?
2d5b0 4e 4e 4e 22 2c 20 22 3a 41 41 41 22 2c 20 22 24  NNN", ":AAA", "$
2d5c0 41 41 41 22 2c 20 6f 72 20 22 40 41 41 41 22 20  AAA", or "@AAA" 
2d5d0 74 68 61 74 20 73 65 72 76 65 20 61 73 0a 2a 2a  that serve as.**
2d5e0 20 70 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 6f   placeholders fo
2d5f0 72 20 76 61 6c 75 65 73 20 74 68 61 74 20 61 72  r values that ar
2d600 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  e [sqlite3_bind_
2d610 62 6c 6f 62 20 7c 20 62 6f 75 6e 64 5d 0a 2a 2a  blob | bound].**
2d620 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65   to the paramete
2d630 72 73 20 61 74 20 61 20 6c 61 74 65 72 20 74 69  rs at a later ti
2d640 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73  me..**.** ^(This
2d650 20 72 6f 75 74 69 6e 65 20 61 63 74 75 61 6c 6c   routine actuall
2d660 79 20 72 65 74 75 72 6e 73 20 74 68 65 20 69 6e  y returns the in
2d670 64 65 78 20 6f 66 20 74 68 65 20 6c 61 72 67 65  dex of the large
2d680 73 74 20 28 72 69 67 68 74 6d 6f 73 74 29 0a 2a  st (rightmost).*
2d690 2a 20 70 61 72 61 6d 65 74 65 72 2e 20 46 6f 72  * parameter. For
2d6a0 20 61 6c 6c 20 66 6f 72 6d 73 20 65 78 63 65 70   all forms excep
2d6b0 74 20 3f 4e 4e 4e 2c 20 74 68 69 73 20 77 69 6c  t ?NNN, this wil
2d6c0 6c 20 63 6f 72 72 65 73 70 6f 6e 64 20 74 6f 20  l correspond to 
2d6d0 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66  the.** number of
2d6e0 20 75 6e 69 71 75 65 20 70 61 72 61 6d 65 74 65   unique paramete
2d6f0 72 73 2e 20 20 49 66 20 70 61 72 61 6d 65 74 65  rs.  If paramete
2d700 72 73 20 6f 66 20 74 68 65 20 3f 4e 4e 4e 20 66  rs of the ?NNN f
2d710 6f 72 6d 20 61 72 65 20 75 73 65 64 2c 0a 2a 2a  orm are used,.**
2d720 20 74 68 65 72 65 20 6d 61 79 20 62 65 20 67 61   there may be ga
2d730 70 73 20 69 6e 20 74 68 65 20 6c 69 73 74 2e 29  ps in the list.)
2d740 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ^.**.** See also
2d750 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  : [sqlite3_bind_
2d760 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e  blob|sqlite3_bin
2d770 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  d()],.** [sqlite
2d780 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
2d790 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a  _name()], and.**
2d7a0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
2d7b0 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29  arameter_index()
2d7c0 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  ]..*/.int sqlite
2d7d0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
2d7e0 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73  _count(sqlite3_s
2d7f0 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  tmt*);../*.** CA
2d800 50 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20  PI3REF: Name Of 
2d810 41 20 48 6f 73 74 20 50 61 72 61 6d 65 74 65 72  A Host Parameter
2d820 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
2d830 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e  te3_stmt.**.** ^
2d840 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  The sqlite3_bind
2d850 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28  _parameter_name(
2d860 50 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 20 72  P,N) interface r
2d870 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 61  eturns.** the na
2d880 6d 65 20 6f 66 20 74 68 65 20 4e 2d 74 68 20 5b  me of the N-th [
2d890 53 51 4c 20 70 61 72 61 6d 65 74 65 72 5d 20 69  SQL parameter] i
2d8a0 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  n the [prepared 
2d8b0 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a  statement] P..**
2d8c0 20 5e 28 53 51 4c 20 70 61 72 61 6d 65 74 65 72   ^(SQL parameter
2d8d0 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f  s of the form "?
2d8e0 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 6f  NNN" or ":AAA" o
2d8f0 72 20 22 40 41 41 41 22 20 6f 72 20 22 24 41 41  r "@AAA" or "$AA
2d900 41 22 0a 2a 2a 20 68 61 76 65 20 61 20 6e 61 6d  A".** have a nam
2d910 65 20 77 68 69 63 68 20 69 73 20 74 68 65 20 73  e which is the s
2d920 74 72 69 6e 67 20 22 3f 4e 4e 4e 22 20 6f 72 20  tring "?NNN" or 
2d930 22 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41 22  ":AAA" or "@AAA"
2d940 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 72 65   or "$AAA".** re
2d950 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 49  spectively..** I
2d960 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74  n other words, t
2d970 68 65 20 69 6e 69 74 69 61 6c 20 22 3a 22 20 6f  he initial ":" o
2d980 72 20 22 24 22 20 6f 72 20 22 40 22 20 6f 72 20  r "$" or "@" or 
2d990 22 3f 22 0a 2a 2a 20 69 73 20 69 6e 63 6c 75 64  "?".** is includ
2d9a0 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 74 68  ed as part of th
2d9b0 65 20 6e 61 6d 65 2e 29 5e 0a 2a 2a 20 5e 50 61  e name.)^.** ^Pa
2d9c0 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20  rameters of the 
2d9d0 66 6f 72 6d 20 22 3f 22 20 77 69 74 68 6f 75 74  form "?" without
2d9e0 20 61 20 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74   a following int
2d9f0 65 67 65 72 20 68 61 76 65 20 6e 6f 20 6e 61 6d  eger have no nam
2da00 65 0a 2a 2a 20 61 6e 64 20 61 72 65 20 72 65 66  e.** and are ref
2da10 65 72 72 65 64 20 74 6f 20 61 73 20 22 6e 61 6d  erred to as "nam
2da20 65 6c 65 73 73 22 20 6f 72 20 22 61 6e 6f 6e 79  eless" or "anony
2da30 6d 6f 75 73 20 70 61 72 61 6d 65 74 65 72 73 22  mous parameters"
2da40 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72  ..**.** ^The fir
2da50 73 74 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65  st host paramete
2da60 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f  r has an index o
2da70 66 20 31 2c 20 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a  f 1, not 0..**.*
2da80 2a 20 5e 49 66 20 74 68 65 20 76 61 6c 75 65 20  * ^If the value 
2da90 4e 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67  N is out of rang
2daa0 65 20 6f 72 20 69 66 20 74 68 65 20 4e 2d 74 68  e or if the N-th
2dab0 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a   parameter is.**
2dac0 20 6e 61 6d 65 6c 65 73 73 2c 20 74 68 65 6e 20   nameless, then 
2dad0 4e 55 4c 4c 20 69 73 20 72 65 74 75 72 6e 65 64  NULL is returned
2dae0 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64  .  ^The returned
2daf0 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 61 6c   string is.** al
2db00 77 61 79 73 20 69 6e 20 55 54 46 2d 38 20 65 6e  ways in UTF-8 en
2db10 63 6f 64 69 6e 67 20 65 76 65 6e 20 69 66 20 74  coding even if t
2db20 68 65 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74  he named paramet
2db30 65 72 20 77 61 73 0a 2a 2a 20 6f 72 69 67 69 6e  er was.** origin
2db40 61 6c 6c 79 20 73 70 65 63 69 66 69 65 64 20 61  ally specified a
2db50 73 20 55 54 46 2d 31 36 20 69 6e 20 5b 73 71 6c  s UTF-16 in [sql
2db60 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29  ite3_prepare16()
2db70 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ] or.** [sqlite3
2db80 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
2db90 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
2dba0 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  : [sqlite3_bind_
2dbb0 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e  blob|sqlite3_bin
2dbc0 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  d()],.** [sqlite
2dbd0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
2dbe0 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a  _count()], and.*
2dbf0 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
2dc00 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28  parameter_index(
2dc10 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61  )]..*/.const cha
2dc20 72 20 2a 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  r *sqlite3_bind_
2dc30 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 73  parameter_name(s
2dc40 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
2dc50 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
2dc60 52 45 46 3a 20 49 6e 64 65 78 20 4f 66 20 41 20  REF: Index Of A 
2dc70 50 61 72 61 6d 65 74 65 72 20 57 69 74 68 20 41  Parameter With A
2dc80 20 47 69 76 65 6e 20 4e 61 6d 65 0a 2a 2a 20 4d   Given Name.** M
2dc90 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73  ETHOD: sqlite3_s
2dca0 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72  tmt.**.** ^Retur
2dcb0 6e 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 61  n the index of a
2dcc0 6e 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20  n SQL parameter 
2dcd0 67 69 76 65 6e 20 69 74 73 20 6e 61 6d 65 2e 20  given its name. 
2dce0 20 5e 54 68 65 0a 2a 2a 20 69 6e 64 65 78 20 76   ^The.** index v
2dcf0 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 69 73  alue returned is
2dd00 20 73 75 69 74 61 62 6c 65 20 66 6f 72 20 75 73   suitable for us
2dd10 65 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 0a  e as the second.
2dd20 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  ** parameter to 
2dd30 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
2dd40 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28  ob|sqlite3_bind(
2dd50 29 5d 2e 20 20 5e 41 20 7a 65 72 6f 0a 2a 2a 20  )].  ^A zero.** 
2dd60 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 6e  is returned if n
2dd70 6f 20 6d 61 74 63 68 69 6e 67 20 70 61 72 61 6d  o matching param
2dd80 65 74 65 72 20 69 73 20 66 6f 75 6e 64 2e 20 20  eter is found.  
2dd90 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a  ^The parameter.*
2dda0 2a 20 6e 61 6d 65 20 6d 75 73 74 20 62 65 20 67  * name must be g
2ddb0 69 76 65 6e 20 69 6e 20 55 54 46 2d 38 20 65 76  iven in UTF-8 ev
2ddc0 65 6e 20 69 66 20 74 68 65 20 6f 72 69 67 69 6e  en if the origin
2ddd0 61 6c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20  al statement.** 
2dde0 77 61 73 20 70 72 65 70 61 72 65 64 20 66 72 6f  was prepared fro
2ddf0 6d 20 55 54 46 2d 31 36 20 74 65 78 74 20 75 73  m UTF-16 text us
2de00 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  ing [sqlite3_pre
2de10 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a  pare16_v2()]..**
2de20 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73  .** See also: [s
2de30 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
2de40 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d  |sqlite3_bind()]
2de50 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  ,.** [sqlite3_bi
2de60 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75  nd_parameter_cou
2de70 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73  nt()], and.** [s
2de80 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
2de90 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2e 0a 2a  meter_name()]..*
2dea0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  /.int sqlite3_bi
2deb0 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64  nd_parameter_ind
2dec0 65 78 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ex(sqlite3_stmt*
2ded0 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
2dee0 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ame);../*.** CAP
2def0 49 33 52 45 46 3a 20 52 65 73 65 74 20 41 6c 6c  I3REF: Reset All
2df00 20 42 69 6e 64 69 6e 67 73 20 4f 6e 20 41 20 50   Bindings On A P
2df10 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e  repared Statemen
2df20 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  t.** METHOD: sql
2df30 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20  ite3_stmt.**.** 
2df40 5e 43 6f 6e 74 72 61 72 79 20 74 6f 20 74 68 65  ^Contrary to the
2df50 20 69 6e 74 75 69 74 69 6f 6e 20 6f 66 20 6d 61   intuition of ma
2df60 6e 79 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  ny, [sqlite3_res
2df70 65 74 28 29 5d 20 64 6f 65 73 20 6e 6f 74 20 72  et()] does not r
2df80 65 73 65 74 0a 2a 2a 20 74 68 65 20 5b 73 71 6c  eset.** the [sql
2df90 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c  ite3_bind_blob |
2dfa0 20 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 61 20   bindings] on a 
2dfb0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2dfc0 65 6e 74 5d 2e 0a 2a 2a 20 5e 55 73 65 20 74 68  ent]..** ^Use th
2dfd0 69 73 20 72 6f 75 74 69 6e 65 20 74 6f 20 72 65  is routine to re
2dfe0 73 65 74 20 61 6c 6c 20 68 6f 73 74 20 70 61 72  set all host par
2dff0 61 6d 65 74 65 72 73 20 74 6f 20 4e 55 4c 4c 2e  ameters to NULL.
2e000 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
2e010 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 73  clear_bindings(s
2e020 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a  qlite3_stmt*);..
2e030 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2e040 4e 75 6d 62 65 72 20 4f 66 20 43 6f 6c 75 6d 6e  Number Of Column
2e050 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65  s In A Result Se
2e060 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  t.** METHOD: sql
2e070 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20  ite3_stmt.**.** 
2e080 5e 52 65 74 75 72 6e 20 74 68 65 20 6e 75 6d 62  ^Return the numb
2e090 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e  er of columns in
2e0a0 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20   the result set 
2e0b0 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 0a  returned by the.
2e0c0 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ** [prepared sta
2e0d0 74 65 6d 65 6e 74 5d 2e 20 5e 54 68 69 73 20 72  tement]. ^This r
2e0e0 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 30  outine returns 0
2e0f0 20 69 66 20 70 53 74 6d 74 20 69 73 20 61 6e 20   if pStmt is an 
2e100 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  SQL.** statement
2e110 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 72   that does not r
2e120 65 74 75 72 6e 20 64 61 74 61 20 28 66 6f 72 20  eturn data (for 
2e130 65 78 61 6d 70 6c 65 20 61 6e 20 5b 55 50 44 41  example an [UPDA
2e140 54 45 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  TE])..**.** See 
2e150 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 64  also: [sqlite3_d
2e160 61 74 61 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a  ata_count()].*/.
2e170 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  int sqlite3_colu
2e180 6d 6e 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33  mn_count(sqlite3
2e190 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a  _stmt *pStmt);..
2e1a0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2e1b0 43 6f 6c 75 6d 6e 20 4e 61 6d 65 73 20 49 6e 20  Column Names In 
2e1c0 41 20 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a 20  A Result Set.** 
2e1d0 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f  METHOD: sqlite3_
2e1e0 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  stmt.**.** ^Thes
2e1f0 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  e routines retur
2e200 6e 20 74 68 65 20 6e 61 6d 65 20 61 73 73 69 67  n the name assig
2e210 6e 65 64 20 74 6f 20 61 20 70 61 72 74 69 63 75  ned to a particu
2e220 6c 61 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e  lar column.** in
2e230 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20   the result set 
2e240 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74  of a [SELECT] st
2e250 61 74 65 6d 65 6e 74 2e 20 20 5e 54 68 65 20 73  atement.  ^The s
2e260 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
2e270 6d 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63  me().** interfac
2e280 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  e returns a poin
2e290 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65  ter to a zero-te
2e2a0 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73  rminated UTF-8 s
2e2b0 74 72 69 6e 67 0a 2a 2a 20 61 6e 64 20 73 71 6c  tring.** and sql
2e2c0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
2e2d0 31 36 28 29 20 72 65 74 75 72 6e 73 20 61 20 70  16() returns a p
2e2e0 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 6f  ointer to a zero
2e2f0 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55  -terminated.** U
2e300 54 46 2d 31 36 20 73 74 72 69 6e 67 2e 20 20 5e  TF-16 string.  ^
2e310 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
2e320 74 65 72 20 69 73 20 74 68 65 20 5b 70 72 65 70  ter is the [prep
2e330 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a  ared statement].
2e340 2a 2a 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e  ** that implemen
2e350 74 73 20 74 68 65 20 5b 53 45 4c 45 43 54 5d 20  ts the [SELECT] 
2e360 73 74 61 74 65 6d 65 6e 74 2e 20 5e 54 68 65 20  statement. ^The 
2e370 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
2e380 20 69 73 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d   is the.** colum
2e390 6e 20 6e 75 6d 62 65 72 2e 20 20 5e 54 68 65 20  n number.  ^The 
2e3a0 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20  leftmost column 
2e3b0 69 73 20 6e 75 6d 62 65 72 20 30 2e 0a 2a 2a 0a  is number 0..**.
2e3c0 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64  ** ^The returned
2e3d0 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 72 20   string pointer 
2e3e0 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 65  is valid until e
2e3f0 69 74 68 65 72 20 74 68 65 20 5b 70 72 65 70 61  ither the [prepa
2e400 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a  red statement].*
2e410 2a 20 69 73 20 64 65 73 74 72 6f 79 65 64 20 62  * is destroyed b
2e420 79 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  y [sqlite3_final
2e430 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20  ize()] or until 
2e440 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73  the statement is
2e450 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a   automatically.*
2e460 2a 20 72 65 70 72 65 70 61 72 65 64 20 62 79 20  * reprepared by 
2e470 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c 20 74  the first call t
2e480 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  o [sqlite3_step(
2e490 29 5d 20 66 6f 72 20 61 20 70 61 72 74 69 63 75  )] for a particu
2e4a0 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e  lar run.** or un
2e4b0 74 69 6c 20 74 68 65 20 6e 65 78 74 20 63 61 6c  til the next cal
2e4c0 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  l to.** sqlite3_
2e4d0 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 20 6f 72  column_name() or
2e4e0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2e4f0 6e 61 6d 65 31 36 28 29 20 6f 6e 20 74 68 65 20  name16() on the 
2e500 73 61 6d 65 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a  same column..**.
2e510 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6d  ** ^If sqlite3_m
2e520 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 20 64 75  alloc() fails du
2e530 72 69 6e 67 20 74 68 65 20 70 72 6f 63 65 73 73  ring the process
2e540 69 6e 67 20 6f 66 20 65 69 74 68 65 72 20 72 6f  ing of either ro
2e550 75 74 69 6e 65 0a 2a 2a 20 28 66 6f 72 20 65 78  utine.** (for ex
2e560 61 6d 70 6c 65 20 64 75 72 69 6e 67 20 61 20 63  ample during a c
2e570 6f 6e 76 65 72 73 69 6f 6e 20 66 72 6f 6d 20 55  onversion from U
2e580 54 46 2d 38 20 74 6f 20 55 54 46 2d 31 36 29 20  TF-8 to UTF-16) 
2e590 74 68 65 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70  then a.** NULL p
2e5a0 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e  ointer is return
2e5b0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e  ed..**.** ^The n
2e5c0 61 6d 65 20 6f 66 20 61 20 72 65 73 75 6c 74 20  ame of a result 
2e5d0 63 6f 6c 75 6d 6e 20 69 73 20 74 68 65 20 76 61  column is the va
2e5e0 6c 75 65 20 6f 66 20 74 68 65 20 22 41 53 22 20  lue of the "AS" 
2e5f0 63 6c 61 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68  clause for.** th
2e600 61 74 20 63 6f 6c 75 6d 6e 2c 20 69 66 20 74 68  at column, if th
2e610 65 72 65 20 69 73 20 61 6e 20 41 53 20 63 6c 61  ere is an AS cla
2e620 75 73 65 2e 20 20 49 66 20 74 68 65 72 65 20 69  use.  If there i
2e630 73 20 6e 6f 20 41 53 20 63 6c 61 75 73 65 0a 2a  s no AS clause.*
2e640 2a 20 74 68 65 6e 20 74 68 65 20 6e 61 6d 65 20  * then the name 
2e650 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69 73  of the column is
2e660 20 75 6e 73 70 65 63 69 66 69 65 64 20 61 6e 64   unspecified and
2e670 20 6d 61 79 20 63 68 61 6e 67 65 20 66 72 6f 6d   may change from
2e680 0a 2a 2a 20 6f 6e 65 20 72 65 6c 65 61 73 65 20  .** one release 
2e690 6f 66 20 53 51 4c 69 74 65 20 74 6f 20 74 68 65  of SQLite to the
2e6a0 20 6e 65 78 74 2e 0a 2a 2f 0a 63 6f 6e 73 74 20   next..*/.const 
2e6b0 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
2e6c0 6c 75 6d 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65  lumn_name(sqlite
2e6d0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b  3_stmt*, int N);
2e6e0 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
2e6f0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
2e700 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
2e710 2c 20 69 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a  , int N);../*.**
2e720 20 43 41 50 49 33 52 45 46 3a 20 53 6f 75 72 63   CAPI3REF: Sourc
2e730 65 20 4f 66 20 44 61 74 61 20 49 6e 20 41 20 51  e Of Data In A Q
2e740 75 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a 20 4d  uery Result.** M
2e750 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73  ETHOD: sqlite3_s
2e760 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  tmt.**.** ^These
2e770 20 72 6f 75 74 69 6e 65 73 20 70 72 6f 76 69 64   routines provid
2e780 65 20 61 20 6d 65 61 6e 73 20 74 6f 20 64 65 74  e a means to det
2e790 65 72 6d 69 6e 65 20 74 68 65 20 64 61 74 61 62  ermine the datab
2e7a0 61 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64 0a  ase, table, and.
2e7b0 2a 2a 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20  ** table column 
2e7c0 74 68 61 74 20 69 73 20 74 68 65 20 6f 72 69 67  that is the orig
2e7d0 69 6e 20 6f 66 20 61 20 70 61 72 74 69 63 75 6c  in of a particul
2e7e0 61 72 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  ar result column
2e7f0 20 69 6e 0a 2a 2a 20 5b 53 45 4c 45 43 54 5d 20   in.** [SELECT] 
2e800 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 5e 54  statement..** ^T
2e810 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64  he name of the d
2e820 61 74 61 62 61 73 65 20 6f 72 20 74 61 62 6c 65  atabase or table
2e830 20 6f 72 20 63 6f 6c 75 6d 6e 20 63 61 6e 20 62   or column can b
2e840 65 20 72 65 74 75 72 6e 65 64 20 61 73 0a 2a 2a  e returned as.**
2e850 20 65 69 74 68 65 72 20 61 20 55 54 46 2d 38 20   either a UTF-8 
2e860 6f 72 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67  or UTF-16 string
2e870 2e 20 20 5e 54 68 65 20 5f 64 61 74 61 62 61 73  .  ^The _databas
2e880 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  e_ routines retu
2e890 72 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61  rn.** the databa
2e8a0 73 65 20 6e 61 6d 65 2c 20 74 68 65 20 5f 74 61  se name, the _ta
2e8b0 62 6c 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65  ble_ routines re
2e8c0 74 75 72 6e 20 74 68 65 20 74 61 62 6c 65 20 6e  turn the table n
2e8d0 61 6d 65 2c 20 61 6e 64 0a 2a 2a 20 74 68 65 20  ame, and.** the 
2e8e0 6f 72 69 67 69 6e 5f 20 72 6f 75 74 69 6e 65 73  origin_ routines
2e8f0 20 72 65 74 75 72 6e 20 74 68 65 20 63 6f 6c 75   return the colu
2e900 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a 20 5e 54 68 65  mn name..** ^The
2e910 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67   returned string
2e920 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20   is valid until 
2e930 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
2e940 61 74 65 6d 65 6e 74 5d 20 69 73 20 64 65 73 74  atement] is dest
2e950 72 6f 79 65 64 0a 2a 2a 20 75 73 69 6e 67 20 5b  royed.** using [
2e960 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
2e970 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65  ()] or until the
2e980 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 75   statement is au
2e990 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 72  tomatically.** r
2e9a0 65 70 72 65 70 61 72 65 64 20 62 79 20 74 68 65  eprepared by the
2e9b0 20 66 69 72 73 74 20 63 61 6c 6c 20 74 6f 20 5b   first call to [
2e9c0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
2e9d0 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72  for a particular
2e9e0 20 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c   run.** or until
2e9f0 20 74 68 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d   the same inform
2ea00 61 74 69 6f 6e 20 69 73 20 72 65 71 75 65 73 74  ation is request
2ea10 65 64 0a 2a 2a 20 61 67 61 69 6e 20 69 6e 20 61  ed.** again in a
2ea20 20 64 69 66 66 65 72 65 6e 74 20 65 6e 63 6f 64   different encod
2ea30 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ing..**.** ^The 
2ea40 6e 61 6d 65 73 20 72 65 74 75 72 6e 65 64 20 61  names returned a
2ea50 72 65 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20  re the original 
2ea60 75 6e 2d 61 6c 69 61 73 65 64 20 6e 61 6d 65 73  un-aliased names
2ea70 20 6f 66 20 74 68 65 0a 2a 2a 20 64 61 74 61 62   of the.** datab
2ea80 61 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64 20  ase, table, and 
2ea90 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54  column..**.** ^T
2eaa0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
2eab0 74 20 74 6f 20 74 68 65 73 65 20 69 6e 74 65 72  t to these inter
2eac0 66 61 63 65 73 20 69 73 20 61 20 5b 70 72 65 70  faces is a [prep
2ead0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
2eae0 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e 63 74  .** ^These funct
2eaf0 69 6f 6e 73 20 72 65 74 75 72 6e 20 69 6e 66 6f  ions return info
2eb00 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 74 68  rmation about th
2eb10 65 20 4e 74 68 20 72 65 73 75 6c 74 20 63 6f 6c  e Nth result col
2eb20 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62 79 0a  umn returned by.
2eb30 2a 2a 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  ** the statement
2eb40 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65  , where N is the
2eb50 20 73 65 63 6f 6e 64 20 66 75 6e 63 74 69 6f 6e   second function
2eb60 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54   argument..** ^T
2eb70 68 65 20 6c 65 66 74 2d 6d 6f 73 74 20 63 6f 6c  he left-most col
2eb80 75 6d 6e 20 69 73 20 63 6f 6c 75 6d 6e 20 30 20  umn is column 0 
2eb90 66 6f 72 20 74 68 65 73 65 20 72 6f 75 74 69 6e  for these routin
2eba0 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  es..**.** ^If th
2ebb0 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 72 65 74  e Nth column ret
2ebc0 75 72 6e 65 64 20 62 79 20 74 68 65 20 73 74 61  urned by the sta
2ebd0 74 65 6d 65 6e 74 20 69 73 20 61 6e 20 65 78 70  tement is an exp
2ebe0 72 65 73 73 69 6f 6e 20 6f 72 0a 2a 2a 20 73 75  ression or.** su
2ebf0 62 71 75 65 72 79 20 61 6e 64 20 69 73 20 6e 6f  bquery and is no
2ec00 74 20 61 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65  t a column value
2ec10 2c 20 74 68 65 6e 20 61 6c 6c 20 6f 66 20 74 68  , then all of th
2ec20 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65  ese functions re
2ec30 74 75 72 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20 20 5e  turn.** NULL.  ^
2ec40 54 68 65 73 65 20 72 6f 75 74 69 6e 65 20 6d 69  These routine mi
2ec50 67 68 74 20 61 6c 73 6f 20 72 65 74 75 72 6e 20  ght also return 
2ec60 4e 55 4c 4c 20 69 66 20 61 20 6d 65 6d 6f 72 79  NULL if a memory
2ec70 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f   allocation erro
2ec80 72 0a 2a 2a 20 6f 63 63 75 72 73 2e 20 20 5e 4f  r.** occurs.  ^O
2ec90 74 68 65 72 77 69 73 65 2c 20 74 68 65 79 20 72  therwise, they r
2eca0 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 6f  eturn the name o
2ecb0 66 20 74 68 65 20 61 74 74 61 63 68 65 64 20 64  f the attached d
2ecc0 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 0a  atabase, table,.
2ecd0 2a 2a 20 6f 72 20 63 6f 6c 75 6d 6e 20 74 68 61  ** or column tha
2ece0 74 20 71 75 65 72 79 20 72 65 73 75 6c 74 20 63  t query result c
2ecf0 6f 6c 75 6d 6e 20 77 61 73 20 65 78 74 72 61 63  olumn was extrac
2ed00 74 65 64 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20  ted from..**.** 
2ed10 5e 41 73 20 77 69 74 68 20 61 6c 6c 20 6f 74 68  ^As with all oth
2ed20 65 72 20 53 51 4c 69 74 65 20 41 50 49 73 2c 20  er SQLite APIs, 
2ed30 74 68 6f 73 65 20 77 68 6f 73 65 20 6e 61 6d 65  those whose name
2ed40 73 20 65 6e 64 20 77 69 74 68 20 22 31 36 22 20  s end with "16" 
2ed50 72 65 74 75 72 6e 0a 2a 2a 20 55 54 46 2d 31 36  return.** UTF-16
2ed60 20 65 6e 63 6f 64 65 64 20 73 74 72 69 6e 67 73   encoded strings
2ed70 20 61 6e 64 20 74 68 65 20 6f 74 68 65 72 20 66   and the other f
2ed80 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20  unctions return 
2ed90 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  UTF-8..**.** ^Th
2eda0 65 73 65 20 41 50 49 73 20 61 72 65 20 6f 6e 6c  ese APIs are onl
2edb0 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20 74  y available if t
2edc0 68 65 20 6c 69 62 72 61 72 79 20 77 61 73 20 63  he library was c
2edd0 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65  ompiled with the
2ede0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42  .** [SQLITE_ENAB
2edf0 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41  LE_COLUMN_METADA
2ee00 54 41 5d 20 43 2d 70 72 65 70 72 6f 63 65 73 73  TA] C-preprocess
2ee10 6f 72 20 73 79 6d 62 6f 6c 2e 0a 2a 2a 0a 2a 2a  or symbol..**.**
2ee20 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20   If two or more 
2ee30 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65  threads call one
2ee40 20 6f 72 20 6d 6f 72 65 20 6f 66 20 74 68 65 73   or more of thes
2ee50 65 20 72 6f 75 74 69 6e 65 73 20 61 67 61 69 6e  e routines again
2ee60 73 74 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 70  st the same.** p
2ee70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2ee80 74 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 61 74 20  t and column at 
2ee90 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68  the same time th
2eea0 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61  en the results a
2eeb0 72 65 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e  re.** undefined.
2eec0 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72  .**.** If two or
2eed0 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63 61   more threads ca
2eee0 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a  ll one or more.*
2eef0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  * [sqlite3_colum
2ef00 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 20  n_database_name 
2ef10 7c 20 63 6f 6c 75 6d 6e 20 6d 65 74 61 64 61 74  | column metadat
2ef20 61 20 69 6e 74 65 72 66 61 63 65 73 5d 0a 2a 2a  a interfaces].**
2ef30 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 5b 70   for the same [p
2ef40 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2ef50 74 5d 20 61 6e 64 20 72 65 73 75 6c 74 20 63 6f  t] and result co
2ef60 6c 75 6d 6e 0a 2a 2a 20 61 74 20 74 68 65 20 73  lumn.** at the s
2ef70 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68  ame time then th
2ef80 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e  e results are un
2ef90 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 63 6f 6e 73  defined..*/.cons
2efa0 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
2efb0 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f  column_database_
2efc0 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  name(sqlite3_stm
2efd0 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76  t*,int);.const v
2efe0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
2eff0 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d  umn_database_nam
2f000 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  e16(sqlite3_stmt
2f010 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68  *,int);.const ch
2f020 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ar *sqlite3_colu
2f030 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 28 73 71  mn_table_name(sq
2f040 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
2f050 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
2f060 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62  lite3_column_tab
2f070 6c 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65  le_name16(sqlite
2f080 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f  3_stmt*,int);.co
2f090 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
2f0a0 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f  3_column_origin_
2f0b0 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  name(sqlite3_stm
2f0c0 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76  t*,int);.const v
2f0d0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
2f0e0 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 31  umn_origin_name1
2f0f0 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
2f100 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  int);../*.** CAP
2f110 49 33 52 45 46 3a 20 44 65 63 6c 61 72 65 64 20  I3REF: Declared 
2f120 44 61 74 61 74 79 70 65 20 4f 66 20 41 20 51 75  Datatype Of A Qu
2f130 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a 20 4d 45  ery Result.** ME
2f140 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74  THOD: sqlite3_st
2f150 6d 74 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66  mt.**.** ^(The f
2f160 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69  irst parameter i
2f170 73 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  s a [prepared st
2f180 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 49 66 20  atement]..** If 
2f190 74 68 69 73 20 73 74 61 74 65 6d 65 6e 74 20 69  this statement i
2f1a0 73 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61  s a [SELECT] sta
2f1b0 74 65 6d 65 6e 74 20 61 6e 64 20 74 68 65 20 4e  tement and the N
2f1c0 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65  th column of the
2f1d0 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 72 65 73  .** returned res
2f1e0 75 6c 74 20 73 65 74 20 6f 66 20 74 68 61 74 20  ult set of that 
2f1f0 5b 53 45 4c 45 43 54 5d 20 69 73 20 61 20 74 61  [SELECT] is a ta
2f200 62 6c 65 20 63 6f 6c 75 6d 6e 20 28 6e 6f 74 20  ble column (not 
2f210 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e  an.** expression
2f220 20 6f 72 20 73 75 62 71 75 65 72 79 29 20 74 68   or subquery) th
2f230 65 6e 20 74 68 65 20 64 65 63 6c 61 72 65 64 20  en the declared 
2f240 74 79 70 65 20 6f 66 20 74 68 65 20 74 61 62 6c  type of the tabl
2f250 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 73 20 72  e.** column is r
2f260 65 74 75 72 6e 65 64 2e 29 5e 20 20 5e 49 66 20  eturned.)^  ^If 
2f270 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f  the Nth column o
2f280 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  f the result set
2f290 20 69 73 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73   is an.** expres
2f2a0 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79  sion or subquery
2f2b0 2c 20 74 68 65 6e 20 61 20 4e 55 4c 4c 20 70 6f  , then a NULL po
2f2c0 69 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e 65  inter is returne
2f2d0 64 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72  d..** ^The retur
2f2e0 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20 61 6c  ned string is al
2f2f0 77 61 79 73 20 55 54 46 2d 38 20 65 6e 63 6f 64  ways UTF-8 encod
2f300 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 46 6f 72 20  ed..**.** ^(For 
2f310 65 78 61 6d 70 6c 65 2c 20 67 69 76 65 6e 20 74  example, given t
2f320 68 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65  he database sche
2f330 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43 52 45 41 54 45  ma:.**.** CREATE
2f340 20 54 41 42 4c 45 20 74 31 28 63 31 20 56 41 52   TABLE t1(c1 VAR
2f350 49 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20 61 6e 64  IANT);.**.** and
2f360 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73   the following s
2f370 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63  tatement to be c
2f380 6f 6d 70 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20 53  ompiled:.**.** S
2f390 45 4c 45 43 54 20 63 31 20 2b 20 31 2c 20 63 31  ELECT c1 + 1, c1
2f3a0 20 46 52 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a 20   FROM t1;.**.** 
2f3b0 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 6f 75  this routine wou
2f3c0 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20 73 74  ld return the st
2f3d0 72 69 6e 67 20 22 56 41 52 49 41 4e 54 22 20 66  ring "VARIANT" f
2f3e0 6f 72 20 74 68 65 20 73 65 63 6f 6e 64 20 72 65  or the second re
2f3f0 73 75 6c 74 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 28  sult.** column (
2f400 69 3d 3d 31 29 2c 20 61 6e 64 20 61 20 4e 55 4c  i==1), and a NUL
2f410 4c 20 70 6f 69 6e 74 65 72 20 66 6f 72 20 74 68  L pointer for th
2f420 65 20 66 69 72 73 74 20 72 65 73 75 6c 74 20 63  e first result c
2f430 6f 6c 75 6d 6e 20 28 69 3d 3d 30 29 2e 29 5e 0a  olumn (i==0).)^.
2f440 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73  **.** ^SQLite us
2f450 65 73 20 64 79 6e 61 6d 69 63 20 72 75 6e 2d 74  es dynamic run-t
2f460 69 6d 65 20 74 79 70 69 6e 67 2e 20 20 5e 53 6f  ime typing.  ^So
2f470 20 6a 75 73 74 20 62 65 63 61 75 73 65 20 61 20   just because a 
2f480 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 64 65 63  column.** is dec
2f490 6c 61 72 65 64 20 74 6f 20 63 6f 6e 74 61 69 6e  lared to contain
2f4a0 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 74 79   a particular ty
2f4b0 70 65 20 64 6f 65 73 20 6e 6f 74 20 6d 65 61 6e  pe does not mean
2f4c0 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 64 61 74   that the.** dat
2f4d0 61 20 73 74 6f 72 65 64 20 69 6e 20 74 68 61 74  a stored in that
2f4e0 20 63 6f 6c 75 6d 6e 20 69 73 20 6f 66 20 74 68   column is of th
2f4f0 65 20 64 65 63 6c 61 72 65 64 20 74 79 70 65 2e  e declared type.
2f500 20 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 73    SQLite is.** s
2f510 74 72 6f 6e 67 6c 79 20 74 79 70 65 64 2c 20 62  trongly typed, b
2f520 75 74 20 74 68 65 20 74 79 70 69 6e 67 20 69 73  ut the typing is
2f530 20 64 79 6e 61 6d 69 63 20 6e 6f 74 20 73 74 61   dynamic not sta
2f540 74 69 63 2e 20 20 5e 54 79 70 65 0a 2a 2a 20 69  tic.  ^Type.** i
2f550 73 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  s associated wit
2f560 68 20 69 6e 64 69 76 69 64 75 61 6c 20 76 61 6c  h individual val
2f570 75 65 73 2c 20 6e 6f 74 20 77 69 74 68 20 74 68  ues, not with th
2f580 65 20 63 6f 6e 74 61 69 6e 65 72 73 0a 2a 2a 20  e containers.** 
2f590 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 74 68 6f  used to hold tho
2f5a0 73 65 20 76 61 6c 75 65 73 2e 0a 2a 2f 0a 63 6f  se values..*/.co
2f5b0 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
2f5c0 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70  3_column_decltyp
2f5d0 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
2f5e0 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  int);.const void
2f5f0 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
2f600 5f 64 65 63 6c 74 79 70 65 31 36 28 73 71 6c 69  _decltype16(sqli
2f610 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
2f620 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2f630 20 45 76 61 6c 75 61 74 65 20 41 6e 20 53 51 4c   Evaluate An SQL
2f640 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 4d 45   Statement.** ME
2f650 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74  THOD: sqlite3_st
2f660 6d 74 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 61  mt.**.** After a
2f670 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2f680 6d 65 6e 74 5d 20 68 61 73 20 62 65 65 6e 20 70  ment] has been p
2f690 72 65 70 61 72 65 64 20 75 73 69 6e 67 20 65 69  repared using ei
2f6a0 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ther.** [sqlite3
2f6b0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
2f6c0 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  r [sqlite3_prepa
2f6d0 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 6f 6e  re16_v2()] or on
2f6e0 65 20 6f 66 20 74 68 65 20 6c 65 67 61 63 79 0a  e of the legacy.
2f6f0 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 5b 73  ** interfaces [s
2f700 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
2f710 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72  ] or [sqlite3_pr
2f720 65 70 61 72 65 31 36 28 29 5d 2c 20 74 68 69 73  epare16()], this
2f730 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6d 75 73   function.** mus
2f740 74 20 62 65 20 63 61 6c 6c 65 64 20 6f 6e 65 20  t be called one 
2f750 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f  or more times to
2f760 20 65 76 61 6c 75 61 74 65 20 74 68 65 20 73 74   evaluate the st
2f770 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54  atement..**.** T
2f780 68 65 20 64 65 74 61 69 6c 73 20 6f 66 20 74 68  he details of th
2f790 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 74 68  e behavior of th
2f7a0 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  e sqlite3_step()
2f7b0 20 69 6e 74 65 72 66 61 63 65 20 64 65 70 65 6e   interface depen
2f7c0 64 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65 72 20  d.** on whether 
2f7d0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77 61  the statement wa
2f7e0 73 20 70 72 65 70 61 72 65 64 20 75 73 69 6e 67  s prepared using
2f7f0 20 74 68 65 20 6e 65 77 65 72 20 22 76 32 22 20   the newer "v2" 
2f800 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 5b 73 71  interface.** [sq
2f810 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
2f820 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
2f830 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
2f840 20 6f 72 20 74 68 65 20 6f 6c 64 65 72 20 6c 65   or the older le
2f850 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63  gacy.** interfac
2f860 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  e [sqlite3_prepa
2f870 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  re()] and [sqlit
2f880 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2e  e3_prepare16()].
2f890 20 20 54 68 65 20 75 73 65 20 6f 66 20 74 68 65    The use of the
2f8a0 0a 2a 2a 20 6e 65 77 20 22 76 32 22 20 69 6e 74  .** new "v2" int
2f8b0 65 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d  erface is recomm
2f8c0 65 6e 64 65 64 20 66 6f 72 20 6e 65 77 20 61 70  ended for new ap
2f8d0 70 6c 69 63 61 74 69 6f 6e 73 20 62 75 74 20 74  plications but t
2f8e0 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74  he legacy.** int
2f8f0 65 72 66 61 63 65 20 77 69 6c 6c 20 63 6f 6e 74  erface will cont
2f900 69 6e 75 65 20 74 6f 20 62 65 20 73 75 70 70 6f  inue to be suppo
2f910 72 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20  rted..**.** ^In 
2f920 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72  the legacy inter
2f930 66 61 63 65 2c 20 74 68 65 20 72 65 74 75 72 6e  face, the return
2f940 20 76 61 6c 75 65 20 77 69 6c 6c 20 62 65 20 65   value will be e
2f950 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 42 55  ither [SQLITE_BU
2f960 53 59 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  SY],.** [SQLITE_
2f970 44 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 52  DONE], [SQLITE_R
2f980 4f 57 5d 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52  OW], [SQLITE_ERR
2f990 4f 52 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  OR], or [SQLITE_
2f9a0 4d 49 53 55 53 45 5d 2e 0a 2a 2a 20 5e 57 69 74  MISUSE]..** ^Wit
2f9b0 68 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72  h the "v2" inter
2f9c0 66 61 63 65 2c 20 61 6e 79 20 6f 66 20 74 68 65  face, any of the
2f9d0 20 6f 74 68 65 72 20 5b 72 65 73 75 6c 74 20 63   other [result c
2f9e0 6f 64 65 73 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74  odes] or.** [ext
2f9f0 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
2fa00 65 73 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74  es] might be ret
2fa10 75 72 6e 65 64 20 61 73 20 77 65 6c 6c 2e 0a 2a  urned as well..*
2fa20 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 42 55  *.** ^[SQLITE_BU
2fa30 53 59 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74  SY] means that t
2fa40 68 65 20 64 61 74 61 62 61 73 65 20 65 6e 67 69  he database engi
2fa50 6e 65 20 77 61 73 20 75 6e 61 62 6c 65 20 74 6f  ne was unable to
2fa60 20 61 63 71 75 69 72 65 20 74 68 65 0a 2a 2a 20   acquire the.** 
2fa70 64 61 74 61 62 61 73 65 20 6c 6f 63 6b 73 20 69  database locks i
2fa80 74 20 6e 65 65 64 73 20 74 6f 20 64 6f 20 69 74  t needs to do it
2fa90 73 20 6a 6f 62 2e 20 20 5e 49 66 20 74 68 65 20  s job.  ^If the 
2faa0 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b  statement is a [
2fab0 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 72 20 6f 63  COMMIT].** or oc
2fac0 63 75 72 73 20 6f 75 74 73 69 64 65 20 6f 66 20  curs outside of 
2fad0 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e  an explicit tran
2fae0 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 79 6f  saction, then yo
2faf0 75 20 63 61 6e 20 72 65 74 72 79 20 74 68 65 0a  u can retry the.
2fb00 2a 2a 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 49  ** statement.  I
2fb10 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  f the statement 
2fb20 69 73 20 6e 6f 74 20 61 20 5b 43 4f 4d 4d 49 54  is not a [COMMIT
2fb30 5d 20 61 6e 64 20 6f 63 63 75 72 73 20 77 69 74  ] and occurs wit
2fb40 68 69 6e 20 61 6e 0a 2a 2a 20 65 78 70 6c 69 63  hin an.** explic
2fb50 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74  it transaction t
2fb60 68 65 6e 20 79 6f 75 20 73 68 6f 75 6c 64 20 72  hen you should r
2fb70 6f 6c 6c 62 61 63 6b 20 74 68 65 20 74 72 61 6e  ollback the tran
2fb80 73 61 63 74 69 6f 6e 20 62 65 66 6f 72 65 0a 2a  saction before.*
2fb90 2a 20 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a  * continuing..**
2fba0 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 44 4f 4e  .** ^[SQLITE_DON
2fbb0 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  E] means that th
2fbc0 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61 73 20  e statement has 
2fbd0 66 69 6e 69 73 68 65 64 20 65 78 65 63 75 74 69  finished executi
2fbe0 6e 67 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c  ng.** successful
2fbf0 6c 79 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65  ly.  sqlite3_ste
2fc00 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62  p() should not b
2fc10 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f  e called again o
2fc20 6e 20 74 68 69 73 20 76 69 72 74 75 61 6c 0a 2a  n this virtual.*
2fc30 2a 20 6d 61 63 68 69 6e 65 20 77 69 74 68 6f 75  * machine withou
2fc40 74 20 66 69 72 73 74 20 63 61 6c 6c 69 6e 67 20  t first calling 
2fc50 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
2fc60 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 76  ] to reset the v
2fc70 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e  irtual.** machin
2fc80 65 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e  e back to its in
2fc90 69 74 69 61 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a  itial state..**.
2fca0 2a 2a 20 5e 49 66 20 74 68 65 20 53 51 4c 20 73  ** ^If the SQL s
2fcb0 74 61 74 65 6d 65 6e 74 20 62 65 69 6e 67 20 65  tatement being e
2fcc0 78 65 63 75 74 65 64 20 72 65 74 75 72 6e 73 20  xecuted returns 
2fcd0 61 6e 79 20 64 61 74 61 2c 20 74 68 65 6e 20 5b  any data, then [
2fce0 53 51 4c 49 54 45 5f 52 4f 57 5d 0a 2a 2a 20 69  SQLITE_ROW].** i
2fcf0 73 20 72 65 74 75 72 6e 65 64 20 65 61 63 68 20  s returned each 
2fd00 74 69 6d 65 20 61 20 6e 65 77 20 72 6f 77 20 6f  time a new row o
2fd10 66 20 64 61 74 61 20 69 73 20 72 65 61 64 79 20  f data is ready 
2fd20 66 6f 72 20 70 72 6f 63 65 73 73 69 6e 67 20 62  for processing b
2fd30 79 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 65 72 2e  y the.** caller.
2fd40 20 54 68 65 20 76 61 6c 75 65 73 20 6d 61 79 20   The values may 
2fd50 62 65 20 61 63 63 65 73 73 65 64 20 75 73 69 6e  be accessed usin
2fd60 67 20 74 68 65 20 5b 63 6f 6c 75 6d 6e 20 61 63  g the [column ac
2fd70 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 2e  cess functions].
2fd80 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70  .** sqlite3_step
2fd90 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61 67 61  () is called aga
2fda0 69 6e 20 74 6f 20 72 65 74 72 69 65 76 65 20 74  in to retrieve t
2fdb0 68 65 20 6e 65 78 74 20 72 6f 77 20 6f 66 20 64  he next row of d
2fdc0 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c  ata..**.** ^[SQL
2fdd0 49 54 45 5f 45 52 52 4f 52 5d 20 6d 65 61 6e 73  ITE_ERROR] means
2fde0 20 74 68 61 74 20 61 20 72 75 6e 2d 74 69 6d 65   that a run-time
2fdf0 20 65 72 72 6f 72 20 28 73 75 63 68 20 61 73 20   error (such as 
2fe00 61 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20  a constraint.** 
2fe10 76 69 6f 6c 61 74 69 6f 6e 29 20 68 61 73 20 6f  violation) has o
2fe20 63 63 75 72 72 65 64 2e 20 20 73 71 6c 69 74 65  ccurred.  sqlite
2fe30 33 5f 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20  3_step() should 
2fe40 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67  not be called ag
2fe50 61 69 6e 20 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d  ain on.** the VM
2fe60 2e 20 4d 6f 72 65 20 69 6e 66 6f 72 6d 61 74 69  . More informati
2fe70 6f 6e 20 6d 61 79 20 62 65 20 66 6f 75 6e 64 20  on may be found 
2fe80 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  by calling [sqli
2fe90 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a  te3_errmsg()]..*
2fea0 2a 20 5e 57 69 74 68 20 74 68 65 20 6c 65 67 61  * ^With the lega
2feb0 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 61 20  cy interface, a 
2fec0 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 65 72  more specific er
2fed0 72 6f 72 20 63 6f 64 65 20 28 66 6f 72 20 65 78  ror code (for ex
2fee0 61 6d 70 6c 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54  ample,.** [SQLIT
2fef0 45 5f 49 4e 54 45 52 52 55 50 54 5d 2c 20 5b 53  E_INTERRUPT], [S
2ff00 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 2c 20 5b  QLITE_SCHEMA], [
2ff10 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d 2c  SQLITE_CORRUPT],
2ff20 20 61 6e 64 20 73 6f 20 66 6f 72 74 68 29 0a 2a   and so forth).*
2ff30 2a 20 63 61 6e 20 62 65 20 6f 62 74 61 69 6e 65  * can be obtaine
2ff40 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71  d by calling [sq
2ff50 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f  lite3_reset()] o
2ff60 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72  n the.** [prepar
2ff70 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20  ed statement].  
2ff80 5e 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74  ^In the "v2" int
2ff90 65 72 66 61 63 65 2c 0a 2a 2a 20 74 68 65 20 6d  erface,.** the m
2ffa0 6f 72 65 20 73 70 65 63 69 66 69 63 20 65 72 72  ore specific err
2ffb0 6f 72 20 63 6f 64 65 20 69 73 20 72 65 74 75 72  or code is retur
2ffc0 6e 65 64 20 64 69 72 65 63 74 6c 79 20 62 79 20  ned directly by 
2ffd0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 0a  sqlite3_step()..
2ffe0 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49  **.** [SQLITE_MI
2fff0 53 55 53 45 5d 20 6d 65 61 6e 73 20 74 68 61 74  SUSE] means that
30000 20 74 68 65 20 74 68 69 73 20 72 6f 75 74 69 6e   the this routin
30010 65 20 77 61 73 20 63 61 6c 6c 65 64 20 69 6e 61  e was called ina
30020 70 70 72 6f 70 72 69 61 74 65 6c 79 2e 0a 2a 2a  ppropriately..**
30030 20 50 65 72 68 61 70 73 20 69 74 20 77 61 73 20   Perhaps it was 
30040 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 70 72 65  called on a [pre
30050 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
30060 20 74 68 61 74 20 68 61 73 0a 2a 2a 20 61 6c 72   that has.** alr
30070 65 61 64 79 20 62 65 65 6e 20 5b 73 71 6c 69 74  eady been [sqlit
30080 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69  e3_finalize | fi
30090 6e 61 6c 69 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f  nalized] or on o
300a0 6e 65 20 74 68 61 74 20 68 61 64 0a 2a 2a 20 70  ne that had.** p
300b0 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e  reviously return
300c0 65 64 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  ed [SQLITE_ERROR
300d0 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e  ] or [SQLITE_DON
300e0 45 5d 2e 20 20 4f 72 20 69 74 20 63 6f 75 6c 64  E].  Or it could
300f0 0a 2a 2a 20 62 65 20 74 68 65 20 63 61 73 65 20  .** be the case 
30100 74 68 61 74 20 74 68 65 20 73 61 6d 65 20 64 61  that the same da
30110 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
30120 6e 20 69 73 20 62 65 69 6e 67 20 75 73 65 64 20  n is being used 
30130 62 79 20 74 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72  by two or.** mor
30140 65 20 74 68 72 65 61 64 73 20 61 74 20 74 68 65  e threads at the
30150 20 73 61 6d 65 20 6d 6f 6d 65 6e 74 20 69 6e 20   same moment in 
30160 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20  time..**.** For 
30170 61 6c 6c 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  all versions of 
30180 53 51 4c 69 74 65 20 75 70 20 74 6f 20 61 6e 64  SQLite up to and
30190 20 69 6e 63 6c 75 64 69 6e 67 20 33 2e 36 2e 32   including 3.6.2
301a0 33 2e 31 2c 20 61 20 63 61 6c 6c 20 74 6f 0a 2a  3.1, a call to.*
301b0 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  * [sqlite3_reset
301c0 28 29 5d 20 77 61 73 20 72 65 71 75 69 72 65 64  ()] was required
301d0 20 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f 73   after sqlite3_s
301e0 74 65 70 28 29 20 72 65 74 75 72 6e 65 64 20 61  tep() returned a
301f0 6e 79 74 68 69 6e 67 0a 2a 2a 20 6f 74 68 65 72  nything.** other
30200 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f   than [SQLITE_RO
30210 57 5d 20 62 65 66 6f 72 65 20 61 6e 79 20 73 75  W] before any su
30220 62 73 65 71 75 65 6e 74 20 69 6e 76 6f 63 61 74  bsequent invocat
30230 69 6f 6e 20 6f 66 0a 2a 2a 20 73 71 6c 69 74 65  ion of.** sqlite
30240 33 5f 73 74 65 70 28 29 2e 20 20 46 61 69 6c 75  3_step().  Failu
30250 72 65 20 74 6f 20 72 65 73 65 74 20 74 68 65 20  re to reset the 
30260 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
30270 6e 74 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71  nt using .** [sq
30280 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 77  lite3_reset()] w
30290 6f 75 6c 64 20 72 65 73 75 6c 74 20 69 6e 20 61  ould result in a
302a0 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  n [SQLITE_MISUSE
302b0 5d 20 72 65 74 75 72 6e 20 66 72 6f 6d 0a 2a 2a  ] return from.**
302c0 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e   sqlite3_step().
302d0 20 20 42 75 74 20 61 66 74 65 72 20 76 65 72 73    But after vers
302e0 69 6f 6e 20 33 2e 36 2e 32 33 2e 31 2c 20 73 71  ion 3.6.23.1, sq
302f0 6c 69 74 65 33 5f 73 74 65 70 28 29 20 62 65 67  lite3_step() beg
30300 61 6e 0a 2a 2a 20 63 61 6c 6c 69 6e 67 20 5b 73  an.** calling [s
30310 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
30320 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 69 6e  automatically in
30330 20 74 68 69 73 20 63 69 72 63 75 6d 73 74 61 6e   this circumstan
30340 63 65 20 72 61 74 68 65 72 0a 2a 2a 20 74 68 61  ce rather.** tha
30350 6e 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c  n returning [SQL
30360 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 54 68  ITE_MISUSE].  Th
30370 69 73 20 69 73 20 6e 6f 74 20 63 6f 6e 73 69 64  is is not consid
30380 65 72 65 64 20 61 20 63 6f 6d 70 61 74 69 62 69  ered a compatibi
30390 6c 69 74 79 0a 2a 2a 20 62 72 65 61 6b 20 62 65  lity.** break be
303a0 63 61 75 73 65 20 61 6e 79 20 61 70 70 6c 69 63  cause any applic
303b0 61 74 69 6f 6e 20 74 68 61 74 20 65 76 65 72 20  ation that ever 
303c0 72 65 63 65 69 76 65 73 20 61 6e 20 53 51 4c 49  receives an SQLI
303d0 54 45 5f 4d 49 53 55 53 45 20 65 72 72 6f 72 0a  TE_MISUSE error.
303e0 2a 2a 20 69 73 20 62 72 6f 6b 65 6e 20 62 79 20  ** is broken by 
303f0 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68 65  definition.  The
30400 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55   [SQLITE_OMIT_AU
30410 54 4f 52 45 53 45 54 5d 20 63 6f 6d 70 69 6c 65  TORESET] compile
30420 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20  -time option.** 
30430 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 72  can be used to r
30440 65 73 74 6f 72 65 20 74 68 65 20 6c 65 67 61 63  estore the legac
30450 79 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a  y behavior..**.*
30460 2a 20 3c 62 3e 47 6f 6f 66 79 20 49 6e 74 65 72  * <b>Goofy Inter
30470 66 61 63 65 20 41 6c 65 72 74 3a 3c 2f 62 3e 20  face Alert:</b> 
30480 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e  In the legacy in
30490 74 65 72 66 61 63 65 2c 20 74 68 65 20 73 71 6c  terface, the sql
304a0 69 74 65 33 5f 73 74 65 70 28 29 0a 2a 2a 20 41  ite3_step().** A
304b0 50 49 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e  PI always return
304c0 73 20 61 20 67 65 6e 65 72 69 63 20 65 72 72 6f  s a generic erro
304d0 72 20 63 6f 64 65 2c 20 5b 53 51 4c 49 54 45 5f  r code, [SQLITE_
304e0 45 52 52 4f 52 5d 2c 20 66 6f 6c 6c 6f 77 69 6e  ERROR], followin
304f0 67 20 61 6e 79 0a 2a 2a 20 65 72 72 6f 72 20 6f  g any.** error o
30500 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54  ther than [SQLIT
30510 45 5f 42 55 53 59 5d 20 61 6e 64 20 5b 53 51 4c  E_BUSY] and [SQL
30520 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 59 6f  ITE_MISUSE].  Yo
30530 75 20 6d 75 73 74 20 63 61 6c 6c 0a 2a 2a 20 5b  u must call.** [
30540 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
30550 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e   or [sqlite3_fin
30560 61 6c 69 7a 65 28 29 5d 20 69 6e 20 6f 72 64 65  alize()] in orde
30570 72 20 74 6f 20 66 69 6e 64 20 6f 6e 65 20 6f 66  r to find one of
30580 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63   the.** specific
30590 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 74   [error codes] t
305a0 68 61 74 20 62 65 74 74 65 72 20 64 65 73 63 72  hat better descr
305b0 69 62 65 73 20 74 68 65 20 65 72 72 6f 72 2e 0a  ibes the error..
305c0 2a 2a 20 57 65 20 61 64 6d 69 74 20 74 68 61 74  ** We admit that
305d0 20 74 68 69 73 20 69 73 20 61 20 67 6f 6f 66 79   this is a goofy
305e0 20 64 65 73 69 67 6e 2e 20 20 54 68 65 20 70 72   design.  The pr
305f0 6f 62 6c 65 6d 20 68 61 73 20 62 65 65 6e 20 66  oblem has been f
30600 69 78 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65  ixed.** with the
30610 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2e   "v2" interface.
30620 20 20 49 66 20 79 6f 75 20 70 72 65 70 61 72 65    If you prepare
30630 20 61 6c 6c 20 6f 66 20 79 6f 75 72 20 53 51 4c   all of your SQL
30640 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 75   statements.** u
30650 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c  sing either [sql
30660 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
30670 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70  )] or [sqlite3_p
30680 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 69  repare16_v2()] i
30690 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 74 68 65  nstead.** of the
306a0 20 6c 65 67 61 63 79 20 5b 73 71 6c 69 74 65 33   legacy [sqlite3
306b0 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20  _prepare()] and 
306c0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
306d0 31 36 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73  16()] interfaces
306e0 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 6d 6f  ,.** then the mo
306f0 72 65 20 73 70 65 63 69 66 69 63 20 5b 65 72 72  re specific [err
30700 6f 72 20 63 6f 64 65 73 5d 20 61 72 65 20 72 65  or codes] are re
30710 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79 0a  turned directly.
30720 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74  ** by sqlite3_st
30730 65 70 28 29 2e 20 20 54 68 65 20 75 73 65 20 6f  ep().  The use o
30740 66 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72  f the "v2" inter
30750 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e  face is recommen
30760 64 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ded..*/.int sqli
30770 74 65 33 5f 73 74 65 70 28 73 71 6c 69 74 65 33  te3_step(sqlite3
30780 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  _stmt*);../*.** 
30790 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72  CAPI3REF: Number
307a0 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61   of columns in a
307b0 20 72 65 73 75 6c 74 20 73 65 74 0a 2a 2a 20 4d   result set.** M
307c0 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73  ETHOD: sqlite3_s
307d0 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  tmt.**.** ^The s
307e0 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e  qlite3_data_coun
307f0 74 28 50 29 20 69 6e 74 65 72 66 61 63 65 20 72  t(P) interface r
30800 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
30810 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20  r of columns in 
30820 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 72  the.** current r
30830 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  ow of the result
30840 20 73 65 74 20 6f 66 20 5b 70 72 65 70 61 72 65   set of [prepare
30850 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a  d statement] P..
30860 2a 2a 20 5e 49 66 20 70 72 65 70 61 72 65 64 20  ** ^If prepared 
30870 73 74 61 74 65 6d 65 6e 74 20 50 20 64 6f 65 73  statement P does
30880 20 6e 6f 74 20 68 61 76 65 20 72 65 73 75 6c 74   not have result
30890 73 20 72 65 61 64 79 20 74 6f 20 72 65 74 75 72  s ready to retur
308a0 6e 0a 2a 2a 20 28 76 69 61 20 63 61 6c 6c 73 20  n.** (via calls 
308b0 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
308c0 63 6f 6c 75 6d 6e 5f 69 6e 74 20 7c 20 73 71 6c  column_int | sql
308d0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 2a 28 29 5d  ite3_column_*()]
308e0 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65   of.** interface
308f0 73 29 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  s) then sqlite3_
30900 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 65  data_count(P) re
30910 74 75 72 6e 73 20 30 2e 0a 2a 2a 20 5e 54 68 65  turns 0..** ^The
30920 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f   sqlite3_data_co
30930 75 6e 74 28 50 29 20 72 6f 75 74 69 6e 65 20 61  unt(P) routine a
30940 6c 73 6f 20 72 65 74 75 72 6e 73 20 30 20 69 66  lso returns 0 if
30950 20 50 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69   P is a NULL poi
30960 6e 74 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 73 71  nter..** ^The sq
30970 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74  lite3_data_count
30980 28 50 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75  (P) routine retu
30990 72 6e 73 20 30 20 69 66 20 74 68 65 20 70 72 65  rns 0 if the pre
309a0 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 0a 2a 2a  vious call to.**
309b0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 5d 28   [sqlite3_step](
309c0 50 29 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c  P) returned [SQL
309d0 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 5e 54 68 65  ITE_DONE].  ^The
309e0 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f   sqlite3_data_co
309f0 75 6e 74 28 50 29 0a 2a 2a 20 77 69 6c 6c 20 72  unt(P).** will r
30a00 65 74 75 72 6e 20 6e 6f 6e 2d 7a 65 72 6f 20 69  eturn non-zero i
30a10 66 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20  f previous call 
30a20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  to [sqlite3_step
30a30 5d 28 50 29 20 72 65 74 75 72 6e 65 64 0a 2a 2a  ](P) returned.**
30a40 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 65   [SQLITE_ROW], e
30a50 78 63 65 70 74 20 69 6e 20 74 68 65 20 63 61 73  xcept in the cas
30a60 65 20 6f 66 20 74 68 65 20 5b 50 52 41 47 4d 41  e of the [PRAGMA
30a70 20 69 6e 63 72 65 6d 65 6e 74 61 6c 5f 76 61 63   incremental_vac
30a80 75 75 6d 5d 0a 2a 2a 20 77 68 65 72 65 20 69 74  uum].** where it
30a90 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20   always returns 
30aa0 7a 65 72 6f 20 73 69 6e 63 65 20 65 61 63 68 20  zero since each 
30ab0 73 74 65 70 20 6f 66 20 74 68 61 74 20 6d 75 6c  step of that mul
30ac0 74 69 2d 73 74 65 70 0a 2a 2a 20 70 72 61 67 6d  ti-step.** pragm
30ad0 61 20 72 65 74 75 72 6e 73 20 30 20 63 6f 6c 75  a returns 0 colu
30ae0 6d 6e 73 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a  mns of data..**.
30af0 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
30b00 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75  lite3_column_cou
30b10 6e 74 28 29 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c  nt()].*/.int sql
30b20 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28  ite3_data_count(
30b30 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
30b40 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
30b50 49 33 52 45 46 3a 20 46 75 6e 64 61 6d 65 6e 74  I3REF: Fundament
30b60 61 6c 20 44 61 74 61 74 79 70 65 73 0a 2a 2a 20  al Datatypes.** 
30b70 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c 49 54 45  KEYWORDS: SQLITE
30b80 5f 54 45 58 54 0a 2a 2a 0a 2a 2a 20 5e 28 45 76  _TEXT.**.** ^(Ev
30b90 65 72 79 20 76 61 6c 75 65 20 69 6e 20 53 51 4c  ery value in SQL
30ba0 69 74 65 20 68 61 73 20 6f 6e 65 20 6f 66 20 66  ite has one of f
30bb0 69 76 65 20 66 75 6e 64 61 6d 65 6e 74 61 6c 20  ive fundamental 
30bc0 64 61 74 61 74 79 70 65 73 3a 0a 2a 2a 0a 2a 2a  datatypes:.**.**
30bd0 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 36 34   <ul>.** <li> 64
30be0 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65  -bit signed inte
30bf0 67 65 72 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62  ger.** <li> 64-b
30c00 69 74 20 49 45 45 45 20 66 6c 6f 61 74 69 6e 67  it IEEE floating
30c10 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 0a 2a 2a   point number.**
30c20 20 3c 6c 69 3e 20 73 74 72 69 6e 67 0a 2a 2a 20   <li> string.** 
30c30 3c 6c 69 3e 20 42 4c 4f 42 0a 2a 2a 20 3c 6c 69  <li> BLOB.** <li
30c40 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e 29  > NULL.** </ul>)
30c50 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f  ^.**.** These co
30c60 6e 73 74 61 6e 74 73 20 61 72 65 20 63 6f 64 65  nstants are code
30c70 73 20 66 6f 72 20 65 61 63 68 20 6f 66 20 74 68  s for each of th
30c80 6f 73 65 20 74 79 70 65 73 2e 0a 2a 2a 0a 2a 2a  ose types..**.**
30c90 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 53   Note that the S
30ca0 51 4c 49 54 45 5f 54 45 58 54 20 63 6f 6e 73 74  QLITE_TEXT const
30cb0 61 6e 74 20 77 61 73 20 61 6c 73 6f 20 75 73 65  ant was also use
30cc0 64 20 69 6e 20 53 51 4c 69 74 65 20 76 65 72 73  d in SQLite vers
30cd0 69 6f 6e 20 32 0a 2a 2a 20 66 6f 72 20 61 20 63  ion 2.** for a c
30ce0 6f 6d 70 6c 65 74 65 6c 79 20 64 69 66 66 65 72  ompletely differ
30cf0 65 6e 74 20 6d 65 61 6e 69 6e 67 2e 20 20 53 6f  ent meaning.  So
30d00 66 74 77 61 72 65 20 74 68 61 74 20 6c 69 6e 6b  ftware that link
30d10 73 20 61 67 61 69 6e 73 74 20 62 6f 74 68 0a 2a  s against both.*
30d20 2a 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  * SQLite version
30d30 20 32 20 61 6e 64 20 53 51 4c 69 74 65 20 76 65   2 and SQLite ve
30d40 72 73 69 6f 6e 20 33 20 73 68 6f 75 6c 64 20 75  rsion 3 should u
30d50 73 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54 2c  se SQLITE3_TEXT,
30d60 20 6e 6f 74 0a 2a 2a 20 53 51 4c 49 54 45 5f 54   not.** SQLITE_T
30d70 45 58 54 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  EXT..*/.#define 
30d80 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 20  SQLITE_INTEGER  
30d90 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
30da0 5f 46 4c 4f 41 54 20 20 20 20 32 0a 23 64 65 66  _FLOAT    2.#def
30db0 69 6e 65 20 53 51 4c 49 54 45 5f 42 4c 4f 42 20  ine SQLITE_BLOB 
30dc0 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51      4.#define SQ
30dd0 4c 49 54 45 5f 4e 55 4c 4c 20 20 20 20 20 35 0a  LITE_NULL     5.
30de0 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 54 45  #ifdef SQLITE_TE
30df0 58 54 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 54  XT.# undef SQLIT
30e00 45 5f 54 45 58 54 0a 23 65 6c 73 65 0a 23 20 64  E_TEXT.#else.# d
30e10 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 58  efine SQLITE_TEX
30e20 54 20 20 20 20 20 33 0a 23 65 6e 64 69 66 0a 23  T     3.#endif.#
30e30 64 65 66 69 6e 65 20 53 51 4c 49 54 45 33 5f 54  define SQLITE3_T
30e40 45 58 54 20 20 20 20 20 33 0a 0a 2f 2a 0a 2a 2a  EXT     3../*.**
30e50 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c   CAPI3REF: Resul
30e60 74 20 56 61 6c 75 65 73 20 46 72 6f 6d 20 41 20  t Values From A 
30e70 51 75 65 72 79 0a 2a 2a 20 4b 45 59 57 4f 52 44  Query.** KEYWORD
30e80 53 3a 20 7b 63 6f 6c 75 6d 6e 20 61 63 63 65 73  S: {column acces
30e90 73 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 20  s functions}.** 
30ea0 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f  METHOD: sqlite3_
30eb0 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  stmt.**.** ^Thes
30ec0 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  e routines retur
30ed0 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62  n information ab
30ee0 6f 75 74 20 61 20 73 69 6e 67 6c 65 20 63 6f 6c  out a single col
30ef0 75 6d 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65  umn of the curre
30f00 6e 74 0a 2a 2a 20 72 65 73 75 6c 74 20 72 6f 77  nt.** result row
30f10 20 6f 66 20 61 20 71 75 65 72 79 2e 20 20 5e 49   of a query.  ^I
30f20 6e 20 65 76 65 72 79 20 63 61 73 65 20 74 68 65  n every case the
30f30 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
30f40 69 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  is a pointer.** 
30f50 74 6f 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  to the [prepared
30f60 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74   statement] that
30f70 20 69 73 20 62 65 69 6e 67 20 65 76 61 6c 75 61   is being evalua
30f80 74 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65  ted (the [sqlite
30f90 33 5f 73 74 6d 74 2a 5d 0a 2a 2a 20 74 68 61 74  3_stmt*].** that
30fa0 20 77 61 73 20 72 65 74 75 72 6e 65 64 20 66 72   was returned fr
30fb0 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  om [sqlite3_prep
30fc0 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65  are_v2()] or one
30fd0 20 6f 66 20 69 74 73 20 76 61 72 69 61 6e 74 73   of its variants
30fe0 29 0a 2a 2a 20 61 6e 64 20 74 68 65 20 73 65 63  ).** and the sec
30ff0 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ond argument is 
31000 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65  the index of the
31010 20 63 6f 6c 75 6d 6e 20 66 6f 72 20 77 68 69 63   column for whic
31020 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a  h information.**
31030 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72   should be retur
31040 6e 65 64 2e 20 5e 54 68 65 20 6c 65 66 74 6d 6f  ned. ^The leftmo
31050 73 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65  st column of the
31060 20 72 65 73 75 6c 74 20 73 65 74 20 68 61 73 20   result set has 
31070 74 68 65 20 69 6e 64 65 78 20 30 2e 0a 2a 2a 20  the index 0..** 
31080 5e 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63  ^The number of c
31090 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65  olumns in the re
310a0 73 75 6c 74 20 63 61 6e 20 62 65 20 64 65 74 65  sult can be dete
310b0 72 6d 69 6e 65 64 20 75 73 69 6e 67 0a 2a 2a 20  rmined using.** 
310c0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
310d0 63 6f 75 6e 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  count()]..**.** 
310e0 49 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  If the SQL state
310f0 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63 75  ment does not cu
31100 72 72 65 6e 74 6c 79 20 70 6f 69 6e 74 20 74 6f  rrently point to
31110 20 61 20 76 61 6c 69 64 20 72 6f 77 2c 20 6f 72   a valid row, or
31120 20 69 66 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d   if the.** colum
31130 6e 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f  n index is out o
31140 66 20 72 61 6e 67 65 2c 20 74 68 65 20 72 65 73  f range, the res
31150 75 6c 74 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ult is undefined
31160 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  ..** These routi
31170 6e 65 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20  nes may only be 
31180 63 61 6c 6c 65 64 20 77 68 65 6e 20 74 68 65 20  called when the 
31190 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c  most recent call
311a0 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
311b0 73 74 65 70 28 29 5d 20 68 61 73 20 72 65 74 75  step()] has retu
311c0 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57  rned [SQLITE_ROW
311d0 5d 20 61 6e 64 20 6e 65 69 74 68 65 72 0a 2a 2a  ] and neither.**
311e0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
311f0 29 5d 20 6e 6f 72 20 5b 73 71 6c 69 74 65 33 5f  )] nor [sqlite3_
31200 66 69 6e 61 6c 69 7a 65 28 29 5d 20 68 61 76 65  finalize()] have
31210 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 73 75 62   been called sub
31220 73 65 71 75 65 6e 74 6c 79 2e 0a 2a 2a 20 49 66  sequently..** If
31230 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f   any of these ro
31240 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65  utines are calle
31250 64 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33  d after [sqlite3
31260 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20  _reset()] or.** 
31270 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
31280 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20 5b 73  e()] or after [s
31290 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68  qlite3_step()] h
312a0 61 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 73  as returned.** s
312b0 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65 72 20 74  omething other t
312c0 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  han [SQLITE_ROW]
312d0 2c 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72  , the results ar
312e0 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20  e undefined..** 
312f0 49 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  If [sqlite3_step
31300 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
31310 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c  reset()] or [sql
31320 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
31330 0a 2a 2a 20 61 72 65 20 63 61 6c 6c 65 64 20 66  .** are called f
31340 72 6f 6d 20 61 20 64 69 66 66 65 72 65 6e 74 20  rom a different 
31350 74 68 72 65 61 64 20 77 68 69 6c 65 20 61 6e 79  thread while any
31360 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
31370 65 73 0a 2a 2a 20 61 72 65 20 70 65 6e 64 69 6e  es.** are pendin
31380 67 2c 20 74 68 65 6e 20 74 68 65 20 72 65 73 75  g, then the resu
31390 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65  lts are undefine
313a0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  d..**.** ^The sq
313b0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70  lite3_column_typ
313c0 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75  e() routine retu
313d0 72 6e 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  rns the.** [SQLI
313e0 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 74  TE_INTEGER | dat
313f0 61 74 79 70 65 20 63 6f 64 65 5d 20 66 6f 72 20  atype code] for 
31400 74 68 65 20 69 6e 69 74 69 61 6c 20 64 61 74 61  the initial data
31410 20 74 79 70 65 0a 2a 2a 20 6f 66 20 74 68 65 20   type.** of the 
31420 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 2e 20 20  result column.  
31430 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 76 61  ^The returned va
31440 6c 75 65 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53  lue is one of [S
31450 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c 0a  QLITE_INTEGER],.
31460 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54  ** [SQLITE_FLOAT
31470 5d 2c 20 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d  ], [SQLITE_TEXT]
31480 2c 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 2c  , [SQLITE_BLOB],
31490 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c   or [SQLITE_NULL
314a0 5d 2e 20 20 54 68 65 20 76 61 6c 75 65 0a 2a 2a  ].  The value.**
314b0 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c   returned by sql
314c0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65  ite3_column_type
314d0 28 29 20 69 73 20 6f 6e 6c 79 20 6d 65 61 6e 69  () is only meani
314e0 6e 67 66 75 6c 20 69 66 20 6e 6f 20 74 79 70 65  ngful if no type
314f0 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20  .** conversions 
31500 68 61 76 65 20 6f 63 63 75 72 72 65 64 20 61 73  have occurred as
31510 20 64 65 73 63 72 69 62 65 64 20 62 65 6c 6f 77   described below
31520 2e 20 20 41 66 74 65 72 20 61 20 74 79 70 65 20  .  After a type 
31530 63 6f 6e 76 65 72 73 69 6f 6e 2c 0a 2a 2a 20 74  conversion,.** t
31540 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
31550 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c  d by sqlite3_col
31560 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 75 6e  umn_type() is un
31570 64 65 66 69 6e 65 64 2e 20 20 46 75 74 75 72 65  defined.  Future
31580 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  .** versions of 
31590 53 51 4c 69 74 65 20 6d 61 79 20 63 68 61 6e 67  SQLite may chang
315a0 65 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f  e the behavior o
315b0 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  f sqlite3_column
315c0 5f 74 79 70 65 28 29 0a 2a 2a 20 66 6f 6c 6c 6f  _type().** follo
315d0 77 69 6e 67 20 61 20 74 79 70 65 20 63 6f 6e 76  wing a type conv
315e0 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49  ersion..**.** ^I
315f0 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
31600 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d 38 20  a BLOB or UTF-8 
31610 73 74 72 69 6e 67 20 74 68 65 6e 20 74 68 65 20  string then the 
31620 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
31630 79 74 65 73 28 29 0a 2a 2a 20 72 6f 75 74 69 6e  ytes().** routin
31640 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  e returns the nu
31650 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e  mber of bytes in
31660 20 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 74   that BLOB or st
31670 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ring..** ^If the
31680 20 72 65 73 75 6c 74 20 69 73 20 61 20 55 54 46   result is a UTF
31690 2d 31 36 20 73 74 72 69 6e 67 2c 20 74 68 65 6e  -16 string, then
316a0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
316b0 62 79 74 65 73 28 29 20 63 6f 6e 76 65 72 74 73  bytes() converts
316c0 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20 74  .** the string t
316d0 6f 20 55 54 46 2d 38 20 61 6e 64 20 74 68 65 6e  o UTF-8 and then
316e0 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
316f0 62 65 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a  ber of bytes..**
31700 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20   ^If the result 
31710 69 73 20 61 20 6e 75 6d 65 72 69 63 20 76 61 6c  is a numeric val
31720 75 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  ue then sqlite3_
31730 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 75  column_bytes() u
31740 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ses.** [sqlite3_
31750 73 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 63  snprintf()] to c
31760 6f 6e 76 65 72 74 20 74 68 61 74 20 76 61 6c 75  onvert that valu
31770 65 20 74 6f 20 61 20 55 54 46 2d 38 20 73 74 72  e to a UTF-8 str
31780 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a  ing and returns.
31790 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ** the number of
317a0 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 73   bytes in that s
317b0 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68  tring..** ^If th
317c0 65 20 72 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c  e result is NULL
317d0 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63  , then sqlite3_c
317e0 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 72 65  olumn_bytes() re
317f0 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a  turns zero..**.*
31800 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74  * ^If the result
31810 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 54   is a BLOB or UT
31820 46 2d 31 36 20 73 74 72 69 6e 67 20 74 68 65 6e  F-16 string then
31830 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c   the sqlite3_col
31840 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 0a 2a 2a  umn_bytes16().**
31850 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
31860 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
31870 79 74 65 73 20 69 6e 20 74 68 61 74 20 42 4c 4f  ytes in that BLO
31880 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20  B or string..** 
31890 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69  ^If the result i
318a0 73 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67  s a UTF-8 string
318b0 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63  , then sqlite3_c
318c0 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20  olumn_bytes16() 
318d0 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65 20  converts.** the 
318e0 73 74 72 69 6e 67 20 74 6f 20 55 54 46 2d 31 36  string to UTF-16
318f0 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e   and then return
31900 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
31910 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68  bytes..** ^If th
31920 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 6e 75  e result is a nu
31930 6d 65 72 69 63 20 76 61 6c 75 65 20 74 68 65 6e  meric value then
31940 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
31950 62 79 74 65 73 31 36 28 29 20 75 73 65 73 0a 2a  bytes16() uses.*
31960 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  * [sqlite3_snpri
31970 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72  ntf()] to conver
31980 74 20 74 68 61 74 20 76 61 6c 75 65 20 74 6f 20  t that value to 
31990 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20  a UTF-16 string 
319a0 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74  and returns.** t
319b0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
319c0 65 73 20 69 6e 20 74 68 61 74 20 73 74 72 69 6e  es in that strin
319d0 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65  g..** ^If the re
319e0 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68  sult is NULL, th
319f0 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  en sqlite3_colum
31a00 6e 5f 62 79 74 65 73 31 36 28 29 20 72 65 74 75  n_bytes16() retu
31a10 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20  rns zero..**.** 
31a20 5e 54 68 65 20 76 61 6c 75 65 73 20 72 65 74 75  ^The values retu
31a30 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  rned by [sqlite3
31a40 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 5d  _column_bytes()]
31a50 20 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69 74 65   and .** [sqlite
31a60 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
31a70 28 29 5d 20 64 6f 20 6e 6f 74 20 69 6e 63 6c 75  ()] do not inclu
31a80 64 65 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d  de the zero term
31a90 69 6e 61 74 6f 72 73 20 61 74 20 74 68 65 20 65  inators at the e
31aa0 6e 64 0a 2a 2a 20 6f 66 20 74 68 65 20 73 74 72  nd.** of the str
31ab0 69 6e 67 2e 20 20 5e 46 6f 72 20 63 6c 61 72 69  ing.  ^For clari
31ac0 74 79 3a 20 74 68 65 20 76 61 6c 75 65 73 20 72  ty: the values r
31ad0 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73  eturned by.** [s
31ae0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
31af0 74 65 73 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  tes()] and [sqli
31b00 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
31b10 31 36 28 29 5d 20 61 72 65 20 74 68 65 20 6e 75  16()] are the nu
31b20 6d 62 65 72 20 6f 66 0a 2a 2a 20 62 79 74 65 73  mber of.** bytes
31b30 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67 2c 20   in the string, 
31b40 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  not the number o
31b50 66 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a  f characters..**
31b60 0a 2a 2a 20 5e 53 74 72 69 6e 67 73 20 72 65 74  .** ^Strings ret
31b70 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
31b80 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 61  _column_text() a
31b90 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nd sqlite3_colum
31ba0 6e 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 65  n_text16(),.** e
31bb0 76 65 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67  ven empty string
31bc0 73 2c 20 61 72 65 20 61 6c 77 61 79 73 20 7a 65  s, are always ze
31bd0 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20 20  ro-terminated.  
31be0 5e 54 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20 76  ^The return.** v
31bf0 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65  alue from sqlite
31c00 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20  3_column_blob() 
31c10 66 6f 72 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74  for a zero-lengt
31c20 68 20 42 4c 4f 42 20 69 73 20 61 20 4e 55 4c 4c  h BLOB is a NULL
31c30 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20   pointer..**.** 
31c40 3c 62 3e 57 61 72 6e 69 6e 67 3a 3c 2f 62 3e 20  <b>Warning:</b> 
31c50 5e 54 68 65 20 6f 62 6a 65 63 74 20 72 65 74 75  ^The object retu
31c60 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  rned by [sqlite3
31c70 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d  _column_value()]
31c80 20 69 73 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f   is an.** [unpro
31c90 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
31ca0 61 6c 75 65 5d 20 6f 62 6a 65 63 74 2e 20 20 49  alue] object.  I
31cb0 6e 20 61 20 6d 75 6c 74 69 74 68 72 65 61 64 65  n a multithreade
31cc0 64 20 65 6e 76 69 72 6f 6e 6d 65 6e 74 2c 0a 2a  d environment,.*
31cd0 2a 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64  * an unprotected
31ce0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
31cf0 62 6a 65 63 74 20 6d 61 79 20 6f 6e 6c 79 20 62  bject may only b
31d00 65 20 75 73 65 64 20 73 61 66 65 6c 79 20 77 69  e used safely wi
31d10 74 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  th.** [sqlite3_b
31d20 69 6e 64 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64  ind_value()] and
31d30 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
31d40 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 49 66  _value()]..** If
31d50 20 74 68 65 20 5b 75 6e 70 72 6f 74 65 63 74 65   the [unprotecte
31d60 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
31d70 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64   object returned
31d80 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   by.** [sqlite3_
31d90 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20  column_value()] 
31da0 69 73 20 75 73 65 64 20 69 6e 20 61 6e 79 20 6f  is used in any o
31db0 74 68 65 72 20 77 61 79 2c 20 69 6e 63 6c 75 64  ther way, includ
31dc0 69 6e 67 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20  ing calls.** to 
31dd0 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73  routines like [s
31de0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74  qlite3_value_int
31df0 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61  ()], [sqlite3_va
31e00 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20  lue_text()],.** 
31e10 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  or [sqlite3_valu
31e20 65 5f 62 79 74 65 73 28 29 5d 2c 20 74 68 65 20  e_bytes()], the 
31e30 62 65 68 61 76 69 6f 72 20 69 73 20 6e 6f 74 20  behavior is not 
31e40 74 68 72 65 61 64 73 61 66 65 2e 0a 2a 2a 0a 2a  threadsafe..**.*
31e50 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
31e60 20 61 74 74 65 6d 70 74 20 74 6f 20 63 6f 6e 76   attempt to conv
31e70 65 72 74 20 74 68 65 20 76 61 6c 75 65 20 77 68  ert the value wh
31e80 65 72 65 20 61 70 70 72 6f 70 72 69 61 74 65 2e  ere appropriate.
31e90 20 20 5e 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c    ^For.** exampl
31ea0 65 2c 20 69 66 20 74 68 65 20 69 6e 74 65 72 6e  e, if the intern
31eb0 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f  al representatio
31ec0 6e 20 69 73 20 46 4c 4f 41 54 20 61 6e 64 20 61  n is FLOAT and a
31ed0 20 74 65 78 74 20 72 65 73 75 6c 74 0a 2a 2a 20   text result.** 
31ee0 69 73 20 72 65 71 75 65 73 74 65 64 2c 20 5b 73  is requested, [s
31ef0 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
31f00 29 5d 20 69 73 20 75 73 65 64 20 69 6e 74 65 72  )] is used inter
31f10 6e 61 6c 6c 79 20 74 6f 20 70 65 72 66 6f 72 6d  nally to perform
31f20 20 74 68 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69   the.** conversi
31f30 6f 6e 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  on automatically
31f40 2e 20 20 5e 28 54 68 65 20 66 6f 6c 6c 6f 77 69  .  ^(The followi
31f50 6e 67 20 74 61 62 6c 65 20 64 65 74 61 69 6c 73  ng table details
31f60 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73   the conversions
31f70 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 61 70 70  .** that are app
31f80 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  lied:.**.** <blo
31f90 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62  ckquote>.** <tab
31fa0 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 3e 0a 2a  le border="1">.*
31fb0 2a 20 3c 74 72 3e 3c 74 68 3e 20 49 6e 74 65 72  * <tr><th> Inter
31fc0 6e 61 6c 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e  nal<br>Type <th>
31fd0 20 52 65 71 75 65 73 74 65 64 3c 62 72 3e 54 79   Requested<br>Ty
31fe0 70 65 20 3c 74 68 3e 20 20 43 6f 6e 76 65 72 73  pe <th>  Convers
31ff0 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74  ion.**.** <tr><t
32000 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e  d>  NULL    <td>
32010 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20   INTEGER   <td> 
32020 52 65 73 75 6c 74 20 69 73 20 30 0a 2a 2a 20 3c  Result is 0.** <
32030 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20  tr><td>  NULL   
32040 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20   <td>  FLOAT    
32050 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30  <td> Result is 0
32060 2e 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  .0.** <tr><td>  
32070 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 54  NULL    <td>   T
32080 45 58 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75  EXT    <td> Resu
32090 6c 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  lt is a NULL poi
320a0 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  nter.** <tr><td>
320b0 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20    NULL    <td>  
320c0 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 52 65   BLOB    <td> Re
320d0 73 75 6c 74 20 69 73 20 61 20 4e 55 4c 4c 20 70  sult is a NULL p
320e0 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74  ointer.** <tr><t
320f0 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e  d> INTEGER  <td>
32100 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20    FLOAT    <td> 
32110 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 69 6e 74  Convert from int
32120 65 67 65 72 20 74 6f 20 66 6c 6f 61 74 0a 2a 2a  eger to float.**
32130 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45   <tr><td> INTEGE
32140 52 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20  R  <td>   TEXT  
32150 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e    <td> ASCII ren
32160 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 69 6e  dering of the in
32170 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64  teger.** <tr><td
32180 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20  > INTEGER  <td> 
32190 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53    BLOB    <td> S
321a0 61 6d 65 20 61 73 20 49 4e 54 45 47 45 52 2d 3e  ame as INTEGER->
321b0 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  TEXT.** <tr><td>
321c0 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 49    FLOAT   <td> I
321d0 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 5b 43  NTEGER   <td> [C
321e0 41 53 54 5d 20 74 6f 20 49 4e 54 45 47 45 52 0a  AST] to INTEGER.
321f0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f  ** <tr><td>  FLO
32200 41 54 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54  AT   <td>   TEXT
32210 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72      <td> ASCII r
32220 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20  endering of the 
32230 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64  float.** <tr><td
32240 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20  >  FLOAT   <td> 
32250 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 5b    BLOB    <td> [
32260 43 41 53 54 5d 20 74 6f 20 42 4c 4f 42 0a 2a 2a  CAST] to BLOB.**
32270 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20   <tr><td>  TEXT 
32280 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20     <td> INTEGER 
32290 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f    <td> [CAST] to
322a0 20 49 4e 54 45 47 45 52 0a 2a 2a 20 3c 74 72 3e   INTEGER.** <tr>
322b0 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74  <td>  TEXT    <t
322c0 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64  d>  FLOAT    <td
322d0 3e 20 5b 43 41 53 54 5d 20 74 6f 20 52 45 41 4c  > [CAST] to REAL
322e0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45  .** <tr><td>  TE
322f0 58 54 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f  XT    <td>   BLO
32300 42 20 20 20 20 3c 74 64 3e 20 4e 6f 20 63 68 61  B    <td> No cha
32310 6e 67 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  nge.** <tr><td> 
32320 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 49 4e   BLOB    <td> IN
32330 54 45 47 45 52 20 20 20 3c 74 64 3e 20 5b 43 41  TEGER   <td> [CA
32340 53 54 5d 20 74 6f 20 49 4e 54 45 47 45 52 0a 2a  ST] to INTEGER.*
32350 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42  * <tr><td>  BLOB
32360 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20      <td>  FLOAT 
32370 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74     <td> [CAST] t
32380 6f 20 52 45 41 4c 0a 2a 2a 20 3c 74 72 3e 3c 74  o REAL.** <tr><t
32390 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e  d>  BLOB    <td>
323a0 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20     TEXT    <td> 
323b0 41 64 64 20 61 20 7a 65 72 6f 20 74 65 72 6d 69  Add a zero termi
323c0 6e 61 74 6f 72 20 69 66 20 6e 65 65 64 65 64 0a  nator if needed.
323d0 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c  ** </table>.** <
323e0 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a  /blockquote>)^.*
323f0 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 77  *.** Note that w
32400 68 65 6e 20 74 79 70 65 20 63 6f 6e 76 65 72 73  hen type convers
32410 69 6f 6e 73 20 6f 63 63 75 72 2c 20 70 6f 69 6e  ions occur, poin
32420 74 65 72 73 20 72 65 74 75 72 6e 65 64 20 62 79  ters returned by
32430 20 70 72 69 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20   prior.** calls 
32440 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  to sqlite3_colum
32450 6e 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65  n_blob(), sqlite
32460 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c  3_column_text(),
32470 20 61 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74   and/or.** sqlit
32480 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
32490 28 29 20 6d 61 79 20 62 65 20 69 6e 76 61 6c 69  () may be invali
324a0 64 61 74 65 64 2e 0a 2a 2a 20 54 79 70 65 20 63  dated..** Type c
324b0 6f 6e 76 65 72 73 69 6f 6e 73 20 61 6e 64 20 70  onversions and p
324c0 6f 69 6e 74 65 72 20 69 6e 76 61 6c 69 64 61 74  ointer invalidat
324d0 69 6f 6e 73 20 6d 69 67 68 74 20 6f 63 63 75 72  ions might occur
324e0 0a 2a 2a 20 69 6e 20 74 68 65 20 66 6f 6c 6c 6f  .** in the follo
324f0 77 69 6e 67 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a  wing cases:.**.*
32500 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54  * <ul>.** <li> T
32510 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65  he initial conte
32520 6e 74 20 69 73 20 61 20 42 4c 4f 42 20 61 6e 64  nt is a BLOB and
32530 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
32540 74 65 78 74 28 29 20 6f 72 0a 2a 2a 20 20 20 20  text() or.**    
32550 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e    sqlite3_column
32560 5f 74 65 78 74 31 36 28 29 20 69 73 20 63 61 6c  _text16() is cal
32570 6c 65 64 2e 20 20 41 20 7a 65 72 6f 2d 74 65 72  led.  A zero-ter
32580 6d 69 6e 61 74 6f 72 20 6d 69 67 68 74 0a 2a 2a  minator might.**
32590 20 20 20 20 20 20 6e 65 65 64 20 74 6f 20 62 65        need to be
325a0 20 61 64 64 65 64 20 74 6f 20 74 68 65 20 73 74   added to the st
325b0 72 69 6e 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c  ring.</li>.** <l
325c0 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63  i> The initial c
325d0 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 38 20  ontent is UTF-8 
325e0 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33  text and sqlite3
325f0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
32600 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c  ) or.**      sql
32610 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
32620 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20  16() is called. 
32630 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73   The content mus
32640 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a  t be converted.*
32650 2a 20 20 20 20 20 20 74 6f 20 55 54 46 2d 31 36  *      to UTF-16
32660 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54  .</li>.** <li> T
32670 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65  he initial conte
32680 6e 74 20 69 73 20 55 54 46 2d 31 36 20 74 65 78  nt is UTF-16 tex
32690 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f  t and sqlite3_co
326a0 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a  lumn_bytes() or.
326b0 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f  **      sqlite3_
326c0 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 69 73  column_text() is
326d0 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f   called.  The co
326e0 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f  ntent must be co
326f0 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20  nverted.**      
32700 74 6f 20 55 54 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a  to UTF-8.</li>.*
32710 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 43  * </ul>.**.** ^C
32720 6f 6e 76 65 72 73 69 6f 6e 73 20 62 65 74 77 65  onversions betwe
32730 65 6e 20 55 54 46 2d 31 36 62 65 20 61 6e 64 20  en UTF-16be and 
32740 55 54 46 2d 31 36 6c 65 20 61 72 65 20 61 6c 77  UTF-16le are alw
32750 61 79 73 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63  ays done in plac
32760 65 20 61 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20  e and do.** not 
32770 69 6e 76 61 6c 69 64 61 74 65 20 61 20 70 72 69  invalidate a pri
32780 6f 72 20 70 6f 69 6e 74 65 72 2c 20 74 68 6f 75  or pointer, thou
32790 67 68 20 6f 66 20 63 6f 75 72 73 65 20 74 68 65  gh of course the
327a0 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20   content of the 
327b0 62 75 66 66 65 72 0a 2a 2a 20 74 68 61 74 20 74  buffer.** that t
327c0 68 65 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72  he prior pointer
327d0 20 72 65 66 65 72 65 6e 63 65 73 20 77 69 6c 6c   references will
327e0 20 68 61 76 65 20 62 65 65 6e 20 6d 6f 64 69 66   have been modif
327f0 69 65 64 2e 20 20 4f 74 68 65 72 20 6b 69 6e 64  ied.  Other kind
32800 73 0a 2a 2a 20 6f 66 20 63 6f 6e 76 65 72 73 69  s.** of conversi
32810 6f 6e 20 61 72 65 20 64 6f 6e 65 20 69 6e 20 70  on are done in p
32820 6c 61 63 65 20 77 68 65 6e 20 69 74 20 69 73 20  lace when it is 
32830 70 6f 73 73 69 62 6c 65 2c 20 62 75 74 20 73 6f  possible, but so
32840 6d 65 74 69 6d 65 73 20 74 68 65 79 0a 2a 2a 20  metimes they.** 
32850 61 72 65 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65  are not possible
32860 20 61 6e 64 20 69 6e 20 74 68 6f 73 65 20 63 61   and in those ca
32870 73 65 73 20 70 72 69 6f 72 20 70 6f 69 6e 74 65  ses prior pointe
32880 72 73 20 61 72 65 20 69 6e 76 61 6c 69 64 61 74  rs are invalidat
32890 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 61  ed..**.** The sa
328a0 66 65 73 74 20 70 6f 6c 69 63 79 20 69 73 20 74  fest policy is t
328b0 6f 20 69 6e 76 6f 6b 65 20 74 68 65 73 65 20 72  o invoke these r
328c0 6f 75 74 69 6e 65 73 0a 2a 2a 20 69 6e 20 6f 6e  outines.** in on
328d0 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69  e of the followi
328e0 6e 67 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c  ng ways:.**.** <
328f0 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69  ul>.**  <li>sqli
32900 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
32910 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71  ) followed by sq
32920 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
32930 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c  es()</li>.**  <l
32940 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  i>sqlite3_column
32950 5f 62 6c 6f 62 28 29 20 66 6f 6c 6c 6f 77 65 64  _blob() followed
32960 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   by sqlite3_colu
32970 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a  mn_bytes()</li>.
32980 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f  **  <li>sqlite3_
32990 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20  column_text16() 
329a0 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69  followed by sqli
329b0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
329c0 31 36 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75  16()</li>.** </u
329d0 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68 65  l>.**.** In othe
329e0 72 20 77 6f 72 64 73 2c 20 79 6f 75 20 73 68 6f  r words, you sho
329f0 75 6c 64 20 63 61 6c 6c 20 73 71 6c 69 74 65 33  uld call sqlite3
32a00 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 0a  _column_text(),.
32a10 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ** sqlite3_colum
32a20 6e 5f 62 6c 6f 62 28 29 2c 20 6f 72 20 73 71 6c  n_blob(), or sql
32a30 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
32a40 31 36 28 29 20 66 69 72 73 74 20 74 6f 20 66 6f  16() first to fo
32a50 72 63 65 20 74 68 65 20 72 65 73 75 6c 74 0a 2a  rce the result.*
32a60 2a 20 69 6e 74 6f 20 74 68 65 20 64 65 73 69 72  * into the desir
32a70 65 64 20 66 6f 72 6d 61 74 2c 20 74 68 65 6e 20  ed format, then 
32a80 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63  invoke sqlite3_c
32a90 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72  olumn_bytes() or
32aa0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  .** sqlite3_colu
32ab0 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 74 6f 20  mn_bytes16() to 
32ac0 66 69 6e 64 20 74 68 65 20 73 69 7a 65 20 6f 66  find the size of
32ad0 20 74 68 65 20 72 65 73 75 6c 74 2e 20 20 44 6f   the result.  Do
32ae0 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 0a 2a   not mix calls.*
32af0 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c  * to sqlite3_col
32b00 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 20 73 71  umn_text() or sq
32b10 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
32b20 62 28 29 20 77 69 74 68 20 63 61 6c 6c 73 20 74  b() with calls t
32b30 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c  o.** sqlite3_col
32b40 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 2c 20 61  umn_bytes16(), a
32b50 6e 64 20 64 6f 20 6e 6f 74 20 6d 69 78 20 63 61  nd do not mix ca
32b60 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  lls to sqlite3_c
32b70 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 0a 2a  olumn_text16().*
32b80 2a 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 20  * with calls to 
32b90 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
32ba0 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ytes()..**.** ^T
32bb0 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75  he pointers retu
32bc0 72 6e 65 64 20 61 72 65 20 76 61 6c 69 64 20 75  rned are valid u
32bd0 6e 74 69 6c 20 61 20 74 79 70 65 20 63 6f 6e 76  ntil a type conv
32be0 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 20 61 73  ersion occurs as
32bf0 0a 2a 2a 20 64 65 73 63 72 69 62 65 64 20 61 62  .** described ab
32c00 6f 76 65 2c 20 6f 72 20 75 6e 74 69 6c 20 5b 73  ove, or until [s
32c10 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f  qlite3_step()] o
32c20 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  r [sqlite3_reset
32c30 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  ()] or.** [sqlit
32c40 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69  e3_finalize()] i
32c50 73 20 63 61 6c 6c 65 64 2e 20 20 5e 54 68 65 20  s called.  ^The 
32c60 6d 65 6d 6f 72 79 20 73 70 61 63 65 20 75 73 65  memory space use
32c70 64 20 74 6f 20 68 6f 6c 64 20 73 74 72 69 6e 67  d to hold string
32c80 73 0a 2a 2a 20 61 6e 64 20 42 4c 4f 42 73 20 69  s.** and BLOBs i
32c90 73 20 66 72 65 65 64 20 61 75 74 6f 6d 61 74 69  s freed automati
32ca0 63 61 6c 6c 79 2e 20 20 44 6f 20 3c 65 6d 3e 6e  cally.  Do <em>n
32cb0 6f 74 3c 2f 65 6d 3e 20 70 61 73 73 20 74 68 65  ot</em> pass the
32cc0 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e   pointers return
32cd0 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69  ed.** from [sqli
32ce0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
32cf0 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  )], [sqlite3_col
32d00 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 65 74 63  umn_text()], etc
32d10 2e 20 69 6e 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  . into.** [sqlit
32d20 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a  e3_free()]..**.*
32d30 2a 20 5e 28 49 66 20 61 20 6d 65 6d 6f 72 79 20  * ^(If a memory 
32d40 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72  allocation error
32d50 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67 20 74   occurs during t
32d60 68 65 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66  he evaluation of
32d70 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 73 65   any.** of these
32d80 20 72 6f 75 74 69 6e 65 73 2c 20 61 20 64 65 66   routines, a def
32d90 61 75 6c 74 20 76 61 6c 75 65 20 69 73 20 72 65  ault value is re
32da0 74 75 72 6e 65 64 2e 20 20 54 68 65 20 64 65 66  turned.  The def
32db0 61 75 6c 74 20 76 61 6c 75 65 0a 2a 2a 20 69 73  ault value.** is
32dc0 20 65 69 74 68 65 72 20 74 68 65 20 69 6e 74 65   either the inte
32dd0 67 65 72 20 30 2c 20 74 68 65 20 66 6c 6f 61 74  ger 0, the float
32de0 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72  ing point number
32df0 20 30 2e 30 2c 20 6f 72 20 61 20 4e 55 4c 4c 0a   0.0, or a NULL.
32e00 2a 2a 20 70 6f 69 6e 74 65 72 2e 20 20 53 75 62  ** pointer.  Sub
32e10 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f  sequent calls to
32e20 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64   [sqlite3_errcod
32e30 65 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e  e()] will return
32e40 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45  .** [SQLITE_NOME
32e50 4d 5d 2e 29 5e 0a 2a 2f 0a 63 6f 6e 73 74 20 76  M].)^.*/.const v
32e60 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
32e70 75 6d 6e 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33  umn_blob(sqlite3
32e80 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
32e90 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
32ea0 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 73 71 6c 69  olumn_bytes(sqli
32eb0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
32ec0 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  Col);.int sqlite
32ed0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
32ee0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
32ef0 69 6e 74 20 69 43 6f 6c 29 3b 0a 64 6f 75 62 6c  int iCol);.doubl
32f00 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
32f10 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f  _double(sqlite3_
32f20 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
32f30 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  ;.int sqlite3_co
32f40 6c 75 6d 6e 5f 69 6e 74 28 73 71 6c 69 74 65 33  lumn_int(sqlite3
32f50 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
32f60 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  );.sqlite3_int64
32f70 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
32f80 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74  int64(sqlite3_st
32f90 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
32fa0 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63  const unsigned c
32fb0 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  har *sqlite3_col
32fc0 75 6d 6e 5f 74 65 78 74 28 73 71 6c 69 74 65 33  umn_text(sqlite3
32fd0 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
32fe0 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
32ff0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
33000 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  xt16(sqlite3_stm
33010 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69  t*, int iCol);.i
33020 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nt sqlite3_colum
33030 6e 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73  n_type(sqlite3_s
33040 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
33050 0a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a  .sqlite3_value *
33060 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76  sqlite3_column_v
33070 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  alue(sqlite3_stm
33080 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 0a  t*, int iCol);..
33090 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
330a0 44 65 73 74 72 6f 79 20 41 20 50 72 65 70 61 72  Destroy A Prepar
330b0 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a  ed Statement Obj
330c0 65 63 74 0a 2a 2a 20 44 45 53 54 52 55 43 54 4f  ect.** DESTRUCTO
330d0 52 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a  R: sqlite3_stmt.
330e0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
330f0 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 66 75  e3_finalize() fu
33100 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64  nction is called
33110 20 74 6f 20 64 65 6c 65 74 65 20 61 20 5b 70 72   to delete a [pr
33120 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
33130 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f  ]..** ^If the mo
33140 73 74 20 72 65 63 65 6e 74 20 65 76 61 6c 75 61  st recent evalua
33150 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 74 61 74  tion of the stat
33160 65 6d 65 6e 74 20 65 6e 63 6f 75 6e 74 65 72 65  ement encountere
33170 64 20 6e 6f 20 65 72 72 6f 72 73 0a 2a 2a 20 6f  d no errors.** o
33180 72 20 69 66 20 74 68 65 20 73 74 61 74 65 6d 65  r if the stateme
33190 6e 74 20 69 73 20 6e 65 76 65 72 20 62 65 65 6e  nt is never been
331a0 20 65 76 61 6c 75 61 74 65 64 2c 20 74 68 65 6e   evaluated, then
331b0 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a   sqlite3_finaliz
331c0 65 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 53  e() returns.** S
331d0 51 4c 49 54 45 5f 4f 4b 2e 20 20 5e 49 66 20 74  QLITE_OK.  ^If t
331e0 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 65  he most recent e
331f0 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 73 74 61  valuation of sta
33200 74 65 6d 65 6e 74 20 53 20 66 61 69 6c 65 64 2c  tement S failed,
33210 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33   then.** sqlite3
33220 5f 66 69 6e 61 6c 69 7a 65 28 53 29 20 72 65 74  _finalize(S) ret
33230 75 72 6e 73 20 74 68 65 20 61 70 70 72 6f 70 72  urns the appropr
33240 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65  iate [error code
33250 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65  ] or.** [extende
33260 64 20 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a  d error code]..*
33270 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
33280 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 20 72 6f  3_finalize(S) ro
33290 75 74 69 6e 65 20 63 61 6e 20 62 65 20 63 61 6c  utine can be cal
332a0 6c 65 64 20 61 74 20 61 6e 79 20 70 6f 69 6e 74  led at any point
332b0 20 64 75 72 69 6e 67 0a 2a 2a 20 74 68 65 20 6c   during.** the l
332c0 69 66 65 20 63 79 63 6c 65 20 6f 66 20 5b 70 72  ife cycle of [pr
332d0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
332e0 5d 20 53 3a 0a 2a 2a 20 62 65 66 6f 72 65 20 73  ] S:.** before s
332f0 74 61 74 65 6d 65 6e 74 20 53 20 69 73 20 65 76  tatement S is ev
33300 65 72 20 65 76 61 6c 75 61 74 65 64 2c 20 61 66  er evaluated, af
33310 74 65 72 0a 2a 2a 20 6f 6e 65 20 6f 72 20 6d 6f  ter.** one or mo
33320 72 65 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c  re calls to [sql
33330 69 74 65 33 5f 72 65 73 65 74 28 29 5d 2c 20 6f  ite3_reset()], o
33340 72 20 61 66 74 65 72 20 61 6e 79 20 63 61 6c 6c  r after any call
33350 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  .** to [sqlite3_
33360 73 74 65 70 28 29 5d 20 72 65 67 61 72 64 6c 65  step()] regardle
33370 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72  ss of whether or
33380 20 6e 6f 74 20 74 68 65 20 73 74 61 74 65 6d 65   not the stateme
33390 6e 74 20 68 61 73 0a 2a 2a 20 63 6f 6d 70 6c 65  nt has.** comple
333a0 74 65 64 20 65 78 65 63 75 74 69 6f 6e 2e 0a 2a  ted execution..*
333b0 2a 0a 2a 2a 20 5e 49 6e 76 6f 6b 69 6e 67 20 73  *.** ^Invoking s
333c0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
333d0 29 20 6f 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  ) on a NULL poin
333e0 74 65 72 20 69 73 20 61 20 68 61 72 6d 6c 65 73  ter is a harmles
333f0 73 20 6e 6f 2d 6f 70 2e 0a 2a 2a 0a 2a 2a 20 54  s no-op..**.** T
33400 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  he application m
33410 75 73 74 20 66 69 6e 61 6c 69 7a 65 20 65 76 65  ust finalize eve
33420 72 79 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ry [prepared sta
33430 74 65 6d 65 6e 74 5d 20 69 6e 20 6f 72 64 65 72  tement] in order
33440 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 72 65 73   to avoid.** res
33450 6f 75 72 63 65 20 6c 65 61 6b 73 2e 20 20 49 74  ource leaks.  It
33460 20 69 73 20 61 20 67 72 69 65 76 6f 75 73 20 65   is a grievous e
33470 72 72 6f 72 20 66 6f 72 20 74 68 65 20 61 70 70  rror for the app
33480 6c 69 63 61 74 69 6f 6e 20 74 6f 20 74 72 79 20  lication to try 
33490 74 6f 20 75 73 65 0a 2a 2a 20 61 20 70 72 65 70  to use.** a prep
334a0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61  ared statement a
334b0 66 74 65 72 20 69 74 20 68 61 73 20 62 65 65 6e  fter it has been
334c0 20 66 69 6e 61 6c 69 7a 65 64 2e 20 20 41 6e 79   finalized.  Any
334d0 20 75 73 65 20 6f 66 20 61 20 70 72 65 70 61 72   use of a prepar
334e0 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20  ed.** statement 
334f0 61 66 74 65 72 20 69 74 20 68 61 73 20 62 65 65  after it has bee
33500 6e 20 66 69 6e 61 6c 69 7a 65 64 20 63 61 6e 20  n finalized can 
33510 72 65 73 75 6c 74 20 69 6e 20 75 6e 64 65 66 69  result in undefi
33520 6e 65 64 20 61 6e 64 0a 2a 2a 20 75 6e 64 65 73  ned and.** undes
33530 69 72 61 62 6c 65 20 62 65 68 61 76 69 6f 72 20  irable behavior 
33540 73 75 63 68 20 61 73 20 73 65 67 66 61 75 6c 74  such as segfault
33550 73 20 61 6e 64 20 68 65 61 70 20 63 6f 72 72 75  s and heap corru
33560 70 74 69 6f 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ption..*/.int sq
33570 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 73  lite3_finalize(s
33580 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74  qlite3_stmt *pSt
33590 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  mt);../*.** CAPI
335a0 33 52 45 46 3a 20 52 65 73 65 74 20 41 20 50 72  3REF: Reset A Pr
335b0 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74  epared Statement
335c0 20 4f 62 6a 65 63 74 0a 2a 2a 20 4d 45 54 48 4f   Object.** METHO
335d0 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a  D: sqlite3_stmt.
335e0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
335f0 33 5f 72 65 73 65 74 28 29 20 66 75 6e 63 74 69  3_reset() functi
33600 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20  on is called to 
33610 72 65 73 65 74 20 61 20 5b 70 72 65 70 61 72 65  reset a [prepare
33620 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20  d statement].** 
33630 6f 62 6a 65 63 74 20 62 61 63 6b 20 74 6f 20 69  object back to i
33640 74 73 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65  ts initial state
33650 2c 20 72 65 61 64 79 20 74 6f 20 62 65 20 72 65  , ready to be re
33660 2d 65 78 65 63 75 74 65 64 2e 0a 2a 2a 20 5e 41  -executed..** ^A
33670 6e 79 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ny SQL statement
33680 20 76 61 72 69 61 62 6c 65 73 20 74 68 61 74 20   variables that 
33690 68 61 64 20 76 61 6c 75 65 73 20 62 6f 75 6e 64  had values bound
336a0 20 74 6f 20 74 68 65 6d 20 75 73 69 6e 67 0a 2a   to them using.*
336b0 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62  * the [sqlite3_b
336c0 69 6e 64 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74  ind_blob | sqlit
336d0 65 33 5f 62 69 6e 64 5f 2a 28 29 20 41 50 49 5d  e3_bind_*() API]
336e0 20 72 65 74 61 69 6e 20 74 68 65 69 72 20 76 61   retain their va
336f0 6c 75 65 73 2e 0a 2a 2a 20 55 73 65 20 5b 73 71  lues..** Use [sq
33700 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64  lite3_clear_bind
33710 69 6e 67 73 28 29 5d 20 74 6f 20 72 65 73 65 74  ings()] to reset
33720 20 74 68 65 20 62 69 6e 64 69 6e 67 73 2e 0a 2a   the bindings..*
33730 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74  *.** ^The [sqlit
33740 65 33 5f 72 65 73 65 74 28 53 29 5d 20 69 6e 74  e3_reset(S)] int
33750 65 72 66 61 63 65 20 72 65 73 65 74 73 20 74 68  erface resets th
33760 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
33770 65 6d 65 6e 74 5d 20 53 0a 2a 2a 20 62 61 63 6b  ement] S.** back
33780 20 74 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e   to the beginnin
33790 67 20 6f 66 20 69 74 73 20 70 72 6f 67 72 61 6d  g of its program
337a0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
337b0 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c  most recent call
337c0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   to [sqlite3_ste
337d0 70 28 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a  p(S)] for the.**
337e0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
337f0 6d 65 6e 74 5d 20 53 20 72 65 74 75 72 6e 65 64  ment] S returned
33800 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 6f 72   [SQLITE_ROW] or
33810 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 0a   [SQLITE_DONE],.
33820 2a 2a 20 6f 72 20 69 66 20 5b 73 71 6c 69 74 65  ** or if [sqlite
33830 33 5f 73 74 65 70 28 53 29 5d 20 68 61 73 20 6e  3_step(S)] has n
33840 65 76 65 72 20 62 65 66 6f 72 65 20 62 65 65 6e  ever before been
33850 20 63 61 6c 6c 65 64 20 6f 6e 20 53 2c 0a 2a 2a   called on S,.**
33860 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72   then [sqlite3_r
33870 65 73 65 74 28 53 29 5d 20 72 65 74 75 72 6e 73  eset(S)] returns
33880 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a   [SQLITE_OK]..**
33890 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74  .** ^If the most
338a0 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20   recent call to 
338b0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29  [sqlite3_step(S)
338c0 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72  ] for the.** [pr
338d0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
338e0 5d 20 53 20 69 6e 64 69 63 61 74 65 64 20 61 6e  ] S indicated an
338f0 20 65 72 72 6f 72 2c 20 74 68 65 6e 0a 2a 2a 20   error, then.** 
33900 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53  [sqlite3_reset(S
33910 29 5d 20 72 65 74 75 72 6e 73 20 61 6e 20 61 70  )] returns an ap
33920 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72  propriate [error
33930 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54   code]..**.** ^T
33940 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  he [sqlite3_rese
33950 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20  t(S)] interface 
33960 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20  does not change 
33970 74 68 65 20 76 61 6c 75 65 73 0a 2a 2a 20 6f 66  the values.** of
33980 20 61 6e 79 20 5b 73 71 6c 69 74 65 33 5f 62 69   any [sqlite3_bi
33990 6e 64 5f 62 6c 6f 62 7c 62 69 6e 64 69 6e 67 73  nd_blob|bindings
339a0 5d 20 6f 6e 20 74 68 65 20 5b 70 72 65 70 61 72  ] on the [prepar
339b0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e  ed statement] S.
339c0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
339d0 72 65 73 65 74 28 73 71 6c 69 74 65 33 5f 73 74  reset(sqlite3_st
339e0 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a  mt *pStmt);../*.
339f0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 72 65  ** CAPI3REF: Cre
33a00 61 74 65 20 4f 72 20 52 65 64 65 66 69 6e 65 20  ate Or Redefine 
33a10 53 51 4c 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a  SQL Functions.**
33a20 20 4b 45 59 57 4f 52 44 53 3a 20 7b 66 75 6e 63   KEYWORDS: {func
33a30 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f  tion creation ro
33a40 75 74 69 6e 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f  utines}.** KEYWO
33a50 52 44 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f  RDS: {applicatio
33a60 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75  n-defined SQL fu
33a70 6e 63 74 69 6f 6e 7d 0a 2a 2a 20 4b 45 59 57 4f  nction}.** KEYWO
33a80 52 44 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f  RDS: {applicatio
33a90 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75  n-defined SQL fu
33aa0 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 20 4d 45 54 48  nctions}.** METH
33ab0 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a  OD: sqlite3.**.*
33ac0 2a 20 5e 54 68 65 73 65 20 66 75 6e 63 74 69 6f  * ^These functio
33ad0 6e 73 20 28 63 6f 6c 6c 65 63 74 69 76 65 6c 79  ns (collectively
33ae0 20 6b 6e 6f 77 6e 20 61 73 20 22 66 75 6e 63 74   known as "funct
33af0 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f 75  ion creation rou
33b00 74 69 6e 65 73 22 29 0a 2a 2a 20 61 72 65 20 75  tines").** are u
33b10 73 65 64 20 74 6f 20 61 64 64 20 53 51 4c 20 66  sed to add SQL f
33b20 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72  unctions or aggr
33b30 65 67 61 74 65 73 20 6f 72 20 74 6f 20 72 65 64  egates or to red
33b40 65 66 69 6e 65 20 74 68 65 20 62 65 68 61 76 69  efine the behavi
33b50 6f 72 0a 2a 2a 20 6f 66 20 65 78 69 73 74 69 6e  or.** of existin
33b60 67 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  g SQL functions 
33b70 6f 72 20 61 67 67 72 65 67 61 74 65 73 2e 20 20  or aggregates.  
33b80 54 68 65 20 6f 6e 6c 79 20 64 69 66 66 65 72 65  The only differe
33b90 6e 63 65 73 20 62 65 74 77 65 65 6e 0a 2a 2a 20  nces between.** 
33ba0 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  these routines a
33bb0 72 65 20 74 68 65 20 74 65 78 74 20 65 6e 63 6f  re the text enco
33bc0 64 69 6e 67 20 65 78 70 65 63 74 65 64 20 66 6f  ding expected fo
33bd0 72 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64 20  r.** the second 
33be0 70 61 72 61 6d 65 74 65 72 20 28 74 68 65 20 6e  parameter (the n
33bf0 61 6d 65 20 6f 66 20 74 68 65 20 66 75 6e 63 74  ame of the funct
33c00 69 6f 6e 20 62 65 69 6e 67 20 63 72 65 61 74 65  ion being create
33c10 64 29 0a 2a 2a 20 61 6e 64 20 74 68 65 20 70 72  d).** and the pr
33c20 65 73 65 6e 63 65 20 6f 72 20 61 62 73 65 6e 63  esence or absenc
33c30 65 20 6f 66 20 61 20 64 65 73 74 72 75 63 74 6f  e of a destructo
33c40 72 20 63 61 6c 6c 62 61 63 6b 20 66 6f 72 0a 2a  r callback for.*
33c50 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * the applicatio
33c60 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72 2e 0a  n data pointer..
33c70 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  **.** ^The first
33c80 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
33c90 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
33ca0 65 63 74 69 6f 6e 5d 20 74 6f 20 77 68 69 63 68  ection] to which
33cb0 20 74 68 65 20 53 51 4c 0a 2a 2a 20 66 75 6e 63   the SQL.** func
33cc0 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 20 61 64  tion is to be ad
33cd0 64 65 64 2e 20 20 5e 49 66 20 61 6e 20 61 70 70  ded.  ^If an app
33ce0 6c 69 63 61 74 69 6f 6e 20 75 73 65 73 20 6d 6f  lication uses mo
33cf0 72 65 20 74 68 61 6e 20 6f 6e 65 20 64 61 74 61  re than one data
33d00 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69  base.** connecti
33d10 6f 6e 20 74 68 65 6e 20 61 70 70 6c 69 63 61 74  on then applicat
33d20 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20  ion-defined SQL 
33d30 66 75 6e 63 74 69 6f 6e 73 20 6d 75 73 74 20 62  functions must b
33d40 65 20 61 64 64 65 64 0a 2a 2a 20 74 6f 20 65 61  e added.** to ea
33d50 63 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ch database conn
33d60 65 63 74 69 6f 6e 20 73 65 70 61 72 61 74 65 6c  ection separatel
33d70 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65  y..**.** ^The se
33d80 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69  cond parameter i
33d90 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
33da0 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74  e SQL function t
33db0 6f 20 62 65 20 63 72 65 61 74 65 64 20 6f 72 0a  o be created or.
33dc0 2a 2a 20 72 65 64 65 66 69 6e 65 64 2e 20 20 5e  ** redefined.  ^
33dd0 54 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68  The length of th
33de0 65 20 6e 61 6d 65 20 69 73 20 6c 69 6d 69 74 65  e name is limite
33df0 64 20 74 6f 20 32 35 35 20 62 79 74 65 73 20 69  d to 255 bytes i
33e00 6e 20 61 20 55 54 46 2d 38 0a 2a 2a 20 72 65 70  n a UTF-8.** rep
33e10 72 65 73 65 6e 74 61 74 69 6f 6e 2c 20 65 78 63  resentation, exc
33e20 6c 75 73 69 76 65 20 6f 66 20 74 68 65 20 7a 65  lusive of the ze
33e30 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20  ro-terminator.  
33e40 5e 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 6e  ^Note that the n
33e50 61 6d 65 0a 2a 2a 20 6c 65 6e 67 74 68 20 6c 69  ame.** length li
33e60 6d 69 74 20 69 73 20 69 6e 20 55 54 46 2d 38 20  mit is in UTF-8 
33e70 62 79 74 65 73 2c 20 6e 6f 74 20 63 68 61 72 61  bytes, not chara
33e80 63 74 65 72 73 20 6e 6f 72 20 55 54 46 2d 31 36  cters nor UTF-16
33e90 20 62 79 74 65 73 2e 20 20 0a 2a 2a 20 5e 41 6e   bytes.  .** ^An
33ea0 79 20 61 74 74 65 6d 70 74 20 74 6f 20 63 72 65  y attempt to cre
33eb0 61 74 65 20 61 20 66 75 6e 63 74 69 6f 6e 20 77  ate a function w
33ec0 69 74 68 20 61 20 6c 6f 6e 67 65 72 20 6e 61 6d  ith a longer nam
33ed0 65 0a 2a 2a 20 77 69 6c 6c 20 72 65 73 75 6c 74  e.** will result
33ee0 20 69 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55   in [SQLITE_MISU
33ef0 53 45 5d 20 62 65 69 6e 67 20 72 65 74 75 72 6e  SE] being return
33f00 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74  ed..**.** ^The t
33f10 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 28  hird parameter (
33f20 6e 41 72 67 29 0a 2a 2a 20 69 73 20 74 68 65 20  nArg).** is the 
33f30 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65  number of argume
33f40 6e 74 73 20 74 68 61 74 20 74 68 65 20 53 51 4c  nts that the SQL
33f50 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20   function or.** 
33f60 61 67 67 72 65 67 61 74 65 20 74 61 6b 65 73 2e  aggregate takes.
33f70 20 5e 49 66 20 74 68 69 73 20 70 61 72 61 6d 65   ^If this parame
33f80 74 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e 20  ter is -1, then 
33f90 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
33fa0 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65   or.** aggregate
33fb0 20 6d 61 79 20 74 61 6b 65 20 61 6e 79 20 6e 75   may take any nu
33fc0 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74  mber of argument
33fd0 73 20 62 65 74 77 65 65 6e 20 30 20 61 6e 64 20  s between 0 and 
33fe0 74 68 65 20 6c 69 6d 69 74 0a 2a 2a 20 73 65 74  the limit.** set
33ff0 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d   by [sqlite3_lim
34000 69 74 5d 28 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  it]([SQLITE_LIMI
34010 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 5d 29  T_FUNCTION_ARG])
34020 2e 20 20 49 66 20 74 68 65 20 74 68 69 72 64 0a  .  If the third.
34030 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  ** parameter is 
34040 6c 65 73 73 20 74 68 61 6e 20 2d 31 20 6f 72 20  less than -1 or 
34050 67 72 65 61 74 65 72 20 74 68 61 6e 20 31 32 37  greater than 127
34060 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69   then the behavi
34070 6f 72 20 69 73 0a 2a 2a 20 75 6e 64 65 66 69 6e  or is.** undefin
34080 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  ed..**.** ^The f
34090 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 2c  ourth parameter,
340a0 20 65 54 65 78 74 52 65 70 2c 20 73 70 65 63 69   eTextRep, speci
340b0 66 69 65 73 20 77 68 61 74 0a 2a 2a 20 5b 53 51  fies what.** [SQ
340c0 4c 49 54 45 5f 55 54 46 38 20 7c 20 74 65 78 74  LITE_UTF8 | text
340d0 20 65 6e 63 6f 64 69 6e 67 5d 20 74 68 69 73 20   encoding] this 
340e0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 70 72 65  SQL function pre
340f0 66 65 72 73 20 66 6f 72 0a 2a 2a 20 69 74 73 20  fers for.** its 
34100 70 61 72 61 6d 65 74 65 72 73 2e 20 20 54 68 65  parameters.  The
34110 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f   application sho
34120 75 6c 64 20 73 65 74 20 74 68 69 73 20 70 61 72  uld set this par
34130 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 53 51  ameter to.** [SQ
34140 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 20 69 66  LITE_UTF16LE] if
34150 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 6d   the function im
34160 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 76  plementation inv
34170 6f 6b 65 73 20 0a 2a 2a 20 5b 73 71 6c 69 74 65  okes .** [sqlite
34180 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65  3_value_text16le
34190 28 29 5d 20 6f 6e 20 61 6e 20 69 6e 70 75 74 2c  ()] on an input,
341a0 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 31   or [SQLITE_UTF1
341b0 36 42 45 5d 20 69 66 20 74 68 65 0a 2a 2a 20 69  6BE] if the.** i
341c0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e  mplementation in
341d0 76 6f 6b 65 73 20 5b 73 71 6c 69 74 65 33 5f 76  vokes [sqlite3_v
341e0 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28 29 5d  alue_text16be()]
341f0 20 6f 6e 20 61 6e 20 69 6e 70 75 74 2c 20 6f 72   on an input, or
34200 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 31  .** [SQLITE_UTF1
34210 36 5d 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 76  6] if [sqlite3_v
34220 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 20 69  alue_text16()] i
34230 73 20 75 73 65 64 2c 20 6f 72 20 5b 53 51 4c 49  s used, or [SQLI
34240 54 45 5f 55 54 46 38 5d 0a 2a 2a 20 6f 74 68 65  TE_UTF8].** othe
34250 72 77 69 73 65 2e 20 20 5e 54 68 65 20 73 61 6d  rwise.  ^The sam
34260 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6d  e SQL function m
34270 61 79 20 62 65 20 72 65 67 69 73 74 65 72 65 64  ay be registered
34280 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20   multiple times 
34290 75 73 69 6e 67 0a 2a 2a 20 64 69 66 66 65 72 65  using.** differe
342a0 6e 74 20 70 72 65 66 65 72 72 65 64 20 74 65 78  nt preferred tex
342b0 74 20 65 6e 63 6f 64 69 6e 67 73 2c 20 77 69 74  t encodings, wit
342c0 68 20 64 69 66 66 65 72 65 6e 74 20 69 6d 70 6c  h different impl
342d0 65 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72 0a  ementations for.
342e0 2a 2a 20 65 61 63 68 20 65 6e 63 6f 64 69 6e 67  ** each encoding
342f0 2e 0a 2a 2a 20 5e 57 68 65 6e 20 6d 75 6c 74 69  ..** ^When multi
34300 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ple implementati
34310 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20  ons of the same 
34320 66 75 6e 63 74 69 6f 6e 20 61 72 65 20 61 76 61  function are ava
34330 69 6c 61 62 6c 65 2c 20 53 51 4c 69 74 65 0a 2a  ilable, SQLite.*
34340 2a 20 77 69 6c 6c 20 70 69 63 6b 20 74 68 65 20  * will pick the 
34350 6f 6e 65 20 74 68 61 74 20 69 6e 76 6f 6c 76 65  one that involve
34360 73 20 74 68 65 20 6c 65 61 73 74 20 61 6d 6f 75  s the least amou
34370 6e 74 20 6f 66 20 64 61 74 61 20 63 6f 6e 76 65  nt of data conve
34380 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  rsion..**.** ^Th
34390 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
343a0 65 72 20 6d 61 79 20 6f 70 74 69 6f 6e 61 6c 6c  er may optionall
343b0 79 20 62 65 20 4f 52 65 64 20 77 69 74 68 20 5b  y be ORed with [
343c0 53 51 4c 49 54 45 5f 44 45 54 45 52 4d 49 4e 49  SQLITE_DETERMINI
343d0 53 54 49 43 5d 0a 2a 2a 20 74 6f 20 73 69 67 6e  STIC].** to sign
343e0 61 6c 20 74 68 61 74 20 74 68 65 20 66 75 6e 63  al that the func
343f0 74 69 6f 6e 20 77 69 6c 6c 20 61 6c 77 61 79 73  tion will always
34400 20 72 65 74 75 72 6e 20 74 68 65 20 73 61 6d 65   return the same
34410 20 72 65 73 75 6c 74 20 67 69 76 65 6e 0a 2a 2a   result given.**
34420 20 74 68 65 20 73 61 6d 65 20 69 6e 70 75 74 73   the same inputs
34430 20 77 69 74 68 69 6e 20 61 20 73 69 6e 67 6c 65   within a single
34440 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20   SQL statement. 
34450 20 4d 6f 73 74 20 53 51 4c 20 66 75 6e 63 74 69   Most SQL functi
34460 6f 6e 73 20 61 72 65 0a 2a 2a 20 64 65 74 65 72  ons are.** deter
34470 6d 69 6e 69 73 74 69 63 2e 20 20 54 68 65 20 62  ministic.  The b
34480 75 69 6c 74 2d 69 6e 20 5b 72 61 6e 64 6f 6d 28  uilt-in [random(
34490 29 5d 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  )] SQL function 
344a0 69 73 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66  is an example of
344b0 20 61 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74   a.** function t
344c0 68 61 74 20 69 73 20 6e 6f 74 20 64 65 74 65 72  hat is not deter
344d0 6d 69 6e 69 73 74 69 63 2e 20 20 54 68 65 20 53  ministic.  The S
344e0 51 4c 69 74 65 20 71 75 65 72 79 20 70 6c 61 6e  QLite query plan
344f0 6e 65 72 20 69 73 20 61 62 6c 65 20 74 6f 0a 2a  ner is able to.*
34500 2a 20 70 65 72 66 6f 72 6d 20 61 64 64 69 74 69  * perform additi
34510 6f 6e 61 6c 20 6f 70 74 69 6d 69 7a 61 74 69 6f  onal optimizatio
34520 6e 73 20 6f 6e 20 64 65 74 65 72 6d 69 6e 69 73  ns on determinis
34530 74 69 63 20 66 75 6e 63 74 69 6f 6e 73 2c 20 73  tic functions, s
34540 6f 20 75 73 65 0a 2a 2a 20 6f 66 20 74 68 65 20  o use.** of the 
34550 5b 53 51 4c 49 54 45 5f 44 45 54 45 52 4d 49 4e  [SQLITE_DETERMIN
34560 49 53 54 49 43 5d 20 66 6c 61 67 20 69 73 20 72  ISTIC] flag is r
34570 65 63 6f 6d 6d 65 6e 64 65 64 20 77 68 65 72 65  ecommended where
34580 20 70 6f 73 73 69 62 6c 65 2e 0a 2a 2a 0a 2a 2a   possible..**.**
34590 20 5e 28 54 68 65 20 66 69 66 74 68 20 70 61 72   ^(The fifth par
345a0 61 6d 65 74 65 72 20 69 73 20 61 6e 20 61 72 62  ameter is an arb
345b0 69 74 72 61 72 79 20 70 6f 69 6e 74 65 72 2e 20  itrary pointer. 
345c0 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   The implementat
345d0 69 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 66 75  ion of the.** fu
345e0 6e 63 74 69 6f 6e 20 63 61 6e 20 67 61 69 6e 20  nction can gain 
345f0 61 63 63 65 73 73 20 74 6f 20 74 68 69 73 20 70  access to this p
34600 6f 69 6e 74 65 72 20 75 73 69 6e 67 20 5b 73 71  ointer using [sq
34610 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28  lite3_user_data(
34620 29 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  )].)^.**.** ^The
34630 20 73 69 78 74 68 2c 20 73 65 76 65 6e 74 68 20   sixth, seventh 
34640 61 6e 64 20 65 69 67 68 74 68 20 70 61 72 61 6d  and eighth param
34650 65 74 65 72 73 2c 20 78 46 75 6e 63 2c 20 78 53  eters, xFunc, xS
34660 74 65 70 20 61 6e 64 20 78 46 69 6e 61 6c 2c 20  tep and xFinal, 
34670 61 72 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 20  are.** pointers 
34680 74 6f 20 43 2d 6c 61 6e 67 75 61 67 65 20 66 75  to C-language fu
34690 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 69 6d 70  nctions that imp
346a0 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 66  lement the SQL f
346b0 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67  unction or.** ag
346c0 67 72 65 67 61 74 65 2e 20 5e 41 20 73 63 61 6c  gregate. ^A scal
346d0 61 72 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  ar SQL function 
346e0 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d 70 6c  requires an impl
346f0 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68  ementation of th
34700 65 20 78 46 75 6e 63 0a 2a 2a 20 63 61 6c 6c 62  e xFunc.** callb
34710 61 63 6b 20 6f 6e 6c 79 3b 20 4e 55 4c 4c 20 70  ack only; NULL p
34720 6f 69 6e 74 65 72 73 20 6d 75 73 74 20 62 65 20  ointers must be 
34730 70 61 73 73 65 64 20 61 73 20 74 68 65 20 78 53  passed as the xS
34740 74 65 70 20 61 6e 64 20 78 46 69 6e 61 6c 0a 2a  tep and xFinal.*
34750 2a 20 70 61 72 61 6d 65 74 65 72 73 2e 20 5e 41  * parameters. ^A
34760 6e 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20  n aggregate SQL 
34770 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65  function require
34780 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74  s an implementat
34790 69 6f 6e 20 6f 66 20 78 53 74 65 70 0a 2a 2a 20  ion of xStep.** 
347a0 61 6e 64 20 78 46 69 6e 61 6c 20 61 6e 64 20 4e  and xFinal and N
347b0 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6d 75 73 74  ULL pointer must
347c0 20 62 65 20 70 61 73 73 65 64 20 66 6f 72 20 78   be passed for x
347d0 46 75 6e 63 2e 20 5e 54 6f 20 64 65 6c 65 74 65  Func. ^To delete
347e0 20 61 6e 20 65 78 69 73 74 69 6e 67 0a 2a 2a 20   an existing.** 
347f0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20  SQL function or 
34800 61 67 67 72 65 67 61 74 65 2c 20 70 61 73 73 20  aggregate, pass 
34810 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20 66 6f  NULL pointers fo
34820 72 20 61 6c 6c 20 74 68 72 65 65 20 66 75 6e 63  r all three func
34830 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b  tion.** callback
34840 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 74 68  s..**.** ^(If th
34850 65 20 6e 69 6e 74 68 20 70 61 72 61 6d 65 74 65  e ninth paramete
34860 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 72 65  r to sqlite3_cre
34870 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28  ate_function_v2(
34880 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 0a 2a  ) is not NULL,.*
34890 2a 20 74 68 65 6e 20 69 74 20 69 73 20 64 65 73  * then it is des
348a0 74 72 75 63 74 6f 72 20 66 6f 72 20 74 68 65 20  tructor for the 
348b0 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61  application data
348c0 20 70 6f 69 6e 74 65 72 2e 20 0a 2a 2a 20 54 68   pointer. .** Th
348d0 65 20 64 65 73 74 72 75 63 74 6f 72 20 69 73 20  e destructor is 
348e0 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 74 68 65  invoked when the
348f0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 64 65 6c   function is del
34900 65 74 65 64 2c 20 65 69 74 68 65 72 20 62 79 20  eted, either by 
34910 62 65 69 6e 67 0a 2a 2a 20 6f 76 65 72 6c 6f 61  being.** overloa
34920 64 65 64 20 6f 72 20 77 68 65 6e 20 74 68 65 20  ded or when the 
34930 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
34940 69 6f 6e 20 63 6c 6f 73 65 73 2e 29 5e 0a 2a 2a  ion closes.)^.**
34950 20 5e 54 68 65 20 64 65 73 74 72 75 63 74 6f 72   ^The destructor
34960 20 69 73 20 61 6c 73 6f 20 69 6e 76 6f 6b 65 64   is also invoked
34970 20 69 66 20 74 68 65 20 63 61 6c 6c 20 74 6f 0a   if the call to.
34980 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  ** sqlite3_creat
34990 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 20  e_function_v2() 
349a0 66 61 69 6c 73 2e 0a 2a 2a 20 5e 57 68 65 6e 20  fails..** ^When 
349b0 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 63  the destructor c
349c0 61 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65 20 74  allback of the t
349d0 65 6e 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  enth parameter i
349e0 73 20 69 6e 76 6f 6b 65 64 2c 20 69 74 0a 2a 2a  s invoked, it.**
349f0 20 69 73 20 70 61 73 73 65 64 20 61 20 73 69 6e   is passed a sin
34a00 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69  gle argument whi
34a10 63 68 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20  ch is a copy of 
34a20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
34a30 64 61 74 61 20 0a 2a 2a 20 70 6f 69 6e 74 65 72  data .** pointer
34a40 20 77 68 69 63 68 20 77 61 73 20 74 68 65 20 66   which was the f
34a50 69 66 74 68 20 70 61 72 61 6d 65 74 65 72 20 74  ifth parameter t
34a60 6f 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  o sqlite3_create
34a70 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 2e 0a  _function_v2()..
34a80 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20 70 65 72  **.** ^It is per
34a90 6d 69 74 74 65 64 20 74 6f 20 72 65 67 69 73 74  mitted to regist
34aa0 65 72 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c  er multiple impl
34ab0 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74  ementations of t
34ac0 68 65 20 73 61 6d 65 0a 2a 2a 20 66 75 6e 63 74  he same.** funct
34ad0 69 6f 6e 73 20 77 69 74 68 20 74 68 65 20 73 61  ions with the sa
34ae0 6d 65 20 6e 61 6d 65 20 62 75 74 20 77 69 74 68  me name but with
34af0 20 65 69 74 68 65 72 20 64 69 66 66 65 72 69 6e   either differin
34b00 67 20 6e 75 6d 62 65 72 73 20 6f 66 0a 2a 2a 20  g numbers of.** 
34b10 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 64 69 66  arguments or dif
34b20 66 65 72 69 6e 67 20 70 72 65 66 65 72 72 65 64  fering preferred
34b30 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 2e   text encodings.
34b40 20 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75    ^SQLite will u
34b50 73 65 0a 2a 2a 20 74 68 65 20 69 6d 70 6c 65 6d  se.** the implem
34b60 65 6e 74 61 74 69 6f 6e 20 74 68 61 74 20 6d 6f  entation that mo
34b70 73 74 20 63 6c 6f 73 65 6c 79 20 6d 61 74 63 68  st closely match
34b80 65 73 20 74 68 65 20 77 61 79 20 69 6e 20 77 68  es the way in wh
34b90 69 63 68 20 74 68 65 0a 2a 2a 20 53 51 4c 20 66  ich the.** SQL f
34ba0 75 6e 63 74 69 6f 6e 20 69 73 20 75 73 65 64 2e  unction is used.
34bb0 20 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 69 6d    ^A function im
34bc0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74  plementation wit
34bd0 68 20 61 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65  h a non-negative
34be0 0a 2a 2a 20 6e 41 72 67 20 70 61 72 61 6d 65 74  .** nArg paramet
34bf0 65 72 20 69 73 20 61 20 62 65 74 74 65 72 20 6d  er is a better m
34c00 61 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63  atch than a func
34c10 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74  tion implementat
34c20 69 6f 6e 20 77 69 74 68 0a 2a 2a 20 61 20 6e 65  ion with.** a ne
34c30 67 61 74 69 76 65 20 6e 41 72 67 2e 20 20 5e 41  gative nArg.  ^A
34c40 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20   function where 
34c50 74 68 65 20 70 72 65 66 65 72 72 65 64 20 74 65  the preferred te
34c60 78 74 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20 6d  xt encoding.** m
34c70 61 74 63 68 65 73 20 74 68 65 20 64 61 74 61 62  atches the datab
34c80 61 73 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20  ase encoding is 
34c90 61 20 62 65 74 74 65 72 0a 2a 2a 20 6d 61 74 63  a better.** matc
34ca0 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f  h than a functio
34cb0 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f  n where the enco
34cc0 64 69 6e 67 20 69 73 20 64 69 66 66 65 72 65 6e  ding is differen
34cd0 74 2e 20 20 0a 2a 2a 20 5e 41 20 66 75 6e 63 74  t.  .** ^A funct
34ce0 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e  ion where the en
34cf0 63 6f 64 69 6e 67 20 64 69 66 66 65 72 65 6e 63  coding differenc
34d00 65 20 69 73 20 62 65 74 77 65 65 6e 20 55 54 46  e is between UTF
34d10 31 36 6c 65 20 61 6e 64 20 55 54 46 31 36 62 65  16le and UTF16be
34d20 0a 2a 2a 20 69 73 20 61 20 63 6c 6f 73 65 72 20  .** is a closer 
34d30 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e  match than a fun
34d40 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20  ction where the 
34d50 65 6e 63 6f 64 69 6e 67 20 64 69 66 66 65 72 65  encoding differe
34d60 6e 63 65 20 69 73 0a 2a 2a 20 62 65 74 77 65 65  nce is.** betwee
34d70 6e 20 55 54 46 38 20 61 6e 64 20 55 54 46 31 36  n UTF8 and UTF16
34d80 2e 0a 2a 2a 0a 2a 2a 20 5e 42 75 69 6c 74 2d 69  ..**.** ^Built-i
34d90 6e 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20  n functions may 
34da0 62 65 20 6f 76 65 72 6c 6f 61 64 65 64 20 62 79  be overloaded by
34db0 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e   new application
34dc0 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
34dd0 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 61 70  ns..**.** ^An ap
34de0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
34df0 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 70 65  d function is pe
34e00 72 6d 69 74 74 65 64 20 74 6f 20 63 61 6c 6c 20  rmitted to call 
34e10 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20  other.** SQLite 
34e20 69 6e 74 65 72 66 61 63 65 73 2e 20 20 48 6f 77  interfaces.  How
34e30 65 76 65 72 2c 20 73 75 63 68 20 63 61 6c 6c 73  ever, such calls
34e40 20 6d 75 73 74 20 6e 6f 74 0a 2a 2a 20 63 6c 6f   must not.** clo
34e50 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  se the database 
34e60 63 6f 6e 6e 65 63 74 69 6f 6e 20 6e 6f 72 20 66  connection nor f
34e70 69 6e 61 6c 69 7a 65 20 6f 72 20 72 65 73 65 74  inalize or reset
34e80 20 74 68 65 20 70 72 65 70 61 72 65 64 0a 2a 2a   the prepared.**
34e90 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 77 68   statement in wh
34ea0 69 63 68 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  ich the function
34eb0 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a   is running..*/.
34ec0 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61  int sqlite3_crea
34ed0 74 65 5f 66 75 6e 63 74 69 6f 6e 28 0a 20 20 73  te_function(.  s
34ee0 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f  qlite3 *db,.  co
34ef0 6e 73 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 74  nst char *zFunct
34f00 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e  ionName,.  int n
34f10 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74  Arg,.  int eText
34f20 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70  Rep,.  void *pAp
34f30 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e  p,.  void (*xFun
34f40 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  c)(sqlite3_conte
34f50 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f  xt*,int,sqlite3_
34f60 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64  value**),.  void
34f70 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65   (*xStep)(sqlite
34f80 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73  3_context*,int,s
34f90 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c  qlite3_value**),
34fa0 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c  .  void (*xFinal
34fb0 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
34fc0 74 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  t*).);.int sqlit
34fd0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
34fe0 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74 65 33 20  on16(.  sqlite3 
34ff0 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 76 6f 69  *db,.  const voi
35000 64 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65  d *zFunctionName
35010 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20  ,.  int nArg,.  
35020 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20  int eTextRep,.  
35030 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f  void *pApp,.  vo
35040 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69  id (*xFunc)(sqli
35050 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74  te3_context*,int
35060 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a  ,sqlite3_value**
35070 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65  ),.  void (*xSte
35080 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  p)(sqlite3_conte
35090 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f  xt*,int,sqlite3_
350a0 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64  value**),.  void
350b0 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74   (*xFinal)(sqlit
350c0 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a  e3_context*).);.
350d0 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61  int sqlite3_crea
350e0 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 0a  te_function_v2(.
350f0 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20    sqlite3 *db,. 
35100 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 75   const char *zFu
35110 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e  nctionName,.  in
35120 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54  t nArg,.  int eT
35130 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a  extRep,.  void *
35140 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78  pApp,.  void (*x
35150 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f  Func)(sqlite3_co
35160 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74  ntext*,int,sqlit
35170 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76  e3_value**),.  v
35180 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c  oid (*xStep)(sql
35190 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e  ite3_context*,in
351a0 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t,sqlite3_value*
351b0 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69  *),.  void (*xFi
351c0 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  nal)(sqlite3_con
351d0 74 65 78 74 2a 29 2c 0a 20 20 76 6f 69 64 28 2a  text*),.  void(*
351e0 78 44 65 73 74 72 6f 79 29 28 76 6f 69 64 2a 29  xDestroy)(void*)
351f0 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
35200 52 45 46 3a 20 54 65 78 74 20 45 6e 63 6f 64 69  REF: Text Encodi
35210 6e 67 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ngs.**.** These 
35220 63 6f 6e 73 74 61 6e 74 20 64 65 66 69 6e 65 20  constant define 
35230 69 6e 74 65 67 65 72 20 63 6f 64 65 73 20 74 68  integer codes th
35240 61 74 20 72 65 70 72 65 73 65 6e 74 20 74 68 65  at represent the
35250 20 76 61 72 69 6f 75 73 0a 2a 2a 20 74 65 78 74   various.** text
35260 20 65 6e 63 6f 64 69 6e 67 73 20 73 75 70 70 6f   encodings suppo
35270 72 74 65 64 20 62 79 20 53 51 4c 69 74 65 2e 0a  rted by SQLite..
35280 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
35290 45 5f 55 54 46 38 20 20 20 20 20 20 20 20 20 20  E_UTF8          
352a0 20 31 20 20 20 20 2f 2a 20 49 4d 50 3a 20 52 2d   1    /* IMP: R-
352b0 33 37 35 31 34 2d 33 35 35 36 36 20 2a 2f 0a 23  37514-35566 */.#
352c0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54  define SQLITE_UT
352d0 46 31 36 4c 45 20 20 20 20 20 20 20 20 32 20 20  F16LE        2  
352e0 20 20 2f 2a 20 49 4d 50 3a 20 52 2d 30 33 33 37    /* IMP: R-0337
352f0 31 2d 33 37 36 33 37 20 2a 2f 0a 23 64 65 66 69  1-37637 */.#defi
35300 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 42  ne SQLITE_UTF16B
35310 45 20 20 20 20 20 20 20 20 33 20 20 20 20 2f 2a  E        3    /*
35320 20 49 4d 50 3a 20 52 2d 35 31 39 37 31 2d 33 34   IMP: R-51971-34
35330 31 35 34 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  154 */.#define S
35340 51 4c 49 54 45 5f 55 54 46 31 36 20 20 20 20 20  QLITE_UTF16     
35350 20 20 20 20 20 34 20 20 20 20 2f 2a 20 55 73 65       4    /* Use
35360 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
35370 65 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  er */.#define SQ
35380 4c 49 54 45 5f 41 4e 59 20 20 20 20 20 20 20 20  LITE_ANY        
35390 20 20 20 20 35 20 20 20 20 2f 2a 20 44 65 70 72      5    /* Depr
353a0 65 63 61 74 65 64 20 2a 2f 0a 23 64 65 66 69 6e  ecated */.#defin
353b0 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41  e SQLITE_UTF16_A
353c0 4c 49 47 4e 45 44 20 20 38 20 20 20 20 2f 2a 20  LIGNED  8    /* 
353d0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
353e0 6f 6c 6c 61 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f  ollation only */
353f0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
35400 3a 20 46 75 6e 63 74 69 6f 6e 20 46 6c 61 67 73  : Function Flags
35410 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e  .**.** These con
35420 73 74 61 6e 74 73 20 6d 61 79 20 62 65 20 4f 52  stants may be OR
35430 65 64 20 74 6f 67 65 74 68 65 72 20 77 69 74 68  ed together with
35440 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45   the .** [SQLITE
35450 5f 55 54 46 38 20 7c 20 70 72 65 66 65 72 72 65  _UTF8 | preferre
35460 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 5d  d text encoding]
35470 20 61 73 20 74 68 65 20 66 6f 75 72 74 68 20 61   as the fourth a
35480 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 5b 73  rgument.** to [s
35490 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
354a0 6e 63 74 69 6f 6e 28 29 5d 2c 20 5b 73 71 6c 69  nction()], [sqli
354b0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
354c0 69 6f 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20  ion16()], or.** 
354d0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
354e0 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 5d 2e 0a  function_v2()]..
354f0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
35500 45 5f 44 45 54 45 52 4d 49 4e 49 53 54 49 43 20  E_DETERMINISTIC 
35510 20 20 20 30 78 38 30 30 0a 0a 2f 2a 0a 2a 2a 20     0x800../*.** 
35520 43 41 50 49 33 52 45 46 3a 20 44 65 70 72 65 63  CAPI3REF: Deprec
35530 61 74 65 64 20 46 75 6e 63 74 69 6f 6e 73 0a 2a  ated Functions.*
35540 2a 20 44 45 50 52 45 43 41 54 45 44 0a 2a 2a 0a  * DEPRECATED.**.
35550 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f  ** These functio
35560 6e 73 20 61 72 65 20 5b 64 65 70 72 65 63 61 74  ns are [deprecat
35570 65 64 5d 2e 20 20 49 6e 20 6f 72 64 65 72 20 74  ed].  In order t
35580 6f 20 6d 61 69 6e 74 61 69 6e 0a 2a 2a 20 62 61  o maintain.** ba
35590 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62  ckwards compatib
355a0 69 6c 69 74 79 20 77 69 74 68 20 6f 6c 64 65 72  ility with older
355b0 20 63 6f 64 65 2c 20 74 68 65 73 65 20 66 75 6e   code, these fun
355c0 63 74 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20  ctions continue 
355d0 0a 2a 2a 20 74 6f 20 62 65 20 73 75 70 70 6f 72  .** to be suppor
355e0 74 65 64 2e 20 20 48 6f 77 65 76 65 72 2c 20 6e  ted.  However, n
355f0 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  ew applications 
35600 73 68 6f 75 6c 64 20 61 76 6f 69 64 0a 2a 2a 20  should avoid.** 
35610 74 68 65 20 75 73 65 20 6f 66 20 74 68 65 73 65  the use of these
35620 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 6f 20   functions.  To 
35630 65 6e 63 6f 75 72 61 67 65 20 70 72 6f 67 72 61  encourage progra
35640 6d 6d 65 72 73 20 74 6f 20 61 76 6f 69 64 0a 2a  mmers to avoid.*
35650 2a 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  * these function
35660 73 2c 20 77 65 20 77 69 6c 6c 20 6e 6f 74 20 65  s, we will not e
35670 78 70 6c 61 69 6e 20 77 68 61 74 20 74 68 65 79  xplain what they
35680 20 64 6f 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20   do..*/.#ifndef 
35690 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 44 45 50 52  SQLITE_OMIT_DEPR
356a0 45 43 41 54 45 44 0a 53 51 4c 49 54 45 5f 44 45  ECATED.SQLITE_DE
356b0 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c  PRECATED int sql
356c0 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
356d0 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e  ount(sqlite3_con
356e0 74 65 78 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44  text*);.SQLITE_D
356f0 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71  EPRECATED int sq
35700 6c 69 74 65 33 5f 65 78 70 69 72 65 64 28 73 71  lite3_expired(sq
35710 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51  lite3_stmt*);.SQ
35720 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20  LITE_DEPRECATED 
35730 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 72 61 6e  int sqlite3_tran
35740 73 66 65 72 5f 62 69 6e 64 69 6e 67 73 28 73 71  sfer_bindings(sq
35750 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 73 71 6c  lite3_stmt*, sql
35760 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c  ite3_stmt*);.SQL
35770 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69  ITE_DEPRECATED i
35780 6e 74 20 73 71 6c 69 74 65 33 5f 67 6c 6f 62 61  nt sqlite3_globa
35790 6c 5f 72 65 63 6f 76 65 72 28 76 6f 69 64 29 3b  l_recover(void);
357a0 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54  .SQLITE_DEPRECAT
357b0 45 44 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  ED void sqlite3_
357c0 74 68 72 65 61 64 5f 63 6c 65 61 6e 75 70 28 76  thread_cleanup(v
357d0 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50  oid);.SQLITE_DEP
357e0 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69  RECATED int sqli
357f0 74 65 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d  te3_memory_alarm
35800 28 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73  (void(*)(void*,s
35810 71 6c 69 74 65 33 5f 69 6e 74 36 34 2c 69 6e 74  qlite3_int64,int
35820 29 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20  ),.             
35830 20 20 20 20 20 20 20 20 20 76 6f 69 64 2a 2c 73           void*,s
35840 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 23  qlite3_int64);.#
35850 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  endif../*.** CAP
35860 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 69 6e 67  I3REF: Obtaining
35870 20 53 51 4c 20 56 61 6c 75 65 73 0a 2a 2a 20 4d   SQL Values.** M
35880 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 76  ETHOD: sqlite3_v
35890 61 6c 75 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43  alue.**.** The C
358a0 2d 6c 61 6e 67 75 61 67 65 20 69 6d 70 6c 65 6d  -language implem
358b0 65 6e 74 61 74 69 6f 6e 20 6f 66 20 53 51 4c 20  entation of SQL 
358c0 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67  functions and ag
358d0 67 72 65 67 61 74 65 73 20 75 73 65 73 0a 2a 2a  gregates uses.**
358e0 20 74 68 69 73 20 73 65 74 20 6f 66 20 69 6e 74   this set of int
358f0 65 72 66 61 63 65 20 72 6f 75 74 69 6e 65 73 20  erface routines 
35900 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 70 61  to access the pa
35910 72 61 6d 65 74 65 72 20 76 61 6c 75 65 73 20 6f  rameter values o
35920 6e 0a 2a 2a 20 74 68 65 20 66 75 6e 63 74 69 6f  n.** the functio
35930 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65 2e 20  n or aggregate. 
35940 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 75 6e   .**.** The xFun
35950 63 20 28 66 6f 72 20 73 63 61 6c 61 72 20 66 75  c (for scalar fu
35960 6e 63 74 69 6f 6e 73 29 20 6f 72 20 78 53 74 65  nctions) or xSte
35970 70 20 28 66 6f 72 20 61 67 67 72 65 67 61 74 65  p (for aggregate
35980 73 29 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a  s) parameters.**
35990 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65   to [sqlite3_cre
359a0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20  ate_function()] 
359b0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  and [sqlite3_cre
359c0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29  ate_function16()
359d0 5d 0a 2a 2a 20 64 65 66 69 6e 65 20 63 61 6c 6c  ].** define call
359e0 62 61 63 6b 73 20 74 68 61 74 20 69 6d 70 6c 65  backs that imple
359f0 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e  ment the SQL fun
35a00 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65  ctions and aggre
35a10 67 61 74 65 73 2e 0a 2a 2a 20 54 68 65 20 33 72  gates..** The 3r
35a20 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  d parameter to t
35a30 68 65 73 65 20 63 61 6c 6c 62 61 63 6b 73 20 69  hese callbacks i
35a40 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f  s an array of po
35a50 69 6e 74 65 72 73 20 74 6f 0a 2a 2a 20 5b 70 72  inters to.** [pr
35a60 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
35a70 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 20  value] objects. 
35a80 20 54 68 65 72 65 20 69 73 20 6f 6e 65 20 5b 73   There is one [s
35a90 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
35aa0 6a 65 63 74 20 66 6f 72 0a 2a 2a 20 65 61 63 68  ject for.** each
35ab0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
35ac0 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 20  e SQL function. 
35ad0 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
35ae0 61 72 65 20 75 73 65 64 20 74 6f 0a 2a 2a 20 65  are used to.** e
35af0 78 74 72 61 63 74 20 76 61 6c 75 65 73 20 66 72  xtract values fr
35b00 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  om the [sqlite3_
35b10 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a  value] objects..
35b20 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
35b30 69 6e 65 73 20 77 6f 72 6b 20 6f 6e 6c 79 20 77  ines work only w
35b40 69 74 68 20 5b 70 72 6f 74 65 63 74 65 64 20 73  ith [protected s
35b50 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
35b60 6a 65 63 74 73 2e 0a 2a 2a 20 41 6e 79 20 61 74  jects..** Any at
35b70 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68 65  tempt to use the
35b80 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e 20 61  se routines on a
35b90 6e 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73  n [unprotected s
35ba0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a  qlite3_value].**
35bb0 20 6f 62 6a 65 63 74 20 72 65 73 75 6c 74 73 20   object results 
35bc0 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68  in undefined beh
35bd0 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  avior..**.** ^Th
35be0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77 6f 72  ese routines wor
35bf0 6b 20 6a 75 73 74 20 6c 69 6b 65 20 74 68 65 20  k just like the 
35c00 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 5b 63  corresponding [c
35c10 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e  olumn access fun
35c20 63 74 69 6f 6e 73 5d 0a 2a 2a 20 65 78 63 65 70  ctions].** excep
35c30 74 20 74 68 61 74 20 74 68 65 73 65 20 72 6f 75  t that these rou
35c40 74 69 6e 65 73 20 74 61 6b 65 20 61 20 73 69 6e  tines take a sin
35c50 67 6c 65 20 5b 70 72 6f 74 65 63 74 65 64 20 73  gle [protected s
35c60 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
35c70 6a 65 63 74 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  ject.** pointer 
35c80 69 6e 73 74 65 61 64 20 6f 66 20 61 20 5b 73 71  instead of a [sq
35c90 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 20 70 6f 69  lite3_stmt*] poi
35ca0 6e 74 65 72 20 61 6e 64 20 61 6e 20 69 6e 74 65  nter and an inte
35cb0 67 65 72 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65  ger column numbe
35cc0 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  r..**.** ^The sq
35cd0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
35ce0 31 36 28 29 20 69 6e 74 65 72 66 61 63 65 20 65  16() interface e
35cf0 78 74 72 61 63 74 73 20 61 20 55 54 46 2d 31 36  xtracts a UTF-16
35d00 20 73 74 72 69 6e 67 0a 2a 2a 20 69 6e 20 74 68   string.** in th
35d10 65 20 6e 61 74 69 76 65 20 62 79 74 65 2d 6f 72  e native byte-or
35d20 64 65 72 20 6f 66 20 74 68 65 20 68 6f 73 74 20  der of the host 
35d30 6d 61 63 68 69 6e 65 2e 20 20 5e 54 68 65 0a 2a  machine.  ^The.*
35d40 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  * sqlite3_value_
35d50 74 65 78 74 31 36 62 65 28 29 20 61 6e 64 20 73  text16be() and s
35d60 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
35d70 74 31 36 6c 65 28 29 20 69 6e 74 65 72 66 61 63  t16le() interfac
35d80 65 73 0a 2a 2a 20 65 78 74 72 61 63 74 20 55 54  es.** extract UT
35d90 46 2d 31 36 20 73 74 72 69 6e 67 73 20 61 73 20  F-16 strings as 
35da0 62 69 67 2d 65 6e 64 69 61 6e 20 61 6e 64 20 6c  big-endian and l
35db0 69 74 74 6c 65 2d 65 6e 64 69 61 6e 20 72 65 73  ittle-endian res
35dc0 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a  pectively..**.**
35dd0 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33 5f 76   ^(The sqlite3_v
35de0 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70  alue_numeric_typ
35df0 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 61 74  e() interface at
35e00 74 65 6d 70 74 73 20 74 6f 20 61 70 70 6c 79 0a  tempts to apply.
35e10 2a 2a 20 6e 75 6d 65 72 69 63 20 61 66 66 69 6e  ** numeric affin
35e20 69 74 79 20 74 6f 20 74 68 65 20 76 61 6c 75 65  ity to the value
35e30 2e 20 20 54 68 69 73 20 6d 65 61 6e 73 20 74 68  .  This means th
35e40 61 74 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73  at an attempt is
35e50 0a 2a 2a 20 6d 61 64 65 20 74 6f 20 63 6f 6e 76  .** made to conv
35e60 65 72 74 20 74 68 65 20 76 61 6c 75 65 20 74 6f  ert the value to
35e70 20 61 6e 20 69 6e 74 65 67 65 72 20 6f 72 20 66   an integer or f
35e80 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 2e 20 20  loating point.  
35e90 49 66 0a 2a 2a 20 73 75 63 68 20 61 20 63 6f 6e  If.** such a con
35ea0 76 65 72 73 69 6f 6e 20 69 73 20 70 6f 73 73 69  version is possi
35eb0 62 6c 65 20 77 69 74 68 6f 75 74 20 6c 6f 73 73  ble without loss
35ec0 20 6f 66 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20   of information 
35ed0 28 69 6e 20 6f 74 68 65 72 0a 2a 2a 20 77 6f 72  (in other.** wor
35ee0 64 73 2c 20 69 66 20 74 68 65 20 76 61 6c 75 65  ds, if the value
35ef0 20 69 73 20 61 20 73 74 72 69 6e 67 20 74 68 61   is a string tha
35f00 74 20 6c 6f 6f 6b 73 20 6c 69 6b 65 20 61 20 6e  t looks like a n
35f10 75 6d 62 65 72 29 0a 2a 2a 20 74 68 65 6e 20 74  umber).** then t
35f20 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73  he conversion is
35f30 20 70 65 72 66 6f 72 6d 65 64 2e 20 20 4f 74 68   performed.  Oth
35f40 65 72 77 69 73 65 20 6e 6f 20 63 6f 6e 76 65 72  erwise no conver
35f50 73 69 6f 6e 20 6f 63 63 75 72 73 2e 0a 2a 2a 20  sion occurs..** 
35f60 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45  The [SQLITE_INTE
35f70 47 45 52 20 7c 20 64 61 74 61 74 79 70 65 5d 20  GER | datatype] 
35f80 61 66 74 65 72 20 63 6f 6e 76 65 72 73 69 6f 6e  after conversion
35f90 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 0a   is returned.)^.
35fa0 2a 2a 0a 2a 2a 20 50 6c 65 61 73 65 20 70 61 79  **.** Please pay
35fb0 20 70 61 72 74 69 63 75 6c 61 72 20 61 74 74 65   particular atte
35fc0 6e 74 69 6f 6e 20 74 6f 20 74 68 65 20 66 61 63  ntion to the fac
35fd0 74 20 74 68 61 74 20 74 68 65 20 70 6f 69 6e 74  t that the point
35fe0 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 66  er returned.** f
35ff0 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  rom [sqlite3_val
36000 75 65 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c  ue_blob()], [sql
36010 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28  ite3_value_text(
36020 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  )], or.** [sqlit
36030 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28  e3_value_text16(
36040 29 5d 20 63 61 6e 20 62 65 20 69 6e 76 61 6c 69  )] can be invali
36050 64 61 74 65 64 20 62 79 20 61 20 73 75 62 73 65  dated by a subse
36060 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a  quent call to.**
36070 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
36080 62 79 74 65 73 28 29 5d 2c 20 5b 73 71 6c 69 74  bytes()], [sqlit
36090 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36  e3_value_bytes16
360a0 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61  ()], [sqlite3_va
360b0 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20  lue_text()],.** 
360c0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  or [sqlite3_valu
360d0 65 5f 74 65 78 74 31 36 28 29 5d 2e 0a 2a 2a 0a  e_text16()]..**.
360e0 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
360f0 73 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64  s must be called
36100 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74   from the same t
36110 68 72 65 61 64 20 61 73 0a 2a 2a 20 74 68 65 20  hread as.** the 
36120 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 68 61  SQL function tha
36130 74 20 73 75 70 70 6c 69 65 64 20 74 68 65 20 5b  t supplied the [
36140 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 5d 20  sqlite3_value*] 
36150 70 61 72 61 6d 65 74 65 72 73 2e 0a 2a 2f 0a 63  parameters..*/.c
36160 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
36170 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 73 71  e3_value_blob(sq
36180 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69  lite3_value*);.i
36190 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt sqlite3_value
361a0 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f 76  _bytes(sqlite3_v
361b0 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69  alue*);.int sqli
361c0 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31  te3_value_bytes1
361d0 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  6(sqlite3_value*
361e0 29 3b 0a 64 6f 75 62 6c 65 20 73 71 6c 69 74 65  );.double sqlite
361f0 33 5f 76 61 6c 75 65 5f 64 6f 75 62 6c 65 28 73  3_value_double(s
36200 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
36210 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  int sqlite3_valu
36220 65 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 76 61  e_int(sqlite3_va
36230 6c 75 65 2a 29 3b 0a 73 71 6c 69 74 65 33 5f 69  lue*);.sqlite3_i
36240 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 76 61 6c  nt64 sqlite3_val
36250 75 65 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33  ue_int64(sqlite3
36260 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20  _value*);.const 
36270 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a 73  unsigned char *s
36280 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
36290 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t(sqlite3_value*
362a0 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
362b0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
362c0 74 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  t16(sqlite3_valu
362d0 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  e*);.const void 
362e0 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  *sqlite3_value_t
362f0 65 78 74 31 36 6c 65 28 73 71 6c 69 74 65 33 5f  ext16le(sqlite3_
36300 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76  value*);.const v
36310 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c  oid *sqlite3_val
36320 75 65 5f 74 65 78 74 31 36 62 65 28 73 71 6c 69  ue_text16be(sqli
36330 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74  te3_value*);.int
36340 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74   sqlite3_value_t
36350 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  ype(sqlite3_valu
36360 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  e*);.int sqlite3
36370 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74  _value_numeric_t
36380 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  ype(sqlite3_valu
36390 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  e*);../*.** CAPI
363a0 33 52 45 46 3a 20 46 69 6e 64 69 6e 67 20 54 68  3REF: Finding Th
363b0 65 20 53 75 62 74 79 70 65 20 4f 66 20 53 51 4c  e Subtype Of SQL
363c0 20 56 61 6c 75 65 73 0a 2a 2a 20 4d 45 54 48 4f   Values.** METHO
363d0 44 3a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  D: sqlite3_value
363e0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
363f0 65 33 5f 76 61 6c 75 65 5f 73 75 62 74 79 70 65  e3_value_subtype
36400 28 56 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74  (V) function ret
36410 75 72 6e 73 20 74 68 65 20 73 75 62 74 79 70 65  urns the subtype
36420 20 66 6f 72 0a 2a 2a 20 61 6e 20 5b 61 70 70 6c   for.** an [appl
36430 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
36440 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 20 61 72  SQL function] ar
36450 67 75 6d 65 6e 74 20 56 2e 20 20 54 68 65 20 73  gument V.  The s
36460 75 62 74 79 70 65 0a 2a 2a 20 69 6e 66 6f 72 6d  ubtype.** inform
36470 61 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65  ation can be use
36480 64 20 74 6f 20 70 61 73 73 20 61 20 6c 69 6d 69  d to pass a limi
36490 74 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 63 6f  ted amount of co
364a0 6e 74 65 78 74 20 66 72 6f 6d 0a 2a 2a 20 6f 6e  ntext from.** on
364b0 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74  e SQL function t
364c0 6f 20 61 6e 6f 74 68 65 72 2e 20 20 55 73 65 20  o another.  Use 
364d0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  the [sqlite3_res
364e0 75 6c 74 5f 73 75 62 74 79 70 65 28 29 5d 0a 2a  ult_subtype()].*
364f0 2a 20 72 6f 75 74 69 6e 65 20 74 6f 20 73 65 74  * routine to set
36500 20 74 68 65 20 73 75 62 74 79 70 65 20 66 6f 72   the subtype for
36510 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
36520 65 20 6f 66 20 61 6e 20 53 51 4c 20 66 75 6e 63  e of an SQL func
36530 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  tion..**.** SQLi
36540 74 65 20 6d 61 6b 65 73 20 6e 6f 20 75 73 65 20  te makes no use 
36550 6f 66 20 73 75 62 74 79 70 65 20 69 74 73 65 6c  of subtype itsel
36560 66 2e 20 20 49 74 20 6d 65 72 65 6c 79 20 70 61  f.  It merely pa
36570 73 73 65 73 20 74 68 65 20 73 75 62 74 79 70 65  sses the subtype
36580 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 72 65 73  .** from the res
36590 75 6c 74 20 6f 66 20 6f 6e 65 20 5b 61 70 70 6c  ult of one [appl
365a0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
365b0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 20 69 6e  SQL function] in
365c0 74 6f 20 74 68 65 0a 2a 2a 20 69 6e 70 75 74 20  to the.** input 
365d0 6f 66 20 61 6e 6f 74 68 65 72 2e 0a 2a 2f 0a 75  of another..*/.u
365e0 6e 73 69 67 6e 65 64 20 69 6e 74 20 73 71 6c 69  nsigned int sqli
365f0 74 65 33 5f 76 61 6c 75 65 5f 73 75 62 74 79 70  te3_value_subtyp
36600 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  e(sqlite3_value*
36610 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
36620 45 46 3a 20 43 6f 70 79 20 41 6e 64 20 46 72 65  EF: Copy And Fre
36630 65 20 53 51 4c 20 56 61 6c 75 65 73 0a 2a 2a 20  e SQL Values.** 
36640 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f  METHOD: sqlite3_
36650 76 61 6c 75 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  value.**.** ^The
36660 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64   sqlite3_value_d
36670 75 70 28 56 29 20 69 6e 74 65 72 66 61 63 65 20  up(V) interface 
36680 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20  makes a copy of 
36690 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  the [sqlite3_val
366a0 75 65 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 44 20  ue].** object D 
366b0 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f  and returns a po
366c0 69 6e 74 65 72 20 74 6f 20 74 68 61 74 20 63 6f  inter to that co
366d0 70 79 2e 20 20 5e 54 68 65 20 5b 73 71 6c 69 74  py.  ^The [sqlit
366e0 65 33 5f 76 61 6c 75 65 5d 20 72 65 74 75 72 6e  e3_value] return
366f0 65 64 0a 2a 2a 20 69 73 20 61 20 5b 70 72 6f 74  ed.** is a [prot
36700 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
36710 6c 75 65 5d 20 6f 62 6a 65 63 74 20 65 76 65 6e  lue] object even
36720 20 69 66 20 74 68 65 20 69 6e 70 75 74 20 69 73   if the input is
36730 20 6e 6f 74 2e 0a 2a 2a 20 5e 54 68 65 20 73 71   not..** ^The sq
36740 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 75 70 28  lite3_value_dup(
36750 56 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  V) interface ret
36760 75 72 6e 73 20 4e 55 4c 4c 20 69 66 20 56 20 69  urns NULL if V i
36770 73 20 4e 55 4c 4c 20 6f 72 20 69 66 20 61 0a 2a  s NULL or if a.*
36780 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  * memory allocat
36790 69 6f 6e 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a  ion fails..**.**
367a0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61   ^The sqlite3_va
367b0 6c 75 65 5f 66 72 65 65 28 56 29 20 69 6e 74 65  lue_free(V) inte
367c0 72 66 61 63 65 20 66 72 65 65 73 20 61 6e 20 5b  rface frees an [
367d0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
367e0 62 6a 65 63 74 0a 2a 2a 20 70 72 65 76 69 6f 75  bject.** previou
367f0 73 6c 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  sly obtained fro
36800 6d 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  m [sqlite3_value
36810 5f 64 75 70 28 29 5d 2e 20 20 5e 49 66 20 56 20  _dup()].  ^If V 
36820 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
36830 72 0a 2a 2a 20 74 68 65 6e 20 73 71 6c 69 74 65  r.** then sqlite
36840 33 5f 76 61 6c 75 65 5f 66 72 65 65 28 56 29 20  3_value_free(V) 
36850 69 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f  is a harmless no
36860 2d 6f 70 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f  -op..*/.sqlite3_
36870 76 61 6c 75 65 20 2a 73 71 6c 69 74 65 33 5f 76  value *sqlite3_v
36880 61 6c 75 65 5f 64 75 70 28 63 6f 6e 73 74 20 73  alue_dup(const s
36890 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
368a0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  void sqlite3_val
368b0 75 65 5f 66 72 65 65 28 73 71 6c 69 74 65 33 5f  ue_free(sqlite3_
368c0 76 61 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  value*);../*.** 
368d0 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e  CAPI3REF: Obtain
368e0 20 41 67 67 72 65 67 61 74 65 20 46 75 6e 63 74   Aggregate Funct
368f0 69 6f 6e 20 43 6f 6e 74 65 78 74 0a 2a 2a 20 4d  ion Context.** M
36900 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 63  ETHOD: sqlite3_c
36910 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20 49 6d 70  ontext.**.** Imp
36920 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20  lementations of 
36930 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75  aggregate SQL fu
36940 6e 63 74 69 6f 6e 73 20 75 73 65 20 74 68 69 73  nctions use this
36950 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 74 6f 20 61  .** routine to a
36960 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 66  llocate memory f
36970 6f 72 20 73 74 6f 72 69 6e 67 20 74 68 65 69 72  or storing their
36980 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54   state..**.** ^T
36990 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 74 68  he first time th
369a0 65 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67  e sqlite3_aggreg
369b0 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29  ate_context(C,N)
369c0 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c 6c   routine is call
369d0 65 64 20 0a 2a 2a 20 66 6f 72 20 61 20 70 61 72  ed .** for a par
369e0 74 69 63 75 6c 61 72 20 61 67 67 72 65 67 61 74  ticular aggregat
369f0 65 20 66 75 6e 63 74 69 6f 6e 2c 20 53 51 4c 69  e function, SQLi
36a00 74 65 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 73 20  te.** allocates 
36a10 4e 20 6f 66 20 6d 65 6d 6f 72 79 2c 20 7a 65 72  N of memory, zer
36a20 6f 65 73 20 6f 75 74 20 74 68 61 74 20 6d 65 6d  oes out that mem
36a30 6f 72 79 2c 20 61 6e 64 20 72 65 74 75 72 6e 73  ory, and returns
36a40 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f   a pointer.** to
36a50 20 74 68 65 20 6e 65 77 20 6d 65 6d 6f 72 79 2e   the new memory.
36a60 20 5e 4f 6e 20 73 65 63 6f 6e 64 20 61 6e 64 20   ^On second and 
36a70 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73  subsequent calls
36a80 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 61   to.** sqlite3_a
36a90 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
36aa0 28 29 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20  () for the same 
36ab0 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69  aggregate functi
36ac0 6f 6e 20 69 6e 73 74 61 6e 63 65 2c 0a 2a 2a 20  on instance,.** 
36ad0 74 68 65 20 73 61 6d 65 20 62 75 66 66 65 72 20  the same buffer 
36ae0 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 53 71  is returned.  Sq
36af0 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
36b00 63 6f 6e 74 65 78 74 28 29 20 69 73 20 6e 6f 72  context() is nor
36b10 6d 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20  mally.** called 
36b20 6f 6e 63 65 20 66 6f 72 20 65 61 63 68 20 69 6e  once for each in
36b30 76 6f 63 61 74 69 6f 6e 20 6f 66 20 74 68 65 20  vocation of the 
36b40 78 53 74 65 70 20 63 61 6c 6c 62 61 63 6b 20 61  xStep callback a
36b50 6e 64 20 74 68 65 6e 20 6f 6e 65 0a 2a 2a 20 6c  nd then one.** l
36b60 61 73 74 20 74 69 6d 65 20 77 68 65 6e 20 74 68  ast time when th
36b70 65 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63  e xFinal callbac
36b80 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20 5e  k is invoked.  ^
36b90 28 57 68 65 6e 20 6e 6f 20 72 6f 77 73 20 6d 61  (When no rows ma
36ba0 74 63 68 0a 2a 2a 20 61 6e 20 61 67 67 72 65 67  tch.** an aggreg
36bb0 61 74 65 20 71 75 65 72 79 2c 20 74 68 65 20 78  ate query, the x
36bc0 53 74 65 70 28 29 20 63 61 6c 6c 62 61 63 6b 20  Step() callback 
36bd0 6f 66 20 74 68 65 20 61 67 67 72 65 67 61 74 65  of the aggregate
36be0 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 69 6d 70   function.** imp
36bf0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 6e  lementation is n
36c00 65 76 65 72 20 63 61 6c 6c 65 64 20 61 6e 64 20  ever called and 
36c10 78 46 69 6e 61 6c 28 29 20 69 73 20 63 61 6c 6c  xFinal() is call
36c20 65 64 20 65 78 61 63 74 6c 79 20 6f 6e 63 65 2e  ed exactly once.
36c30 0a 2a 2a 20 49 6e 20 74 68 6f 73 65 20 63 61 73  .** In those cas
36c40 65 73 2c 20 73 71 6c 69 74 65 33 5f 61 67 67 72  es, sqlite3_aggr
36c50 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20  egate_context() 
36c60 6d 69 67 68 74 20 62 65 20 63 61 6c 6c 65 64 20  might be called 
36c70 66 6f 72 20 74 68 65 0a 2a 2a 20 66 69 72 73 74  for the.** first
36c80 20 74 69 6d 65 20 66 72 6f 6d 20 77 69 74 68 69   time from withi
36c90 6e 20 78 46 69 6e 61 6c 28 29 2e 29 5e 0a 2a 2a  n xFinal().)^.**
36ca0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
36cb0 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
36cc0 78 74 28 43 2c 4e 29 20 72 6f 75 74 69 6e 65 20  xt(C,N) routine 
36cd0 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70  returns a NULL p
36ce0 6f 69 6e 74 65 72 20 0a 2a 2a 20 77 68 65 6e 20  ointer .** when 
36cf0 66 69 72 73 74 20 63 61 6c 6c 65 64 20 69 66 20  first called if 
36d00 4e 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 6f  N is less than o
36d10 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 20  r equal to zero 
36d20 6f 72 20 69 66 20 61 20 6d 65 6d 6f 72 79 0a 2a  or if a memory.*
36d30 2a 20 61 6c 6c 6f 63 61 74 65 20 65 72 72 6f 72  * allocate error
36d40 20 6f 63 63 75 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e   occurs..**.** ^
36d50 28 54 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 73  (The amount of s
36d60 70 61 63 65 20 61 6c 6c 6f 63 61 74 65 64 20 62  pace allocated b
36d70 79 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67  y sqlite3_aggreg
36d80 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29  ate_context(C,N)
36d90 20 69 73 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 65   is.** determine
36da0 64 20 62 79 20 74 68 65 20 4e 20 70 61 72 61 6d  d by the N param
36db0 65 74 65 72 20 6f 6e 20 66 69 72 73 74 20 73 75  eter on first su
36dc0 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 2e 20 20  ccessful call.  
36dd0 43 68 61 6e 67 69 6e 67 20 74 68 65 0a 2a 2a 20  Changing the.** 
36de0 76 61 6c 75 65 20 6f 66 20 4e 20 69 6e 20 73 75  value of N in su
36df0 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f  bsequent call to
36e00 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   sqlite3_aggrega
36e10 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 77 69 74  te_context() wit
36e20 68 69 6e 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20  hin.** the same 
36e30 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69  aggregate functi
36e40 6f 6e 20 69 6e 73 74 61 6e 63 65 20 77 69 6c 6c  on instance will
36e50 20 6e 6f 74 20 72 65 73 69 7a 65 20 74 68 65 20   not resize the 
36e60 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61  memory.** alloca
36e70 74 69 6f 6e 2e 29 5e 20 20 57 69 74 68 69 6e 20  tion.)^  Within 
36e80 74 68 65 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62  the xFinal callb
36e90 61 63 6b 2c 20 69 74 20 69 73 20 63 75 73 74 6f  ack, it is custo
36ea0 6d 61 72 79 20 74 6f 20 73 65 74 0a 2a 2a 20 4e  mary to set.** N
36eb0 3d 30 20 69 6e 20 63 61 6c 6c 73 20 74 6f 20 73  =0 in calls to s
36ec0 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
36ed0 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 73 6f  _context(C,N) so
36ee0 20 74 68 61 74 20 6e 6f 20 0a 2a 2a 20 70 6f 69   that no .** poi
36ef0 6e 74 6c 65 73 73 20 6d 65 6d 6f 72 79 20 61 6c  ntless memory al
36f00 6c 6f 63 61 74 69 6f 6e 73 20 6f 63 63 75 72 2e  locations occur.
36f10 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 61  .**.** ^SQLite a
36f20 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 66 72 65  utomatically fre
36f30 65 73 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c  es the memory al
36f40 6c 6f 63 61 74 65 64 20 62 79 20 0a 2a 2a 20 73  located by .** s
36f50 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
36f60 5f 63 6f 6e 74 65 78 74 28 29 20 77 68 65 6e 20  _context() when 
36f70 74 68 65 20 61 67 67 72 65 67 61 74 65 20 71 75  the aggregate qu
36f80 65 72 79 20 63 6f 6e 63 6c 75 64 65 73 2e 0a 2a  ery concludes..*
36f90 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70  *.** The first p
36fa0 61 72 61 6d 65 74 65 72 20 6d 75 73 74 20 62 65  arameter must be
36fb0 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a   a copy of the.*
36fc0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  * [sqlite3_conte
36fd0 78 74 20 7c 20 53 51 4c 20 66 75 6e 63 74 69 6f  xt | SQL functio
36fe0 6e 20 63 6f 6e 74 65 78 74 5d 20 74 68 61 74 20  n context] that 
36ff0 69 73 20 74 68 65 20 66 69 72 73 74 20 70 61 72  is the first par
37000 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65  ameter.** to the
37010 20 78 53 74 65 70 20 6f 72 20 78 46 69 6e 61 6c   xStep or xFinal
37020 20 63 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e   callback routin
37030 65 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74  e that implement
37040 73 20 74 68 65 20 61 67 67 72 65 67 61 74 65 0a  s the aggregate.
37050 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a  ** function..**.
37060 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  ** This routine 
37070 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66  must be called f
37080 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72  rom the same thr
37090 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20  ead in which.** 
370a0 74 68 65 20 61 67 67 72 65 67 61 74 65 20 53 51  the aggregate SQ
370b0 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75  L function is ru
370c0 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a  nning..*/.void *
370d0 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
370e0 65 5f 63 6f 6e 74 65 78 74 28 73 71 6c 69 74 65  e_context(sqlite
370f0 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20  3_context*, int 
37100 6e 42 79 74 65 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20  nBytes);../*.** 
37110 43 41 50 49 33 52 45 46 3a 20 55 73 65 72 20 44  CAPI3REF: User D
37120 61 74 61 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e  ata For Function
37130 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  s.** METHOD: sql
37140 69 74 65 33 5f 63 6f 6e 74 65 78 74 0a 2a 2a 0a  ite3_context.**.
37150 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
37160 75 73 65 72 5f 64 61 74 61 28 29 20 69 6e 74 65  user_data() inte
37170 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20  rface returns a 
37180 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70  copy of.** the p
37190 6f 69 6e 74 65 72 20 74 68 61 74 20 77 61 73 20  ointer that was 
371a0 74 68 65 20 70 55 73 65 72 44 61 74 61 20 70 61  the pUserData pa
371b0 72 61 6d 65 74 65 72 20 28 74 68 65 20 35 74 68  rameter (the 5th
371c0 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f   parameter).** o
371d0 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  f the [sqlite3_c
371e0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29  reate_function()
371f0 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65  ].** and [sqlite
37200 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
37210 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20  n16()] routines 
37220 74 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a  that originally.
37230 2a 2a 20 72 65 67 69 73 74 65 72 65 64 20 74 68  ** registered th
37240 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65  e application de
37250 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a  fined function..
37260 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69  **.** This routi
37270 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65  ne must be calle
37280 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20  d from the same 
37290 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a  thread in which.
372a0 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ** the applicati
372b0 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
372c0 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a  ion is running..
372d0 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  */.void *sqlite3
372e0 5f 75 73 65 72 5f 64 61 74 61 28 73 71 6c 69 74  _user_data(sqlit
372f0 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f  e3_context*);../
37300 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
37310 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69  atabase Connecti
37320 6f 6e 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73  on For Functions
37330 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
37340 74 65 33 5f 63 6f 6e 74 65 78 74 0a 2a 2a 0a 2a  te3_context.**.*
37350 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63  * ^The sqlite3_c
37360 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65  ontext_db_handle
37370 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  () interface ret
37380 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a  urns a copy of.*
37390 2a 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74 6f  * the pointer to
373a0 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
373b0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 74 68 65 20  onnection] (the 
373c0 31 73 74 20 70 61 72 61 6d 65 74 65 72 29 0a 2a  1st parameter).*
373d0 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  * of the [sqlite
373e0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
373f0 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c  n()].** and [sql
37400 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
37410 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e  tion16()] routin
37420 65 73 20 74 68 61 74 20 6f 72 69 67 69 6e 61 6c  es that original
37430 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64  ly.** registered
37440 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
37450 20 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f   defined functio
37460 6e 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 20 2a 73  n..*/.sqlite3 *s
37470 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64  qlite3_context_d
37480 62 5f 68 61 6e 64 6c 65 28 73 71 6c 69 74 65 33  b_handle(sqlite3
37490 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a  _context*);../*.
374a0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e  ** CAPI3REF: Fun
374b0 63 74 69 6f 6e 20 41 75 78 69 6c 69 61 72 79 20  ction Auxiliary 
374c0 44 61 74 61 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  Data.** METHOD: 
374d0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 0a  sqlite3_context.
374e0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63  **.** These func
374f0 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 75 73 65  tions may be use
37500 64 20 62 79 20 28 6e 6f 6e 2d 61 67 67 72 65 67  d by (non-aggreg
37510 61 74 65 29 20 53 51 4c 20 66 75 6e 63 74 69 6f  ate) SQL functio
37520 6e 73 20 74 6f 0a 2a 2a 20 61 73 73 6f 63 69 61  ns to.** associa
37530 74 65 20 6d 65 74 61 64 61 74 61 20 77 69 74 68  te metadata with
37540 20 61 72 67 75 6d 65 6e 74 20 76 61 6c 75 65 73   argument values
37550 2e 20 49 66 20 74 68 65 20 73 61 6d 65 20 76 61  . If the same va
37560 6c 75 65 20 69 73 20 70 61 73 73 65 64 20 74 6f  lue is passed to
37570 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65 20 69 6e 76  .** multiple inv
37580 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20  ocations of the 
37590 73 61 6d 65 20 53 51 4c 20 66 75 6e 63 74 69 6f  same SQL functio
375a0 6e 20 64 75 72 69 6e 67 20 71 75 65 72 79 20 65  n during query e
375b0 78 65 63 75 74 69 6f 6e 2c 20 75 6e 64 65 72 0a  xecution, under.
375c0 2a 2a 20 73 6f 6d 65 20 63 69 72 63 75 6d 73 74  ** some circumst
375d0 61 6e 63 65 73 20 74 68 65 20 61 73 73 6f 63 69  ances the associ
375e0 61 74 65 64 20 6d 65 74 61 64 61 74 61 20 6d 61  ated metadata ma
375f0 79 20 62 65 20 70 72 65 73 65 72 76 65 64 2e 20  y be preserved. 
37600 20 41 6e 20 65 78 61 6d 70 6c 65 0a 2a 2a 20 6f   An example.** o
37610 66 20 77 68 65 72 65 20 74 68 69 73 20 6d 69 67  f where this mig
37620 68 74 20 62 65 20 75 73 65 66 75 6c 20 69 73 20  ht be useful is 
37630 69 6e 20 61 20 72 65 67 75 6c 61 72 2d 65 78 70  in a regular-exp
37640 72 65 73 73 69 6f 6e 20 6d 61 74 63 68 69 6e 67  ression matching
37650 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 20 54 68  .** function. Th
37660 65 20 63 6f 6d 70 69 6c 65 64 20 76 65 72 73 69  e compiled versi
37670 6f 6e 20 6f 66 20 74 68 65 20 72 65 67 75 6c 61  on of the regula
37680 72 20 65 78 70 72 65 73 73 69 6f 6e 20 63 61 6e  r expression can
37690 20 62 65 20 73 74 6f 72 65 64 20 61 73 0a 2a 2a   be stored as.**
376a0 20 6d 65 74 61 64 61 74 61 20 61 73 73 6f 63 69   metadata associ
376b0 61 74 65 64 20 77 69 74 68 20 74 68 65 20 70 61  ated with the pa
376c0 74 74 65 72 6e 20 73 74 72 69 6e 67 2e 20 20 0a  ttern string.  .
376d0 2a 2a 20 54 68 65 6e 20 61 73 20 6c 6f 6e 67 20  ** Then as long 
376e0 61 73 20 74 68 65 20 70 61 74 74 65 72 6e 20 73  as the pattern s
376f0 74 72 69 6e 67 20 72 65 6d 61 69 6e 73 20 74 68  tring remains th
37700 65 20 73 61 6d 65 2c 0a 2a 2a 20 74 68 65 20 63  e same,.** the c
37710 6f 6d 70 69 6c 65 64 20 72 65 67 75 6c 61 72 20  ompiled regular 
37720 65 78 70 72 65 73 73 69 6f 6e 20 63 61 6e 20 62  expression can b
37730 65 20 72 65 75 73 65 64 20 6f 6e 20 6d 75 6c 74  e reused on mult
37740 69 70 6c 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69  iple.** invocati
37750 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20  ons of the same 
37760 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  function..**.** 
37770 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74  ^The sqlite3_get
37780 5f 61 75 78 64 61 74 61 28 29 20 69 6e 74 65 72  _auxdata() inter
37790 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70  face returns a p
377a0 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65  ointer to the me
377b0 74 61 64 61 74 61 0a 2a 2a 20 61 73 73 6f 63 69  tadata.** associ
377c0 61 74 65 64 20 62 79 20 74 68 65 20 73 71 6c 69  ated by the sqli
377d0 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28  te3_set_auxdata(
377e0 29 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20  ) function with 
377f0 74 68 65 20 4e 74 68 20 61 72 67 75 6d 65 6e 74  the Nth argument
37800 0a 2a 2a 20 76 61 6c 75 65 20 74 6f 20 74 68 65  .** value to the
37810 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
37820 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20 5e  ined function. ^
37830 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20 6d  If there is no m
37840 65 74 61 64 61 74 61 0a 2a 2a 20 61 73 73 6f 63  etadata.** assoc
37850 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20 66  iated with the f
37860 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74  unction argument
37870 2c 20 74 68 69 73 20 73 71 6c 69 74 65 33 5f 67  , this sqlite3_g
37880 65 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e 74  et_auxdata() int
37890 65 72 66 61 63 65 0a 2a 2a 20 72 65 74 75 72 6e  erface.** return
378a0 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
378b0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
378c0 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
378d0 28 43 2c 4e 2c 50 2c 58 29 20 69 6e 74 65 72 66  (C,N,P,X) interf
378e0 61 63 65 20 73 61 76 65 73 20 50 20 61 73 20 6d  ace saves P as m
378f0 65 74 61 64 61 74 61 20 66 6f 72 20 74 68 65 20  etadata for the 
37900 4e 2d 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  N-th.** argument
37910 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74   of the applicat
37920 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
37930 74 69 6f 6e 2e 20 20 5e 53 75 62 73 65 71 75 65  tion.  ^Subseque
37940 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73  nt.** calls to s
37950 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61  qlite3_get_auxda
37960 74 61 28 43 2c 4e 29 20 72 65 74 75 72 6e 20 50  ta(C,N) return P
37970 20 66 72 6f 6d 20 74 68 65 20 6d 6f 73 74 20 72   from the most r
37980 65 63 65 6e 74 0a 2a 2a 20 73 71 6c 69 74 65 33  ecent.** sqlite3
37990 5f 73 65 74 5f 61 75 78 64 61 74 61 28 43 2c 4e  _set_auxdata(C,N
379a0 2c 50 2c 58 29 20 63 61 6c 6c 20 69 66 20 74 68  ,P,X) call if th
379b0 65 20 6d 65 74 61 64 61 74 61 20 69 73 20 73 74  e metadata is st
379c0 69 6c 6c 20 76 61 6c 69 64 20 6f 72 0a 2a 2a 20  ill valid or.** 
379d0 4e 55 4c 4c 20 69 66 20 74 68 65 20 6d 65 74 61  NULL if the meta
379e0 64 61 74 61 20 68 61 73 20 62 65 65 6e 20 64 69  data has been di
379f0 73 63 61 72 64 65 64 2e 0a 2a 2a 20 5e 41 66 74  scarded..** ^Aft
37a00 65 72 20 65 61 63 68 20 63 61 6c 6c 20 74 6f 20  er each call to 
37a10 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
37a20 61 74 61 28 43 2c 4e 2c 50 2c 58 29 20 77 68 65  ata(C,N,P,X) whe
37a30 72 65 20 58 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  re X is not NULL
37a40 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c  ,.** SQLite will
37a50 20 69 6e 76 6f 6b 65 20 74 68 65 20 64 65 73 74   invoke the dest
37a60 72 75 63 74 6f 72 20 66 75 6e 63 74 69 6f 6e 20  ructor function 
37a70 58 20 77 69 74 68 20 70 61 72 61 6d 65 74 65 72  X with parameter
37a80 20 50 20 65 78 61 63 74 6c 79 0a 2a 2a 20 6f 6e   P exactly.** on
37a90 63 65 2c 20 77 68 65 6e 20 74 68 65 20 6d 65 74  ce, when the met
37aa0 61 64 61 74 61 20 69 73 20 64 69 73 63 61 72 64  adata is discard
37ab0 65 64 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 69 73  ed..** SQLite is
37ac0 20 66 72 65 65 20 74 6f 20 64 69 73 63 61 72 64   free to discard
37ad0 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 61 74   the metadata at
37ae0 20 61 6e 79 20 74 69 6d 65 2c 20 69 6e 63 6c 75   any time, inclu
37af0 64 69 6e 67 3a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  ding: <ul>.** <l
37b00 69 3e 20 77 68 65 6e 20 74 68 65 20 63 6f 72 72  i> when the corr
37b10 65 73 70 6f 6e 64 69 6e 67 20 66 75 6e 63 74 69  esponding functi
37b20 6f 6e 20 70 61 72 61 6d 65 74 65 72 20 63 68 61  on parameter cha
37b30 6e 67 65 73 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e  nges, or.** <li>
37b40 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72   when [sqlite3_r
37b50 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69  eset()] or [sqli
37b60 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
37b70 69 73 20 63 61 6c 6c 65 64 20 66 6f 72 20 74 68  is called for th
37b80 65 0a 2a 2a 20 20 20 20 20 20 53 51 4c 20 73 74  e.**      SQL st
37b90 61 74 65 6d 65 6e 74 2c 20 6f 72 0a 2a 2a 20 3c  atement, or.** <
37ba0 6c 69 3e 20 77 68 65 6e 20 73 71 6c 69 74 65 33  li> when sqlite3
37bb0 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 69  _set_auxdata() i
37bc0 73 20 69 6e 76 6f 6b 65 64 20 61 67 61 69 6e 20  s invoked again 
37bd0 6f 6e 20 74 68 65 20 73 61 6d 65 20 70 61 72 61  on the same para
37be0 6d 65 74 65 72 2c 20 6f 72 0a 2a 2a 20 3c 6c 69  meter, or.** <li
37bf0 3e 20 64 75 72 69 6e 67 20 74 68 65 20 6f 72 69  > during the ori
37c00 67 69 6e 61 6c 20 73 71 6c 69 74 65 33 5f 73 65  ginal sqlite3_se
37c10 74 5f 61 75 78 64 61 74 61 28 29 20 63 61 6c 6c  t_auxdata() call
37c20 20 77 68 65 6e 20 61 20 6d 65 6d 6f 72 79 20 0a   when a memory .
37c30 2a 2a 20 20 20 20 20 20 61 6c 6c 6f 63 61 74 69  **      allocati
37c40 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e  on error occurs.
37c50 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 4e   </ul>)^.**.** N
37c60 6f 74 65 20 74 68 65 20 6c 61 73 74 20 62 75 6c  ote the last bul
37c70 6c 65 74 20 69 6e 20 70 61 72 74 69 63 75 6c 61  let in particula
37c80 72 2e 20 20 54 68 65 20 64 65 73 74 72 75 63 74  r.  The destruct
37c90 6f 72 20 58 20 69 6e 20 0a 2a 2a 20 73 71 6c 69  or X in .** sqli
37ca0 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28  te3_set_auxdata(
37cb0 43 2c 4e 2c 50 2c 58 29 20 6d 69 67 68 74 20 62  C,N,P,X) might b
37cc0 65 20 63 61 6c 6c 65 64 20 69 6d 6d 65 64 69 61  e called immedia
37cd0 74 65 6c 79 2c 20 62 65 66 6f 72 65 20 74 68 65  tely, before the
37ce0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 65 74 5f  .** sqlite3_set_
37cf0 61 75 78 64 61 74 61 28 29 20 69 6e 74 65 72 66  auxdata() interf
37d00 61 63 65 20 65 76 65 6e 20 72 65 74 75 72 6e 73  ace even returns
37d10 2e 20 20 48 65 6e 63 65 20 73 71 6c 69 74 65 33  .  Hence sqlite3
37d20 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 0a 2a  _set_auxdata().*
37d30 2a 20 73 68 6f 75 6c 64 20 62 65 20 63 61 6c 6c  * should be call
37d40 65 64 20 6e 65 61 72 20 74 68 65 20 65 6e 64 20  ed near the end 
37d50 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  of the function 
37d60 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 61  implementation a
37d70 6e 64 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69  nd the.** functi
37d80 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  on implementatio
37d90 6e 20 73 68 6f 75 6c 64 20 6e 6f 74 20 6d 61 6b  n should not mak
37da0 65 20 61 6e 79 20 75 73 65 20 6f 66 20 50 20 61  e any use of P a
37db0 66 74 65 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  fter.** sqlite3_
37dc0 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 68 61  set_auxdata() ha
37dd0 73 20 62 65 65 6e 20 63 61 6c 6c 65 64 2e 0a 2a  s been called..*
37de0 2a 0a 2a 2a 20 5e 28 49 6e 20 70 72 61 63 74 69  *.** ^(In practi
37df0 63 65 2c 20 6d 65 74 61 64 61 74 61 20 69 73 20  ce, metadata is 
37e00 70 72 65 73 65 72 76 65 64 20 62 65 74 77 65 65  preserved betwee
37e10 6e 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 73  n function calls
37e20 20 66 6f 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e   for.** function
37e30 20 70 61 72 61 6d 65 74 65 72 73 20 74 68 61 74   parameters that
37e40 20 61 72 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d   are compile-tim
37e50 65 20 63 6f 6e 73 74 61 6e 74 73 2c 20 69 6e 63  e constants, inc
37e60 6c 75 64 69 6e 67 20 6c 69 74 65 72 61 6c 0a 2a  luding literal.*
37e70 2a 20 76 61 6c 75 65 73 20 61 6e 64 20 5b 70 61  * values and [pa
37e80 72 61 6d 65 74 65 72 73 5d 20 61 6e 64 20 65 78  rameters] and ex
37e90 70 72 65 73 73 69 6f 6e 73 20 63 6f 6d 70 6f 73  pressions compos
37ea0 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65  ed from the same
37eb0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  .)^.**.** These 
37ec0 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65  routines must be
37ed0 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65   called from the
37ee0 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20   same thread in 
37ef0 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 53 51 4c  which.** the SQL
37f00 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e   function is run
37f10 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73  ning..*/.void *s
37f20 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61  qlite3_get_auxda
37f30 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ta(sqlite3_conte
37f40 78 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 76 6f 69  xt*, int N);.voi
37f50 64 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  d sqlite3_set_au
37f60 78 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f  xdata(sqlite3_co
37f70 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e 2c 20 76  ntext*, int N, v
37f80 6f 69 64 2a 2c 20 76 6f 69 64 20 28 2a 29 28 76  oid*, void (*)(v
37f90 6f 69 64 2a 29 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20  oid*));.../*.** 
37fa0 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 73 74 61  CAPI3REF: Consta
37fb0 6e 74 73 20 44 65 66 69 6e 69 6e 67 20 53 70 65  nts Defining Spe
37fc0 63 69 61 6c 20 44 65 73 74 72 75 63 74 6f 72 20  cial Destructor 
37fd0 42 65 68 61 76 69 6f 72 0a 2a 2a 0a 2a 2a 20 54  Behavior.**.** T
37fe0 68 65 73 65 20 61 72 65 20 73 70 65 63 69 61 6c  hese are special
37ff0 20 76 61 6c 75 65 73 20 66 6f 72 20 74 68 65 20   values for the 
38000 64 65 73 74 72 75 63 74 6f 72 20 74 68 61 74 20  destructor that 
38010 69 73 20 70 61 73 73 65 64 20 69 6e 20 61 73 20  is passed in as 
38020 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 61 72 67  the.** final arg
38030 75 6d 65 6e 74 20 74 6f 20 72 6f 75 74 69 6e 65  ument to routine
38040 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f  s like [sqlite3_
38050 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29 5d 2e 20  result_blob()]. 
38060 20 5e 49 66 20 74 68 65 20 64 65 73 74 72 75 63   ^If the destruc
38070 74 6f 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  tor.** argument 
38080 69 73 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43  is SQLITE_STATIC
38090 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20  , it means that 
380a0 74 68 65 20 63 6f 6e 74 65 6e 74 20 70 6f 69 6e  the content poin
380b0 74 65 72 20 69 73 20 63 6f 6e 73 74 61 6e 74 0a  ter is constant.
380c0 2a 2a 20 61 6e 64 20 77 69 6c 6c 20 6e 65 76 65  ** and will neve
380d0 72 20 63 68 61 6e 67 65 2e 20 20 49 74 20 64 6f  r change.  It do
380e0 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62  es not need to b
380f0 65 20 64 65 73 74 72 6f 79 65 64 2e 20 20 5e 54  e destroyed.  ^T
38100 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 52 41  he.** SQLITE_TRA
38110 4e 53 49 45 4e 54 20 76 61 6c 75 65 20 6d 65 61  NSIENT value mea
38120 6e 73 20 74 68 61 74 20 74 68 65 20 63 6f 6e 74  ns that the cont
38130 65 6e 74 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20  ent will likely 
38140 63 68 61 6e 67 65 20 69 6e 0a 2a 2a 20 74 68 65  change in.** the
38150 20 6e 65 61 72 20 66 75 74 75 72 65 20 61 6e 64   near future and
38160 20 74 68 61 74 20 53 51 4c 69 74 65 20 73 68 6f   that SQLite sho
38170 75 6c 64 20 6d 61 6b 65 20 69 74 73 20 6f 77 6e  uld make its own
38180 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66   private copy of
38190 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20  .** the content 
381a0 62 65 66 6f 72 65 20 72 65 74 75 72 6e 69 6e 67  before returning
381b0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65  ..**.** The type
381c0 64 65 66 20 69 73 20 6e 65 63 65 73 73 61 72 79  def is necessary
381d0 20 74 6f 20 77 6f 72 6b 20 61 72 6f 75 6e 64 20   to work around 
381e0 70 72 6f 62 6c 65 6d 73 20 69 6e 20 63 65 72 74  problems in cert
381f0 61 69 6e 0a 2a 2a 20 43 2b 2b 20 63 6f 6d 70 69  ain.** C++ compi
38200 6c 65 72 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  lers..*/.typedef
38210 20 76 6f 69 64 20 28 2a 73 71 6c 69 74 65 33 5f   void (*sqlite3_
38220 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29  destructor_type)
38230 28 76 6f 69 64 2a 29 3b 0a 23 64 65 66 69 6e 65  (void*);.#define
38240 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 20 20   SQLITE_STATIC  
38250 20 20 20 20 28 28 73 71 6c 69 74 65 33 5f 64 65      ((sqlite3_de
38260 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29 30 29  structor_type)0)
38270 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
38280 54 52 41 4e 53 49 45 4e 54 20 20 20 28 28 73 71  TRANSIENT   ((sq
38290 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72  lite3_destructor
382a0 5f 74 79 70 65 29 2d 31 29 0a 0a 2f 2a 0a 2a 2a  _type)-1)../*.**
382b0 20 43 41 50 49 33 52 45 46 3a 20 53 65 74 74 69   CAPI3REF: Setti
382c0 6e 67 20 54 68 65 20 52 65 73 75 6c 74 20 4f 66  ng The Result Of
382d0 20 41 6e 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e   An SQL Function
382e0 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
382f0 74 65 33 5f 63 6f 6e 74 65 78 74 0a 2a 2a 0a 2a  te3_context.**.*
38300 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
38310 20 61 72 65 20 75 73 65 64 20 62 79 20 74 68 65   are used by the
38320 20 78 46 75 6e 63 20 6f 72 20 78 46 69 6e 61 6c   xFunc or xFinal
38330 20 63 61 6c 6c 62 61 63 6b 73 20 74 68 61 74 0a   callbacks that.
38340 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 20 53 51 4c  ** implement SQL
38350 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61   functions and a
38360 67 67 72 65 67 61 74 65 73 2e 20 20 53 65 65 0a  ggregates.  See.
38370 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  ** [sqlite3_crea
38380 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61  te_function()] a
38390 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  nd [sqlite3_crea
383a0 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d  te_function16()]
383b0 0a 2a 2a 20 66 6f 72 20 61 64 64 69 74 69 6f 6e  .** for addition
383c0 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a  al information..
383d0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63  **.** These func
383e0 74 69 6f 6e 73 20 77 6f 72 6b 20 76 65 72 79 20  tions work very 
383f0 6d 75 63 68 20 6c 69 6b 65 20 74 68 65 20 5b 70  much like the [p
38400 61 72 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67  arameter binding
38410 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 66  ] family of.** f
38420 75 6e 63 74 69 6f 6e 73 20 75 73 65 64 20 74 6f  unctions used to
38430 20 62 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20   bind values to 
38440 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 20  host parameters 
38450 69 6e 20 70 72 65 70 61 72 65 64 20 73 74 61 74  in prepared stat
38460 65 6d 65 6e 74 73 2e 0a 2a 2a 20 52 65 66 65 72  ements..** Refer
38470 20 74 6f 20 74 68 65 20 5b 53 51 4c 20 70 61 72   to the [SQL par
38480 61 6d 65 74 65 72 5d 20 64 6f 63 75 6d 65 6e 74  ameter] document
38490 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69  ation for additi
384a0 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  onal information
384b0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
384c0 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62  ite3_result_blob
384d0 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74  () interface set
384e0 73 20 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f  s the result fro
384f0 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61 74  m.** an applicat
38500 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
38510 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 42  tion to be the B
38520 4c 4f 42 20 77 68 6f 73 65 20 63 6f 6e 74 65 6e  LOB whose conten
38530 74 20 69 73 20 70 6f 69 6e 74 65 64 0a 2a 2a 20  t is pointed.** 
38540 74 6f 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64  to by the second
38550 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20 77   parameter and w
38560 68 69 63 68 20 69 73 20 4e 20 62 79 74 65 73 20  hich is N bytes 
38570 6c 6f 6e 67 20 77 68 65 72 65 20 4e 20 69 73 20  long where N is 
38580 74 68 65 0a 2a 2a 20 74 68 69 72 64 20 70 61 72  the.** third par
38590 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ameter..**.** ^T
385a0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
385b0 74 5f 7a 65 72 6f 62 6c 6f 62 28 43 2c 4e 29 20  t_zeroblob(C,N) 
385c0 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  and sqlite3_resu
385d0 6c 74 5f 7a 65 72 6f 62 6c 6f 62 36 34 28 43 2c  lt_zeroblob64(C,
385e0 4e 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73  N).** interfaces
385f0 20 73 65 74 20 74 68 65 20 72 65 73 75 6c 74 20   set the result 
38600 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  of the applicati
38610 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
38620 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 61 20 42  ion to be.** a B
38630 4c 4f 42 20 63 6f 6e 74 61 69 6e 69 6e 67 20 61  LOB containing a
38640 6c 6c 20 7a 65 72 6f 20 62 79 74 65 73 20 61 6e  ll zero bytes an
38650 64 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a  d N bytes in siz
38660 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  e..**.** ^The sq
38670 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75  lite3_result_dou
38680 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 20  ble() interface 
38690 73 65 74 73 20 74 68 65 20 72 65 73 75 6c 74 20  sets the result 
386a0 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69  from.** an appli
386b0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
386c0 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20  unction to be a 
386d0 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76  floating point v
386e0 61 6c 75 65 20 73 70 65 63 69 66 69 65 64 0a 2a  alue specified.*
386f0 2a 20 62 79 20 69 74 73 20 32 6e 64 20 61 72 67  * by its 2nd arg
38700 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ument..**.** ^Th
38710 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
38720 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 73 71 6c  _error() and sql
38730 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
38740 72 31 36 28 29 20 66 75 6e 63 74 69 6f 6e 73 0a  r16() functions.
38750 2a 2a 20 63 61 75 73 65 20 74 68 65 20 69 6d 70  ** cause the imp
38760 6c 65 6d 65 6e 74 65 64 20 53 51 4c 20 66 75 6e  lemented SQL fun
38770 63 74 69 6f 6e 20 74 6f 20 74 68 72 6f 77 20 61  ction to throw a
38780 6e 20 65 78 63 65 70 74 69 6f 6e 2e 0a 2a 2a 20  n exception..** 
38790 5e 53 51 4c 69 74 65 20 75 73 65 73 20 74 68 65  ^SQLite uses the
387a0 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 64 20   string pointed 
387b0 74 6f 20 62 79 20 74 68 65 0a 2a 2a 20 32 6e 64  to by the.** 2nd
387c0 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 73 71   parameter of sq
387d0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
387e0 6f 72 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  or() or sqlite3_
387f0 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29  result_error16()
38800 0a 2a 2a 20 61 73 20 74 68 65 20 74 65 78 74 20  .** as the text 
38810 6f 66 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73  of an error mess
38820 61 67 65 2e 20 20 5e 53 51 4c 69 74 65 20 69 6e  age.  ^SQLite in
38830 74 65 72 70 72 65 74 73 20 74 68 65 20 65 72 72  terprets the err
38840 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 73 74