System.Data.SQLite
Hex Artifact Content
Not logged in

Artifact 6b8b6639a1150f1c4d0cef10518ee0b4ba677335:


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 6f 20 6d 61 6b 65 20 6d 69 6e 6f  rve to make mino
03c0: 72 20 63 68 61 6e 67 65 73 20 69 66 0a 2a 2a 20  r changes if.** 
03d0: 65 78 70 65 72 69 65 6e 63 65 20 66 72 6f 6d 20  experience from 
03e0: 75 73 65 20 22 69 6e 20 74 68 65 20 77 69 6c 64  use "in the wild
03f0: 22 20 73 75 67 67 65 73 74 20 73 75 63 68 20 63  " suggest such c
0400: 68 61 6e 67 65 73 20 61 72 65 20 70 72 75 64 65  hanges are prude
0410: 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6f 66  nt..**.** The of
0420: 66 69 63 69 61 6c 20 43 2d 6c 61 6e 67 75 61 67  ficial C-languag
0430: 65 20 41 50 49 20 64 6f 63 75 6d 65 6e 74 61 74  e API documentat
0440: 69 6f 6e 20 66 6f 72 20 53 51 4c 69 74 65 20 69  ion for SQLite i
0450: 73 20 64 65 72 69 76 65 64 0a 2a 2a 20 66 72 6f  s derived.** fro
0460: 6d 20 63 6f 6d 6d 65 6e 74 73 20 69 6e 20 74 68  m comments in th
0470: 69 73 20 66 69 6c 65 2e 20 20 54 68 69 73 20 66  is file.  This f
0480: 69 6c 65 20 69 73 20 74 68 65 20 61 75 74 68 6f  ile is the autho
0490: 72 69 74 61 74 69 76 65 20 73 6f 75 72 63 65 0a  ritative source.
04a0: 2a 2a 20 6f 6e 20 68 6f 77 20 53 51 4c 69 74 65  ** on how SQLite
04b0: 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20   interfaces are 
04c0: 73 75 70 70 6f 73 65 20 74 6f 20 6f 70 65 72 61  suppose to opera
04d0: 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6e 61  te..**.** The na
04e0: 6d 65 20 6f 66 20 74 68 69 73 20 66 69 6c 65 20  me of this file 
04f0: 75 6e 64 65 72 20 63 6f 6e 66 69 67 75 72 61 74  under configurat
0500: 69 6f 6e 20 6d 61 6e 61 67 65 6d 65 6e 74 20 69  ion management i
0510: 73 20 22 73 71 6c 69 74 65 2e 68 2e 69 6e 22 2e  s "sqlite.h.in".
0520: 0a 2a 2a 20 54 68 65 20 6d 61 6b 65 66 69 6c 65  .** The makefile
0530: 20 6d 61 6b 65 73 20 73 6f 6d 65 20 6d 69 6e 6f   makes some mino
0540: 72 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 69  r changes to thi
0550: 73 20 66 69 6c 65 20 28 73 75 63 68 20 61 73 20  s file (such as 
0560: 69 6e 73 65 72 74 69 6e 67 0a 2a 2a 20 74 68 65  inserting.** the
0570: 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 29   version number)
0580: 20 61 6e 64 20 63 68 61 6e 67 65 73 20 69 74 73   and changes its
0590: 20 6e 61 6d 65 20 74 6f 20 22 73 71 6c 69 74 65   name to "sqlite
05a0: 33 2e 68 22 20 61 73 0a 2a 2a 20 70 61 72 74 20  3.h" as.** part 
05b0: 6f 66 20 74 68 65 20 62 75 69 6c 64 20 70 72 6f  of the build pro
05c0: 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 40 28 23 29  cess..**.** @(#)
05d0: 20 24 49 64 3a 20 73 71 6c 69 74 65 33 2e 68 2c   $Id: sqlite3.h,
05e0: 76 20 31 2e 34 30 20 32 30 30 39 2f 30 36 2f 31  v 1.40 2009/06/1
05f0: 39 20 32 31 3a 30 34 3a 31 32 20 72 6d 73 69 6d  9 21:04:12 rmsim
0600: 70 73 6f 6e 20 45 78 70 20 24 0a 2a 2f 0a 23 69  pson Exp $.*/.#i
0610: 66 6e 64 65 66 20 5f 53 51 4c 49 54 45 33 5f 48  fndef _SQLITE3_H
0620: 5f 0a 23 64 65 66 69 6e 65 20 5f 53 51 4c 49 54  _.#define _SQLIT
0630: 45 33 5f 48 5f 0a 23 69 6e 63 6c 75 64 65 20 3c  E3_H_.#include <
0640: 73 74 64 61 72 67 2e 68 3e 20 20 20 20 20 2f 2a  stdarg.h>     /*
0650: 20 4e 65 65 64 65 64 20 66 6f 72 20 74 68 65 20   Needed for the 
0660: 64 65 66 69 6e 69 74 69 6f 6e 20 6f 66 20 76 61  definition of va
0670: 5f 6c 69 73 74 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20  _list */../*.** 
0680: 4d 61 6b 65 20 73 75 72 65 20 77 65 20 63 61 6e  Make sure we can
0690: 20 63 61 6c 6c 20 74 68 69 73 20 73 74 75 66 66   call this stuff
06a0: 20 66 72 6f 6d 20 43 2b 2b 2e 0a 2a 2f 0a 23 69   from C++..*/.#i
06b0: 66 64 65 66 20 5f 5f 63 70 6c 75 73 70 6c 75 73  fdef __cplusplus
06c0: 0a 65 78 74 65 72 6e 20 22 43 22 20 7b 0a 23 65  .extern "C" {.#e
06d0: 6e 64 69 66 0a 0a 0a 2f 2a 0a 2a 2a 20 41 64 64  ndif.../*.** Add
06e0: 20 74 68 65 20 61 62 69 6c 69 74 79 20 74 6f 20   the ability to 
06f0: 6f 76 65 72 72 69 64 65 20 27 65 78 74 65 72 6e  override 'extern
0700: 27 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c  '.*/.#ifndef SQL
0710: 49 54 45 5f 45 58 54 45 52 4e 0a 23 20 64 65 66  ITE_EXTERN.# def
0720: 69 6e 65 20 53 51 4c 49 54 45 5f 45 58 54 45 52  ine SQLITE_EXTER
0730: 4e 20 65 78 74 65 72 6e 0a 23 65 6e 64 69 66 0a  N extern.#endif.
0740: 0a 2f 2a 0a 2a 2a 20 54 68 65 73 65 20 6e 6f 2d  ./*.** These no-
0750: 6f 70 20 6d 61 63 72 6f 73 20 61 72 65 20 75 73  op macros are us
0760: 65 64 20 69 6e 20 66 72 6f 6e 74 20 6f 66 20 69  ed in front of i
0770: 6e 74 65 72 66 61 63 65 73 20 74 6f 20 6d 61 72  nterfaces to mar
0780: 6b 20 74 68 6f 73 65 0a 2a 2a 20 69 6e 74 65 72  k those.** inter
0790: 66 61 63 65 73 20 61 73 20 65 69 74 68 65 72 20  faces as either 
07a0: 64 65 70 72 65 63 61 74 65 64 20 6f 72 20 65 78  deprecated or ex
07b0: 70 65 72 69 6d 65 6e 74 61 6c 2e 20 20 4e 65 77  perimental.  New
07c0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a   applications.**
07d0: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 75 73 65 20   should not use 
07e0: 64 65 70 72 65 63 61 74 65 64 20 69 6e 74 72 66  deprecated intrf
07f0: 61 63 65 73 20 2d 20 74 68 65 79 20 61 72 65 20  aces - they are 
0800: 73 75 70 70 6f 72 74 20 66 6f 72 20 62 61 63 6b  support for back
0810: 77 61 72 64 73 0a 2a 2a 20 63 6f 6d 70 61 74 69  wards.** compati
0820: 62 69 6c 69 74 79 20 6f 6e 6c 79 2e 20 20 41 70  bility only.  Ap
0830: 70 6c 69 63 61 74 69 6f 6e 20 77 72 69 74 65 72  plication writer
0840: 73 20 73 68 6f 75 6c 64 20 62 65 20 61 77 61 72  s should be awar
0850: 65 20 74 68 61 74 0a 2a 2a 20 65 78 70 65 72 69  e that.** experi
0860: 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66 61 63 65  mental interface
0870: 73 20 61 72 65 20 73 75 62 6a 65 63 74 20 74 6f  s are subject to
0880: 20 63 68 61 6e 67 65 20 69 6e 20 70 6f 69 6e 74   change in point
0890: 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2a 0a 2a 2a   releases..**.**
08a0: 20 54 68 65 73 65 20 6d 61 63 72 6f 73 20 75 73   These macros us
08b0: 65 64 20 74 6f 20 72 65 73 6f 6c 76 65 20 74 6f  ed to resolve to
08c0: 20 76 61 72 69 6f 75 73 20 6b 69 6e 64 73 20 6f   various kinds o
08d0: 66 20 63 6f 6d 70 69 6c 65 72 20 6d 61 67 69 63  f compiler magic
08e0: 20 74 68 61 74 0a 2a 2a 20 77 6f 75 6c 64 20 67   that.** would g
08f0: 65 6e 65 72 61 74 65 20 77 61 72 6e 69 6e 67 20  enerate warning 
0900: 6d 65 73 73 61 67 65 73 20 77 68 65 6e 20 74 68  messages when th
0910: 65 79 20 77 65 72 65 20 75 73 65 64 2e 20 20 42  ey were used.  B
0920: 75 74 20 74 68 61 74 0a 2a 2a 20 63 6f 6d 70 69  ut that.** compi
0930: 6c 65 72 20 6d 61 67 69 63 20 65 6e 64 65 64 20  ler magic ended 
0940: 75 70 20 67 65 6e 65 72 61 74 69 6e 67 20 73 75  up generating su
0950: 63 68 20 61 20 66 6c 75 72 72 79 20 6f 66 20 62  ch a flurry of b
0960: 75 67 20 72 65 70 6f 72 74 73 0a 2a 2a 20 74 68  ug reports.** th
0970: 61 74 20 77 65 20 68 61 76 65 20 74 61 6b 65 6e  at we have taken
0980: 20 69 74 20 61 6c 6c 20 6f 75 74 20 61 6e 64 20   it all out and 
0990: 67 6f 6e 65 20 62 61 63 6b 20 74 6f 20 75 73 69  gone back to usi
09a0: 6e 67 20 73 69 6d 70 6c 65 0a 2a 2a 20 6e 6f 6f  ng simple.** noo
09b0: 70 20 6d 61 63 72 6f 73 2e 0a 2a 2f 0a 23 64 65  p macros..*/.#de
09c0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 50 52  fine SQLITE_DEPR
09d0: 45 43 41 54 45 44 0a 23 64 65 66 69 6e 65 20 53  ECATED.#define S
09e0: 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54  QLITE_EXPERIMENT
09f0: 41 4c 0a 0a 2f 2a 0a 2a 2a 20 45 6e 73 75 72 65  AL../*.** Ensure
0a00: 20 74 68 65 73 65 20 73 79 6d 62 6f 6c 73 20 77   these symbols w
0a10: 65 72 65 20 6e 6f 74 20 64 65 66 69 6e 65 64 20  ere not defined 
0a20: 62 79 20 73 6f 6d 65 20 70 72 65 76 69 6f 75 73  by some previous
0a30: 20 68 65 61 64 65 72 20 66 69 6c 65 2e 0a 2a 2f   header file..*/
0a40: 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 56  .#ifdef SQLITE_V
0a50: 45 52 53 49 4f 4e 0a 23 20 75 6e 64 65 66 20 53  ERSION.# undef S
0a60: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 0a 23 65  QLITE_VERSION.#e
0a70: 6e 64 69 66 0a 23 69 66 64 65 66 20 53 51 4c 49  ndif.#ifdef SQLI
0a80: 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45  TE_VERSION_NUMBE
0a90: 52 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 54 45  R.# undef SQLITE
0aa0: 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 0a  _VERSION_NUMBER.
0ab0: 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41  #endif../*.** CA
0ac0: 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d  PI3REF: Compile-
0ad0: 54 69 6d 65 20 4c 69 62 72 61 72 79 20 56 65 72  Time Library Ver
0ae0: 73 69 6f 6e 20 4e 75 6d 62 65 72 73 20 7b 48 31  sion Numbers {H1
0af0: 30 30 31 30 7d 20 3c 53 36 30 31 30 30 3e 0a 2a  0010} <S60100>.*
0b00: 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f  *.** The SQLITE_
0b10: 56 45 52 53 49 4f 4e 20 61 6e 64 20 53 51 4c 49  VERSION and SQLI
0b20: 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45  TE_VERSION_NUMBE
0b30: 52 20 23 64 65 66 69 6e 65 73 20 69 6e 0a 2a 2a  R #defines in.**
0b40: 20 74 68 65 20 73 71 6c 69 74 65 33 2e 68 20 66   the sqlite3.h f
0b50: 69 6c 65 20 73 70 65 63 69 66 79 20 74 68 65 20  ile specify the 
0b60: 76 65 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74  version of SQLit
0b70: 65 20 77 69 74 68 20 77 68 69 63 68 0a 2a 2a 20  e with which.** 
0b80: 74 68 61 74 20 68 65 61 64 65 72 20 66 69 6c 65  that header file
0b90: 20 69 73 20 61 73 73 6f 63 69 61 74 65 64 2e 0a   is associated..
0ba0: 2a 2a 0a 2a 2a 20 54 68 65 20 22 76 65 72 73 69  **.** The "versi
0bb0: 6f 6e 22 20 6f 66 20 53 51 4c 69 74 65 20 69 73  on" of SQLite is
0bc0: 20 61 20 73 74 72 69 6e 67 20 6f 66 20 74 68 65   a string of the
0bd0: 20 66 6f 72 6d 20 22 58 2e 59 2e 5a 22 2e 0a 2a   form "X.Y.Z"..*
0be0: 2a 20 54 68 65 20 70 68 72 61 73 65 20 22 61 6c  * The phrase "al
0bf0: 70 68 61 22 20 6f 72 20 22 62 65 74 61 22 20 6d  pha" or "beta" m
0c00: 69 67 68 74 20 62 65 20 61 70 70 65 6e 64 65 64  ight be appended
0c10: 20 61 66 74 65 72 20 74 68 65 20 5a 2e 0a 2a 2a   after the Z..**
0c20: 20 54 68 65 20 58 20 76 61 6c 75 65 20 69 73 20   The X value is 
0c30: 6d 61 6a 6f 72 20 76 65 72 73 69 6f 6e 20 6e 75  major version nu
0c40: 6d 62 65 72 20 61 6c 77 61 79 73 20 33 20 69 6e  mber always 3 in
0c50: 20 53 51 4c 69 74 65 33 2e 0a 2a 2a 20 54 68 65   SQLite3..** The
0c60: 20 58 20 76 61 6c 75 65 20 6f 6e 6c 79 20 63 68   X value only ch
0c70: 61 6e 67 65 73 20 77 68 65 6e 20 62 61 63 6b 77  anges when backw
0c80: 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69  ards compatibili
0c90: 74 79 20 69 73 0a 2a 2a 20 62 72 6f 6b 65 6e 20  ty is.** broken 
0ca0: 61 6e 64 20 77 65 20 69 6e 74 65 6e 64 20 74 6f  and we intend to
0cb0: 20 6e 65 76 65 72 20 62 72 65 61 6b 20 62 61 63   never break bac
0cc0: 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69  kwards compatibi
0cd0: 6c 69 74 79 2e 0a 2a 2a 20 54 68 65 20 59 20 76  lity..** The Y v
0ce0: 61 6c 75 65 20 69 73 20 74 68 65 20 6d 69 6e 6f  alue is the mino
0cf0: 72 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72  r version number
0d00: 20 61 6e 64 20 6f 6e 6c 79 20 63 68 61 6e 67 65   and only change
0d10: 73 20 77 68 65 6e 0a 2a 2a 20 74 68 65 72 65 20  s when.** there 
0d20: 61 72 65 20 6d 61 6a 6f 72 20 66 65 61 74 75 72  are major featur
0d30: 65 20 65 6e 68 61 6e 63 65 6d 65 6e 74 73 20 74  e enhancements t
0d40: 68 61 74 20 61 72 65 20 66 6f 72 77 61 72 64 73  hat are forwards
0d50: 20 63 6f 6d 70 61 74 69 62 6c 65 0a 2a 2a 20 62   compatible.** b
0d60: 75 74 20 6e 6f 74 20 62 61 63 6b 77 61 72 64 73  ut not backwards
0d70: 20 63 6f 6d 70 61 74 69 62 6c 65 2e 0a 2a 2a 20   compatible..** 
0d80: 54 68 65 20 5a 20 76 61 6c 75 65 20 69 73 20 74  The Z value is t
0d90: 68 65 20 72 65 6c 65 61 73 65 20 6e 75 6d 62 65  he release numbe
0da0: 72 20 61 6e 64 20 69 73 20 69 6e 63 72 65 6d 65  r and is increme
0db0: 6e 74 65 64 20 77 69 74 68 0a 2a 2a 20 65 61 63  nted with.** eac
0dc0: 68 20 72 65 6c 65 61 73 65 20 62 75 74 20 72 65  h release but re
0dd0: 73 65 74 73 20 62 61 63 6b 20 74 6f 20 30 20 77  sets back to 0 w
0de0: 68 65 6e 65 76 65 72 20 59 20 69 73 20 69 6e 63  henever Y is inc
0df0: 72 65 6d 65 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20  remented..**.** 
0e00: 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
0e10: 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 5d  e3_libversion()]
0e20: 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 6c 69   and [sqlite3_li
0e30: 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28  bversion_number(
0e40: 29 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72  )]..**.** Requir
0e50: 65 6d 65 6e 74 73 3a 20 5b 48 31 30 30 31 31 5d  ements: [H10011]
0e60: 20 5b 48 31 30 30 31 34 5d 0a 2a 2f 0a 23 64 65   [H10014].*/.#de
0e70: 66 69 6e 65 20 53 51 4c 49 54 45 5f 56 45 52 53  fine SQLITE_VERS
0e80: 49 4f 4e 20 20 20 20 20 20 20 20 20 22 33 2e 36  ION         "3.6
0e90: 2e 31 35 22 0a 23 64 65 66 69 6e 65 20 53 51 4c  .15".#define SQL
0ea0: 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42  ITE_VERSION_NUMB
0eb0: 45 52 20 20 33 30 30 36 30 31 35 0a 0a 2f 2a 0a  ER  3006015../*.
0ec0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e  ** CAPI3REF: Run
0ed0: 2d 54 69 6d 65 20 4c 69 62 72 61 72 79 20 56 65  -Time Library Ve
0ee0: 72 73 69 6f 6e 20 4e 75 6d 62 65 72 73 20 7b 48  rsion Numbers {H
0ef0: 31 30 30 32 30 7d 20 3c 53 36 30 31 30 30 3e 0a  10020} <S60100>.
0f00: 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c  ** KEYWORDS: sql
0f10: 69 74 65 33 5f 76 65 72 73 69 6f 6e 0a 2a 2a 0a  ite3_version.**.
0f20: 2a 2a 20 54 68 65 73 65 20 66 65 61 74 75 72 65  ** These feature
0f30: 73 20 70 72 6f 76 69 64 65 20 74 68 65 20 73 61  s provide the sa
0f40: 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61  me information a
0f50: 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 56 45  s the [SQLITE_VE
0f60: 52 53 49 4f 4e 5d 0a 2a 2a 20 61 6e 64 20 5b 53  RSION].** and [S
0f70: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55  QLITE_VERSION_NU
0f80: 4d 42 45 52 5d 20 23 64 65 66 69 6e 65 73 20 69  MBER] #defines i
0f90: 6e 20 74 68 65 20 68 65 61 64 65 72 2c 20 62 75  n the header, bu
0fa0: 74 20 61 72 65 20 61 73 73 6f 63 69 61 74 65 64  t are associated
0fb0: 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 6c 69 62  .** with the lib
0fc0: 72 61 72 79 20 69 6e 73 74 65 61 64 20 6f 66 20  rary instead of 
0fd0: 74 68 65 20 68 65 61 64 65 72 20 66 69 6c 65 2e  the header file.
0fe0: 20 20 43 61 75 74 69 6f 75 73 20 70 72 6f 67 72    Cautious progr
0ff0: 61 6d 6d 65 72 73 20 6d 69 67 68 74 0a 2a 2a 20  ammers might.** 
1000: 69 6e 63 6c 75 64 65 20 61 20 63 68 65 63 6b 20  include a check 
1010: 69 6e 20 74 68 65 69 72 20 61 70 70 6c 69 63 61  in their applica
1020: 74 69 6f 6e 20 74 6f 20 76 65 72 69 66 79 20 74  tion to verify t
1030: 68 61 74 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6c  hat.** sqlite3_l
1040: 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72  ibversion_number
1050: 28 29 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e  () always return
1060: 73 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 5b  s the value.** [
1070: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e  SQLITE_VERSION_N
1080: 55 4d 42 45 52 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68  UMBER]..**.** Th
1090: 65 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72  e sqlite3_libver
10a0: 73 69 6f 6e 28 29 20 66 75 6e 63 74 69 6f 6e 20  sion() function 
10b0: 72 65 74 75 72 6e 73 20 74 68 65 20 73 61 6d 65  returns the same
10c0: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 73 20   information as 
10d0: 69 73 0a 2a 2a 20 69 6e 20 74 68 65 20 73 71 6c  is.** in the sql
10e0: 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 20 73  ite3_version[] s
10f0: 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 2e 20  tring constant. 
1100: 20 54 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73   The function is
1110: 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 66 6f 72   provided.** for
1120: 20 75 73 65 20 69 6e 20 44 4c 4c 73 20 73 69 6e   use in DLLs sin
1130: 63 65 20 44 4c 4c 20 75 73 65 72 73 20 75 73 75  ce DLL users usu
1140: 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 68 61 76 65  ally do not have
1150: 20 64 69 72 65 63 74 20 61 63 63 65 73 73 20 74   direct access t
1160: 6f 20 73 74 72 69 6e 67 0a 2a 2a 20 63 6f 6e 73  o string.** cons
1170: 74 61 6e 74 73 20 77 69 74 68 69 6e 20 74 68 65  tants within the
1180: 20 44 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75   DLL..**.** Requ
1190: 69 72 65 6d 65 6e 74 73 3a 20 5b 48 31 30 30 32  irements: [H1002
11a0: 31 5d 20 5b 48 31 30 30 32 32 5d 20 5b 48 31 30  1] [H10022] [H10
11b0: 30 32 33 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45  023].*/.SQLITE_E
11c0: 58 54 45 52 4e 20 63 6f 6e 73 74 20 63 68 61 72  XTERN const char
11d0: 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e   sqlite3_version
11e0: 5b 5d 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  [];.const char *
11f0: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
1200: 6f 6e 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71  on(void);.int sq
1210: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
1220: 5f 6e 75 6d 62 65 72 28 76 6f 69 64 29 3b 0a 0a  _number(void);..
1230: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1240: 54 65 73 74 20 54 6f 20 53 65 65 20 49 66 20 54  Test To See If T
1250: 68 65 20 4c 69 62 72 61 72 79 20 49 73 20 54 68  he Library Is Th
1260: 72 65 61 64 73 61 66 65 20 7b 48 31 30 31 30 30  readsafe {H10100
1270: 7d 20 3c 53 36 30 31 30 30 3e 0a 2a 2a 0a 2a 2a  } <S60100>.**.**
1280: 20 53 51 4c 69 74 65 20 63 61 6e 20 62 65 20 63   SQLite can be c
1290: 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 6f 72 20  ompiled with or 
12a0: 77 69 74 68 6f 75 74 20 6d 75 74 65 78 65 73 2e  without mutexes.
12b0: 20 20 57 68 65 6e 0a 2a 2a 20 74 68 65 20 5b 53    When.** the [S
12c0: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
12d0: 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72  ] C preprocessor
12e0: 20 6d 61 63 72 6f 20 31 20 6f 72 20 32 2c 20 6d   macro 1 or 2, m
12f0: 75 74 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e  utexes.** are en
1300: 61 62 6c 65 64 20 61 6e 64 20 53 51 4c 69 74 65  abled and SQLite
1310: 20 69 73 20 74 68 72 65 61 64 73 61 66 65 2e 20   is threadsafe. 
1320: 20 57 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 53 51   When the.** [SQ
1330: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d  LITE_THREADSAFE]
1340: 20 6d 61 63 72 6f 20 69 73 20 30 2c 20 0a 2a 2a   macro is 0, .**
1350: 20 74 68 65 20 6d 75 74 65 78 65 73 20 61 72 65   the mutexes are
1360: 20 6f 6d 69 74 74 65 64 2e 20 20 57 69 74 68 6f   omitted.  Witho
1370: 75 74 20 74 68 65 20 6d 75 74 65 78 65 73 2c 20  ut the mutexes, 
1380: 69 74 20 69 73 20 6e 6f 74 20 73 61 66 65 0a 2a  it is not safe.*
1390: 2a 20 74 6f 20 75 73 65 20 53 51 4c 69 74 65 20  * to use SQLite 
13a0: 63 6f 6e 63 75 72 72 65 6e 74 6c 79 20 66 72 6f  concurrently fro
13b0: 6d 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20  m more than one 
13c0: 74 68 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 45 6e  thread..**.** En
13d0: 61 62 6c 69 6e 67 20 6d 75 74 65 78 65 73 20 69  abling mutexes i
13e0: 6e 63 75 72 73 20 61 20 6d 65 61 73 75 72 61 62  ncurs a measurab
13f0: 6c 65 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 70  le performance p
1400: 65 6e 61 6c 74 79 2e 0a 2a 2a 20 53 6f 20 69 66  enalty..** So if
1410: 20 73 70 65 65 64 20 69 73 20 6f 66 20 75 74 6d   speed is of utm
1420: 6f 73 74 20 69 6d 70 6f 72 74 61 6e 63 65 2c 20  ost importance, 
1430: 69 74 20 6d 61 6b 65 73 20 73 65 6e 73 65 20 74  it makes sense t
1440: 6f 20 64 69 73 61 62 6c 65 0a 2a 2a 20 74 68 65  o disable.** the
1450: 20 6d 75 74 65 78 65 73 2e 20 20 42 75 74 20 66   mutexes.  But f
1460: 6f 72 20 6d 61 78 69 6d 75 6d 20 73 61 66 65 74  or maximum safet
1470: 79 2c 20 6d 75 74 65 78 65 73 20 73 68 6f 75 6c  y, mutexes shoul
1480: 64 20 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a  d be enabled..**
1490: 20 54 68 65 20 64 65 66 61 75 6c 74 20 62 65 68   The default beh
14a0: 61 76 69 6f 72 20 69 73 20 66 6f 72 20 6d 75 74  avior is for mut
14b0: 65 78 65 73 20 74 6f 20 62 65 20 65 6e 61 62 6c  exes to be enabl
14c0: 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69  ed..**.** This i
14d0: 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20  nterface can be 
14e0: 75 73 65 64 20 62 79 20 61 20 70 72 6f 67 72 61  used by a progra
14f0: 6d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74  m to make sure t
1500: 68 61 74 20 74 68 65 0a 2a 2a 20 76 65 72 73 69  hat the.** versi
1510: 6f 6e 20 6f 66 20 53 51 4c 69 74 65 20 74 68 61  on of SQLite tha
1520: 74 20 69 74 20 69 73 20 6c 69 6e 6b 69 6e 67 20  t it is linking 
1530: 61 67 61 69 6e 73 74 20 77 61 73 20 63 6f 6d 70  against was comp
1540: 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65  iled with.** the
1550: 20 64 65 73 69 72 65 64 20 73 65 74 74 69 6e 67   desired setting
1560: 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   of the [SQLITE_
1570: 54 48 52 45 41 44 53 41 46 45 5d 20 6d 61 63 72  THREADSAFE] macr
1580: 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e  o..**.** This in
1590: 74 65 72 66 61 63 65 20 6f 6e 6c 79 20 72 65 70  terface only rep
15a0: 6f 72 74 73 20 6f 6e 20 74 68 65 20 63 6f 6d 70  orts on the comp
15b0: 69 6c 65 2d 74 69 6d 65 20 6d 75 74 65 78 20 73  ile-time mutex s
15c0: 65 74 74 69 6e 67 0a 2a 2a 20 6f 66 20 74 68 65  etting.** of the
15d0: 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53   [SQLITE_THREADS
15e0: 41 46 45 5d 20 66 6c 61 67 2e 20 20 49 66 20 53  AFE] flag.  If S
15f0: 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
1600: 64 20 77 69 74 68 0a 2a 2a 20 53 51 4c 49 54 45  d with.** SQLITE
1610: 5f 54 48 52 45 41 44 53 41 46 45 3d 31 20 74 68  _THREADSAFE=1 th
1620: 65 6e 20 6d 75 74 65 78 65 73 20 61 72 65 20 65  en mutexes are e
1630: 6e 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c  nabled by defaul
1640: 74 20 62 75 74 0a 2a 2a 20 63 61 6e 20 62 65 20  t but.** can be 
1650: 66 75 6c 6c 79 20 6f 72 20 70 61 72 74 69 61 6c  fully or partial
1660: 6c 79 20 64 69 73 61 62 6c 65 64 20 75 73 69 6e  ly disabled usin
1670: 67 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  g a call to [sql
1680: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 0a 2a  ite3_config()].*
1690: 2a 20 77 69 74 68 20 74 68 65 20 76 65 72 62 73  * with the verbs
16a0: 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
16b0: 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 2c 20 5b  SINGLETHREAD], [
16c0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
16d0: 4c 54 49 54 48 52 45 41 44 5d 2c 0a 2a 2a 20 6f  LTITHREAD],.** o
16e0: 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  r [SQLITE_CONFIG
16f0: 5f 4d 55 54 45 58 5d 2e 20 20 54 68 65 20 72 65  _MUTEX].  The re
1700: 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68  turn value of th
1710: 69 73 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 77  is function show
1720: 73 0a 2a 2a 20 6f 6e 6c 79 20 74 68 65 20 64 65  s.** only the de
1730: 66 61 75 6c 74 20 63 6f 6d 70 69 6c 65 2d 74 69  fault compile-ti
1740: 6d 65 20 73 65 74 74 69 6e 67 2c 20 6e 6f 74 20  me setting, not 
1750: 61 6e 79 20 72 75 6e 2d 74 69 6d 65 20 63 68 61  any run-time cha
1760: 6e 67 65 73 0a 2a 2a 20 74 6f 20 74 68 61 74 20  nges.** to that 
1770: 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 53  setting..**.** S
1780: 65 65 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e  ee the [threadin
1790: 67 20 6d 6f 64 65 5d 20 64 6f 63 75 6d 65 6e 74  g mode] document
17a0: 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69  ation for additi
17b0: 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  onal information
17c0: 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d  ..**.** Requirem
17d0: 65 6e 74 73 3a 20 5b 48 31 30 31 30 31 5d 20 5b  ents: [H10101] [
17e0: 48 31 30 31 30 32 5d 0a 2a 2f 0a 69 6e 74 20 73  H10102].*/.int s
17f0: 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66  qlite3_threadsaf
1800: 65 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20  e(void);../*.** 
1810: 43 41 50 49 33 52 45 46 3a 20 44 61 74 61 62 61  CAPI3REF: Databa
1820: 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 48 61  se Connection Ha
1830: 6e 64 6c 65 20 7b 48 31 32 30 30 30 7d 20 3c 53  ndle {H12000} <S
1840: 34 30 32 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52  40200>.** KEYWOR
1850: 44 53 3a 20 7b 64 61 74 61 62 61 73 65 20 63 6f  DS: {database co
1860: 6e 6e 65 63 74 69 6f 6e 7d 20 7b 64 61 74 61 62  nnection} {datab
1870: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 7d  ase connections}
1880: 0a 2a 2a 0a 2a 2a 20 45 61 63 68 20 6f 70 65 6e  .**.** Each open
1890: 20 53 51 4c 69 74 65 20 64 61 74 61 62 61 73 65   SQLite database
18a0: 20 69 73 20 72 65 70 72 65 73 65 6e 74 65 64 20   is represented 
18b0: 62 79 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  by a pointer to 
18c0: 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 0a 2a  an instance of.*
18d0: 2a 20 74 68 65 20 6f 70 61 71 75 65 20 73 74 72  * the opaque str
18e0: 75 63 74 75 72 65 20 6e 61 6d 65 64 20 22 73 71  ucture named "sq
18f0: 6c 69 74 65 33 22 2e 20 20 49 74 20 69 73 20 75  lite3".  It is u
1900: 73 65 66 75 6c 20 74 6f 20 74 68 69 6e 6b 20 6f  seful to think o
1910: 66 20 61 6e 20 73 71 6c 69 74 65 33 0a 2a 2a 20  f an sqlite3.** 
1920: 70 6f 69 6e 74 65 72 20 61 73 20 61 6e 20 6f 62  pointer as an ob
1930: 6a 65 63 74 2e 20 20 54 68 65 20 5b 73 71 6c 69  ject.  The [sqli
1940: 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71  te3_open()], [sq
1950: 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c  lite3_open16()],
1960: 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
1970: 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65  _open_v2()] inte
1980: 72 66 61 63 65 73 20 61 72 65 20 69 74 73 20 63  rfaces are its c
1990: 6f 6e 73 74 72 75 63 74 6f 72 73 2c 20 61 6e 64  onstructors, and
19a0: 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28   [sqlite3_close(
19b0: 29 5d 0a 2a 2a 20 69 73 20 69 74 73 20 64 65 73  )].** is its des
19c0: 74 72 75 63 74 6f 72 2e 20 20 54 68 65 72 65 20  tructor.  There 
19d0: 61 72 65 20 6d 61 6e 79 20 6f 74 68 65 72 20 69  are many other i
19e0: 6e 74 65 72 66 61 63 65 73 20 28 73 75 63 68 20  nterfaces (such 
19f0: 61 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  as.** [sqlite3_p
1a00: 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73  repare_v2()], [s
1a10: 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
1a20: 6e 63 74 69 6f 6e 28 29 5d 2c 20 61 6e 64 0a 2a  nction()], and.*
1a30: 2a 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  * [sqlite3_busy_
1a40: 74 69 6d 65 6f 75 74 28 29 5d 20 74 6f 20 6e 61  timeout()] to na
1a50: 6d 65 20 62 75 74 20 74 68 72 65 65 29 20 74 68  me but three) th
1a60: 61 74 20 61 72 65 20 6d 65 74 68 6f 64 73 20 6f  at are methods o
1a70: 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 20  n an.** sqlite3 
1a80: 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 74 79 70 65 64  object..*/.typed
1a90: 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
1aa0: 33 20 73 71 6c 69 74 65 33 3b 0a 0a 2f 2a 0a 2a  3 sqlite3;../*.*
1ab0: 2a 20 43 41 50 49 33 52 45 46 3a 20 36 34 2d 42  * CAPI3REF: 64-B
1ac0: 69 74 20 49 6e 74 65 67 65 72 20 54 79 70 65 73  it Integer Types
1ad0: 20 7b 48 31 30 32 30 30 7d 20 3c 53 31 30 31 31   {H10200} <S1011
1ae0: 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  0>.** KEYWORDS: 
1af0: 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 73 71 6c  sqlite_int64 sql
1b00: 69 74 65 5f 75 69 6e 74 36 34 0a 2a 2a 0a 2a 2a  ite_uint64.**.**
1b10: 20 42 65 63 61 75 73 65 20 74 68 65 72 65 20 69   Because there i
1b20: 73 20 6e 6f 20 63 72 6f 73 73 2d 70 6c 61 74 66  s no cross-platf
1b30: 6f 72 6d 20 77 61 79 20 74 6f 20 73 70 65 63 69  orm way to speci
1b40: 66 79 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65  fy 64-bit intege
1b50: 72 20 74 79 70 65 73 0a 2a 2a 20 53 51 4c 69 74  r types.** SQLit
1b60: 65 20 69 6e 63 6c 75 64 65 73 20 74 79 70 65 64  e includes typed
1b70: 65 66 73 20 66 6f 72 20 36 34 2d 62 69 74 20 73  efs for 64-bit s
1b80: 69 67 6e 65 64 20 61 6e 64 20 75 6e 73 69 67 6e  igned and unsign
1b90: 65 64 20 69 6e 74 65 67 65 72 73 2e 0a 2a 2a 0a  ed integers..**.
1ba0: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69  ** The sqlite3_i
1bb0: 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 33  nt64 and sqlite3
1bc0: 5f 75 69 6e 74 36 34 20 61 72 65 20 74 68 65 20  _uint64 are the 
1bd0: 70 72 65 66 65 72 72 65 64 20 74 79 70 65 20 64  preferred type d
1be0: 65 66 69 6e 69 74 69 6f 6e 73 2e 0a 2a 2a 20 54  efinitions..** T
1bf0: 68 65 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20  he sqlite_int64 
1c00: 61 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74 36  and sqlite_uint6
1c10: 34 20 74 79 70 65 73 20 61 72 65 20 73 75 70 70  4 types are supp
1c20: 6f 72 74 65 64 20 66 6f 72 20 62 61 63 6b 77 61  orted for backwa
1c30: 72 64 73 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69  rds.** compatibi
1c40: 6c 69 74 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a  lity only..**.**
1c50: 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 20 5b   Requirements: [
1c60: 48 31 30 32 30 31 5d 20 5b 48 31 30 32 30 32 5d  H10201] [H10202]
1c70: 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c 49 54  .*/.#ifdef SQLIT
1c80: 45 5f 49 4e 54 36 34 5f 54 59 50 45 0a 20 20 74  E_INT64_TYPE.  t
1c90: 79 70 65 64 65 66 20 53 51 4c 49 54 45 5f 49 4e  ypedef SQLITE_IN
1ca0: 54 36 34 5f 54 59 50 45 20 73 71 6c 69 74 65 5f  T64_TYPE sqlite_
1cb0: 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66  int64;.  typedef
1cc0: 20 75 6e 73 69 67 6e 65 64 20 53 51 4c 49 54 45   unsigned SQLITE
1cd0: 5f 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69  _INT64_TYPE sqli
1ce0: 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c 69 66  te_uint64;.#elif
1cf0: 20 64 65 66 69 6e 65 64 28 5f 4d 53 43 5f 56 45   defined(_MSC_VE
1d00: 52 29 20 7c 7c 20 64 65 66 69 6e 65 64 28 5f 5f  R) || defined(__
1d10: 42 4f 52 4c 41 4e 44 43 5f 5f 29 0a 20 20 74 79  BORLANDC__).  ty
1d20: 70 65 64 65 66 20 5f 5f 69 6e 74 36 34 20 73 71  pedef __int64 sq
1d30: 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79  lite_int64;.  ty
1d40: 70 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20 5f  pedef unsigned _
1d50: 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 5f 75 69  _int64 sqlite_ui
1d60: 6e 74 36 34 3b 0a 23 65 6c 73 65 0a 20 20 74 79  nt64;.#else.  ty
1d70: 70 65 64 65 66 20 6c 6f 6e 67 20 6c 6f 6e 67 20  pedef long long 
1d80: 69 6e 74 20 73 71 6c 69 74 65 5f 69 6e 74 36 34  int sqlite_int64
1d90: 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73 69  ;.  typedef unsi
1da0: 67 6e 65 64 20 6c 6f 6e 67 20 6c 6f 6e 67 20 69  gned long long i
1db0: 6e 74 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34  nt sqlite_uint64
1dc0: 3b 0a 23 65 6e 64 69 66 0a 74 79 70 65 64 65 66  ;.#endif.typedef
1dd0: 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 73 71   sqlite_int64 sq
1de0: 6c 69 74 65 33 5f 69 6e 74 36 34 3b 0a 74 79 70  lite3_int64;.typ
1df0: 65 64 65 66 20 73 71 6c 69 74 65 5f 75 69 6e 74  edef sqlite_uint
1e00: 36 34 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36  64 sqlite3_uint6
1e10: 34 3b 0a 0a 2f 2a 0a 2a 2a 20 49 66 20 63 6f 6d  4;../*.** If com
1e20: 70 69 6c 69 6e 67 20 66 6f 72 20 61 20 70 72 6f  piling for a pro
1e30: 63 65 73 73 6f 72 20 74 68 61 74 20 6c 61 63 6b  cessor that lack
1e40: 73 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74  s floating point
1e50: 20 73 75 70 70 6f 72 74 2c 0a 2a 2a 20 73 75 62   support,.** sub
1e60: 73 74 69 74 75 74 65 20 69 6e 74 65 67 65 72 20  stitute integer 
1e70: 66 6f 72 20 66 6c 6f 61 74 69 6e 67 2d 70 6f 69  for floating-poi
1e80: 6e 74 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51  nt..*/.#ifdef SQ
1e90: 4c 49 54 45 5f 4f 4d 49 54 5f 46 4c 4f 41 54 49  LITE_OMIT_FLOATI
1ea0: 4e 47 5f 50 4f 49 4e 54 0a 23 20 64 65 66 69 6e  NG_POINT.# defin
1eb0: 65 20 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33  e double sqlite3
1ec0: 5f 69 6e 74 36 34 0a 23 65 6e 64 69 66 0a 0a 2f  _int64.#endif../
1ed0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
1ee0: 6c 6f 73 69 6e 67 20 41 20 44 61 74 61 62 61 73  losing A Databas
1ef0: 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 7b 48 31  e Connection {H1
1f00: 32 30 31 30 7d 20 3c 53 33 30 31 30 30 3e 3c 53  2010} <S30100><S
1f10: 34 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69  40200>.**.** Thi
1f20: 73 20 72 6f 75 74 69 6e 65 20 69 73 20 74 68 65  s routine is the
1f30: 20 64 65 73 74 72 75 63 74 6f 72 20 66 6f 72 20   destructor for 
1f40: 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62  the [sqlite3] ob
1f50: 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c  ject..**.** Appl
1f60: 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20  ications should 
1f70: 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
1f80: 65 20 7c 20 66 69 6e 61 6c 69 7a 65 5d 20 61 6c  e | finalize] al
1f90: 6c 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  l [prepared stat
1fa0: 65 6d 65 6e 74 73 5d 0a 2a 2a 20 61 6e 64 20 5b  ements].** and [
1fb0: 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f  sqlite3_blob_clo
1fc0: 73 65 20 7c 20 63 6c 6f 73 65 5d 20 61 6c 6c 20  se | close] all 
1fd0: 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 20 61  [BLOB handles] a
1fe0: 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 0a 2a  ssociated with.*
1ff0: 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20  * the [sqlite3] 
2000: 6f 62 6a 65 63 74 20 70 72 69 6f 72 20 74 6f 20  object prior to 
2010: 61 74 74 65 6d 70 74 69 6e 67 20 74 6f 20 63 6c  attempting to cl
2020: 6f 73 65 20 74 68 65 20 6f 62 6a 65 63 74 2e 0a  ose the object..
2030: 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** The [sqlite3_
2040: 6e 65 78 74 5f 73 74 6d 74 28 29 5d 20 69 6e 74  next_stmt()] int
2050: 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 73  erface can be us
2060: 65 64 20 74 6f 20 6c 6f 63 61 74 65 20 61 6c 6c  ed to locate all
2070: 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
2080: 61 74 65 6d 65 6e 74 73 5d 20 61 73 73 6f 63 69  atements] associ
2090: 61 74 65 64 20 77 69 74 68 20 61 20 5b 64 61 74  ated with a [dat
20a0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
20b0: 5d 20 69 66 20 64 65 73 69 72 65 64 2e 0a 2a 2a  ] if desired..**
20c0: 20 54 79 70 69 63 61 6c 20 63 6f 64 65 20 6d 69   Typical code mi
20d0: 67 68 74 20 6c 6f 6f 6b 20 6c 69 6b 65 20 74 68  ght look like th
20e0: 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  is:.**.** <block
20f0: 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 73  quote><pre>.** s
2100: 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74  qlite3_stmt *pSt
2110: 6d 74 3b 0a 2a 2a 20 77 68 69 6c 65 28 20 28 70  mt;.** while( (p
2120: 53 74 6d 74 20 3d 20 73 71 6c 69 74 65 33 5f 6e  Stmt = sqlite3_n
2130: 65 78 74 5f 73 74 6d 74 28 64 62 2c 20 30 29 29  ext_stmt(db, 0))
2140: 21 3d 30 20 29 7b 0a 2a 2a 20 26 6e 62 73 70 3b  !=0 ){.** &nbsp;
2150: 20 20 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c     sqlite3_final
2160: 69 7a 65 28 70 53 74 6d 74 29 3b 0a 2a 2a 20 7d  ize(pStmt);.** }
2170: 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
2180: 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 49 66  kquote>.**.** If
2190: 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28   [sqlite3_close(
21a0: 29 5d 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68  )] is invoked wh
21b0: 69 6c 65 20 61 20 74 72 61 6e 73 61 63 74 69 6f  ile a transactio
21c0: 6e 20 69 73 20 6f 70 65 6e 2c 0a 2a 2a 20 74 68  n is open,.** th
21d0: 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73  e transaction is
21e0: 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72   automatically r
21f0: 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a  olled back..**.*
2200: 2a 20 54 68 65 20 43 20 70 61 72 61 6d 65 74 65  * The C paramete
2210: 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c  r to [sqlite3_cl
2220: 6f 73 65 28 43 29 5d 20 6d 75 73 74 20 62 65 20  ose(C)] must be 
2230: 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 0a 2a 2a  either a NULL.**
2240: 20 70 6f 69 6e 74 65 72 20 6f 72 20 61 6e 20 5b   pointer or an [
2250: 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20  sqlite3] object 
2260: 70 6f 69 6e 74 65 72 20 6f 62 74 61 69 6e 65 64  pointer obtained
2270: 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  .** from [sqlite
2280: 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69  3_open()], [sqli
2290: 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 6f  te3_open16()], o
22a0: 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70  r.** [sqlite3_op
22b0: 65 6e 5f 76 32 28 29 5d 2c 20 61 6e 64 20 6e 6f  en_v2()], and no
22c0: 74 20 70 72 65 76 69 6f 75 73 6c 79 20 63 6c 6f  t previously clo
22d0: 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69  sed..**.** Requi
22e0: 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32  rements:.** [H12
22f0: 30 31 31 5d 20 5b 48 31 32 30 31 32 5d 20 5b 48  011] [H12012] [H
2300: 31 32 30 31 33 5d 20 5b 48 31 32 30 31 34 5d 20  12013] [H12014] 
2310: 5b 48 31 32 30 31 35 5d 20 5b 48 31 32 30 31 39  [H12015] [H12019
2320: 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ].*/.int sqlite3
2330: 5f 63 6c 6f 73 65 28 73 71 6c 69 74 65 33 20 2a  _close(sqlite3 *
2340: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 74 79  );../*.** The ty
2350: 70 65 20 66 6f 72 20 61 20 63 61 6c 6c 62 61 63  pe for a callbac
2360: 6b 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54  k function..** T
2370: 68 69 73 20 69 73 20 6c 65 67 61 63 79 20 61 6e  his is legacy an
2380: 64 20 64 65 70 72 65 63 61 74 65 64 2e 20 20 49  d deprecated.  I
2390: 74 20 69 73 20 69 6e 63 6c 75 64 65 64 20 66 6f  t is included fo
23a0: 72 20 68 69 73 74 6f 72 69 63 61 6c 0a 2a 2a 20  r historical.** 
23b0: 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 61 6e  compatibility an
23c0: 64 20 69 73 20 6e 6f 74 20 64 6f 63 75 6d 65 6e  d is not documen
23d0: 74 65 64 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ted..*/.typedef 
23e0: 69 6e 74 20 28 2a 73 71 6c 69 74 65 33 5f 63 61  int (*sqlite3_ca
23f0: 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e  llback)(void*,in
2400: 74 2c 63 68 61 72 2a 2a 2c 20 63 68 61 72 2a 2a  t,char**, char**
2410: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2420: 45 46 3a 20 4f 6e 65 2d 53 74 65 70 20 51 75 65  EF: One-Step Que
2430: 72 79 20 45 78 65 63 75 74 69 6f 6e 20 49 6e 74  ry Execution Int
2440: 65 72 66 61 63 65 20 7b 48 31 32 31 30 30 7d 20  erface {H12100} 
2450: 3c 53 31 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 54  <S10000>.**.** T
2460: 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  he sqlite3_exec(
2470: 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 61  ) interface is a
2480: 20 63 6f 6e 76 65 6e 69 65 6e 74 20 77 61 79 20   convenient way 
2490: 6f 66 20 72 75 6e 6e 69 6e 67 20 6f 6e 65 20 6f  of running one o
24a0: 72 20 6d 6f 72 65 0a 2a 2a 20 53 51 4c 20 73 74  r more.** SQL st
24b0: 61 74 65 6d 65 6e 74 73 20 77 69 74 68 6f 75 74  atements without
24c0: 20 68 61 76 69 6e 67 20 74 6f 20 77 72 69 74 65   having to write
24d0: 20 61 20 6c 6f 74 20 6f 66 20 43 20 63 6f 64 65   a lot of C code
24e0: 2e 20 20 54 68 65 20 55 54 46 2d 38 20 65 6e 63  .  The UTF-8 enc
24f0: 6f 64 65 64 0a 2a 2a 20 53 51 4c 20 73 74 61 74  oded.** SQL stat
2500: 65 6d 65 6e 74 73 20 61 72 65 20 70 61 73 73 65  ements are passe
2510: 64 20 69 6e 20 61 73 20 74 68 65 20 73 65 63 6f  d in as the seco
2520: 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  nd parameter to 
2530: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 2e 0a  sqlite3_exec()..
2540: 2a 2a 20 54 68 65 20 73 74 61 74 65 6d 65 6e 74  ** The statement
2550: 73 20 61 72 65 20 65 76 61 6c 75 61 74 65 64 20  s are evaluated 
2560: 6f 6e 65 20 62 79 20 6f 6e 65 20 75 6e 74 69 6c  one by one until
2570: 20 65 69 74 68 65 72 20 61 6e 20 65 72 72 6f 72   either an error
2580: 20 6f 72 0a 2a 2a 20 61 6e 20 69 6e 74 65 72 72   or.** an interr
2590: 75 70 74 20 69 73 20 65 6e 63 6f 75 6e 74 65 72  upt is encounter
25a0: 65 64 2c 20 6f 72 20 75 6e 74 69 6c 20 74 68 65  ed, or until the
25b0: 79 20 61 72 65 20 61 6c 6c 20 64 6f 6e 65 2e 20  y are all done. 
25c0: 20 54 68 65 20 33 72 64 20 70 61 72 61 6d 65 74   The 3rd paramet
25d0: 65 72 0a 2a 2a 20 69 73 20 61 6e 20 6f 70 74 69  er.** is an opti
25e0: 6f 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 74 68  onal callback th
25f0: 61 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e  at is invoked on
2600: 63 65 20 66 6f 72 20 65 61 63 68 20 72 6f 77 20  ce for each row 
2610: 6f 66 20 61 6e 79 20 71 75 65 72 79 0a 2a 2a 20  of any query.** 
2620: 72 65 73 75 6c 74 73 20 70 72 6f 64 75 63 65 64  results produced
2630: 20 62 79 20 74 68 65 20 53 51 4c 20 73 74 61 74   by the SQL stat
2640: 65 6d 65 6e 74 73 2e 20 20 54 68 65 20 35 74 68  ements.  The 5th
2650: 20 70 61 72 61 6d 65 74 65 72 20 74 65 6c 6c 73   parameter tells
2660: 20 77 68 65 72 65 0a 2a 2a 20 74 6f 20 77 72 69   where.** to wri
2670: 74 65 20 61 6e 79 20 65 72 72 6f 72 20 6d 65 73  te any error mes
2680: 73 61 67 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  sages..**.** The
2690: 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 70   error message p
26a0: 61 73 73 65 64 20 62 61 63 6b 20 74 68 72 6f 75  assed back throu
26b0: 67 68 20 74 68 65 20 35 74 68 20 70 61 72 61 6d  gh the 5th param
26c0: 65 74 65 72 20 69 73 20 68 65 6c 64 0a 2a 2a 20  eter is held.** 
26d0: 69 6e 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e  in memory obtain
26e0: 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
26f0: 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 20 54 6f 20  _malloc()].  To 
2700: 61 76 6f 69 64 20 61 20 6d 65 6d 6f 72 79 20 6c  avoid a memory l
2710: 65 61 6b 2c 0a 2a 2a 20 74 68 65 20 63 61 6c 6c  eak,.** the call
2720: 69 6e 67 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  ing application 
2730: 73 68 6f 75 6c 64 20 63 61 6c 6c 20 5b 73 71 6c  should call [sql
2740: 69 74 65 33 5f 66 72 65 65 28 29 5d 20 6f 6e 20  ite3_free()] on 
2750: 61 6e 79 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73  any error.** mes
2760: 73 61 67 65 20 72 65 74 75 72 6e 65 64 20 74 68  sage returned th
2770: 72 6f 75 67 68 20 74 68 65 20 35 74 68 20 70 61  rough the 5th pa
2780: 72 61 6d 65 74 65 72 20 77 68 65 6e 20 69 74 20  rameter when it 
2790: 68 61 73 20 66 69 6e 69 73 68 65 64 20 75 73 69  has finished usi
27a0: 6e 67 0a 2a 2a 20 74 68 65 20 65 72 72 6f 72 20  ng.** the error 
27b0: 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 49  message..**.** I
27c0: 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  f the SQL statem
27d0: 65 6e 74 20 69 6e 20 74 68 65 20 32 6e 64 20 70  ent in the 2nd p
27e0: 61 72 61 6d 65 74 65 72 20 69 73 20 4e 55 4c 4c  arameter is NULL
27f0: 20 6f 72 20 61 6e 20 65 6d 70 74 79 20 73 74 72   or an empty str
2800: 69 6e 67 0a 2a 2a 20 6f 72 20 61 20 73 74 72 69  ing.** or a stri
2810: 6e 67 20 63 6f 6e 74 61 69 6e 69 6e 67 20 6f 6e  ng containing on
2820: 6c 79 20 77 68 69 74 65 73 70 61 63 65 20 61 6e  ly whitespace an
2830: 64 20 63 6f 6d 6d 65 6e 74 73 2c 20 74 68 65 6e  d comments, then
2840: 20 6e 6f 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65   no SQL.** state
2850: 6d 65 6e 74 73 20 61 72 65 20 65 76 61 6c 75 61  ments are evalua
2860: 74 65 64 20 61 6e 64 20 74 68 65 20 64 61 74 61  ted and the data
2870: 62 61 73 65 20 69 73 20 6e 6f 74 20 63 68 61 6e  base is not chan
2880: 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ged..**.** The s
2890: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 6e  qlite3_exec() in
28a0: 74 65 72 66 61 63 65 20 69 73 20 69 6d 70 6c 65  terface is imple
28b0: 6d 65 6e 74 65 64 20 69 6e 20 74 65 72 6d 73 20  mented in terms 
28c0: 6f 66 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  of.** [sqlite3_p
28d0: 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73  repare_v2()], [s
28e0: 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 20  qlite3_step()], 
28f0: 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  and [sqlite3_fin
2900: 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20 54 68 65  alize()]..** The
2910: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
2920: 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6e 6f 74  routine does not
2930: 68 69 6e 67 20 74 6f 20 74 68 65 20 64 61 74 61  hing to the data
2940: 62 61 73 65 20 74 68 61 74 20 63 61 6e 6e 6f 74  base that cannot
2950: 20 62 65 20 64 6f 6e 65 0a 2a 2a 20 62 79 20 5b   be done.** by [
2960: 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
2970: 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  v2()], [sqlite3_
2980: 73 74 65 70 28 29 5d 2c 20 61 6e 64 20 5b 73 71  step()], and [sq
2990: 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
29a0: 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72  ]..**.** The fir
29b0: 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
29c0: 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d  [sqlite3_exec()]
29d0: 20 6d 75 73 74 20 62 65 20 61 6e 20 76 61 6c 69   must be an vali
29e0: 64 20 61 6e 64 20 6f 70 65 6e 0a 2a 2a 20 5b 64  d and open.** [d
29f0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2a00: 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64  on]..**.** The d
2a10: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2a20: 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 62 65 20 63  on must not be c
2a30: 6c 6f 73 65 64 20 77 68 69 6c 65 0a 2a 2a 20 5b  losed while.** [
2a40: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20  sqlite3_exec()] 
2a50: 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 0a 2a  is running..**.*
2a60: 2a 20 54 68 65 20 63 61 6c 6c 69 6e 67 20 66 75  * The calling fu
2a70: 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73  nction should us
2a80: 65 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  e [sqlite3_free(
2a90: 29 5d 20 74 6f 20 66 72 65 65 0a 2a 2a 20 74 68  )] to free.** th
2aa0: 65 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 2a 65  e memory that *e
2ab0: 72 72 6d 73 67 20 69 73 20 6c 65 66 74 20 70 6f  rrmsg is left po
2ac0: 69 6e 74 69 6e 67 20 61 74 20 6f 6e 63 65 20 74  inting at once t
2ad0: 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73  he error.** mess
2ae0: 61 67 65 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72  age is no longer
2af0: 20 6e 65 65 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 54   needed..**.** T
2b00: 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
2b10: 20 74 65 78 74 20 69 6e 20 74 68 65 20 32 6e 64   text in the 2nd
2b20: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73   parameter to [s
2b30: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 0a 2a  qlite3_exec()].*
2b40: 2a 20 6d 75 73 74 20 72 65 6d 61 69 6e 20 75 6e  * must remain un
2b50: 63 68 61 6e 67 65 64 20 77 68 69 6c 65 20 5b 73  changed while [s
2b60: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 69  qlite3_exec()] i
2b70: 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a  s running..**.**
2b80: 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a   Requirements:.*
2b90: 2a 20 5b 48 31 32 31 30 31 5d 20 5b 48 31 32 31  * [H12101] [H121
2ba0: 30 32 5d 20 5b 48 31 32 31 30 34 5d 20 5b 48 31  02] [H12104] [H1
2bb0: 32 31 30 35 5d 20 5b 48 31 32 31 30 37 5d 20 5b  2105] [H12107] [
2bc0: 48 31 32 31 31 30 5d 20 5b 48 31 32 31 31 33 5d  H12110] [H12113]
2bd0: 20 5b 48 31 32 31 31 36 5d 0a 2a 2a 20 5b 48 31   [H12116].** [H1
2be0: 32 31 31 39 5d 20 5b 48 31 32 31 32 32 5d 20 5b  2119] [H12122] [
2bf0: 48 31 32 31 32 35 5d 20 5b 48 31 32 31 33 31 5d  H12125] [H12131]
2c00: 20 5b 48 31 32 31 33 34 5d 20 5b 48 31 32 31 33   [H12134] [H1213
2c10: 37 5d 20 5b 48 31 32 31 33 38 5d 0a 2a 2f 0a 69  7] [H12138].*/.i
2c20: 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  nt sqlite3_exec(
2c30: 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 20 20 20  .  sqlite3*,    
2c40: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2c50: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
2c60: 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73   An open databas
2c70: 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
2c80: 72 20 2a 73 71 6c 2c 20 20 20 20 20 20 20 20 20  r *sql,         
2c90: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2ca0: 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65    /* SQL to be e
2cb0: 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 69 6e  valuated */.  in
2cc0: 74 20 28 2a 63 61 6c 6c 62 61 63 6b 29 28 76 6f  t (*callback)(vo
2cd0: 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 63  id*,int,char**,c
2ce0: 68 61 72 2a 2a 29 2c 20 20 2f 2a 20 43 61 6c 6c  har**),  /* Call
2cf0: 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 2a 2f  back function */
2d00: 0a 20 20 76 6f 69 64 20 2a 2c 20 20 20 20 20 20  .  void *,      
2d10: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2d20: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
2d30: 20 31 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f   1st argument to
2d40: 20 63 61 6c 6c 62 61 63 6b 20 2a 2f 0a 20 20 63   callback */.  c
2d50: 68 61 72 20 2a 2a 65 72 72 6d 73 67 20 20 20 20  har **errmsg    
2d60: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2d70: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 45 72 72            /* Err
2d80: 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68  or msg written h
2d90: 65 72 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  ere */.);../*.**
2da0: 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c   CAPI3REF: Resul
2db0: 74 20 43 6f 64 65 73 20 7b 48 31 30 32 31 30 7d  t Codes {H10210}
2dc0: 20 3c 53 31 30 37 30 30 3e 0a 2a 2a 20 4b 45 59   <S10700>.** KEY
2dd0: 57 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 4f 4b  WORDS: SQLITE_OK
2de0: 20 7b 65 72 72 6f 72 20 63 6f 64 65 7d 20 7b 65   {error code} {e
2df0: 72 72 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b  rror codes}.** K
2e00: 45 59 57 4f 52 44 53 3a 20 7b 72 65 73 75 6c 74  EYWORDS: {result
2e10: 20 63 6f 64 65 7d 20 7b 72 65 73 75 6c 74 20 63   code} {result c
2e20: 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79  odes}.**.** Many
2e30: 20 53 51 4c 69 74 65 20 66 75 6e 63 74 69 6f 6e   SQLite function
2e40: 73 20 72 65 74 75 72 6e 20 61 6e 20 69 6e 74 65  s return an inte
2e50: 67 65 72 20 72 65 73 75 6c 74 20 63 6f 64 65 20  ger result code 
2e60: 66 72 6f 6d 20 74 68 65 20 73 65 74 20 73 68 6f  from the set sho
2e70: 77 6e 0a 2a 2a 20 68 65 72 65 20 69 6e 20 6f 72  wn.** here in or
2e80: 64 65 72 20 74 6f 20 69 6e 64 69 63 61 74 65 73  der to indicates
2e90: 20 73 75 63 63 65 73 73 20 6f 72 20 66 61 69 6c   success or fail
2ea0: 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65  ure..**.** New e
2eb0: 72 72 6f 72 20 63 6f 64 65 73 20 6d 61 79 20 62  rror codes may b
2ec0: 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72  e added in futur
2ed0: 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  e versions of SQ
2ee0: 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  Lite..**.** See 
2ef0: 61 6c 73 6f 3a 20 5b 53 51 4c 49 54 45 5f 49 4f  also: [SQLITE_IO
2f00: 45 52 52 5f 52 45 41 44 20 7c 20 65 78 74 65 6e  ERR_READ | exten
2f10: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
2f20: 5d 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ].*/.#define SQL
2f30: 49 54 45 5f 4f 4b 20 20 20 20 20 20 20 20 20 20  ITE_OK          
2f40: 20 30 20 20 20 2f 2a 20 53 75 63 63 65 73 73 66   0   /* Successf
2f50: 75 6c 20 72 65 73 75 6c 74 20 2a 2f 0a 2f 2a 20  ul result */./* 
2f60: 62 65 67 69 6e 6e 69 6e 67 2d 6f 66 2d 65 72 72  beginning-of-err
2f70: 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 23 64 65 66  or-codes */.#def
2f80: 69 6e 65 20 53 51 4c 49 54 45 5f 45 52 52 4f 52  ine SQLITE_ERROR
2f90: 20 20 20 20 20 20 20 20 31 20 20 20 2f 2a 20 53          1   /* S
2fa0: 51 4c 20 65 72 72 6f 72 20 6f 72 20 6d 69 73 73  QL error or miss
2fb0: 69 6e 67 20 64 61 74 61 62 61 73 65 20 2a 2f 0a  ing database */.
2fc0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
2fd0: 4e 54 45 52 4e 41 4c 20 20 20 20 20 32 20 20 20  NTERNAL     2   
2fe0: 2f 2a 20 49 6e 74 65 72 6e 61 6c 20 6c 6f 67 69  /* Internal logi
2ff0: 63 20 65 72 72 6f 72 20 69 6e 20 53 51 4c 69 74  c error in SQLit
3000: 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  e */.#define SQL
3010: 49 54 45 5f 50 45 52 4d 20 20 20 20 20 20 20 20  ITE_PERM        
3020: 20 33 20 20 20 2f 2a 20 41 63 63 65 73 73 20 70   3   /* Access p
3030: 65 72 6d 69 73 73 69 6f 6e 20 64 65 6e 69 65 64  ermission denied
3040: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
3050: 54 45 5f 41 42 4f 52 54 20 20 20 20 20 20 20 20  TE_ABORT        
3060: 34 20 20 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20  4   /* Callback 
3070: 72 6f 75 74 69 6e 65 20 72 65 71 75 65 73 74 65  routine requeste
3080: 64 20 61 6e 20 61 62 6f 72 74 20 2a 2f 0a 23 64  d an abort */.#d
3090: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53  efine SQLITE_BUS
30a0: 59 20 20 20 20 20 20 20 20 20 35 20 20 20 2f 2a  Y         5   /*
30b0: 20 54 68 65 20 64 61 74 61 62 61 73 65 20 66 69   The database fi
30c0: 6c 65 20 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a  le is locked */.
30d0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
30e0: 4f 43 4b 45 44 20 20 20 20 20 20 20 36 20 20 20  OCKED       6   
30f0: 2f 2a 20 41 20 74 61 62 6c 65 20 69 6e 20 74 68  /* A table in th
3100: 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6c 6f  e database is lo
3110: 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  cked */.#define 
3120: 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 20 20 20  SQLITE_NOMEM    
3130: 20 20 20 20 37 20 20 20 2f 2a 20 41 20 6d 61 6c      7   /* A mal
3140: 6c 6f 63 28 29 20 66 61 69 6c 65 64 20 2a 2f 0a  loc() failed */.
3150: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
3160: 45 41 44 4f 4e 4c 59 20 20 20 20 20 38 20 20 20  EADONLY     8   
3170: 2f 2a 20 41 74 74 65 6d 70 74 20 74 6f 20 77 72  /* Attempt to wr
3180: 69 74 65 20 61 20 72 65 61 64 6f 6e 6c 79 20 64  ite a readonly d
3190: 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 65 66 69  atabase */.#defi
31a0: 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 52 52  ne SQLITE_INTERR
31b0: 55 50 54 20 20 20 20 39 20 20 20 2f 2a 20 4f 70  UPT    9   /* Op
31c0: 65 72 61 74 69 6f 6e 20 74 65 72 6d 69 6e 61 74  eration terminat
31d0: 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e  ed by sqlite3_in
31e0: 74 65 72 72 75 70 74 28 29 2a 2f 0a 23 64 65 66  terrupt()*/.#def
31f0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
3200: 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20 53         10   /* S
3210: 6f 6d 65 20 6b 69 6e 64 20 6f 66 20 64 69 73 6b  ome kind of disk
3220: 20 49 2f 4f 20 65 72 72 6f 72 20 6f 63 63 75 72   I/O error occur
3230: 72 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  red */.#define S
3240: 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20 20 20  QLITE_CORRUPT   
3250: 20 20 31 31 20 20 20 2f 2a 20 54 68 65 20 64 61    11   /* The da
3260: 74 61 62 61 73 65 20 64 69 73 6b 20 69 6d 61 67  tabase disk imag
3270: 65 20 69 73 20 6d 61 6c 66 6f 72 6d 65 64 20 2a  e is malformed *
3280: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
3290: 5f 4e 4f 54 46 4f 55 4e 44 20 20 20 20 31 32 20  _NOTFOUND    12 
32a0: 20 20 2f 2a 20 4e 4f 54 20 55 53 45 44 2e 20 54    /* NOT USED. T
32b0: 61 62 6c 65 20 6f 72 20 72 65 63 6f 72 64 20 6e  able or record n
32c0: 6f 74 20 66 6f 75 6e 64 20 2a 2f 0a 23 64 65 66  ot found */.#def
32d0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 4c 4c 20  ine SQLITE_FULL 
32e0: 20 20 20 20 20 20 20 31 33 20 20 20 2f 2a 20 49         13   /* I
32f0: 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c 65 64 20  nsertion failed 
3300: 62 65 63 61 75 73 65 20 64 61 74 61 62 61 73 65  because database
3310: 20 69 73 20 66 75 6c 6c 20 2a 2f 0a 23 64 65 66   is full */.#def
3320: 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f  ine SQLITE_CANTO
3330: 50 45 4e 20 20 20 20 31 34 20 20 20 2f 2a 20 55  PEN    14   /* U
3340: 6e 61 62 6c 65 20 74 6f 20 6f 70 65 6e 20 74 68  nable to open th
3350: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
3360: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
3370: 45 5f 50 52 4f 54 4f 43 4f 4c 20 20 20 20 31 35  E_PROTOCOL    15
3380: 20 20 20 2f 2a 20 4e 4f 54 20 55 53 45 44 2e 20     /* NOT USED. 
3390: 44 61 74 61 62 61 73 65 20 6c 6f 63 6b 20 70 72  Database lock pr
33a0: 6f 74 6f 63 6f 6c 20 65 72 72 6f 72 20 2a 2f 0a  otocol error */.
33b0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45  #define SQLITE_E
33c0: 4d 50 54 59 20 20 20 20 20 20 20 31 36 20 20 20  MPTY       16   
33d0: 2f 2a 20 44 61 74 61 62 61 73 65 20 69 73 20 65  /* Database is e
33e0: 6d 70 74 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  mpty */.#define 
33f0: 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 20 20 20  SQLITE_SCHEMA   
3400: 20 20 20 31 37 20 20 20 2f 2a 20 54 68 65 20 64     17   /* The d
3410: 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 20 63  atabase schema c
3420: 68 61 6e 67 65 64 20 2a 2f 0a 23 64 65 66 69 6e  hanged */.#defin
3430: 65 20 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47 20  e SQLITE_TOOBIG 
3440: 20 20 20 20 20 31 38 20 20 20 2f 2a 20 53 74 72       18   /* Str
3450: 69 6e 67 20 6f 72 20 42 4c 4f 42 20 65 78 63 65  ing or BLOB exce
3460: 65 64 73 20 73 69 7a 65 20 6c 69 6d 69 74 20 2a  eds size limit *
3470: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
3480: 5f 43 4f 4e 53 54 52 41 49 4e 54 20 20 31 39 20  _CONSTRAINT  19 
3490: 20 20 2f 2a 20 41 62 6f 72 74 20 64 75 65 20 74    /* Abort due t
34a0: 6f 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f  o constraint vio
34b0: 6c 61 74 69 6f 6e 20 2a 2f 0a 23 64 65 66 69 6e  lation */.#defin
34c0: 65 20 53 51 4c 49 54 45 5f 4d 49 53 4d 41 54 43  e SQLITE_MISMATC
34d0: 48 20 20 20 20 32 30 20 20 20 2f 2a 20 44 61 74  H    20   /* Dat
34e0: 61 20 74 79 70 65 20 6d 69 73 6d 61 74 63 68 20  a type mismatch 
34f0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
3500: 45 5f 4d 49 53 55 53 45 20 20 20 20 20 20 32 31  E_MISUSE      21
3510: 20 20 20 2f 2a 20 4c 69 62 72 61 72 79 20 75 73     /* Library us
3520: 65 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 2a  ed incorrectly *
3530: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
3540: 5f 4e 4f 4c 46 53 20 20 20 20 20 20 20 32 32 20  _NOLFS       22 
3550: 20 20 2f 2a 20 55 73 65 73 20 4f 53 20 66 65 61    /* Uses OS fea
3560: 74 75 72 65 73 20 6e 6f 74 20 73 75 70 70 6f 72  tures not suppor
3570: 74 65 64 20 6f 6e 20 68 6f 73 74 20 2a 2f 0a 23  ted on host */.#
3580: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 55  define SQLITE_AU
3590: 54 48 20 20 20 20 20 20 20 20 32 33 20 20 20 2f  TH        23   /
35a0: 2a 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20  * Authorization 
35b0: 64 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e  denied */.#defin
35c0: 65 20 53 51 4c 49 54 45 5f 46 4f 52 4d 41 54 20  e SQLITE_FORMAT 
35d0: 20 20 20 20 20 32 34 20 20 20 2f 2a 20 41 75 78       24   /* Aux
35e0: 69 6c 69 61 72 79 20 64 61 74 61 62 61 73 65 20  iliary database 
35f0: 66 6f 72 6d 61 74 20 65 72 72 6f 72 20 2a 2f 0a  format error */.
3600: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
3610: 41 4e 47 45 20 20 20 20 20 20 20 32 35 20 20 20  ANGE       25   
3620: 2f 2a 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  /* 2nd parameter
3630: 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   to sqlite3_bind
3640: 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 2a 2f   out of range */
3650: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
3660: 4e 4f 54 41 44 42 20 20 20 20 20 20 32 36 20 20  NOTADB      26  
3670: 20 2f 2a 20 46 69 6c 65 20 6f 70 65 6e 65 64 20   /* File opened 
3680: 74 68 61 74 20 69 73 20 6e 6f 74 20 61 20 64 61  that is not a da
3690: 74 61 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23  tabase file */.#
36a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 4f  define SQLITE_RO
36b0: 57 20 20 20 20 20 20 20 20 20 31 30 30 20 20 2f  W         100  /
36c0: 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  * sqlite3_step()
36d0: 20 68 61 73 20 61 6e 6f 74 68 65 72 20 72 6f 77   has another row
36e0: 20 72 65 61 64 79 20 2a 2f 0a 23 64 65 66 69 6e   ready */.#defin
36f0: 65 20 53 51 4c 49 54 45 5f 44 4f 4e 45 20 20 20  e SQLITE_DONE   
3700: 20 20 20 20 20 31 30 31 20 20 2f 2a 20 73 71 6c       101  /* sql
3710: 69 74 65 33 5f 73 74 65 70 28 29 20 68 61 73 20  ite3_step() has 
3720: 66 69 6e 69 73 68 65 64 20 65 78 65 63 75 74 69  finished executi
3730: 6e 67 20 2a 2f 0a 2f 2a 20 65 6e 64 2d 6f 66 2d  ng */./* end-of-
3740: 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 0a  error-codes */..
3750: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
3760: 45 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20  Extended Result 
3770: 43 6f 64 65 73 20 7b 48 31 30 32 32 30 7d 20 3c  Codes {H10220} <
3780: 53 31 30 37 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f  S10700>.** KEYWO
3790: 52 44 53 3a 20 7b 65 78 74 65 6e 64 65 64 20 65  RDS: {extended e
37a0: 72 72 6f 72 20 63 6f 64 65 7d 20 7b 65 78 74 65  rror code} {exte
37b0: 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 73  nded error codes
37c0: 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  }.** KEYWORDS: {
37d0: 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
37e0: 63 6f 64 65 7d 20 7b 65 78 74 65 6e 64 65 64 20  code} {extended 
37f0: 72 65 73 75 6c 74 20 63 6f 64 65 73 7d 0a 2a 2a  result codes}.**
3800: 0a 2a 2a 20 49 6e 20 69 74 73 20 64 65 66 61 75  .** In its defau
3810: 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  lt configuration
3820: 2c 20 53 51 4c 69 74 65 20 41 50 49 20 72 6f 75  , SQLite API rou
3830: 74 69 6e 65 73 20 72 65 74 75 72 6e 20 6f 6e 65  tines return one
3840: 20 6f 66 20 32 36 20 69 6e 74 65 67 65 72 0a 2a   of 26 integer.*
3850: 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 20 7c 20 72  * [SQLITE_OK | r
3860: 65 73 75 6c 74 20 63 6f 64 65 73 5d 2e 20 20 48  esult codes].  H
3870: 6f 77 65 76 65 72 2c 20 65 78 70 65 72 69 65 6e  owever, experien
3880: 63 65 20 68 61 73 20 73 68 6f 77 6e 20 74 68 61  ce has shown tha
3890: 74 20 6d 61 6e 79 20 6f 66 0a 2a 2a 20 74 68 65  t many of.** the
38a0: 73 65 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20  se result codes 
38b0: 61 72 65 20 74 6f 6f 20 63 6f 61 72 73 65 2d 67  are too coarse-g
38c0: 72 61 69 6e 65 64 2e 20 20 54 68 65 79 20 64 6f  rained.  They do
38d0: 20 6e 6f 74 20 70 72 6f 76 69 64 65 20 61 73 0a   not provide as.
38e0: 2a 2a 20 6d 75 63 68 20 69 6e 66 6f 72 6d 61 74  ** much informat
38f0: 69 6f 6e 20 61 62 6f 75 74 20 70 72 6f 62 6c 65  ion about proble
3900: 6d 73 20 61 73 20 70 72 6f 67 72 61 6d 6d 65 72  ms as programmer
3910: 73 20 6d 69 67 68 74 20 6c 69 6b 65 2e 20 20 49  s might like.  I
3920: 6e 20 61 6e 20 65 66 66 6f 72 74 20 74 6f 0a 2a  n an effort to.*
3930: 2a 20 61 64 64 72 65 73 73 20 74 68 69 73 2c 20  * address this, 
3940: 6e 65 77 65 72 20 76 65 72 73 69 6f 6e 73 20 6f  newer versions o
3950: 66 20 53 51 4c 69 74 65 20 28 76 65 72 73 69 6f  f SQLite (versio
3960: 6e 20 33 2e 33 2e 38 20 61 6e 64 20 6c 61 74 65  n 3.3.8 and late
3970: 72 29 20 69 6e 63 6c 75 64 65 0a 2a 2a 20 73 75  r) include.** su
3980: 70 70 6f 72 74 20 66 6f 72 20 61 64 64 69 74 69  pport for additi
3990: 6f 6e 61 6c 20 72 65 73 75 6c 74 20 63 6f 64 65  onal result code
39a0: 73 20 74 68 61 74 20 70 72 6f 76 69 64 65 20 6d  s that provide m
39b0: 6f 72 65 20 64 65 74 61 69 6c 65 64 20 69 6e 66  ore detailed inf
39c0: 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75  ormation.** abou
39d0: 74 20 65 72 72 6f 72 73 2e 20 54 68 65 20 65 78  t errors. The ex
39e0: 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
39f0: 64 65 73 20 61 72 65 20 65 6e 61 62 6c 65 64 20  des are enabled 
3a00: 6f 72 20 64 69 73 61 62 6c 65 64 0a 2a 2a 20 6f  or disabled.** o
3a10: 6e 20 61 20 70 65 72 20 64 61 74 61 62 61 73 65  n a per database
3a20: 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73 69   connection basi
3a30: 73 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b  s using the.** [
3a40: 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64  sqlite3_extended
3a50: 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29 5d  _result_codes()]
3a60: 20 41 50 49 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d 65   API..**.** Some
3a70: 20 6f 66 20 74 68 65 20 61 76 61 69 6c 61 62 6c   of the availabl
3a80: 65 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c  e extended resul
3a90: 74 20 63 6f 64 65 73 20 61 72 65 20 6c 69 73 74  t codes are list
3aa0: 65 64 20 68 65 72 65 2e 0a 2a 2a 20 4f 6e 65 20  ed here..** One 
3ab0: 6d 61 79 20 65 78 70 65 63 74 20 74 68 65 20 6e  may expect the n
3ac0: 75 6d 62 65 72 20 6f 66 20 65 78 74 65 6e 64 65  umber of extende
3ad0: 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 77  d result codes w
3ae0: 69 6c 6c 20 62 65 20 65 78 70 61 6e 64 0a 2a 2a  ill be expand.**
3af0: 20 6f 76 65 72 20 74 69 6d 65 2e 20 20 53 6f 66   over time.  Sof
3b00: 74 77 61 72 65 20 74 68 61 74 20 75 73 65 73 20  tware that uses 
3b10: 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
3b20: 63 6f 64 65 73 20 73 68 6f 75 6c 64 20 65 78 70  codes should exp
3b30: 65 63 74 0a 2a 2a 20 74 6f 20 73 65 65 20 6e 65  ect.** to see ne
3b40: 77 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 69  w result codes i
3b50: 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  n future release
3b60: 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a  s of SQLite..**.
3b70: 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 4f 4b  ** The SQLITE_OK
3b80: 20 72 65 73 75 6c 74 20 63 6f 64 65 20 77 69 6c   result code wil
3b90: 6c 20 6e 65 76 65 72 20 62 65 20 65 78 74 65 6e  l never be exten
3ba0: 64 65 64 2e 20 20 49 74 20 77 69 6c 6c 20 61 6c  ded.  It will al
3bb0: 77 61 79 73 0a 2a 2a 20 62 65 20 65 78 61 63 74  ways.** be exact
3bc0: 6c 79 20 7a 65 72 6f 2e 0a 2a 2f 0a 23 64 65 66  ly zero..*/.#def
3bd0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
3be0: 5f 52 45 41 44 20 20 20 20 20 20 20 20 20 20 20  _READ           
3bf0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
3c00: 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69   | (1<<8)).#defi
3c10: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
3c20: 53 48 4f 52 54 5f 52 45 41 44 20 20 20 20 20 20  SHORT_READ      
3c30: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
3c40: 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (2<<8)).#defin
3c50: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 57  e SQLITE_IOERR_W
3c60: 52 49 54 45 20 20 20 20 20 20 20 20 20 20 20 20  RITE            
3c70: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
3c80: 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (3<<8)).#define
3c90: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46 53   SQLITE_IOERR_FS
3ca0: 59 4e 43 20 20 20 20 20 20 20 20 20 20 20 20 20  YNC             
3cb0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
3cc0: 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (4<<8)).#define 
3cd0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49 52  SQLITE_IOERR_DIR
3ce0: 5f 46 53 59 4e 43 20 20 20 20 20 20 20 20 20 28  _FSYNC         (
3cf0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
3d00: 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  5<<8)).#define S
3d10: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 54 52 55 4e  QLITE_IOERR_TRUN
3d20: 43 41 54 45 20 20 20 20 20 20 20 20 20 20 28 53  CATE          (S
3d30: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 36  QLITE_IOERR | (6
3d40: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
3d50: 4c 49 54 45 5f 49 4f 45 52 52 5f 46 53 54 41 54  LITE_IOERR_FSTAT
3d60: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51               (SQ
3d70: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 37 3c  LITE_IOERR | (7<
3d80: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
3d90: 49 54 45 5f 49 4f 45 52 52 5f 55 4e 4c 4f 43 4b  ITE_IOERR_UNLOCK
3da0: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
3db0: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 38 3c 3c  ITE_IOERR | (8<<
3dc0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
3dd0: 54 45 5f 49 4f 45 52 52 5f 52 44 4c 4f 43 4b 20  TE_IOERR_RDLOCK 
3de0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
3df0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 39 3c 3c 38  TE_IOERR | (9<<8
3e00: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
3e10: 45 5f 49 4f 45 52 52 5f 44 45 4c 45 54 45 20 20  E_IOERR_DELETE  
3e20: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
3e30: 45 5f 49 4f 45 52 52 20 7c 20 28 31 30 3c 3c 38  E_IOERR | (10<<8
3e40: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
3e50: 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 20  E_IOERR_BLOCKED 
3e60: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
3e70: 45 5f 49 4f 45 52 52 20 7c 20 28 31 31 3c 3c 38  E_IOERR | (11<<8
3e80: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
3e90: 45 5f 49 4f 45 52 52 5f 4e 4f 4d 45 4d 20 20 20  E_IOERR_NOMEM   
3ea0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
3eb0: 45 5f 49 4f 45 52 52 20 7c 20 28 31 32 3c 3c 38  E_IOERR | (12<<8
3ec0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
3ed0: 45 5f 49 4f 45 52 52 5f 41 43 43 45 53 53 20 20  E_IOERR_ACCESS  
3ee0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
3ef0: 45 5f 49 4f 45 52 52 20 7c 20 28 31 33 3c 3c 38  E_IOERR | (13<<8
3f00: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
3f10: 45 5f 49 4f 45 52 52 5f 43 48 45 43 4b 52 45 53  E_IOERR_CHECKRES
3f20: 45 52 56 45 44 4c 4f 43 4b 20 28 53 51 4c 49 54  ERVEDLOCK (SQLIT
3f30: 45 5f 49 4f 45 52 52 20 7c 20 28 31 34 3c 3c 38  E_IOERR | (14<<8
3f40: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
3f50: 45 5f 49 4f 45 52 52 5f 4c 4f 43 4b 20 20 20 20  E_IOERR_LOCK    
3f60: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
3f70: 45 5f 49 4f 45 52 52 20 7c 20 28 31 35 3c 3c 38  E_IOERR | (15<<8
3f80: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
3f90: 45 5f 49 4f 45 52 52 5f 43 4c 4f 53 45 20 20 20  E_IOERR_CLOSE   
3fa0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
3fb0: 45 5f 49 4f 45 52 52 20 7c 20 28 31 36 3c 3c 38  E_IOERR | (16<<8
3fc0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
3fd0: 45 5f 49 4f 45 52 52 5f 44 49 52 5f 43 4c 4f 53  E_IOERR_DIR_CLOS
3fe0: 45 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54  E         (SQLIT
3ff0: 45 5f 49 4f 45 52 52 20 7c 20 28 31 37 3c 3c 38  E_IOERR | (17<<8
4000: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
4010: 45 5f 4c 4f 43 4b 45 44 5f 53 48 41 52 45 44 43  E_LOCKED_SHAREDC
4020: 41 43 48 45 20 20 20 20 20 20 28 53 51 4c 49 54  ACHE      (SQLIT
4030: 45 5f 4c 4f 43 4b 45 44 20 7c 20 28 31 3c 3c 38  E_LOCKED | (1<<8
4040: 29 20 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  ) )../*.** CAPI3
4050: 52 45 46 3a 20 46 6c 61 67 73 20 46 6f 72 20 46  REF: Flags For F
4060: 69 6c 65 20 4f 70 65 6e 20 4f 70 65 72 61 74 69  ile Open Operati
4070: 6f 6e 73 20 7b 48 31 30 32 33 30 7d 20 3c 48 31  ons {H10230} <H1
4080: 31 31 32 30 3e 20 3c 48 31 32 37 30 30 3e 0a 2a  1120> <H12700>.*
4090: 2a 0a 2a 2a 20 54 68 65 73 65 20 62 69 74 20 76  *.** These bit v
40a0: 61 6c 75 65 73 20 61 72 65 20 69 6e 74 65 6e 64  alues are intend
40b0: 65 64 20 66 6f 72 20 75 73 65 20 69 6e 20 74 68  ed for use in th
40c0: 65 0a 2a 2a 20 33 72 64 20 70 61 72 61 6d 65 74  e.** 3rd paramet
40d0: 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  er to the [sqlit
40e0: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e  e3_open_v2()] in
40f0: 74 65 72 66 61 63 65 20 61 6e 64 0a 2a 2a 20 69  terface and.** i
4100: 6e 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65  n the 4th parame
4110: 74 65 72 20 74 6f 20 74 68 65 20 78 4f 70 65 6e  ter to the xOpen
4120: 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 0a 2a   method of the.*
4130: 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  * [sqlite3_vfs] 
4140: 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 23 64 65 66 69  object..*/.#defi
4150: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  ne SQLITE_OPEN_R
4160: 45 41 44 4f 4e 4c 59 20 20 20 20 20 20 20 20 20  EADONLY         
4170: 30 78 30 30 30 30 30 30 30 31 20 20 2f 2a 20 4f  0x00000001  /* O
4180: 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  k for sqlite3_op
4190: 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69  en_v2() */.#defi
41a0: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  ne SQLITE_OPEN_R
41b0: 45 41 44 57 52 49 54 45 20 20 20 20 20 20 20 20  EADWRITE        
41c0: 30 78 30 30 30 30 30 30 30 32 20 20 2f 2a 20 4f  0x00000002  /* O
41d0: 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  k for sqlite3_op
41e0: 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69  en_v2() */.#defi
41f0: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43  ne SQLITE_OPEN_C
4200: 52 45 41 54 45 20 20 20 20 20 20 20 20 20 20 20  REATE           
4210: 30 78 30 30 30 30 30 30 30 34 20 20 2f 2a 20 4f  0x00000004  /* O
4220: 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  k for sqlite3_op
4230: 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69  en_v2() */.#defi
4240: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44  ne SQLITE_OPEN_D
4250: 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 20 20 20 20  ELETEONCLOSE    
4260: 30 78 30 30 30 30 30 30 30 38 20 20 2f 2a 20 56  0x00000008  /* V
4270: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
4280: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45  ne SQLITE_OPEN_E
4290: 58 43 4c 55 53 49 56 45 20 20 20 20 20 20 20 20  XCLUSIVE        
42a0: 30 78 30 30 30 30 30 30 31 30 20 20 2f 2a 20 56  0x00000010  /* V
42b0: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
42c0: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d  ne SQLITE_OPEN_M
42d0: 41 49 4e 5f 44 42 20 20 20 20 20 20 20 20 20 20  AIN_DB          
42e0: 30 78 30 30 30 30 30 31 30 30 20 20 2f 2a 20 56  0x00000100  /* V
42f0: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
4300: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54  ne SQLITE_OPEN_T
4310: 45 4d 50 5f 44 42 20 20 20 20 20 20 20 20 20 20  EMP_DB          
4320: 30 78 30 30 30 30 30 32 30 30 20 20 2f 2a 20 56  0x00000200  /* V
4330: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
4340: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54  ne SQLITE_OPEN_T
4350: 52 41 4e 53 49 45 4e 54 5f 44 42 20 20 20 20 20  RANSIENT_DB     
4360: 30 78 30 30 30 30 30 34 30 30 20 20 2f 2a 20 56  0x00000400  /* V
4370: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
4380: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d  ne SQLITE_OPEN_M
4390: 41 49 4e 5f 4a 4f 55 52 4e 41 4c 20 20 20 20 20  AIN_JOURNAL     
43a0: 30 78 30 30 30 30 30 38 30 30 20 20 2f 2a 20 56  0x00000800  /* V
43b0: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
43c0: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54  ne SQLITE_OPEN_T
43d0: 45 4d 50 5f 4a 4f 55 52 4e 41 4c 20 20 20 20 20  EMP_JOURNAL     
43e0: 30 78 30 30 30 30 31 30 30 30 20 20 2f 2a 20 56  0x00001000  /* V
43f0: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
4400: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53  ne SQLITE_OPEN_S
4410: 55 42 4a 4f 55 52 4e 41 4c 20 20 20 20 20 20 20  UBJOURNAL       
4420: 30 78 30 30 30 30 32 30 30 30 20 20 2f 2a 20 56  0x00002000  /* V
4430: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
4440: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d  ne SQLITE_OPEN_M
4450: 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 20 20 20  ASTER_JOURNAL   
4460: 30 78 30 30 30 30 34 30 30 30 20 20 2f 2a 20 56  0x00004000  /* V
4470: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
4480: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e  ne SQLITE_OPEN_N
4490: 4f 4d 55 54 45 58 20 20 20 20 20 20 20 20 20 20  OMUTEX          
44a0: 30 78 30 30 30 30 38 30 30 30 20 20 2f 2a 20 4f  0x00008000  /* O
44b0: 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  k for sqlite3_op
44c0: 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69  en_v2() */.#defi
44d0: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46  ne SQLITE_OPEN_F
44e0: 55 4c 4c 4d 55 54 45 58 20 20 20 20 20 20 20 20  ULLMUTEX        
44f0: 30 78 30 30 30 31 30 30 30 30 20 20 2f 2a 20 4f  0x00010000  /* O
4500: 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  k for sqlite3_op
4510: 65 6e 5f 76 32 28 29 20 2a 2f 0a 0a 2f 2a 0a 2a  en_v2() */../*.*
4520: 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 76 69  * CAPI3REF: Devi
4530: 63 65 20 43 68 61 72 61 63 74 65 72 69 73 74 69  ce Characteristi
4540: 63 73 20 7b 48 31 30 32 34 30 7d 20 3c 48 31 31  cs {H10240} <H11
4550: 31 32 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  120>.**.** The x
4560: 44 65 76 69 63 65 43 61 70 61 62 69 6c 69 74 69  DeviceCapabiliti
4570: 65 73 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65  es method of the
4580: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
4590: 68 6f 64 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20  hods].** object 
45a0: 72 65 74 75 72 6e 73 20 61 6e 20 69 6e 74 65 67  returns an integ
45b0: 65 72 20 77 68 69 63 68 20 69 73 20 61 20 76 65  er which is a ve
45c0: 63 74 6f 72 20 6f 66 20 74 68 65 20 74 68 65 73  ctor of the thes
45d0: 65 0a 2a 2a 20 62 69 74 20 76 61 6c 75 65 73 20  e.** bit values 
45e0: 65 78 70 72 65 73 73 69 6e 67 20 49 2f 4f 20 63  expressing I/O c
45f0: 68 61 72 61 63 74 65 72 69 73 74 69 63 73 20 6f  haracteristics o
4600: 66 20 74 68 65 20 6d 61 73 73 20 73 74 6f 72 61  f the mass stora
4610: 67 65 0a 2a 2a 20 64 65 76 69 63 65 20 74 68 61  ge.** device tha
4620: 74 20 68 6f 6c 64 73 20 74 68 65 20 66 69 6c 65  t holds the file
4630: 20 74 68 61 74 20 74 68 65 20 5b 73 71 6c 69 74   that the [sqlit
4640: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a  e3_io_methods].*
4650: 2a 20 72 65 66 65 72 73 20 74 6f 2e 0a 2a 2a 0a  * refers to..**.
4660: 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  ** The SQLITE_IO
4670: 43 41 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65  CAP_ATOMIC prope
4680: 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 20 61  rty means that a
4690: 6c 6c 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20  ll writes of.** 
46a0: 61 6e 79 20 73 69 7a 65 20 61 72 65 20 61 74 6f  any size are ato
46b0: 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45  mic.  The SQLITE
46c0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e  _IOCAP_ATOMICnnn
46d0: 20 76 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20   values.** mean 
46e0: 74 68 61 74 20 77 72 69 74 65 73 20 6f 66 20 62  that writes of b
46f0: 6c 6f 63 6b 73 20 74 68 61 74 20 61 72 65 20 6e  locks that are n
4700: 6e 6e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65  nn bytes in size
4710: 20 61 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67   and.** are alig
4720: 6e 65 64 20 74 6f 20 61 6e 20 61 64 64 72 65 73  ned to an addres
4730: 73 20 77 68 69 63 68 20 69 73 20 61 6e 20 69 6e  s which is an in
4740: 74 65 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f  teger multiple o
4750: 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f  f.** nnn are ato
4760: 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45  mic.  The SQLITE
4770: 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45  _IOCAP_SAFE_APPE
4780: 4e 44 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a  ND value means.*
4790: 2a 20 74 68 61 74 20 77 68 65 6e 20 64 61 74 61  * that when data
47a0: 20 69 73 20 61 70 70 65 6e 64 65 64 20 74 6f 20   is appended to 
47b0: 61 20 66 69 6c 65 2c 20 74 68 65 20 64 61 74 61  a file, the data
47c0: 20 69 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20   is appended.** 
47d0: 66 69 72 73 74 20 74 68 65 6e 20 74 68 65 20 73  first then the s
47e0: 69 7a 65 20 6f 66 20 74 68 65 20 66 69 6c 65 20  ize of the file 
47f0: 69 73 20 65 78 74 65 6e 64 65 64 2c 20 6e 65 76  is extended, nev
4800: 65 72 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20  er the other.** 
4810: 77 61 79 20 61 72 6f 75 6e 64 2e 20 20 54 68 65  way around.  The
4820: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45   SQLITE_IOCAP_SE
4830: 51 55 45 4e 54 49 41 4c 20 70 72 6f 70 65 72 74  QUENTIAL propert
4840: 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20  y means that.** 
4850: 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77  information is w
4860: 72 69 74 74 65 6e 20 74 6f 20 64 69 73 6b 20 69  ritten to disk i
4870: 6e 20 74 68 65 20 73 61 6d 65 20 6f 72 64 65 72  n the same order
4880: 20 61 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20   as calls.** to 
4890: 78 57 72 69 74 65 28 29 2e 0a 2a 2f 0a 23 64 65  xWrite()..*/.#de
48a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
48b0: 50 5f 41 54 4f 4d 49 43 20 20 20 20 20 20 20 20  P_ATOMIC        
48c0: 20 20 30 78 30 30 30 30 30 30 30 31 0a 23 64 65    0x00000001.#de
48d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
48e0: 50 5f 41 54 4f 4d 49 43 35 31 32 20 20 20 20 20  P_ATOMIC512     
48f0: 20 20 30 78 30 30 30 30 30 30 30 32 0a 23 64 65    0x00000002.#de
4900: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
4910: 50 5f 41 54 4f 4d 49 43 31 4b 20 20 20 20 20 20  P_ATOMIC1K      
4920: 20 20 30 78 30 30 30 30 30 30 30 34 0a 23 64 65    0x00000004.#de
4930: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
4940: 50 5f 41 54 4f 4d 49 43 32 4b 20 20 20 20 20 20  P_ATOMIC2K      
4950: 20 20 30 78 30 30 30 30 30 30 30 38 0a 23 64 65    0x00000008.#de
4960: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
4970: 50 5f 41 54 4f 4d 49 43 34 4b 20 20 20 20 20 20  P_ATOMIC4K      
4980: 20 20 30 78 30 30 30 30 30 30 31 30 0a 23 64 65    0x00000010.#de
4990: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
49a0: 50 5f 41 54 4f 4d 49 43 38 4b 20 20 20 20 20 20  P_ATOMIC8K      
49b0: 20 20 30 78 30 30 30 30 30 30 32 30 0a 23 64 65    0x00000020.#de
49c0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
49d0: 50 5f 41 54 4f 4d 49 43 31 36 4b 20 20 20 20 20  P_ATOMIC16K     
49e0: 20 20 30 78 30 30 30 30 30 30 34 30 0a 23 64 65    0x00000040.#de
49f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
4a00: 50 5f 41 54 4f 4d 49 43 33 32 4b 20 20 20 20 20  P_ATOMIC32K     
4a10: 20 20 30 78 30 30 30 30 30 30 38 30 0a 23 64 65    0x00000080.#de
4a20: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
4a30: 50 5f 41 54 4f 4d 49 43 36 34 4b 20 20 20 20 20  P_ATOMIC64K     
4a40: 20 20 30 78 30 30 30 30 30 31 30 30 0a 23 64 65    0x00000100.#de
4a50: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
4a60: 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 20 20  P_SAFE_APPEND   
4a70: 20 20 30 78 30 30 30 30 30 32 30 30 0a 23 64 65    0x00000200.#de
4a80: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
4a90: 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 20 20 20  P_SEQUENTIAL    
4aa0: 20 20 30 78 30 30 30 30 30 34 30 30 0a 0a 2f 2a    0x00000400../*
4ab0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 69  .** CAPI3REF: Fi
4ac0: 6c 65 20 4c 6f 63 6b 69 6e 67 20 4c 65 76 65 6c  le Locking Level
4ad0: 73 20 7b 48 31 30 32 35 30 7d 20 3c 48 31 31 31  s {H10250} <H111
4ae0: 32 30 3e 20 3c 48 31 31 33 31 30 3e 0a 2a 2a 0a  20> <H11310>.**.
4af0: 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 6f  ** SQLite uses o
4b00: 6e 65 20 6f 66 20 74 68 65 73 65 20 69 6e 74 65  ne of these inte
4b10: 67 65 72 20 76 61 6c 75 65 73 20 61 73 20 74 68  ger values as th
4b20: 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 61 72 67 75  e second.** argu
4b30: 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 73 20 69 74  ment to calls it
4b40: 20 6d 61 6b 65 73 20 74 6f 20 74 68 65 20 78 4c   makes to the xL
4b50: 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63  ock() and xUnloc
4b60: 6b 28 29 20 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f  k() methods.** o
4b70: 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f  f an [sqlite3_io
4b80: 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74  _methods] object
4b90: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
4ba0: 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20 20 20  ITE_LOCK_NONE   
4bb0: 20 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65         0.#define
4bc0: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41   SQLITE_LOCK_SHA
4bd0: 52 45 44 20 20 20 20 20 20 20 20 31 0a 23 64 65  RED        1.#de
4be0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
4bf0: 5f 52 45 53 45 52 56 45 44 20 20 20 20 20 20 32  _RESERVED      2
4c00: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4c10: 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 20 20 20 20  LOCK_PENDING    
4c20: 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c     3.#define SQL
4c30: 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49  ITE_LOCK_EXCLUSI
4c40: 56 45 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20  VE     4../*.** 
4c50: 43 41 50 49 33 52 45 46 3a 20 53 79 6e 63 68 72  CAPI3REF: Synchr
4c60: 6f 6e 69 7a 61 74 69 6f 6e 20 54 79 70 65 20 46  onization Type F
4c70: 6c 61 67 73 20 7b 48 31 30 32 36 30 7d 20 3c 48  lags {H10260} <H
4c80: 31 31 31 32 30 3e 0a 2a 2a 0a 2a 2a 20 57 68 65  11120>.**.** Whe
4c90: 6e 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73  n SQLite invokes
4ca0: 20 74 68 65 20 78 53 79 6e 63 28 29 20 6d 65 74   the xSync() met
4cb0: 68 6f 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73 71  hod of an.** [sq
4cc0: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
4cd0: 5d 20 6f 62 6a 65 63 74 20 69 74 20 75 73 65 73  ] object it uses
4ce0: 20 61 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f   a combination o
4cf0: 66 0a 2a 2a 20 74 68 65 73 65 20 69 6e 74 65 67  f.** these integ
4d00: 65 72 20 76 61 6c 75 65 73 20 61 73 20 74 68 65  er values as the
4d10: 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
4d20: 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65  ..**.** When the
4d30: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54   SQLITE_SYNC_DAT
4d40: 41 4f 4e 4c 59 20 66 6c 61 67 20 69 73 20 75 73  AONLY flag is us
4d50: 65 64 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61  ed, it means tha
4d60: 74 20 74 68 65 0a 2a 2a 20 73 79 6e 63 20 6f 70  t the.** sync op
4d70: 65 72 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65 65  eration only nee
4d80: 64 73 20 74 6f 20 66 6c 75 73 68 20 64 61 74 61  ds to flush data
4d90: 20 74 6f 20 6d 61 73 73 20 73 74 6f 72 61 67 65   to mass storage
4da0: 2e 20 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66 6f  .  Inode.** info
4db0: 72 6d 61 74 69 6f 6e 20 6e 65 65 64 20 6e 6f 74  rmation need not
4dc0: 20 62 65 20 66 6c 75 73 68 65 64 2e 20 49 66 20   be flushed. If 
4dd0: 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62  the lower four b
4de0: 69 74 73 20 6f 66 20 74 68 65 20 66 6c 61 67 0a  its of the flag.
4df0: 2a 2a 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f  ** equal SQLITE_
4e00: 53 59 4e 43 5f 4e 4f 52 4d 41 4c 2c 20 74 68 61  SYNC_NORMAL, tha
4e10: 74 20 6d 65 61 6e 73 20 74 6f 20 75 73 65 20 6e  t means to use n
4e20: 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 20 73 65  ormal fsync() se
4e30: 6d 61 6e 74 69 63 73 2e 0a 2a 2a 20 49 66 20 74  mantics..** If t
4e40: 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69  he lower four bi
4e50: 74 73 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f  ts equal SQLITE_
4e60: 53 59 4e 43 5f 46 55 4c 4c 2c 20 74 68 61 74 20  SYNC_FULL, that 
4e70: 6d 65 61 6e 73 0a 2a 2a 20 74 6f 20 75 73 65 20  means.** to use 
4e80: 4d 61 63 20 4f 53 20 58 20 73 74 79 6c 65 20 66  Mac OS X style f
4e90: 75 6c 6c 73 79 6e 63 20 69 6e 73 74 65 61 64 20  ullsync instead 
4ea0: 6f 66 20 66 73 79 6e 63 28 29 2e 0a 2a 2f 0a 23  of fsync()..*/.#
4eb0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59  define SQLITE_SY
4ec0: 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20 20 20 20 20  NC_NORMAL       
4ed0: 20 30 78 30 30 30 30 32 0a 23 64 65 66 69 6e 65   0x00002.#define
4ee0: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c   SQLITE_SYNC_FUL
4ef0: 4c 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30  L          0x000
4f00: 30 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  03.#define SQLIT
4f10: 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20  E_SYNC_DATAONLY 
4f20: 20 20 20 20 20 30 78 30 30 30 31 30 0a 0a 2f 2a       0x00010../*
4f30: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53  .** CAPI3REF: OS
4f40: 20 49 6e 74 65 72 66 61 63 65 20 4f 70 65 6e 20   Interface Open 
4f50: 46 69 6c 65 20 48 61 6e 64 6c 65 20 7b 48 31 31  File Handle {H11
4f60: 31 31 30 7d 20 3c 53 32 30 31 31 30 3e 0a 2a 2a  110} <S20110>.**
4f70: 0a 2a 2a 20 41 6e 20 5b 73 71 6c 69 74 65 33 5f  .** An [sqlite3_
4f80: 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 72 65 70  file] object rep
4f90: 72 65 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20  resents an open 
4fa0: 66 69 6c 65 20 69 6e 20 74 68 65 20 4f 53 0a 2a  file in the OS.*
4fb0: 2a 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65  * interface laye
4fc0: 72 2e 20 20 49 6e 64 69 76 69 64 75 61 6c 20 4f  r.  Individual O
4fd0: 53 20 69 6e 74 65 72 66 61 63 65 20 69 6d 70 6c  S interface impl
4fe0: 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c 6c  ementations will
4ff0: 0a 2a 2a 20 77 61 6e 74 20 74 6f 20 73 75 62 63  .** want to subc
5000: 6c 61 73 73 20 74 68 69 73 20 6f 62 6a 65 63 74  lass this object
5010: 20 62 79 20 61 70 70 65 6e 64 69 6e 67 20 61 64   by appending ad
5020: 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 0a  ditional fields.
5030: 2a 2a 20 66 6f 72 20 74 68 65 69 72 20 6f 77 6e  ** for their own
5040: 20 75 73 65 2e 20 20 54 68 65 20 70 4d 65 74 68   use.  The pMeth
5050: 6f 64 73 20 65 6e 74 72 79 20 69 73 20 61 20 70  ods entry is a p
5060: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20  ointer to an.** 
5070: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
5080: 6f 64 73 5d 20 6f 62 6a 65 63 74 20 74 68 61 74  ods] object that
5090: 20 64 65 66 69 6e 65 73 20 6d 65 74 68 6f 64 73   defines methods
50a0: 20 66 6f 72 20 70 65 72 66 6f 72 6d 69 6e 67 0a   for performing.
50b0: 2a 2a 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e  ** I/O operation
50c0: 73 20 6f 6e 20 74 68 65 20 6f 70 65 6e 20 66 69  s on the open fi
50d0: 6c 65 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  le..*/.typedef s
50e0: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 66 69  truct sqlite3_fi
50f0: 6c 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 3b  le sqlite3_file;
5100: 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f  .struct sqlite3_
5110: 66 69 6c 65 20 7b 0a 20 20 63 6f 6e 73 74 20 73  file {.  const s
5120: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f  truct sqlite3_io
5130: 5f 6d 65 74 68 6f 64 73 20 2a 70 4d 65 74 68 6f  _methods *pMetho
5140: 64 73 3b 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20  ds;  /* Methods 
5150: 66 6f 72 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65  for an open file
5160: 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.};../*.** CA
5170: 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72  PI3REF: OS Inter
5180: 66 61 63 65 20 46 69 6c 65 20 56 69 72 74 75 61  face File Virtua
5190: 6c 20 4d 65 74 68 6f 64 73 20 4f 62 6a 65 63 74  l Methods Object
51a0: 20 7b 48 31 31 31 32 30 7d 20 3c 53 32 30 31 31   {H11120} <S2011
51b0: 30 3e 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 66  0>.**.** Every f
51c0: 69 6c 65 20 6f 70 65 6e 65 64 20 62 79 20 74 68  ile opened by th
51d0: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  e [sqlite3_vfs] 
51e0: 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 70 6f 70  xOpen method pop
51f0: 75 6c 61 74 65 73 20 61 6e 0a 2a 2a 20 5b 73 71  ulates an.** [sq
5200: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
5210: 63 74 20 28 6f 72 2c 20 6d 6f 72 65 20 63 6f 6d  ct (or, more com
5220: 6d 6f 6e 6c 79 2c 20 61 20 73 75 62 63 6c 61 73  monly, a subclas
5230: 73 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  s of the.** [sql
5240: 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63  ite3_file] objec
5250: 74 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65  t) with a pointe
5260: 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65  r to an instance
5270: 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 2e   of this object.
5280: 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20  .** This object 
5290: 64 65 66 69 6e 65 73 20 74 68 65 20 6d 65 74 68  defines the meth
52a0: 6f 64 73 20 75 73 65 64 20 74 6f 20 70 65 72 66  ods used to perf
52b0: 6f 72 6d 20 76 61 72 69 6f 75 73 20 6f 70 65 72  orm various oper
52c0: 61 74 69 6f 6e 73 0a 2a 2a 20 61 67 61 69 6e 73  ations.** agains
52d0: 74 20 74 68 65 20 6f 70 65 6e 20 66 69 6c 65 20  t the open file 
52e0: 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20 74  represented by t
52f0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  he [sqlite3_file
5300: 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20  ] object..**.** 
5310: 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65  The flags argume
5320: 6e 74 20 74 6f 20 78 53 79 6e 63 20 6d 61 79 20  nt to xSync may 
5330: 62 65 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54  be one of [SQLIT
5340: 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 5d 20 6f  E_SYNC_NORMAL] o
5350: 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 59 4e  r.** [SQLITE_SYN
5360: 43 5f 46 55 4c 4c 5d 2e 20 20 54 68 65 20 66 69  C_FULL].  The fi
5370: 72 73 74 20 63 68 6f 69 63 65 20 69 73 20 74 68  rst choice is th
5380: 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29  e normal fsync()
5390: 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  ..** The second 
53a0: 63 68 6f 69 63 65 20 69 73 20 61 20 4d 61 63 20  choice is a Mac 
53b0: 4f 53 20 58 20 73 74 79 6c 65 20 66 75 6c 6c 73  OS X style fulls
53c0: 79 6e 63 2e 20 20 54 68 65 20 5b 53 51 4c 49 54  ync.  The [SQLIT
53d0: 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 5d  E_SYNC_DATAONLY]
53e0: 0a 2a 2a 20 66 6c 61 67 20 6d 61 79 20 62 65 20  .** flag may be 
53f0: 4f 52 65 64 20 69 6e 20 74 6f 20 69 6e 64 69 63  ORed in to indic
5400: 61 74 65 20 74 68 61 74 20 6f 6e 6c 79 20 74 68  ate that only th
5410: 65 20 64 61 74 61 20 6f 66 20 74 68 65 20 66 69  e data of the fi
5420: 6c 65 0a 2a 2a 20 61 6e 64 20 6e 6f 74 20 69 74  le.** and not it
5430: 73 20 69 6e 6f 64 65 20 6e 65 65 64 73 20 74 6f  s inode needs to
5440: 20 62 65 20 73 79 6e 63 65 64 2e 0a 2a 2a 0a 2a   be synced..**.*
5450: 2a 20 54 68 65 20 69 6e 74 65 67 65 72 20 76 61  * The integer va
5460: 6c 75 65 73 20 74 6f 20 78 4c 6f 63 6b 28 29 20  lues to xLock() 
5470: 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 61 72  and xUnlock() ar
5480: 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 3c 75 6c 3e  e one of.** <ul>
5490: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
54a0: 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20  _LOCK_NONE],.** 
54b0: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  <li> [SQLITE_LOC
54c0: 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 3c 6c  K_SHARED],.** <l
54d0: 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  i> [SQLITE_LOCK_
54e0: 52 45 53 45 52 56 45 44 5d 2c 0a 2a 2a 20 3c 6c  RESERVED],.** <l
54f0: 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  i> [SQLITE_LOCK_
5500: 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 0a 2a 2a 20  PENDING], or.** 
5510: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  <li> [SQLITE_LOC
5520: 4b 5f 45 58 43 4c 55 53 49 56 45 5d 2e 0a 2a 2a  K_EXCLUSIVE]..**
5530: 20 3c 2f 75 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b 28   </ul>.** xLock(
5540: 29 20 69 6e 63 72 65 61 73 65 73 20 74 68 65 20  ) increases the 
5550: 6c 6f 63 6b 2e 20 78 55 6e 6c 6f 63 6b 28 29 20  lock. xUnlock() 
5560: 64 65 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f  decreases the lo
5570: 63 6b 2e 0a 2a 2a 20 54 68 65 20 78 43 68 65 63  ck..** The xChec
5580: 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 28 29 20  kReservedLock() 
5590: 6d 65 74 68 6f 64 20 63 68 65 63 6b 73 20 77 68  method checks wh
55a0: 65 74 68 65 72 20 61 6e 79 20 64 61 74 61 62 61  ether any databa
55b0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 0a 2a  se connection,.*
55c0: 2a 20 65 69 74 68 65 72 20 69 6e 20 74 68 69 73  * either in this
55d0: 20 70 72 6f 63 65 73 73 20 6f 72 20 69 6e 20 73   process or in s
55e0: 6f 6d 65 20 6f 74 68 65 72 20 70 72 6f 63 65 73  ome other proces
55f0: 73 2c 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20  s, is holding a 
5600: 52 45 53 45 52 56 45 44 2c 0a 2a 2a 20 50 45 4e  RESERVED,.** PEN
5610: 44 49 4e 47 2c 20 6f 72 20 45 58 43 4c 55 53 49  DING, or EXCLUSI
5620: 56 45 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 66  VE lock on the f
5630: 69 6c 65 2e 20 20 49 74 20 72 65 74 75 72 6e 73  ile.  It returns
5640: 20 74 72 75 65 0a 2a 2a 20 69 66 20 73 75 63 68   true.** if such
5650: 20 61 20 6c 6f 63 6b 20 65 78 69 73 74 73 20 61   a lock exists a
5660: 6e 64 20 66 61 6c 73 65 20 6f 74 68 65 72 77 69  nd false otherwi
5670: 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46  se..**.** The xF
5680: 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 65 74  ileControl() met
5690: 68 6f 64 20 69 73 20 61 20 67 65 6e 65 72 69 63  hod is a generic
56a0: 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20   interface that 
56b0: 61 6c 6c 6f 77 73 20 63 75 73 74 6f 6d 0a 2a 2a  allows custom.**
56c0: 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74   VFS implementat
56d0: 69 6f 6e 73 20 74 6f 20 64 69 72 65 63 74 6c 79  ions to directly
56e0: 20 63 6f 6e 74 72 6f 6c 20 61 6e 20 6f 70 65 6e   control an open
56f0: 20 66 69 6c 65 20 75 73 69 6e 67 20 74 68 65 0a   file using the.
5700: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ** [sqlite3_file
5710: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e 74 65  _control()] inte
5720: 72 66 61 63 65 2e 20 20 54 68 65 20 73 65 63 6f  rface.  The seco
5730: 6e 64 20 22 6f 70 22 20 61 72 67 75 6d 65 6e 74  nd "op" argument
5740: 20 69 73 20 61 6e 0a 2a 2a 20 69 6e 74 65 67 65   is an.** intege
5750: 72 20 6f 70 63 6f 64 65 2e 20 20 54 68 65 20 74  r opcode.  The t
5760: 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73  hird argument is
5770: 20 61 20 67 65 6e 65 72 69 63 20 70 6f 69 6e 74   a generic point
5780: 65 72 20 69 6e 74 65 6e 64 65 64 20 74 6f 0a 2a  er intended to.*
5790: 2a 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72  * point to a str
57a0: 75 63 74 75 72 65 20 74 68 61 74 20 6d 61 79 20  ucture that may 
57b0: 63 6f 6e 74 61 69 6e 20 61 72 67 75 6d 65 6e 74  contain argument
57c0: 73 20 6f 72 20 73 70 61 63 65 20 69 6e 20 77 68  s or space in wh
57d0: 69 63 68 20 74 6f 0a 2a 2a 20 77 72 69 74 65 20  ich to.** write 
57e0: 72 65 74 75 72 6e 20 76 61 6c 75 65 73 2e 20 20  return values.  
57f0: 50 6f 74 65 6e 74 69 61 6c 20 75 73 65 73 20 66  Potential uses f
5800: 6f 72 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28  or xFileControl(
5810: 29 20 6d 69 67 68 74 20 62 65 0a 2a 2a 20 66 75  ) might be.** fu
5820: 6e 63 74 69 6f 6e 73 20 74 6f 20 65 6e 61 62 6c  nctions to enabl
5830: 65 20 62 6c 6f 63 6b 69 6e 67 20 6c 6f 63 6b 73  e blocking locks
5840: 20 77 69 74 68 20 74 69 6d 65 6f 75 74 73 2c 20   with timeouts, 
5850: 74 6f 20 63 68 61 6e 67 65 20 74 68 65 0a 2a 2a  to change the.**
5860: 20 6c 6f 63 6b 69 6e 67 20 73 74 72 61 74 65 67   locking strateg
5870: 79 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 74  y (for example t
5880: 6f 20 75 73 65 20 64 6f 74 2d 66 69 6c 65 20 6c  o use dot-file l
5890: 6f 63 6b 73 29 2c 20 74 6f 20 69 6e 71 75 69 72  ocks), to inquir
58a0: 65 0a 2a 2a 20 61 62 6f 75 74 20 74 68 65 20 73  e.** about the s
58b0: 74 61 74 75 73 20 6f 66 20 61 20 6c 6f 63 6b 2c  tatus of a lock,
58c0: 20 6f 72 20 74 6f 20 62 72 65 61 6b 20 73 74 61   or to break sta
58d0: 6c 65 20 6c 6f 63 6b 73 2e 20 20 54 68 65 20 53  le locks.  The S
58e0: 51 4c 69 74 65 0a 2a 2a 20 63 6f 72 65 20 72 65  QLite.** core re
58f0: 73 65 72 76 65 73 20 61 6c 6c 20 6f 70 63 6f 64  serves all opcod
5900: 65 73 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30  es less than 100
5910: 20 66 6f 72 20 69 74 73 20 6f 77 6e 20 75 73 65   for its own use
5920: 2e 0a 2a 2a 20 41 20 5b 53 51 4c 49 54 45 5f 46  ..** A [SQLITE_F
5930: 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 7c  CNTL_LOCKSTATE |
5940: 20 6c 69 73 74 20 6f 66 20 6f 70 63 6f 64 65 73   list of opcodes
5950: 5d 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20  ] less than 100 
5960: 69 73 20 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a  is available..**
5970: 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68   Applications th
5980: 61 74 20 64 65 66 69 6e 65 20 61 20 63 75 73 74  at define a cust
5990: 6f 6d 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20  om xFileControl 
59a0: 6d 65 74 68 6f 64 20 73 68 6f 75 6c 64 20 75 73  method should us
59b0: 65 20 6f 70 63 6f 64 65 73 0a 2a 2a 20 67 72 65  e opcodes.** gre
59c0: 61 74 65 72 20 74 68 61 6e 20 31 30 30 20 74 6f  ater than 100 to
59d0: 20 61 76 6f 69 64 20 63 6f 6e 66 6c 69 63 74 73   avoid conflicts
59e0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 65 63  ..**.** The xSec
59f0: 74 6f 72 53 69 7a 65 28 29 20 6d 65 74 68 6f 64  torSize() method
5a00: 20 72 65 74 75 72 6e 73 20 74 68 65 20 73 65 63   returns the sec
5a10: 74 6f 72 20 73 69 7a 65 20 6f 66 20 74 68 65 0a  tor size of the.
5a20: 2a 2a 20 64 65 76 69 63 65 20 74 68 61 74 20 75  ** device that u
5a30: 6e 64 65 72 6c 69 65 73 20 74 68 65 20 66 69 6c  nderlies the fil
5a40: 65 2e 20 20 54 68 65 20 73 65 63 74 6f 72 20 73  e.  The sector s
5a50: 69 7a 65 20 69 73 20 74 68 65 0a 2a 2a 20 6d 69  ize is the.** mi
5a60: 6e 69 6d 75 6d 20 77 72 69 74 65 20 74 68 61 74  nimum write that
5a70: 20 63 61 6e 20 62 65 20 70 65 72 66 6f 72 6d 65   can be performe
5a80: 64 20 77 69 74 68 6f 75 74 20 64 69 73 74 75 72  d without distur
5a90: 62 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 62 79  bing.** other by
5aa0: 74 65 73 20 69 6e 20 74 68 65 20 66 69 6c 65 2e  tes in the file.
5ab0: 20 20 54 68 65 20 78 44 65 76 69 63 65 43 68 61    The xDeviceCha
5ac0: 72 61 63 74 65 72 69 73 74 69 63 73 28 29 0a 2a  racteristics().*
5ad0: 2a 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73  * method returns
5ae0: 20 61 20 62 69 74 20 76 65 63 74 6f 72 20 64 65   a bit vector de
5af0: 73 63 72 69 62 69 6e 67 20 62 65 68 61 76 69 6f  scribing behavio
5b00: 72 73 20 6f 66 20 74 68 65 0a 2a 2a 20 75 6e 64  rs of the.** und
5b10: 65 72 6c 79 69 6e 67 20 64 65 76 69 63 65 3a 0a  erlying device:.
5b20: 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
5b30: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
5b40: 5f 41 54 4f 4d 49 43 5d 0a 2a 2a 20 3c 6c 69 3e  _ATOMIC].** <li>
5b50: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
5b60: 54 4f 4d 49 43 35 31 32 5d 0a 2a 2a 20 3c 6c 69  TOMIC512].** <li
5b70: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
5b80: 41 54 4f 4d 49 43 31 4b 5d 0a 2a 2a 20 3c 6c 69  ATOMIC1K].** <li
5b90: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
5ba0: 41 54 4f 4d 49 43 32 4b 5d 0a 2a 2a 20 3c 6c 69  ATOMIC2K].** <li
5bb0: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
5bc0: 41 54 4f 4d 49 43 34 4b 5d 0a 2a 2a 20 3c 6c 69  ATOMIC4K].** <li
5bd0: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
5be0: 41 54 4f 4d 49 43 38 4b 5d 0a 2a 2a 20 3c 6c 69  ATOMIC8K].** <li
5bf0: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
5c00: 41 54 4f 4d 49 43 31 36 4b 5d 0a 2a 2a 20 3c 6c  ATOMIC16K].** <l
5c10: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
5c20: 5f 41 54 4f 4d 49 43 33 32 4b 5d 0a 2a 2a 20 3c  _ATOMIC32K].** <
5c30: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
5c40: 50 5f 41 54 4f 4d 49 43 36 34 4b 5d 0a 2a 2a 20  P_ATOMIC64K].** 
5c50: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
5c60: 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 5d 0a  AP_SAFE_APPEND].
5c70: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
5c80: 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c  IOCAP_SEQUENTIAL
5c90: 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  ].** </ul>.**.**
5ca0: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
5cb0: 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74  P_ATOMIC propert
5cc0: 79 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c  y means that all
5cd0: 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e   writes of.** an
5ce0: 79 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69  y size are atomi
5cf0: 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  c.  The SQLITE_I
5d00: 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76  OCAP_ATOMICnnn v
5d10: 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68  alues.** mean th
5d20: 61 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f  at writes of blo
5d30: 63 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e  cks that are nnn
5d40: 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61   bytes in size a
5d50: 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65  nd.** are aligne
5d60: 64 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20  d to an address 
5d70: 77 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65  which is an inte
5d80: 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a  ger multiple of.
5d90: 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69  ** nnn are atomi
5da0: 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  c.  The SQLITE_I
5db0: 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44  OCAP_SAFE_APPEND
5dc0: 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20   value means.** 
5dd0: 74 68 61 74 20 77 68 65 6e 20 64 61 74 61 20 69  that when data i
5de0: 73 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20  s appended to a 
5df0: 66 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69  file, the data i
5e00: 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69  s appended.** fi
5e10: 72 73 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a  rst then the siz
5e20: 65 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73  e of the file is
5e30: 20 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72   extended, never
5e40: 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61   the other.** wa
5e50: 79 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53  y around.  The S
5e60: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55  QLITE_IOCAP_SEQU
5e70: 45 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20  ENTIAL property 
5e80: 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e  means that.** in
5e90: 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69  formation is wri
5ea0: 74 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20  tten to disk in 
5eb0: 74 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61  the same order a
5ec0: 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57  s calls.** to xW
5ed0: 72 69 74 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 49 66  rite()..**.** If
5ee0: 20 78 52 65 61 64 28 29 20 72 65 74 75 72 6e 73   xRead() returns
5ef0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48   SQLITE_IOERR_SH
5f00: 4f 52 54 5f 52 45 41 44 20 69 74 20 6d 75 73 74  ORT_READ it must
5f10: 20 61 6c 73 6f 20 66 69 6c 6c 0a 2a 2a 20 69 6e   also fill.** in
5f20: 20 74 68 65 20 75 6e 72 65 61 64 20 70 6f 72 74   the unread port
5f30: 69 6f 6e 73 20 6f 66 20 74 68 65 20 62 75 66 66  ions of the buff
5f40: 65 72 20 77 69 74 68 20 7a 65 72 6f 73 2e 20 20  er with zeros.  
5f50: 41 20 56 46 53 20 74 68 61 74 0a 2a 2a 20 66 61  A VFS that.** fa
5f60: 69 6c 73 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c  ils to zero-fill
5f70: 20 73 68 6f 72 74 20 72 65 61 64 73 20 6d 69 67   short reads mig
5f80: 68 74 20 73 65 65 6d 20 74 6f 20 77 6f 72 6b 2e  ht seem to work.
5f90: 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 61    However,.** fa
5fa0: 69 6c 75 72 65 20 74 6f 20 7a 65 72 6f 2d 66 69  ilure to zero-fi
5fb0: 6c 6c 20 73 68 6f 72 74 20 72 65 61 64 73 20 77  ll short reads w
5fc0: 69 6c 6c 20 65 76 65 6e 74 75 61 6c 6c 79 20 6c  ill eventually l
5fd0: 65 61 64 20 74 6f 0a 2a 2a 20 64 61 74 61 62 61  ead to.** databa
5fe0: 73 65 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a  se corruption..*
5ff0: 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
6000: 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68   sqlite3_io_meth
6010: 6f 64 73 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  ods sqlite3_io_m
6020: 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73  ethods;.struct s
6030: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
6040: 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69  s {.  int iVersi
6050: 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f  on;.  int (*xClo
6060: 73 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  se)(sqlite3_file
6070: 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 65 61  *);.  int (*xRea
6080: 64 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  d)(sqlite3_file*
6090: 2c 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d  , void*, int iAm
60a0: 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  t, sqlite3_int64
60b0: 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28   iOfst);.  int (
60c0: 2a 78 57 72 69 74 65 29 28 73 71 6c 69 74 65 33  *xWrite)(sqlite3
60d0: 5f 66 69 6c 65 2a 2c 20 63 6f 6e 73 74 20 76 6f  _file*, const vo
60e0: 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73  id*, int iAmt, s
60f0: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66  qlite3_int64 iOf
6100: 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 54 72  st);.  int (*xTr
6110: 75 6e 63 61 74 65 29 28 73 71 6c 69 74 65 33 5f  uncate)(sqlite3_
6120: 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69  file*, sqlite3_i
6130: 6e 74 36 34 20 73 69 7a 65 29 3b 0a 20 20 69 6e  nt64 size);.  in
6140: 74 20 28 2a 78 53 79 6e 63 29 28 73 71 6c 69 74  t (*xSync)(sqlit
6150: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 66 6c  e3_file*, int fl
6160: 61 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46  ags);.  int (*xF
6170: 69 6c 65 53 69 7a 65 29 28 73 71 6c 69 74 65 33  ileSize)(sqlite3
6180: 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f  _file*, sqlite3_
6190: 69 6e 74 36 34 20 2a 70 53 69 7a 65 29 3b 0a 20  int64 *pSize);. 
61a0: 20 69 6e 74 20 28 2a 78 4c 6f 63 6b 29 28 73 71   int (*xLock)(sq
61b0: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74  lite3_file*, int
61c0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e 6c 6f  );.  int (*xUnlo
61d0: 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ck)(sqlite3_file
61e0: 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28  *, int);.  int (
61f0: 2a 78 43 68 65 63 6b 52 65 73 65 72 76 65 64 4c  *xCheckReservedL
6200: 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ock)(sqlite3_fil
6210: 65 2a 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 74  e*, int *pResOut
6220: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65  );.  int (*xFile
6230: 43 6f 6e 74 72 6f 6c 29 28 73 71 6c 69 74 65 33  Control)(sqlite3
6240: 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 70 2c 20  _file*, int op, 
6250: 76 6f 69 64 20 2a 70 41 72 67 29 3b 0a 20 20 69  void *pArg);.  i
6260: 6e 74 20 28 2a 78 53 65 63 74 6f 72 53 69 7a 65  nt (*xSectorSize
6270: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29  )(sqlite3_file*)
6280: 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 76 69 63  ;.  int (*xDevic
6290: 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73  eCharacteristics
62a0: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29  )(sqlite3_file*)
62b0: 3b 0a 20 20 2f 2a 20 41 64 64 69 74 69 6f 6e 61  ;.  /* Additiona
62c0: 6c 20 6d 65 74 68 6f 64 73 20 6d 61 79 20 62 65  l methods may be
62d0: 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65   added in future
62e0: 20 72 65 6c 65 61 73 65 73 20 2a 2f 0a 7d 3b 0a   releases */.};.
62f0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
6300: 20 53 74 61 6e 64 61 72 64 20 46 69 6c 65 20 43   Standard File C
6310: 6f 6e 74 72 6f 6c 20 4f 70 63 6f 64 65 73 20 7b  ontrol Opcodes {
6320: 48 31 31 33 31 30 7d 20 3c 53 33 30 38 30 30 3e  H11310} <S30800>
6330: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74  .**.** These int
6340: 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 61  eger constants a
6350: 72 65 20 6f 70 63 6f 64 65 73 20 66 6f 72 20 74  re opcodes for t
6360: 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20  he xFileControl 
6370: 6d 65 74 68 6f 64 0a 2a 2a 20 6f 66 20 74 68 65  method.** of the
6380: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
6390: 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 61 6e 64  hods] object and
63a0: 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65   for the [sqlite
63b0: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
63c0: 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 2e 0a  ].** interface..
63d0: 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  **.** The [SQLIT
63e0: 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54  E_FCNTL_LOCKSTAT
63f0: 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65  E] opcode is use
6400: 64 20 66 6f 72 20 64 65 62 75 67 67 69 6e 67 2e  d for debugging.
6410: 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65    This.** opcode
6420: 20 63 61 75 73 65 73 20 74 68 65 20 78 46 69 6c   causes the xFil
6430: 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20  eControl method 
6440: 74 6f 20 77 72 69 74 65 20 74 68 65 20 63 75 72  to write the cur
6450: 72 65 6e 74 20 73 74 61 74 65 20 6f 66 0a 2a 2a  rent state of.**
6460: 20 74 68 65 20 6c 6f 63 6b 20 28 6f 6e 65 20 6f   the lock (one o
6470: 66 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e  f [SQLITE_LOCK_N
6480: 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f  ONE], [SQLITE_LO
6490: 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 5b  CK_SHARED],.** [
64a0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45  SQLITE_LOCK_RESE
64b0: 52 56 45 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c  RVED], [SQLITE_L
64c0: 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72  OCK_PENDING], or
64d0: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58   [SQLITE_LOCK_EX
64e0: 43 4c 55 53 49 56 45 5d 29 0a 2a 2a 20 69 6e 74  CLUSIVE]).** int
64f0: 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 74 68 61  o an integer tha
6500: 74 20 74 68 65 20 70 41 72 67 20 61 72 67 75 6d  t the pArg argum
6510: 65 6e 74 20 70 6f 69 6e 74 73 20 74 6f 2e 20 54  ent points to. T
6520: 68 69 73 20 63 61 70 61 62 69 6c 69 74 79 0a 2a  his capability.*
6530: 2a 20 69 73 20 75 73 65 64 20 64 75 72 69 6e 67  * is used during
6540: 20 74 65 73 74 69 6e 67 20 61 6e 64 20 6f 6e 6c   testing and onl
6550: 79 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73 75  y needs to be su
6560: 70 70 6f 72 74 65 64 20 77 68 65 6e 20 53 51 4c  pported when SQL
6570: 49 54 45 5f 54 45 53 54 0a 2a 2a 20 69 73 20 64  ITE_TEST.** is d
6580: 65 66 69 6e 65 64 2e 0a 2a 2f 0a 23 64 65 66 69  efined..*/.#defi
6590: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
65a0: 4c 4f 43 4b 53 54 41 54 45 20 20 20 20 20 20 20  LOCKSTATE       
65b0: 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   1.#define SQLIT
65c0: 45 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46  E_GET_LOCKPROXYF
65d0: 49 4c 45 20 20 20 20 20 20 32 0a 23 64 65 66 69  ILE      2.#defi
65e0: 6e 65 20 53 51 4c 49 54 45 5f 53 45 54 5f 4c 4f  ne SQLITE_SET_LO
65f0: 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20  CKPROXYFILE     
6600: 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   3.#define SQLIT
6610: 45 5f 4c 41 53 54 5f 45 52 52 4e 4f 20 20 20 20  E_LAST_ERRNO    
6620: 20 20 20 20 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a           4../*.*
6630: 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 75 74 65  * CAPI3REF: Mute
6640: 78 20 48 61 6e 64 6c 65 20 7b 48 31 37 31 31 30  x Handle {H17110
6650: 7d 20 3c 53 32 30 31 33 30 3e 0a 2a 2a 0a 2a 2a  } <S20130>.**.**
6660: 20 54 68 65 20 6d 75 74 65 78 20 6d 6f 64 75 6c   The mutex modul
6670: 65 20 77 69 74 68 69 6e 20 53 51 4c 69 74 65 20  e within SQLite 
6680: 64 65 66 69 6e 65 73 20 5b 73 71 6c 69 74 65 33  defines [sqlite3
6690: 5f 6d 75 74 65 78 5d 20 74 6f 20 62 65 20 61 6e  _mutex] to be an
66a0: 0a 2a 2a 20 61 62 73 74 72 61 63 74 20 74 79 70  .** abstract typ
66b0: 65 20 66 6f 72 20 61 20 6d 75 74 65 78 20 6f 62  e for a mutex ob
66c0: 6a 65 63 74 2e 20 20 54 68 65 20 53 51 4c 69 74  ject.  The SQLit
66d0: 65 20 63 6f 72 65 20 6e 65 76 65 72 20 6c 6f 6f  e core never loo
66e0: 6b 73 0a 2a 2a 20 61 74 20 74 68 65 20 69 6e 74  ks.** at the int
66f0: 65 72 6e 61 6c 20 72 65 70 72 65 73 65 6e 74 61  ernal representa
6700: 74 69 6f 6e 20 6f 66 20 61 6e 20 5b 73 71 6c 69  tion of an [sqli
6710: 74 65 33 5f 6d 75 74 65 78 5d 2e 20 20 49 74 20  te3_mutex].  It 
6720: 6f 6e 6c 79 0a 2a 2a 20 64 65 61 6c 73 20 77 69  only.** deals wi
6730: 74 68 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 74  th pointers to t
6740: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  he [sqlite3_mute
6750: 78 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a  x] object..**.**
6760: 20 4d 75 74 65 78 65 73 20 61 72 65 20 63 72 65   Mutexes are cre
6770: 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69  ated using [sqli
6780: 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28  te3_mutex_alloc(
6790: 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  )]..*/.typedef s
67a0: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 75  truct sqlite3_mu
67b0: 74 65 78 20 73 71 6c 69 74 65 33 5f 6d 75 74 65  tex sqlite3_mute
67c0: 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  x;../*.** CAPI3R
67d0: 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65  EF: OS Interface
67e0: 20 4f 62 6a 65 63 74 20 7b 48 31 31 31 34 30 7d   Object {H11140}
67f0: 20 3c 53 32 30 31 30 30 3e 0a 2a 2a 0a 2a 2a 20   <S20100>.**.** 
6800: 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  An instance of t
6810: 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f  he sqlite3_vfs o
6820: 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 68  bject defines th
6830: 65 20 69 6e 74 65 72 66 61 63 65 20 62 65 74 77  e interface betw
6840: 65 65 6e 0a 2a 2a 20 74 68 65 20 53 51 4c 69 74  een.** the SQLit
6850: 65 20 63 6f 72 65 20 61 6e 64 20 74 68 65 20 75  e core and the u
6860: 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65 72 61 74  nderlying operat
6870: 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 54 68 65  ing system.  The
6880: 20 22 76 66 73 22 0a 2a 2a 20 69 6e 20 74 68 65   "vfs".** in the
6890: 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6f 62 6a   name of the obj
68a0: 65 63 74 20 73 74 61 6e 64 73 20 66 6f 72 20 22  ect stands for "
68b0: 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73 79 73  virtual file sys
68c0: 74 65 6d 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  tem"..**.** The 
68d0: 76 61 6c 75 65 20 6f 66 20 74 68 65 20 69 56 65  value of the iVe
68e0: 72 73 69 6f 6e 20 66 69 65 6c 64 20 69 73 20 69  rsion field is i
68f0: 6e 69 74 69 61 6c 6c 79 20 31 20 62 75 74 20 6d  nitially 1 but m
6900: 61 79 20 62 65 20 6c 61 72 67 65 72 20 69 6e 0a  ay be larger in.
6910: 2a 2a 20 66 75 74 75 72 65 20 76 65 72 73 69 6f  ** future versio
6920: 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 41  ns of SQLite.  A
6930: 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73  dditional fields
6940: 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65 64   may be appended
6950: 20 74 6f 20 74 68 69 73 0a 2a 2a 20 6f 62 6a 65   to this.** obje
6960: 63 74 20 77 68 65 6e 20 74 68 65 20 69 56 65 72  ct when the iVer
6970: 73 69 6f 6e 20 76 61 6c 75 65 20 69 73 20 69 6e  sion value is in
6980: 63 72 65 61 73 65 64 2e 20 20 4e 6f 74 65 20 74  creased.  Note t
6990: 68 61 74 20 74 68 65 20 73 74 72 75 63 74 75 72  hat the structur
69a0: 65 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69  e.** of the sqli
69b0: 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 63  te3_vfs object c
69c0: 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 74 72  hanges in the tr
69d0: 61 6e 73 61 63 74 69 6f 6e 20 62 65 74 77 65 65  ansaction betwee
69e0: 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 73  n.** SQLite vers
69f0: 69 6f 6e 20 33 2e 35 2e 39 20 61 6e 64 20 33 2e  ion 3.5.9 and 3.
6a00: 36 2e 30 20 61 6e 64 20 79 65 74 20 74 68 65 20  6.0 and yet the 
6a10: 69 56 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 77  iVersion field w
6a20: 61 73 20 6e 6f 74 0a 2a 2a 20 6d 6f 64 69 66 69  as not.** modifi
6a30: 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 7a  ed..**.** The sz
6a40: 4f 73 46 69 6c 65 20 66 69 65 6c 64 20 69 73 20  OsFile field is 
6a50: 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  the size of the 
6a60: 73 75 62 63 6c 61 73 73 65 64 20 5b 73 71 6c 69  subclassed [sqli
6a70: 74 65 33 5f 66 69 6c 65 5d 0a 2a 2a 20 73 74 72  te3_file].** str
6a80: 75 63 74 75 72 65 20 75 73 65 64 20 62 79 20 74  ucture used by t
6a90: 68 69 73 20 56 46 53 2e 20 20 6d 78 50 61 74 68  his VFS.  mxPath
6aa0: 6e 61 6d 65 20 69 73 20 74 68 65 20 6d 61 78 69  name is the maxi
6ab0: 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 0a 2a 2a  mum length of.**
6ac0: 20 61 20 70 61 74 68 6e 61 6d 65 20 69 6e 20 74   a pathname in t
6ad0: 68 69 73 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 52  his VFS..**.** R
6ae0: 65 67 69 73 74 65 72 65 64 20 73 71 6c 69 74 65  egistered sqlite
6af0: 33 5f 76 66 73 20 6f 62 6a 65 63 74 73 20 61 72  3_vfs objects ar
6b00: 65 20 6b 65 70 74 20 6f 6e 20 61 20 6c 69 6e 6b  e kept on a link
6b10: 65 64 20 6c 69 73 74 20 66 6f 72 6d 65 64 20 62  ed list formed b
6b20: 79 0a 2a 2a 20 74 68 65 20 70 4e 65 78 74 20 70  y.** the pNext p
6b30: 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 5b 73 71  ointer.  The [sq
6b40: 6c 69 74 65 33 5f 76 66 73 5f 72 65 67 69 73 74  lite3_vfs_regist
6b50: 65 72 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71  er()].** and [sq
6b60: 6c 69 74 65 33 5f 76 66 73 5f 75 6e 72 65 67 69  lite3_vfs_unregi
6b70: 73 74 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63  ster()] interfac
6b80: 65 73 20 6d 61 6e 61 67 65 20 74 68 69 73 20 6c  es manage this l
6b90: 69 73 74 0a 2a 2a 20 69 6e 20 61 20 74 68 72 65  ist.** in a thre
6ba0: 61 64 2d 73 61 66 65 20 77 61 79 2e 20 20 54 68  ad-safe way.  Th
6bb0: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 66  e [sqlite3_vfs_f
6bc0: 69 6e 64 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ind()] interface
6bd0: 0a 2a 2a 20 73 65 61 72 63 68 65 73 20 74 68 65  .** searches the
6be0: 20 6c 69 73 74 2e 20 20 4e 65 69 74 68 65 72 20   list.  Neither 
6bf0: 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
6c00: 63 6f 64 65 20 6e 6f 72 20 74 68 65 20 56 46 53  code nor the VFS
6c10: 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
6c20: 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 20 74 68  on should use th
6c30: 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e  e pNext pointer.
6c40: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 4e 65 78 74  .**.** The pNext
6c50: 20 66 69 65 6c 64 20 69 73 20 74 68 65 20 6f 6e   field is the on
6c60: 6c 79 20 66 69 65 6c 64 20 69 6e 20 74 68 65 20  ly field in the 
6c70: 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20 73  sqlite3_vfs.** s
6c80: 74 72 75 63 74 75 72 65 20 74 68 61 74 20 53 51  tructure that SQ
6c90: 4c 69 74 65 20 77 69 6c 6c 20 65 76 65 72 20 6d  Lite will ever m
6ca0: 6f 64 69 66 79 2e 20 20 53 51 4c 69 74 65 20 77  odify.  SQLite w
6cb0: 69 6c 6c 20 6f 6e 6c 79 20 61 63 63 65 73 73 0a  ill only access.
6cc0: 2a 2a 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69  ** or modify thi
6cd0: 73 20 66 69 65 6c 64 20 77 68 69 6c 65 20 68 6f  s field while ho
6ce0: 6c 64 69 6e 67 20 61 20 70 61 72 74 69 63 75 6c  lding a particul
6cf0: 61 72 20 73 74 61 74 69 63 20 6d 75 74 65 78 2e  ar static mutex.
6d00: 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74  .** The applicat
6d10: 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72  ion should never
6d20: 20 6d 6f 64 69 66 79 20 61 6e 79 74 68 69 6e 67   modify anything
6d30: 20 77 69 74 68 69 6e 20 74 68 65 20 73 71 6c 69   within the sqli
6d40: 74 65 33 5f 76 66 73 0a 2a 2a 20 6f 62 6a 65 63  te3_vfs.** objec
6d50: 74 20 6f 6e 63 65 20 74 68 65 20 6f 62 6a 65 63  t once the objec
6d60: 74 20 68 61 73 20 62 65 65 6e 20 72 65 67 69 73  t has been regis
6d70: 74 65 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  tered..**.** The
6d80: 20 7a 4e 61 6d 65 20 66 69 65 6c 64 20 68 6f 6c   zName field hol
6d90: 64 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  ds the name of t
6da0: 68 65 20 56 46 53 20 6d 6f 64 75 6c 65 2e 20 20  he VFS module.  
6db0: 54 68 65 20 6e 61 6d 65 20 6d 75 73 74 0a 2a 2a  The name must.**
6dc0: 20 62 65 20 75 6e 69 71 75 65 20 61 63 72 6f 73   be unique acros
6dd0: 73 20 61 6c 6c 20 56 46 53 20 6d 6f 64 75 6c 65  s all VFS module
6de0: 73 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  s..**.** SQLite 
6df0: 77 69 6c 6c 20 67 75 61 72 61 6e 74 65 65 20 74  will guarantee t
6e00: 68 61 74 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d  hat the zFilenam
6e10: 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78  e parameter to x
6e20: 4f 70 65 6e 0a 2a 2a 20 69 73 20 65 69 74 68 65  Open.** is eithe
6e30: 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  r a NULL pointer
6e40: 20 6f 72 20 73 74 72 69 6e 67 20 6f 62 74 61 69   or string obtai
6e50: 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 78 46 75 6c  ned.** from xFul
6e60: 6c 50 61 74 68 6e 61 6d 65 28 29 2e 20 20 53 51  lPathname().  SQ
6e70: 4c 69 74 65 20 66 75 72 74 68 65 72 20 67 75 61  Lite further gua
6e80: 72 61 6e 74 65 65 73 20 74 68 61 74 0a 2a 2a 20  rantees that.** 
6e90: 74 68 65 20 73 74 72 69 6e 67 20 77 69 6c 6c 20  the string will 
6ea0: 62 65 20 76 61 6c 69 64 20 61 6e 64 20 75 6e 63  be valid and unc
6eb0: 68 61 6e 67 65 64 20 75 6e 74 69 6c 20 78 43 6c  hanged until xCl
6ec0: 6f 73 65 28 29 20 69 73 0a 2a 2a 20 63 61 6c 6c  ose() is.** call
6ed0: 65 64 2e 20 42 65 63 61 75 73 65 20 6f 66 20 74  ed. Because of t
6ee0: 68 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e 74  he previous sent
6ef0: 65 6e 73 65 2c 0a 2a 2a 20 74 68 65 20 5b 73 71  ense,.** the [sq
6f00: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 63 61 6e 20  lite3_file] can 
6f10: 73 61 66 65 6c 79 20 73 74 6f 72 65 20 61 20 70  safely store a p
6f20: 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a  ointer to the.**
6f30: 20 66 69 6c 65 6e 61 6d 65 20 69 66 20 69 74 20   filename if it 
6f40: 6e 65 65 64 73 20 74 6f 20 72 65 6d 65 6d 62 65  needs to remembe
6f50: 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 66  r the filename f
6f60: 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2e 0a  or some reason..
6f70: 2a 2a 20 49 66 20 74 68 65 20 7a 46 69 6c 65 6e  ** If the zFilen
6f80: 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 69 73  ame parameter is
6f90: 20 78 4f 70 65 6e 20 69 73 20 61 20 4e 55 4c 4c   xOpen is a NULL
6fa0: 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 78 4f   pointer then xO
6fb0: 70 65 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e 76 69  pen.** must invi
6fc0: 74 65 20 69 74 73 20 6f 77 6e 20 74 65 6d 70 6f  te its own tempo
6fd0: 72 61 72 79 20 6e 61 6d 65 20 66 6f 72 20 74 68  rary name for th
6fe0: 65 20 66 69 6c 65 2e 20 20 57 68 65 6e 65 76 65  e file.  Wheneve
6ff0: 72 20 74 68 65 20 0a 2a 2a 20 78 46 69 6c 65 6e  r the .** xFilen
7000: 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 69 73  ame parameter is
7010: 20 4e 55 4c 4c 20 69 74 20 77 69 6c 6c 20 61 6c   NULL it will al
7020: 73 6f 20 62 65 20 74 68 65 20 63 61 73 65 20 74  so be the case t
7030: 68 61 74 20 74 68 65 0a 2a 2a 20 66 6c 61 67 73  hat the.** flags
7040: 20 70 61 72 61 6d 65 74 65 72 20 77 69 6c 6c 20   parameter will 
7050: 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f  include [SQLITE_
7060: 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f  OPEN_DELETEONCLO
7070: 53 45 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  SE]..**.** The f
7080: 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f  lags argument to
7090: 20 78 4f 70 65 6e 28 29 20 69 6e 63 6c 75 64 65   xOpen() include
70a0: 73 20 61 6c 6c 20 62 69 74 73 20 73 65 74 20 69  s all bits set i
70b0: 6e 0a 2a 2a 20 74 68 65 20 66 6c 61 67 73 20 61  n.** the flags a
70c0: 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69  rgument to [sqli
70d0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 20  te3_open_v2()]. 
70e0: 20 4f 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f   Or if [sqlite3_
70f0: 6f 70 65 6e 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73  open()].** or [s
7100: 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d  qlite3_open16()]
7110: 20 69 73 20 75 73 65 64 2c 20 74 68 65 6e 20 66   is used, then f
7120: 6c 61 67 73 20 69 6e 63 6c 75 64 65 73 20 61 74  lags includes at
7130: 20 6c 65 61 73 74 0a 2a 2a 20 5b 53 51 4c 49 54   least.** [SQLIT
7140: 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45  E_OPEN_READWRITE
7150: 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  ] | [SQLITE_OPEN
7160: 5f 43 52 45 41 54 45 5d 2e 20 0a 2a 2a 20 49 66  _CREATE]. .** If
7170: 20 78 4f 70 65 6e 28 29 20 6f 70 65 6e 73 20 61   xOpen() opens a
7180: 20 66 69 6c 65 20 72 65 61 64 2d 6f 6e 6c 79 20   file read-only 
7190: 74 68 65 6e 20 69 74 20 73 65 74 73 20 2a 70 4f  then it sets *pO
71a0: 75 74 46 6c 61 67 73 20 74 6f 0a 2a 2a 20 69 6e  utFlags to.** in
71b0: 63 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50  clude [SQLITE_OP
71c0: 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 2e 20 20 4f  EN_READONLY].  O
71d0: 74 68 65 72 20 62 69 74 73 20 69 6e 20 2a 70 4f  ther bits in *pO
71e0: 75 74 46 6c 61 67 73 20 6d 61 79 20 62 65 20 73  utFlags may be s
71f0: 65 74 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  et..**.** SQLite
7200: 20 77 69 6c 6c 20 61 6c 73 6f 20 61 64 64 20 6f   will also add o
7210: 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77  ne of the follow
7220: 69 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 68 65  ing flags to the
7230: 20 78 4f 70 65 6e 28 29 0a 2a 2a 20 63 61 6c 6c   xOpen().** call
7240: 2c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74  , depending on t
7250: 68 65 20 6f 62 6a 65 63 74 20 62 65 69 6e 67 20  he object being 
7260: 6f 70 65 6e 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75  opened:.**.** <u
7270: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  l>.** <li>  [SQL
7280: 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42  ITE_OPEN_MAIN_DB
7290: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  ].** <li>  [SQLI
72a0: 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55  TE_OPEN_MAIN_JOU
72b0: 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b  RNAL].** <li>  [
72c0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50  SQLITE_OPEN_TEMP
72d0: 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  _DB].** <li>  [S
72e0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f  QLITE_OPEN_TEMP_
72f0: 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e  JOURNAL].** <li>
7300: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54    [SQLITE_OPEN_T
7310: 52 41 4e 53 49 45 4e 54 5f 44 42 5d 0a 2a 2a 20  RANSIENT_DB].** 
7320: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
7330: 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 5d 0a 2a  EN_SUBJOURNAL].*
7340: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
7350: 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52  OPEN_MASTER_JOUR
7360: 4e 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  NAL].** </ul>.**
7370: 0a 2a 2a 20 54 68 65 20 66 69 6c 65 20 49 2f 4f  .** The file I/O
7380: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
7390: 63 61 6e 20 75 73 65 20 74 68 65 20 6f 62 6a 65  can use the obje
73a0: 63 74 20 74 79 70 65 20 66 6c 61 67 73 20 74 6f  ct type flags to
73b0: 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20 77  .** change the w
73c0: 61 79 20 69 74 20 64 65 61 6c 73 20 77 69 74 68  ay it deals with
73d0: 20 66 69 6c 65 73 2e 20 20 46 6f 72 20 65 78 61   files.  For exa
73e0: 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 61  mple, an applica
73f0: 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 64 6f 65  tion.** that doe
7400: 73 20 6e 6f 74 20 63 61 72 65 20 61 62 6f 75 74  s not care about
7410: 20 63 72 61 73 68 20 72 65 63 6f 76 65 72 79 20   crash recovery 
7420: 6f 72 20 72 6f 6c 6c 62 61 63 6b 20 6d 69 67 68  or rollback migh
7430: 74 20 6d 61 6b 65 0a 2a 2a 20 74 68 65 20 6f 70  t make.** the op
7440: 65 6e 20 6f 66 20 61 20 6a 6f 75 72 6e 61 6c 20  en of a journal 
7450: 66 69 6c 65 20 61 20 6e 6f 2d 6f 70 2e 20 20 57  file a no-op.  W
7460: 72 69 74 65 73 20 74 6f 20 74 68 69 73 20 6a 6f  rites to this jo
7470: 75 72 6e 61 6c 20 77 6f 75 6c 64 0a 2a 2a 20 61  urnal would.** a
7480: 6c 73 6f 20 62 65 20 6e 6f 2d 6f 70 73 2c 20 61  lso be no-ops, a
7490: 6e 64 20 61 6e 79 20 61 74 74 65 6d 70 74 20 74  nd any attempt t
74a0: 6f 20 72 65 61 64 20 74 68 65 20 6a 6f 75 72 6e  o read the journ
74b0: 61 6c 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 0a  al would return.
74c0: 2a 2a 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 2e  ** SQLITE_IOERR.
74d0: 20 20 4f 72 20 74 68 65 20 69 6d 70 6c 65 6d 65    Or the impleme
74e0: 6e 74 61 74 69 6f 6e 20 6d 69 67 68 74 20 72 65  ntation might re
74f0: 63 6f 67 6e 69 7a 65 20 74 68 61 74 20 61 20 64  cognize that a d
7500: 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20  atabase.** file 
7510: 77 69 6c 6c 20 62 65 20 64 6f 69 6e 67 20 70 61  will be doing pa
7520: 67 65 2d 61 6c 69 67 6e 65 64 20 73 65 63 74 6f  ge-aligned secto
7530: 72 20 72 65 61 64 73 20 61 6e 64 20 77 72 69 74  r reads and writ
7540: 65 73 20 69 6e 20 61 20 72 61 6e 64 6f 6d 0a 2a  es in a random.*
7550: 2a 20 6f 72 64 65 72 20 61 6e 64 20 73 65 74 20  * order and set 
7560: 75 70 20 69 74 73 20 49 2f 4f 20 73 75 62 73 79  up its I/O subsy
7570: 73 74 65 6d 20 61 63 63 6f 72 64 69 6e 67 6c 79  stem accordingly
7580: 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 6d  ..**.** SQLite m
7590: 69 67 68 74 20 61 6c 73 6f 20 61 64 64 20 6f 6e  ight also add on
75a0: 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69  e of the followi
75b0: 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 68 65 20  ng flags to the 
75c0: 78 4f 70 65 6e 20 6d 65 74 68 6f 64 3a 0a 2a 2a  xOpen method:.**
75d0: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
75e0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45   [SQLITE_OPEN_DE
75f0: 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20  LETEONCLOSE].** 
7600: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45  <li> [SQLITE_OPE
7610: 4e 5f 45 58 43 4c 55 53 49 56 45 5d 0a 2a 2a 20  N_EXCLUSIVE].** 
7620: 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  </ul>.**.** The 
7630: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c  [SQLITE_OPEN_DEL
7640: 45 54 45 4f 4e 43 4c 4f 53 45 5d 20 66 6c 61 67  ETEONCLOSE] flag
7650: 20 6d 65 61 6e 73 20 74 68 65 20 66 69 6c 65 20   means the file 
7660: 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 64 65 6c  should be.** del
7670: 65 74 65 64 20 77 68 65 6e 20 69 74 20 69 73 20  eted when it is 
7680: 63 6c 6f 73 65 64 2e 20 20 54 68 65 20 5b 53 51  closed.  The [SQ
7690: 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45  LITE_OPEN_DELETE
76a0: 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 77 69 6c 6c  ONCLOSE].** will
76b0: 20 62 65 20 73 65 74 20 66 6f 72 20 54 45 4d 50   be set for TEMP
76c0: 20 20 64 61 74 61 62 61 73 65 73 2c 20 6a 6f 75    databases, jou
76d0: 72 6e 61 6c 73 20 61 6e 64 20 66 6f 72 20 73 75  rnals and for su
76e0: 62 6a 6f 75 72 6e 61 6c 73 2e 0a 2a 2a 0a 2a 2a  bjournals..**.**
76f0: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45   The [SQLITE_OPE
7700: 4e 5f 45 58 43 4c 55 53 49 56 45 5d 20 66 6c 61  N_EXCLUSIVE] fla
7710: 67 20 69 73 20 61 6c 77 61 79 73 20 75 73 65 64  g is always used
7720: 20 69 6e 20 63 6f 6e 6a 75 6e 63 74 69 6f 6e 0a   in conjunction.
7730: 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c  ** with the [SQL
7740: 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d  ITE_OPEN_CREATE]
7750: 20 66 6c 61 67 2c 20 77 68 69 63 68 20 61 72 65   flag, which are
7760: 20 62 6f 74 68 20 64 69 72 65 63 74 6c 79 0a 2a   both directly.*
7770: 2a 20 61 6e 61 6c 6f 67 6f 75 73 20 74 6f 20 74  * analogous to t
7780: 68 65 20 4f 5f 45 58 43 4c 20 61 6e 64 20 4f 5f  he O_EXCL and O_
7790: 43 52 45 41 54 20 66 6c 61 67 73 20 6f 66 20 74  CREAT flags of t
77a0: 68 65 20 50 4f 53 49 58 20 6f 70 65 6e 28 29 0a  he POSIX open().
77b0: 2a 2a 20 41 50 49 2e 20 20 54 68 65 20 53 51 4c  ** API.  The SQL
77c0: 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49  ITE_OPEN_EXCLUSI
77d0: 56 45 20 66 6c 61 67 2c 20 77 68 65 6e 20 70 61  VE flag, when pa
77e0: 69 72 65 64 20 77 69 74 68 20 74 68 65 20 0a 2a  ired with the .*
77f0: 2a 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52  * SQLITE_OPEN_CR
7800: 45 41 54 45 2c 20 69 73 20 75 73 65 64 20 74 6f  EATE, is used to
7810: 20 69 6e 64 69 63 61 74 65 20 74 68 61 74 20 66   indicate that f
7820: 69 6c 65 20 73 68 6f 75 6c 64 20 61 6c 77 61 79  ile should alway
7830: 73 0a 2a 2a 20 62 65 20 63 72 65 61 74 65 64 2c  s.** be created,
7840: 20 61 6e 64 20 74 68 61 74 20 69 74 20 69 73 20   and that it is 
7850: 61 6e 20 65 72 72 6f 72 20 69 66 20 69 74 20 61  an error if it a
7860: 6c 72 65 61 64 79 20 65 78 69 73 74 73 2e 0a 2a  lready exists..*
7870: 2a 20 49 74 20 69 73 20 3c 69 3e 6e 6f 74 3c 2f  * It is <i>not</
7880: 69 3e 20 75 73 65 64 20 74 6f 20 69 6e 64 69 63  i> used to indic
7890: 61 74 65 20 74 68 65 20 66 69 6c 65 20 73 68 6f  ate the file sho
78a0: 75 6c 64 20 62 65 20 6f 70 65 6e 65 64 20 0a 2a  uld be opened .*
78b0: 2a 20 66 6f 72 20 65 78 63 6c 75 73 69 76 65 20  * for exclusive 
78c0: 61 63 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 41 74  access..**.** At
78d0: 20 6c 65 61 73 74 20 73 7a 4f 73 46 69 6c 65 20   least szOsFile 
78e0: 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 20  bytes of memory 
78f0: 61 72 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79  are allocated by
7900: 20 53 51 4c 69 74 65 0a 2a 2a 20 74 6f 20 68 6f   SQLite.** to ho
7910: 6c 64 20 74 68 65 20 20 5b 73 71 6c 69 74 65 33  ld the  [sqlite3
7920: 5f 66 69 6c 65 5d 20 73 74 72 75 63 74 75 72 65  _file] structure
7930: 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 74   passed as the t
7940: 68 69 72 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  hird.** argument
7950: 20 74 6f 20 78 4f 70 65 6e 2e 20 20 54 68 65 20   to xOpen.  The 
7960: 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 64 6f 65  xOpen method doe
7970: 73 20 6e 6f 74 20 68 61 76 65 20 74 6f 0a 2a 2a  s not have to.**
7980: 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 20 73 74   allocate the st
7990: 72 75 63 74 75 72 65 3b 20 69 74 20 73 68 6f 75  ructure; it shou
79a0: 6c 64 20 6a 75 73 74 20 66 69 6c 6c 20 69 74 20  ld just fill it 
79b0: 69 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c  in..**.** The fl
79c0: 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ags argument to 
79d0: 78 41 63 63 65 73 73 28 29 20 6d 61 79 20 62 65  xAccess() may be
79e0: 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f   [SQLITE_ACCESS_
79f0: 45 58 49 53 54 53 5d 0a 2a 2a 20 74 6f 20 74 65  EXISTS].** to te
7a00: 73 74 20 66 6f 72 20 74 68 65 20 65 78 69 73 74  st for the exist
7a10: 65 6e 63 65 20 6f 66 20 61 20 66 69 6c 65 2c 20  ence of a file, 
7a20: 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53  or [SQLITE_ACCES
7a30: 53 5f 52 45 41 44 57 52 49 54 45 5d 20 74 6f 0a  S_READWRITE] to.
7a40: 2a 2a 20 74 65 73 74 20 77 68 65 74 68 65 72 20  ** test whether 
7a50: 61 20 66 69 6c 65 20 69 73 20 72 65 61 64 61 62  a file is readab
7a60: 6c 65 20 61 6e 64 20 77 72 69 74 61 62 6c 65 2c  le and writable,
7a70: 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 45   or [SQLITE_ACCE
7a80: 53 53 5f 52 45 41 44 5d 0a 2a 2a 20 74 6f 20 74  SS_READ].** to t
7a90: 65 73 74 20 77 68 65 74 68 65 72 20 61 20 66 69  est whether a fi
7aa0: 6c 65 20 69 73 20 61 74 20 6c 65 61 73 74 20 72  le is at least r
7ab0: 65 61 64 61 62 6c 65 2e 20 20 20 54 68 65 20 66  eadable.   The f
7ac0: 69 6c 65 20 63 61 6e 20 62 65 20 61 0a 2a 2a 20  ile can be a.** 
7ad0: 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a  directory..**.**
7ae0: 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 77   SQLite will alw
7af0: 61 79 73 20 61 6c 6c 6f 63 61 74 65 20 61 74 20  ays allocate at 
7b00: 6c 65 61 73 74 20 6d 78 50 61 74 68 6e 61 6d 65  least mxPathname
7b10: 2b 31 20 62 79 74 65 73 20 66 6f 72 20 74 68 65  +1 bytes for the
7b20: 0a 2a 2a 20 6f 75 74 70 75 74 20 62 75 66 66 65  .** output buffe
7b30: 72 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 2e  r xFullPathname.
7b40: 20 20 54 68 65 20 65 78 61 63 74 20 73 69 7a 65    The exact size
7b50: 20 6f 66 20 74 68 65 20 6f 75 74 70 75 74 20 62   of the output b
7b60: 75 66 66 65 72 0a 2a 2a 20 69 73 20 61 6c 73 6f  uffer.** is also
7b70: 20 70 61 73 73 65 64 20 61 73 20 61 20 70 61 72   passed as a par
7b80: 61 6d 65 74 65 72 20 74 6f 20 62 6f 74 68 20 20  ameter to both  
7b90: 6d 65 74 68 6f 64 73 2e 20 49 66 20 74 68 65 20  methods. If the 
7ba0: 6f 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a  output buffer.**
7bb0: 20 69 73 20 6e 6f 74 20 6c 61 72 67 65 20 65 6e   is not large en
7bc0: 6f 75 67 68 2c 20 5b 53 51 4c 49 54 45 5f 43 41  ough, [SQLITE_CA
7bd0: 4e 54 4f 50 45 4e 5d 20 73 68 6f 75 6c 64 20 62  NTOPEN] should b
7be0: 65 20 72 65 74 75 72 6e 65 64 2e 20 53 69 6e 63  e returned. Sinc
7bf0: 65 20 74 68 69 73 20 69 73 0a 2a 2a 20 68 61 6e  e this is.** han
7c00: 64 6c 65 64 20 61 73 20 61 20 66 61 74 61 6c 20  dled as a fatal 
7c10: 65 72 72 6f 72 20 62 79 20 53 51 4c 69 74 65 2c  error by SQLite,
7c20: 20 76 66 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74   vfs implementat
7c30: 69 6f 6e 73 20 73 68 6f 75 6c 64 20 65 6e 64 65  ions should ende
7c40: 61 76 6f 72 0a 2a 2a 20 74 6f 20 70 72 65 76 65  avor.** to preve
7c50: 6e 74 20 74 68 69 73 20 62 79 20 73 65 74 74 69  nt this by setti
7c60: 6e 67 20 6d 78 50 61 74 68 6e 61 6d 65 20 74 6f  ng mxPathname to
7c70: 20 61 20 73 75 66 66 69 63 69 65 6e 74 6c 79 20   a sufficiently 
7c80: 6c 61 72 67 65 20 76 61 6c 75 65 2e 0a 2a 2a 0a  large value..**.
7c90: 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65  ** The xRandomne
7ca0: 73 73 28 29 2c 20 78 53 6c 65 65 70 28 29 2c 20  ss(), xSleep(), 
7cb0: 61 6e 64 20 78 43 75 72 72 65 6e 74 54 69 6d 65  and xCurrentTime
7cc0: 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  () interfaces.**
7cd0: 20 61 72 65 20 6e 6f 74 20 73 74 72 69 63 74 6c   are not strictl
7ce0: 79 20 61 20 70 61 72 74 20 6f 66 20 74 68 65 20  y a part of the 
7cf0: 66 69 6c 65 73 79 73 74 65 6d 2c 20 62 75 74 20  filesystem, but 
7d00: 74 68 65 79 20 61 72 65 0a 2a 2a 20 69 6e 63 6c  they are.** incl
7d10: 75 64 65 64 20 69 6e 20 74 68 65 20 56 46 53 20  uded in the VFS 
7d20: 73 74 72 75 63 74 75 72 65 20 66 6f 72 20 63 6f  structure for co
7d30: 6d 70 6c 65 74 65 6e 65 73 73 2e 0a 2a 2a 20 54  mpleteness..** T
7d40: 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29  he xRandomness()
7d50: 20 66 75 6e 63 74 69 6f 6e 20 61 74 74 65 6d 70   function attemp
7d60: 74 73 20 74 6f 20 72 65 74 75 72 6e 20 6e 42 79  ts to return nBy
7d70: 74 65 73 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20  tes bytes.** of 
7d80: 67 6f 6f 64 2d 71 75 61 6c 69 74 79 20 72 61 6e  good-quality ran
7d90: 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 7a 4f 75  domness into zOu
7da0: 74 2e 20 20 54 68 65 20 72 65 74 75 72 6e 20 76  t.  The return v
7db0: 61 6c 75 65 20 69 73 0a 2a 2a 20 74 68 65 20 61  alue is.** the a
7dc0: 63 74 75 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20  ctual number of 
7dd0: 62 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e  bytes of randomn
7de0: 65 73 73 20 6f 62 74 61 69 6e 65 64 2e 0a 2a 2a  ess obtained..**
7df0: 20 54 68 65 20 78 53 6c 65 65 70 28 29 20 6d 65   The xSleep() me
7e00: 74 68 6f 64 20 63 61 75 73 65 73 20 74 68 65 20  thod causes the 
7e10: 63 61 6c 6c 69 6e 67 20 74 68 72 65 61 64 20 74  calling thread t
7e20: 6f 20 73 6c 65 65 70 20 66 6f 72 20 61 74 0a 2a  o sleep for at.*
7e30: 2a 20 6c 65 61 73 74 20 74 68 65 20 6e 75 6d 62  * least the numb
7e40: 65 72 20 6f 66 20 6d 69 63 72 6f 73 65 63 6f 6e  er of microsecon
7e50: 64 73 20 67 69 76 65 6e 2e 20 20 54 68 65 20 78  ds given.  The x
7e60: 43 75 72 72 65 6e 74 54 69 6d 65 28 29 0a 2a 2a  CurrentTime().**
7e70: 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20   method returns 
7e80: 61 20 4a 75 6c 69 61 6e 20 44 61 79 20 4e 75 6d  a Julian Day Num
7e90: 62 65 72 20 66 6f 72 20 74 68 65 20 63 75 72 72  ber for the curr
7ea0: 65 6e 74 20 64 61 74 65 20 61 6e 64 20 74 69 6d  ent date and tim
7eb0: 65 2e 0a 2a 2a 0a 2a 2f 0a 74 79 70 65 64 65 66  e..**.*/.typedef
7ec0: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
7ed0: 76 66 73 20 73 71 6c 69 74 65 33 5f 76 66 73 3b  vfs sqlite3_vfs;
7ee0: 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f  .struct sqlite3_
7ef0: 76 66 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72  vfs {.  int iVer
7f00: 73 69 6f 6e 3b 20 20 20 20 20 20 20 20 20 20 20  sion;           
7f10: 20 2f 2a 20 53 74 72 75 63 74 75 72 65 20 76 65   /* Structure ve
7f20: 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 2a 2f 0a  rsion number */.
7f30: 20 20 69 6e 74 20 73 7a 4f 73 46 69 6c 65 3b 20    int szOsFile; 
7f40: 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 69             /* Si
7f50: 7a 65 20 6f 66 20 73 75 62 63 6c 61 73 73 65 64  ze of subclassed
7f60: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 2a 2f   sqlite3_file */
7f70: 0a 20 20 69 6e 74 20 6d 78 50 61 74 68 6e 61 6d  .  int mxPathnam
7f80: 65 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d  e;          /* M
7f90: 61 78 69 6d 75 6d 20 66 69 6c 65 20 70 61 74 68  aximum file path
7fa0: 6e 61 6d 65 20 6c 65 6e 67 74 68 20 2a 2f 0a 20  name length */. 
7fb0: 20 73 71 6c 69 74 65 33 5f 76 66 73 20 2a 70 4e   sqlite3_vfs *pN
7fc0: 65 78 74 3b 20 20 20 20 20 20 2f 2a 20 4e 65 78  ext;      /* Nex
7fd0: 74 20 72 65 67 69 73 74 65 72 65 64 20 56 46 53  t registered VFS
7fe0: 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
7ff0: 20 2a 7a 4e 61 6d 65 3b 20 20 20 20 20 20 20 2f   *zName;       /
8000: 2a 20 4e 61 6d 65 20 6f 66 20 74 68 69 73 20 76  * Name of this v
8010: 69 72 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74  irtual file syst
8020: 65 6d 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41  em */.  void *pA
8030: 70 70 44 61 74 61 3b 20 20 20 20 20 20 20 20 20  ppData;         
8040: 20 2f 2a 20 50 6f 69 6e 74 65 72 20 74 6f 20 61   /* Pointer to a
8050: 70 70 6c 69 63 61 74 69 6f 6e 2d 73 70 65 63 69  pplication-speci
8060: 66 69 63 20 64 61 74 61 20 2a 2f 0a 20 20 69 6e  fic data */.  in
8070: 74 20 28 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74  t (*xOpen)(sqlit
8080: 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63  e3_vfs*, const c
8090: 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69  har *zName, sqli
80a0: 74 65 33 5f 66 69 6c 65 2a 2c 0a 20 20 20 20 20  te3_file*,.     
80b0: 20 20 20 20 20 20 20 20 20 20 69 6e 74 20 66 6c            int fl
80c0: 61 67 73 2c 20 69 6e 74 20 2a 70 4f 75 74 46 6c  ags, int *pOutFl
80d0: 61 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44  ags);.  int (*xD
80e0: 65 6c 65 74 65 29 28 73 71 6c 69 74 65 33 5f 76  elete)(sqlite3_v
80f0: 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  fs*, const char 
8100: 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 73 79 6e 63  *zName, int sync
8110: 44 69 72 29 3b 0a 20 20 69 6e 74 20 28 2a 78 41  Dir);.  int (*xA
8120: 63 63 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76  ccess)(sqlite3_v
8130: 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  fs*, const char 
8140: 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 66 6c 61 67  *zName, int flag
8150: 73 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 74 29  s, int *pResOut)
8160: 3b 0a 20 20 69 6e 74 20 28 2a 78 46 75 6c 6c 50  ;.  int (*xFullP
8170: 61 74 68 6e 61 6d 65 29 28 73 71 6c 69 74 65 33  athname)(sqlite3
8180: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61  _vfs*, const cha
8190: 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 6e 4f  r *zName, int nO
81a0: 75 74 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b  ut, char *zOut);
81b0: 0a 20 20 76 6f 69 64 20 2a 28 2a 78 44 6c 4f 70  .  void *(*xDlOp
81c0: 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  en)(sqlite3_vfs*
81d0: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46  , const char *zF
81e0: 69 6c 65 6e 61 6d 65 29 3b 0a 20 20 76 6f 69 64  ilename);.  void
81f0: 20 28 2a 78 44 6c 45 72 72 6f 72 29 28 73 71 6c   (*xDlError)(sql
8200: 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e  ite3_vfs*, int n
8210: 42 79 74 65 2c 20 63 68 61 72 20 2a 7a 45 72 72  Byte, char *zErr
8220: 4d 73 67 29 3b 0a 20 20 76 6f 69 64 20 28 2a 28  Msg);.  void (*(
8230: 2a 78 44 6c 53 79 6d 29 28 73 71 6c 69 74 65 33  *xDlSym)(sqlite3
8240: 5f 76 66 73 2a 2c 76 6f 69 64 2a 2c 20 63 6f 6e  _vfs*,void*, con
8250: 73 74 20 63 68 61 72 20 2a 7a 53 79 6d 62 6f 6c  st char *zSymbol
8260: 29 29 28 76 6f 69 64 29 3b 0a 20 20 76 6f 69 64  ))(void);.  void
8270: 20 28 2a 78 44 6c 43 6c 6f 73 65 29 28 73 71 6c   (*xDlClose)(sql
8280: 69 74 65 33 5f 76 66 73 2a 2c 20 76 6f 69 64 2a  ite3_vfs*, void*
8290: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 61 6e 64  );.  int (*xRand
82a0: 6f 6d 6e 65 73 73 29 28 73 71 6c 69 74 65 33 5f  omness)(sqlite3_
82b0: 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c  vfs*, int nByte,
82c0: 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20   char *zOut);.  
82d0: 69 6e 74 20 28 2a 78 53 6c 65 65 70 29 28 73 71  int (*xSleep)(sq
82e0: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20  lite3_vfs*, int 
82f0: 6d 69 63 72 6f 73 65 63 6f 6e 64 73 29 3b 0a 20  microseconds);. 
8300: 20 69 6e 74 20 28 2a 78 43 75 72 72 65 6e 74 54   int (*xCurrentT
8310: 69 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ime)(sqlite3_vfs
8320: 2a 2c 20 64 6f 75 62 6c 65 2a 29 3b 0a 20 20 69  *, double*);.  i
8330: 6e 74 20 28 2a 78 47 65 74 4c 61 73 74 45 72 72  nt (*xGetLastErr
8340: 6f 72 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  or)(sqlite3_vfs*
8350: 2c 20 69 6e 74 2c 20 63 68 61 72 20 2a 29 3b 0a  , int, char *);.
8360: 20 20 2f 2a 20 4e 65 77 20 66 69 65 6c 64 73 20    /* New fields 
8370: 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65 64 20  may be appended 
8380: 69 6e 20 66 69 67 75 72 65 20 76 65 72 73 69 6f  in figure versio
8390: 6e 73 2e 20 20 54 68 65 20 69 56 65 72 73 69 6f  ns.  The iVersio
83a0: 6e 0a 20 20 2a 2a 20 76 61 6c 75 65 20 77 69 6c  n.  ** value wil
83b0: 6c 20 69 6e 63 72 65 6d 65 6e 74 20 77 68 65 6e  l increment when
83c0: 65 76 65 72 20 74 68 69 73 20 68 61 70 70 65 6e  ever this happen
83d0: 73 2e 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20  s. */.};../*.** 
83e0: 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20  CAPI3REF: Flags 
83f0: 66 6f 72 20 74 68 65 20 78 41 63 63 65 73 73 20  for the xAccess 
8400: 56 46 53 20 6d 65 74 68 6f 64 20 7b 48 31 31 31  VFS method {H111
8410: 39 30 7d 20 3c 48 31 31 31 34 30 3e 0a 2a 2a 0a  90} <H11140>.**.
8420: 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65 72  ** These integer
8430: 20 63 6f 6e 73 74 61 6e 74 73 20 63 61 6e 20 62   constants can b
8440: 65 20 75 73 65 64 20 61 73 20 74 68 65 20 74 68  e used as the th
8450: 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ird parameter to
8460: 0a 2a 2a 20 74 68 65 20 78 41 63 63 65 73 73 20  .** the xAccess 
8470: 6d 65 74 68 6f 64 20 6f 66 20 61 6e 20 5b 73 71  method of an [sq
8480: 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63  lite3_vfs] objec
8490: 74 2e 20 7b 45 4e 44 7d 20 20 54 68 65 79 20 64  t. {END}  They d
84a0: 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 77 68 61 74  etermine.** what
84b0: 20 6b 69 6e 64 20 6f 66 20 70 65 72 6d 69 73 73   kind of permiss
84c0: 69 6f 6e 73 20 74 68 65 20 78 41 63 63 65 73 73  ions the xAccess
84d0: 20 6d 65 74 68 6f 64 20 69 73 20 6c 6f 6f 6b 69   method is looki
84e0: 6e 67 20 66 6f 72 2e 0a 2a 2a 20 57 69 74 68 20  ng for..** With 
84f0: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58  SQLITE_ACCESS_EX
8500: 49 53 54 53 2c 20 74 68 65 20 78 41 63 63 65 73  ISTS, the xAcces
8510: 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 73 69 6d 70  s method.** simp
8520: 6c 79 20 63 68 65 63 6b 73 20 77 68 65 74 68 65  ly checks whethe
8530: 72 20 74 68 65 20 66 69 6c 65 20 65 78 69 73 74  r the file exist
8540: 73 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54  s..** With SQLIT
8550: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49  E_ACCESS_READWRI
8560: 54 45 2c 20 74 68 65 20 78 41 63 63 65 73 73 20  TE, the xAccess 
8570: 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73  method.** checks
8580: 20 77 68 65 74 68 65 72 20 74 68 65 20 66 69 6c   whether the fil
8590: 65 20 69 73 20 62 6f 74 68 20 72 65 61 64 61 62  e is both readab
85a0: 6c 65 20 61 6e 64 20 77 72 69 74 61 62 6c 65 2e  le and writable.
85b0: 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f  .** With SQLITE_
85c0: 41 43 43 45 53 53 5f 52 45 41 44 2c 20 74 68 65  ACCESS_READ, the
85d0: 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a   xAccess method.
85e0: 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68 65  ** checks whethe
85f0: 72 20 74 68 65 20 66 69 6c 65 20 69 73 20 72 65  r the file is re
8600: 61 64 61 62 6c 65 2e 0a 2a 2f 0a 23 64 65 66 69  adable..*/.#defi
8610: 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53  ne SQLITE_ACCESS
8620: 5f 45 58 49 53 54 53 20 20 20 20 30 0a 23 64 65  _EXISTS    0.#de
8630: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45  fine SQLITE_ACCE
8640: 53 53 5f 52 45 41 44 57 52 49 54 45 20 31 0a 23  SS_READWRITE 1.#
8650: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43  define SQLITE_AC
8660: 43 45 53 53 5f 52 45 41 44 20 20 20 20 20 20 32  CESS_READ      2
8670: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
8680: 3a 20 49 6e 69 74 69 61 6c 69 7a 65 20 54 68 65  : Initialize The
8690: 20 53 51 4c 69 74 65 20 4c 69 62 72 61 72 79 20   SQLite Library 
86a0: 7b 48 31 30 31 33 30 7d 20 3c 53 32 30 30 30 30  {H10130} <S20000
86b0: 3e 3c 53 33 30 31 30 30 3e 0a 2a 2a 0a 2a 2a 20  ><S30100>.**.** 
86c0: 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  The sqlite3_init
86d0: 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65  ialize() routine
86e0: 20 69 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65   initializes the
86f0: 0a 2a 2a 20 53 51 4c 69 74 65 20 6c 69 62 72 61  .** SQLite libra
8700: 72 79 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33  ry.  The sqlite3
8710: 5f 73 68 75 74 64 6f 77 6e 28 29 20 72 6f 75 74  _shutdown() rout
8720: 69 6e 65 0a 2a 2a 20 64 65 61 6c 6c 6f 63 61 74  ine.** deallocat
8730: 65 73 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73  es any resources
8740: 20 74 68 61 74 20 77 65 72 65 20 61 6c 6c 6f 63   that were alloc
8750: 61 74 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  ated by sqlite3_
8760: 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 0a 2a 2a  initialize()..**
8770: 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 71  .** A call to sq
8780: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
8790: 28 29 20 69 73 20 61 6e 20 22 65 66 66 65 63 74  () is an "effect
87a0: 69 76 65 22 20 63 61 6c 6c 20 69 66 20 69 74 20  ive" call if it 
87b0: 69 73 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20  is.** the first 
87c0: 74 69 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e 69  time sqlite3_ini
87d0: 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76  tialize() is inv
87e0: 6f 6b 65 64 20 64 75 72 69 6e 67 20 74 68 65 20  oked during the 
87f0: 6c 69 66 65 74 69 6d 65 20 6f 66 0a 2a 2a 20 74  lifetime of.** t
8800: 68 65 20 70 72 6f 63 65 73 73 2c 20 6f 72 20 69  he process, or i
8810: 66 20 69 74 20 69 73 20 74 68 65 20 66 69 72 73  f it is the firs
8820: 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f 69  t time sqlite3_i
8830: 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69  nitialize() is i
8840: 6e 76 6f 6b 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77  nvoked.** follow
8850: 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20 73 71  ing a call to sq
8860: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
8870: 2e 20 20 4f 6e 6c 79 20 61 6e 20 65 66 66 65 63  .  Only an effec
8880: 74 69 76 65 20 63 61 6c 6c 0a 2a 2a 20 6f 66 20  tive call.** of 
8890: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
88a0: 7a 65 28 29 20 64 6f 65 73 20 61 6e 79 20 69 6e  ze() does any in
88b0: 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 20 20 41  itialization.  A
88c0: 6c 6c 20 6f 74 68 65 72 20 63 61 6c 6c 73 0a 2a  ll other calls.*
88d0: 2a 20 61 72 65 20 68 61 72 6d 6c 65 73 73 20 6e  * are harmless n
88e0: 6f 2d 6f 70 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 63  o-ops..**.** A c
88f0: 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  all to sqlite3_s
8900: 68 75 74 64 6f 77 6e 28 29 20 69 73 20 61 6e 20  hutdown() is an 
8910: 22 65 66 66 65 63 74 69 76 65 22 20 63 61 6c 6c  "effective" call
8920: 20 69 66 20 69 74 20 69 73 20 74 68 65 20 66 69   if it is the fi
8930: 72 73 74 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 73  rst.** call to s
8940: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
8950: 29 20 73 69 6e 63 65 20 74 68 65 20 6c 61 73 74  ) since the last
8960: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
8970: 69 7a 65 28 29 2e 20 20 4f 6e 6c 79 0a 2a 2a 20  ize().  Only.** 
8980: 61 6e 20 65 66 66 65 63 74 69 76 65 20 63 61 6c  an effective cal
8990: 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75  l to sqlite3_shu
89a0: 74 64 6f 77 6e 28 29 20 64 6f 65 73 20 61 6e 79  tdown() does any
89b0: 20 64 65 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f   deinitializatio
89c0: 6e 2e 0a 2a 2a 20 41 6c 6c 20 6f 74 68 65 72 20  n..** All other 
89d0: 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
89e0: 5f 73 68 75 74 64 6f 77 6e 28 29 20 61 72 65 20  _shutdown() are 
89f0: 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e  harmless no-ops.
8a00: 0a 2a 2a 0a 2a 2a 20 41 6d 6f 6e 67 20 6f 74 68  .**.** Among oth
8a10: 65 72 20 74 68 69 6e 67 73 2c 20 73 71 6c 69 74  er things, sqlit
8a20: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
8a30: 73 68 61 6c 6c 20 69 6e 76 6f 6b 65 0a 2a 2a 20  shall invoke.** 
8a40: 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
8a50: 29 2e 20 20 53 69 6d 69 6c 61 72 6c 79 2c 20 73  ).  Similarly, s
8a60: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
8a70: 29 0a 2a 2a 20 73 68 61 6c 6c 20 69 6e 76 6f 6b  ).** shall invok
8a80: 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  e sqlite3_os_end
8a90: 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ()..**.** The sq
8aa0: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
8ab0: 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  () routine retur
8ac0: 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f  ns [SQLITE_OK] o
8ad0: 6e 20 73 75 63 63 65 73 73 2e 0a 2a 2a 20 49 66  n success..** If
8ae0: 20 66 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e   for some reason
8af0: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  , sqlite3_initia
8b00: 6c 69 7a 65 28 29 20 69 73 20 75 6e 61 62 6c 65  lize() is unable
8b10: 20 74 6f 20 69 6e 69 74 69 61 6c 69 7a 65 0a 2a   to initialize.*
8b20: 2a 20 74 68 65 20 6c 69 62 72 61 72 79 20 28 70  * the library (p
8b30: 65 72 68 61 70 73 20 69 74 20 69 73 20 75 6e 61  erhaps it is una
8b40: 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20  ble to allocate 
8b50: 61 20 6e 65 65 64 65 64 20 72 65 73 6f 75 72 63  a needed resourc
8b60: 65 20 73 75 63 68 0a 2a 2a 20 61 73 20 61 20 6d  e such.** as a m
8b70: 75 74 65 78 29 20 69 74 20 72 65 74 75 72 6e 73  utex) it returns
8b80: 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d   an [error code]
8b90: 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c   other than [SQL
8ba0: 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 54  ITE_OK]..**.** T
8bb0: 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  he sqlite3_initi
8bc0: 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20  alize() routine 
8bd0: 69 73 20 63 61 6c 6c 65 64 20 69 6e 74 65 72 6e  is called intern
8be0: 61 6c 6c 79 20 62 79 20 6d 61 6e 79 20 6f 74 68  ally by many oth
8bf0: 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74  er.** SQLite int
8c00: 65 72 66 61 63 65 73 20 73 6f 20 74 68 61 74 20  erfaces so that 
8c10: 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 75  an application u
8c20: 73 75 61 6c 6c 79 20 64 6f 65 73 20 6e 6f 74 20  sually does not 
8c30: 6e 65 65 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b  need to.** invok
8c40: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
8c50: 6c 69 7a 65 28 29 20 64 69 72 65 63 74 6c 79 2e  lize() directly.
8c60: 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 5b    For example, [
8c70: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a  sqlite3_open()].
8c80: 2a 2a 20 63 61 6c 6c 73 20 73 71 6c 69 74 65 33  ** calls sqlite3
8c90: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 73 6f  _initialize() so
8ca0: 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72   the SQLite libr
8cb0: 61 72 79 20 77 69 6c 6c 20 62 65 20 61 75 74 6f  ary will be auto
8cc0: 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 69 6e 69  matically.** ini
8cd0: 74 69 61 6c 69 7a 65 64 20 77 68 65 6e 20 5b 73  tialized when [s
8ce0: 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 69  qlite3_open()] i
8cf0: 73 20 63 61 6c 6c 65 64 20 69 66 20 69 74 20 68  s called if it h
8d00: 61 73 20 6e 6f 74 20 62 65 20 69 6e 69 74 69 61  as not be initia
8d10: 6c 69 7a 65 64 0a 2a 2a 20 61 6c 72 65 61 64 79  lized.** already
8d20: 2e 20 20 48 6f 77 65 76 65 72 2c 20 69 66 20 53  .  However, if S
8d30: 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
8d40: 64 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49  d with the [SQLI
8d50: 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54  TE_OMIT_AUTOINIT
8d60: 5d 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  ].** compile-tim
8d70: 65 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 74  e option, then t
8d80: 68 65 20 61 75 74 6f 6d 61 74 69 63 20 63 61 6c  he automatic cal
8d90: 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e  ls to sqlite3_in
8da0: 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 61 72  itialize().** ar
8db0: 65 20 6f 6d 69 74 74 65 64 20 61 6e 64 20 74 68  e omitted and th
8dc0: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75  e application mu
8dd0: 73 74 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f  st call sqlite3_
8de0: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72  initialize() dir
8df0: 65 63 74 6c 79 0a 2a 2a 20 70 72 69 6f 72 20 74  ectly.** prior t
8e00: 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 65  o using any othe
8e10: 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  r SQLite interfa
8e20: 63 65 2e 20 20 46 6f 72 20 6d 61 78 69 6d 75 6d  ce.  For maximum
8e30: 20 70 6f 72 74 61 62 69 6c 69 74 79 2c 0a 2a 2a   portability,.**
8e40: 20 69 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64   it is recommend
8e50: 65 64 20 74 68 61 74 20 61 70 70 6c 69 63 61 74  ed that applicat
8e60: 69 6f 6e 73 20 61 6c 77 61 79 73 20 69 6e 76 6f  ions always invo
8e70: 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  ke sqlite3_initi
8e80: 61 6c 69 7a 65 28 29 0a 2a 2a 20 64 69 72 65 63  alize().** direc
8e90: 74 6c 79 20 70 72 69 6f 72 20 74 6f 20 75 73 69  tly prior to usi
8ea0: 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51 4c  ng any other SQL
8eb0: 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20  ite interface.  
8ec0: 46 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 0a  Future releases.
8ed0: 2a 2a 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79  ** of SQLite may
8ee0: 20 72 65 71 75 69 72 65 20 74 68 69 73 2e 20 20   require this.  
8ef0: 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20  In other words, 
8f00: 74 68 65 20 62 65 68 61 76 69 6f 72 20 65 78 68  the behavior exh
8f10: 69 62 69 74 65 64 0a 2a 2a 20 77 68 65 6e 20 53  ibited.** when S
8f20: 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
8f30: 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 4f  d with [SQLITE_O
8f40: 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d 20 6d 69  MIT_AUTOINIT] mi
8f50: 67 68 74 20 62 65 63 6f 6d 65 20 74 68 65 0a 2a  ght become the.*
8f60: 2a 20 64 65 66 61 75 6c 74 20 62 65 68 61 76 69  * default behavi
8f70: 6f 72 20 69 6e 20 73 6f 6d 65 20 66 75 74 75 72  or in some futur
8f80: 65 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c  e release of SQL
8f90: 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ite..**.** The s
8fa0: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
8fb0: 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6f 70   routine does op
8fc0: 65 72 61 74 69 6e 67 2d 73 79 73 74 65 6d 20 73  erating-system s
8fd0: 70 65 63 69 66 69 63 0a 2a 2a 20 69 6e 69 74 69  pecific.** initi
8fe0: 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 74 68 65  alization of the
8ff0: 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e   SQLite library.
9000: 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73    The sqlite3_os
9010: 5f 65 6e 64 28 29 0a 2a 2a 20 72 6f 75 74 69 6e  _end().** routin
9020: 65 20 75 6e 64 6f 65 73 20 74 68 65 20 65 66 66  e undoes the eff
9030: 65 63 74 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f  ect of sqlite3_o
9040: 73 5f 69 6e 69 74 28 29 2e 20 20 54 79 70 69 63  s_init().  Typic
9050: 61 6c 20 74 61 73 6b 73 0a 2a 2a 20 70 65 72 66  al tasks.** perf
9060: 6f 72 6d 65 64 20 62 79 20 74 68 65 73 65 20 72  ormed by these r
9070: 6f 75 74 69 6e 65 73 20 69 6e 63 6c 75 64 65 20  outines include 
9080: 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 72 20 64 65  allocation or de
9090: 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66  allocation.** of
90a0: 20 73 74 61 74 69 63 20 72 65 73 6f 75 72 63 65   static resource
90b0: 73 2c 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f  s, initializatio
90c0: 6e 20 6f 66 20 67 6c 6f 62 61 6c 20 76 61 72 69  n of global vari
90d0: 61 62 6c 65 73 2c 0a 2a 2a 20 73 65 74 74 69 6e  ables,.** settin
90e0: 67 20 75 70 20 61 20 64 65 66 61 75 6c 74 20 5b  g up a default [
90f0: 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6d 6f 64  sqlite3_vfs] mod
9100: 75 6c 65 2c 20 6f 72 20 73 65 74 74 69 6e 67 20  ule, or setting 
9110: 75 70 0a 2a 2a 20 61 20 64 65 66 61 75 6c 74 20  up.** a default 
9120: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 75 73  configuration us
9130: 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  ing [sqlite3_con
9140: 66 69 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68  fig()]..**.** Th
9150: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68  e application sh
9160: 6f 75 6c 64 20 6e 65 76 65 72 20 69 6e 76 6f 6b  ould never invok
9170: 65 20 65 69 74 68 65 72 20 73 71 6c 69 74 65 33  e either sqlite3
9180: 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 6f 72  _os_init().** or
9190: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28   sqlite3_os_end(
91a0: 29 20 64 69 72 65 63 74 6c 79 2e 20 20 54 68 65  ) directly.  The
91b0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f   application sho
91c0: 75 6c 64 20 6f 6e 6c 79 20 69 6e 76 6f 6b 65 0a  uld only invoke.
91d0: 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  ** sqlite3_initi
91e0: 61 6c 69 7a 65 28 29 20 61 6e 64 20 73 71 6c 69  alize() and sqli
91f0: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20  te3_shutdown(). 
9200: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f   The sqlite3_os_
9210: 69 6e 69 74 28 29 0a 2a 2a 20 69 6e 74 65 72 66  init().** interf
9220: 61 63 65 20 69 73 20 63 61 6c 6c 65 64 20 61 75  ace is called au
9230: 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 73  tomatically by s
9240: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
9250: 65 28 29 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74  e() and.** sqlit
9260: 65 33 5f 6f 73 5f 65 6e 64 28 29 20 69 73 20 63  e3_os_end() is c
9270: 61 6c 6c 65 64 20 62 79 20 73 71 6c 69 74 65 33  alled by sqlite3
9280: 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 41 70  _shutdown().  Ap
9290: 70 72 6f 70 72 69 61 74 65 0a 2a 2a 20 69 6d 70  propriate.** imp
92a0: 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72  lementations for
92b0: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
92c0: 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f  () and sqlite3_o
92d0: 73 5f 65 6e 64 28 29 0a 2a 2a 20 61 72 65 20 62  s_end().** are b
92e0: 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65  uilt into SQLite
92f0: 20 77 68 65 6e 20 69 74 20 69 73 20 63 6f 6d 70   when it is comp
9300: 69 6c 65 64 20 66 6f 72 20 75 6e 69 78 2c 20 77  iled for unix, w
9310: 69 6e 64 6f 77 73 2c 20 6f 72 20 6f 73 2f 32 2e  indows, or os/2.
9320: 0a 2a 2a 20 57 68 65 6e 20 62 75 69 6c 74 20 66  .** When built f
9330: 6f 72 20 6f 74 68 65 72 20 70 6c 61 74 66 6f 72  or other platfor
9340: 6d 73 20 28 75 73 69 6e 67 20 74 68 65 20 5b 53  ms (using the [S
9350: 51 4c 49 54 45 5f 4f 53 5f 4f 54 48 45 52 3d 31  QLITE_OS_OTHER=1
9360: 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a  ] compile-time.*
9370: 2a 20 6f 70 74 69 6f 6e 29 20 74 68 65 20 61 70  * option) the ap
9380: 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 73  plication must s
9390: 75 70 70 6c 79 20 61 20 73 75 69 74 61 62 6c 65  upply a suitable
93a0: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
93b0: 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f  for.** sqlite3_o
93c0: 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71 6c  s_init() and sql
93d0: 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 20 20  ite3_os_end().  
93e0: 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73  An application-s
93f0: 75 70 70 6c 69 65 64 0a 2a 2a 20 69 6d 70 6c 65  upplied.** imple
9400: 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c  mentation of sql
9410: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 6f  ite3_os_init() o
9420: 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  r sqlite3_os_end
9430: 28 29 0a 2a 2a 20 6d 75 73 74 20 72 65 74 75 72  ().** must retur
9440: 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e  n [SQLITE_OK] on
9450: 20 73 75 63 63 65 73 73 20 61 6e 64 20 73 6f 6d   success and som
9460: 65 20 6f 74 68 65 72 20 5b 65 72 72 6f 72 20 63  e other [error c
9470: 6f 64 65 5d 20 75 70 6f 6e 0a 2a 2a 20 66 61 69  ode] upon.** fai
9480: 6c 75 72 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  lure..*/.int sql
9490: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
94a0: 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74  void);.int sqlit
94b0: 65 33 5f 73 68 75 74 64 6f 77 6e 28 76 6f 69 64  e3_shutdown(void
94c0: 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f  );.int sqlite3_o
94d0: 73 5f 69 6e 69 74 28 76 6f 69 64 29 3b 0a 69 6e  s_init(void);.in
94e0: 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  t sqlite3_os_end
94f0: 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  (void);../*.** C
9500: 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75  API3REF: Configu
9510: 72 69 6e 67 20 54 68 65 20 53 51 4c 69 74 65 20  ring The SQLite 
9520: 4c 69 62 72 61 72 79 20 7b 48 31 34 31 30 30 7d  Library {H14100}
9530: 20 3c 53 32 30 30 30 30 3e 3c 53 33 30 32 30 30   <S20000><S30200
9540: 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41  >.** EXPERIMENTA
9550: 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  L.**.** The sqli
9560: 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74  te3_config() int
9570: 65 72 66 61 63 65 20 69 73 20 75 73 65 64 20 74  erface is used t
9580: 6f 20 6d 61 6b 65 20 67 6c 6f 62 61 6c 20 63 6f  o make global co
9590: 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63  nfiguration.** c
95a0: 68 61 6e 67 65 73 20 74 6f 20 53 51 4c 69 74 65  hanges to SQLite
95b0: 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 74 75 6e   in order to tun
95c0: 65 20 53 51 4c 69 74 65 20 74 6f 20 74 68 65 20  e SQLite to the 
95d0: 73 70 65 63 69 66 69 63 20 6e 65 65 64 73 20 6f  specific needs o
95e0: 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61  f.** the applica
95f0: 74 69 6f 6e 2e 20 20 54 68 65 20 64 65 66 61 75  tion.  The defau
9600: 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  lt configuration
9610: 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20   is recommended 
9620: 66 6f 72 20 6d 6f 73 74 0a 2a 2a 20 61 70 70 6c  for most.** appl
9630: 69 63 61 74 69 6f 6e 73 20 61 6e 64 20 73 6f 20  ications and so 
9640: 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20  this routine is 
9650: 75 73 75 61 6c 6c 79 20 6e 6f 74 20 6e 65 63 65  usually not nece
9660: 73 73 61 72 79 2e 20 20 49 74 20 69 73 0a 2a 2a  ssary.  It is.**
9670: 20 70 72 6f 76 69 64 65 64 20 74 6f 20 73 75 70   provided to sup
9680: 70 6f 72 74 20 72 61 72 65 20 61 70 70 6c 69 63  port rare applic
9690: 61 74 69 6f 6e 73 20 77 69 74 68 20 75 6e 75 73  ations with unus
96a0: 75 61 6c 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a  ual needs..**.**
96b0: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e   The sqlite3_con
96c0: 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20  fig() interface 
96d0: 69 73 20 6e 6f 74 20 74 68 72 65 61 64 73 61 66  is not threadsaf
96e0: 65 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61 74  e.  The applicat
96f0: 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e 73 75  ion.** must insu
9700: 72 65 20 74 68 61 74 20 6e 6f 20 6f 74 68 65 72  re that no other
9710: 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
9720: 65 73 20 61 72 65 20 69 6e 76 6f 6b 65 64 20 62  es are invoked b
9730: 79 20 6f 74 68 65 72 0a 2a 2a 20 74 68 72 65 61  y other.** threa
9740: 64 73 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33  ds while sqlite3
9750: 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 72 75 6e  _config() is run
9760: 6e 69 6e 67 2e 20 20 46 75 72 74 68 65 72 6d 6f  ning.  Furthermo
9770: 72 65 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66  re, sqlite3_conf
9780: 69 67 28 29 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79  ig().** may only
9790: 20 62 65 20 69 6e 76 6f 6b 65 64 20 70 72 69 6f   be invoked prio
97a0: 72 20 74 6f 20 6c 69 62 72 61 72 79 20 69 6e 69  r to library ini
97b0: 74 69 61 6c 69 7a 61 74 69 6f 6e 20 75 73 69 6e  tialization usin
97c0: 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6e  g.** [sqlite3_in
97d0: 69 74 69 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61  itialize()] or a
97e0: 66 74 65 72 20 73 68 75 74 64 6f 77 6e 20 62 79  fter shutdown by
97f0: 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f   [sqlite3_shutdo
9800: 77 6e 28 29 5d 2e 0a 2a 2a 20 4e 6f 74 65 2c 20  wn()]..** Note, 
9810: 68 6f 77 65 76 65 72 2c 20 74 68 61 74 20 73 71  however, that sq
9820: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 63  lite3_config() c
9830: 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 73 20  an be called as 
9840: 70 61 72 74 20 6f 66 20 74 68 65 0a 2a 2a 20 69  part of the.** i
9850: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
9860: 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d   an application-
9870: 64 65 66 69 6e 65 64 20 5b 73 71 6c 69 74 65 33  defined [sqlite3
9880: 5f 6f 73 5f 69 6e 69 74 28 29 5d 2e 0a 2a 2a 0a  _os_init()]..**.
9890: 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67  ** The first arg
98a0: 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33  ument to sqlite3
98b0: 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 61 6e 20  _config() is an 
98c0: 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 53 51 4c 49  integer.** [SQLI
98d0: 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45  TE_CONFIG_SINGLE
98e0: 54 48 52 45 41 44 20 7c 20 63 6f 6e 66 69 67 75  THREAD | configu
98f0: 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 20 74  ration option] t
9900: 68 61 74 20 64 65 74 65 72 6d 69 6e 65 73 0a 2a  hat determines.*
9910: 2a 20 77 68 61 74 20 70 72 6f 70 65 72 74 79 20  * what property 
9920: 6f 66 20 53 51 4c 69 74 65 20 69 73 20 74 6f 20  of SQLite is to 
9930: 62 65 20 63 6f 6e 66 69 67 75 72 65 64 2e 20 20  be configured.  
9940: 53 75 62 73 65 71 75 65 6e 74 20 61 72 67 75 6d  Subsequent argum
9950: 65 6e 74 73 0a 2a 2a 20 76 61 72 79 20 64 65 70  ents.** vary dep
9960: 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 5b 53  ending on the [S
9970: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e  QLITE_CONFIG_SIN
9980: 47 4c 45 54 48 52 45 41 44 20 7c 20 63 6f 6e 66  GLETHREAD | conf
9990: 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
99a0: 5d 0a 2a 2a 20 69 6e 20 74 68 65 20 66 69 72 73  ].** in the firs
99b0: 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a  t argument..**.*
99c0: 2a 20 57 68 65 6e 20 61 20 63 6f 6e 66 69 67 75  * When a configu
99d0: 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73  ration option is
99e0: 20 73 65 74 2c 20 73 71 6c 69 74 65 33 5f 63 6f   set, sqlite3_co
99f0: 6e 66 69 67 28 29 20 72 65 74 75 72 6e 73 20 5b  nfig() returns [
9a00: 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 20 49  SQLITE_OK]..** I
9a10: 66 20 74 68 65 20 6f 70 74 69 6f 6e 20 69 73 20  f the option is 
9a20: 75 6e 6b 6e 6f 77 6e 20 6f 72 20 53 51 4c 69 74  unknown or SQLit
9a30: 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 73  e is unable to s
9a40: 65 74 20 74 68 65 20 6f 70 74 69 6f 6e 0a 2a 2a  et the option.**
9a50: 20 74 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69   then this routi
9a60: 6e 65 20 72 65 74 75 72 6e 73 20 61 20 6e 6f 6e  ne returns a non
9a70: 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64  -zero [error cod
9a80: 65 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72  e]..**.** Requir
9a90: 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 34 31  ements:.** [H141
9aa0: 30 33 5d 20 5b 48 31 34 31 30 36 5d 20 5b 48 31  03] [H14106] [H1
9ab0: 34 31 32 30 5d 20 5b 48 31 34 31 32 33 5d 20 5b  4120] [H14123] [
9ac0: 48 31 34 31 32 36 5d 20 5b 48 31 34 31 32 39 5d  H14126] [H14129]
9ad0: 20 5b 48 31 34 31 33 32 5d 20 5b 48 31 34 31 33   [H14132] [H1413
9ae0: 35 5d 0a 2a 2a 20 5b 48 31 34 31 33 38 5d 20 5b  5].** [H14138] [
9af0: 48 31 34 31 34 31 5d 20 5b 48 31 34 31 34 34 5d  H14141] [H14144]
9b00: 20 5b 48 31 34 31 34 37 5d 20 5b 48 31 34 31 35   [H14147] [H1415
9b10: 30 5d 20 5b 48 31 34 31 35 33 5d 20 5b 48 31 34  0] [H14153] [H14
9b20: 31 35 36 5d 20 5b 48 31 34 31 35 39 5d 0a 2a 2a  156] [H14159].**
9b30: 20 5b 48 31 34 31 36 32 5d 20 5b 48 31 34 31 36   [H14162] [H1416
9b40: 35 5d 20 5b 48 31 34 31 36 38 5d 0a 2a 2f 0a 53  5] [H14168].*/.S
9b50: 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54  QLITE_EXPERIMENT
9b60: 41 4c 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  AL int sqlite3_c
9b70: 6f 6e 66 69 67 28 69 6e 74 2c 20 2e 2e 2e 29 3b  onfig(int, ...);
9b80: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
9b90: 3a 20 43 6f 6e 66 69 67 75 72 65 20 64 61 74 61  : Configure data
9ba0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
9bb0: 20 20 7b 48 31 34 32 30 30 7d 20 3c 53 32 30 30    {H14200} <S200
9bc0: 30 30 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e  00>.** EXPERIMEN
9bd0: 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  TAL.**.** The sq
9be0: 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
9bf0: 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 75  ) interface is u
9c00: 73 65 64 20 74 6f 20 6d 61 6b 65 20 63 6f 6e 66  sed to make conf
9c10: 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61  iguration.** cha
9c20: 6e 67 65 73 20 74 6f 20 61 20 5b 64 61 74 61 62  nges to a [datab
9c30: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e  ase connection].
9c40: 20 20 54 68 65 20 69 6e 74 65 72 66 61 63 65 20    The interface 
9c50: 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 0a 2a 2a  is similar to.**
9c60: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
9c70: 28 29 5d 20 65 78 63 65 70 74 20 74 68 61 74 20  ()] except that 
9c80: 74 68 65 20 63 68 61 6e 67 65 73 20 61 70 70 6c  the changes appl
9c90: 79 20 74 6f 20 61 20 73 69 6e 67 6c 65 0a 2a 2a  y to a single.**
9ca0: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
9cb0: 63 74 69 6f 6e 5d 20 28 73 70 65 63 69 66 69 65  ction] (specifie
9cc0: 64 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61  d in the first a
9cd0: 72 67 75 6d 65 6e 74 29 2e 20 20 54 68 65 0a 2a  rgument).  The.*
9ce0: 2a 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e  * sqlite3_db_con
9cf0: 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20  fig() interface 
9d00: 63 61 6e 20 6f 6e 6c 79 20 62 65 20 75 73 65 64  can only be used
9d10: 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 61 66 74   immediately aft
9d20: 65 72 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61  er.** the databa
9d30: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
9d40: 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 20 5b   created using [
9d50: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c  sqlite3_open()],
9d60: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  .** [sqlite3_ope
9d70: 6e 31 36 28 29 5d 2c 20 6f 72 20 5b 73 71 6c 69  n16()], or [sqli
9d80: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 20  te3_open_v2()]. 
9d90: 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f   .**.** The seco
9da0: 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  nd argument to s
9db0: 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
9dc0: 28 44 2c 56 2c 2e 2e 2e 29 20 20 69 73 20 74 68  (D,V,...)  is th
9dd0: 65 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69  e.** configurati
9de0: 6f 6e 20 76 65 72 62 20 2d 20 61 6e 20 69 6e 74  on verb - an int
9df0: 65 67 65 72 20 63 6f 64 65 20 74 68 61 74 20 69  eger code that i
9e00: 6e 64 69 63 61 74 65 73 20 77 68 61 74 0a 2a 2a  ndicates what.**
9e10: 20 61 73 70 65 63 74 20 6f 66 20 74 68 65 20 5b   aspect of the [
9e20: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
9e30: 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20 63 6f  ion] is being co
9e40: 6e 66 69 67 75 72 65 64 2e 0a 2a 2a 20 54 68 65  nfigured..** The
9e50: 20 6f 6e 6c 79 20 63 68 6f 69 63 65 20 66 6f 72   only choice for
9e60: 20 74 68 69 73 20 76 61 6c 75 65 20 69 73 20 5b   this value is [
9e70: 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
9e80: 4c 4f 4f 4b 41 53 49 44 45 5d 2e 0a 2a 2a 20 4e  LOOKASIDE]..** N
9e90: 65 77 20 76 65 72 62 73 20 61 72 65 20 6c 69 6b  ew verbs are lik
9ea0: 65 6c 79 20 74 6f 20 62 65 20 61 64 64 65 64 20  ely to be added 
9eb0: 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  in future releas
9ec0: 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a  es of SQLite..**
9ed0: 20 41 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75   Additional argu
9ee0: 6d 65 6e 74 73 20 64 65 70 65 6e 64 20 6f 6e 20  ments depend on 
9ef0: 74 68 65 20 76 65 72 62 2e 0a 2a 2a 0a 2a 2a 20  the verb..**.** 
9f00: 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a  Requirements:.**
9f10: 20 5b 48 31 34 32 30 33 5d 20 5b 48 31 34 32 30   [H14203] [H1420
9f20: 36 5d 20 5b 48 31 34 32 30 39 5d 20 5b 48 31 34  6] [H14209] [H14
9f30: 32 31 32 5d 20 5b 48 31 34 32 31 35 5d 0a 2a 2f  212] [H14215].*/
9f40: 0a 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45  .SQLITE_EXPERIME
9f50: 4e 54 41 4c 20 69 6e 74 20 73 71 6c 69 74 65 33  NTAL int sqlite3
9f60: 5f 64 62 5f 63 6f 6e 66 69 67 28 73 71 6c 69 74  _db_config(sqlit
9f70: 65 33 2a 2c 20 69 6e 74 20 6f 70 2c 20 2e 2e 2e  e3*, int op, ...
9f80: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
9f90: 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63  EF: Memory Alloc
9fa0: 61 74 69 6f 6e 20 52 6f 75 74 69 6e 65 73 20 7b  ation Routines {
9fb0: 48 31 30 31 35 35 7d 20 3c 53 32 30 31 32 30 3e  H10155} <S20120>
9fc0: 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c  .** EXPERIMENTAL
9fd0: 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e  .**.** An instan
9fe0: 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63  ce of this objec
9ff0: 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e  t defines the in
a000: 74 65 72 66 61 63 65 20 62 65 74 77 65 65 6e 20  terface between 
a010: 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 6c 6f  SQLite.** and lo
a020: 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61  w-level memory a
a030: 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e  llocation routin
a040: 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 6f  es..**.** This o
a050: 62 6a 65 63 74 20 69 73 20 75 73 65 64 20 69 6e  bject is used in
a060: 20 6f 6e 6c 79 20 6f 6e 65 20 70 6c 61 63 65 20   only one place 
a070: 69 6e 20 74 68 65 20 53 51 4c 69 74 65 20 69 6e  in the SQLite in
a080: 74 65 72 66 61 63 65 2e 0a 2a 2a 20 41 20 70 6f  terface..** A po
a090: 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74  inter to an inst
a0a0: 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a  ance of this obj
a0b0: 65 63 74 20 69 73 20 74 68 65 20 61 72 67 75 6d  ect is the argum
a0c0: 65 6e 74 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  ent to.** [sqlit
a0d0: 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 68 65  e3_config()] whe
a0e0: 6e 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74  n the configurat
a0f0: 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a  ion option is.**
a100: 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
a110: 4d 41 4c 4c 4f 43 5d 2e 20 20 42 79 20 63 72 65  MALLOC].  By cre
a120: 61 74 69 6e 67 20 61 6e 20 69 6e 73 74 61 6e 63  ating an instanc
a130: 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74  e of this object
a140: 0a 2a 2a 20 61 6e 64 20 70 61 73 73 69 6e 67 20  .** and passing 
a150: 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  it to [sqlite3_c
a160: 6f 6e 66 69 67 28 29 5d 20 64 75 72 69 6e 67 20  onfig()] during 
a170: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20 61  configuration, a
a180: 6e 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e  n.** application
a190: 20 63 61 6e 20 73 70 65 63 69 66 79 20 61 6e 20   can specify an 
a1a0: 61 6c 74 65 72 6e 61 74 69 76 65 20 6d 65 6d 6f  alternative memo
a1b0: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75  ry allocation su
a1c0: 62 73 79 73 74 65 6d 0a 2a 2a 20 66 6f 72 20 53  bsystem.** for S
a1d0: 51 4c 69 74 65 20 74 6f 20 75 73 65 20 66 6f 72  QLite to use for
a1e0: 20 61 6c 6c 20 6f 66 20 69 74 73 20 64 79 6e 61   all of its dyna
a1f0: 6d 69 63 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73  mic memory needs
a200: 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ..**.** Note tha
a210: 74 20 53 51 4c 69 74 65 20 63 6f 6d 65 73 20 77  t SQLite comes w
a220: 69 74 68 20 61 20 62 75 69 6c 74 2d 69 6e 20 6d  ith a built-in m
a230: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20  emory allocator 
a240: 74 68 61 74 20 69 73 0a 2a 2a 20 70 65 72 66 65  that is.** perfe
a250: 63 74 6c 79 20 61 64 65 71 75 61 74 65 20 66 6f  ctly adequate fo
a260: 72 20 74 68 65 20 6f 76 65 72 77 68 65 6c 6d 69  r the overwhelmi
a270: 6e 67 20 6d 61 6a 6f 72 69 74 79 20 6f 66 20 61  ng majority of a
a280: 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 61  pplications.** a
a290: 6e 64 20 74 68 61 74 20 74 68 69 73 20 6f 62 6a  nd that this obj
a2a0: 65 63 74 20 69 73 20 6f 6e 6c 79 20 75 73 65 66  ect is only usef
a2b0: 75 6c 20 74 6f 20 61 20 74 69 6e 79 20 6d 69 6e  ul to a tiny min
a2c0: 6f 72 69 74 79 20 6f 66 20 61 70 70 6c 69 63 61  ority of applica
a2d0: 74 69 6f 6e 73 0a 2a 2a 20 77 69 74 68 20 73 70  tions.** with sp
a2e0: 65 63 69 61 6c 69 7a 65 64 20 6d 65 6d 6f 72 79  ecialized memory
a2f0: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75   allocation requ
a300: 69 72 65 6d 65 6e 74 73 2e 20 20 54 68 69 73 20  irements.  This 
a310: 6f 62 6a 65 63 74 20 69 73 0a 2a 2a 20 61 6c 73  object is.** als
a320: 6f 20 75 73 65 64 20 64 75 72 69 6e 67 20 74 65  o used during te
a330: 73 74 69 6e 67 20 6f 66 20 53 51 4c 69 74 65 20  sting of SQLite 
a340: 69 6e 20 6f 72 64 65 72 20 74 6f 20 73 70 65 63  in order to spec
a350: 69 66 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 69  ify an alternati
a360: 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c  ve.** memory all
a370: 6f 63 61 74 6f 72 20 74 68 61 74 20 73 69 6d 75  ocator that simu
a380: 6c 61 74 65 73 20 6d 65 6d 6f 72 79 20 6f 75 74  lates memory out
a390: 2d 6f 66 2d 6d 65 6d 6f 72 79 20 63 6f 6e 64 69  -of-memory condi
a3a0: 74 69 6f 6e 73 20 69 6e 0a 2a 2a 20 6f 72 64 65  tions in.** orde
a3b0: 72 20 74 6f 20 76 65 72 69 66 79 20 74 68 61 74  r to verify that
a3c0: 20 53 51 4c 69 74 65 20 72 65 63 6f 76 65 72 73   SQLite recovers
a3d0: 20 67 72 61 63 65 66 75 6c 6c 79 20 66 72 6f 6d   gracefully from
a3e0: 20 73 75 63 68 0a 2a 2a 20 63 6f 6e 64 69 74 69   such.** conditi
a3f0: 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  ons..**.** The x
a400: 4d 61 6c 6c 6f 63 2c 20 78 46 72 65 65 2c 20 61  Malloc, xFree, a
a410: 6e 64 20 78 52 65 61 6c 6c 6f 63 20 6d 65 74 68  nd xRealloc meth
a420: 6f 64 73 20 6d 75 73 74 20 77 6f 72 6b 20 6c 69  ods must work li
a430: 6b 65 20 74 68 65 0a 2a 2a 20 6d 61 6c 6c 6f 63  ke the.** malloc
a440: 28 29 2c 20 66 72 65 65 28 29 2c 20 61 6e 64 20  (), free(), and 
a450: 72 65 61 6c 6c 6f 63 28 29 20 66 75 6e 63 74 69  realloc() functi
a460: 6f 6e 73 20 66 72 6f 6d 20 74 68 65 20 73 74 61  ons from the sta
a470: 6e 64 61 72 64 20 6c 69 62 72 61 72 79 2e 0a 2a  ndard library..*
a480: 2a 0a 2a 2a 20 78 53 69 7a 65 20 73 68 6f 75 6c  *.** xSize shoul
a490: 64 20 72 65 74 75 72 6e 20 74 68 65 20 61 6c 6c  d return the all
a4a0: 6f 63 61 74 65 64 20 73 69 7a 65 20 6f 66 20 61  ocated size of a
a4b0: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
a4c0: 6f 6e 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79  on.** previously
a4d0: 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 78   obtained from x
a4e0: 4d 61 6c 6c 6f 63 20 6f 72 20 78 52 65 61 6c 6c  Malloc or xReall
a4f0: 6f 63 2e 20 20 54 68 65 20 61 6c 6c 6f 63 61 74  oc.  The allocat
a500: 65 64 20 73 69 7a 65 0a 2a 2a 20 69 73 20 61 6c  ed size.** is al
a510: 77 61 79 73 20 61 74 20 6c 65 61 73 74 20 61 73  ways at least as
a520: 20 62 69 67 20 61 73 20 74 68 65 20 72 65 71 75   big as the requ
a530: 65 73 74 65 64 20 73 69 7a 65 20 62 75 74 20 6d  ested size but m
a540: 61 79 20 62 65 20 6c 61 72 67 65 72 2e 0a 2a 2a  ay be larger..**
a550: 0a 2a 2a 20 54 68 65 20 78 52 6f 75 6e 64 75 70  .** The xRoundup
a560: 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20   method returns 
a570: 77 68 61 74 20 77 6f 75 6c 64 20 62 65 20 74 68  what would be th
a580: 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65  e allocated size
a590: 20 6f 66 0a 2a 2a 20 61 20 6d 65 6d 6f 72 79 20   of.** a memory 
a5a0: 61 6c 6c 6f 63 61 74 69 6f 6e 20 67 69 76 65 6e  allocation given
a5b0: 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 65   a particular re
a5c0: 71 75 65 73 74 65 64 20 73 69 7a 65 2e 20 20 4d  quested size.  M
a5d0: 6f 73 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c  ost memory.** al
a5e0: 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75  locators round u
a5f0: 70 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  p memory allocat
a600: 69 6f 6e 73 20 61 74 20 6c 65 61 73 74 20 74 6f  ions at least to
a610: 20 74 68 65 20 6e 65 78 74 20 6d 75 6c 74 69 70   the next multip
a620: 6c 65 0a 2a 2a 20 6f 66 20 38 2e 20 20 53 6f 6d  le.** of 8.  Som
a630: 65 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75  e allocators rou
a640: 6e 64 20 75 70 20 74 6f 20 61 20 6c 61 72 67 65  nd up to a large
a650: 72 20 6d 75 6c 74 69 70 6c 65 20 6f 72 20 74 6f  r multiple or to
a660: 20 61 20 70 6f 77 65 72 20 6f 66 20 32 2e 0a 2a   a power of 2..*
a670: 2a 0a 2a 2a 20 54 68 65 20 78 49 6e 69 74 20 6d  *.** The xInit m
a680: 65 74 68 6f 64 20 69 6e 69 74 69 61 6c 69 7a 65  ethod initialize
a690: 73 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  s the memory all
a6a0: 6f 63 61 74 6f 72 2e 20 20 28 46 6f 72 20 65 78  ocator.  (For ex
a6b0: 61 6d 70 6c 65 2c 0a 2a 2a 20 69 74 20 6d 69 67  ample,.** it mig
a6c0: 68 74 20 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20  ht allocate any 
a6d0: 72 65 71 75 69 72 65 20 6d 75 74 65 78 65 73 20  require mutexes 
a6e0: 6f 72 20 69 6e 69 74 69 61 6c 69 7a 65 20 69 6e  or initialize in
a6f0: 74 65 72 6e 61 6c 20 64 61 74 61 0a 2a 2a 20 73  ternal data.** s
a700: 74 72 75 63 74 75 72 65 73 2e 20 20 54 68 65 20  tructures.  The 
a710: 78 53 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64  xShutdown method
a720: 20 69 73 20 69 6e 76 6f 6b 65 64 20 28 69 6e 64   is invoked (ind
a730: 69 72 65 63 74 6c 79 29 20 62 79 0a 2a 2a 20 5b  irectly) by.** [
a740: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
a750: 28 29 5d 20 61 6e 64 20 73 68 6f 75 6c 64 20 64  ()] and should d
a760: 65 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65  eallocate any re
a770: 73 6f 75 72 63 65 73 20 61 63 71 75 69 72 65 64  sources acquired
a780: 0a 2a 2a 20 62 79 20 78 49 6e 69 74 2e 20 20 54  .** by xInit.  T
a790: 68 65 20 70 41 70 70 44 61 74 61 20 70 6f 69 6e  he pAppData poin
a7a0: 74 65 72 20 69 73 20 75 73 65 64 20 61 73 20 74  ter is used as t
a7b0: 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65  he only paramete
a7c0: 72 20 74 6f 0a 2a 2a 20 78 49 6e 69 74 20 61 6e  r to.** xInit an
a7d0: 64 20 78 53 68 75 74 64 6f 77 6e 2e 0a 2a 2f 0a  d xShutdown..*/.
a7e0: 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
a7f0: 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
a800: 64 73 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  ds sqlite3_mem_m
a810: 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73  ethods;.struct s
a820: 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
a830: 64 73 20 7b 0a 20 20 76 6f 69 64 20 2a 28 2a 78  ds {.  void *(*x
a840: 4d 61 6c 6c 6f 63 29 28 69 6e 74 29 3b 20 20 20  Malloc)(int);   
a850: 20 20 20 20 20 20 2f 2a 20 4d 65 6d 6f 72 79 20        /* Memory 
a860: 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 75 6e 63 74  allocation funct
a870: 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a  ion */.  void (*
a880: 78 46 72 65 65 29 28 76 6f 69 64 2a 29 3b 20 20  xFree)(void*);  
a890: 20 20 20 20 20 20 20 20 2f 2a 20 46 72 65 65 20          /* Free 
a8a0: 61 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69  a prior allocati
a8b0: 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 28 2a  on */.  void *(*
a8c0: 78 52 65 61 6c 6c 6f 63 29 28 76 6f 69 64 2a 2c  xRealloc)(void*,
a8d0: 69 6e 74 29 3b 20 20 2f 2a 20 52 65 73 69 7a 65  int);  /* Resize
a8e0: 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a   an allocation *
a8f0: 2f 0a 20 20 69 6e 74 20 28 2a 78 53 69 7a 65 29  /.  int (*xSize)
a900: 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20  (void*);        
a910: 20 20 20 2f 2a 20 52 65 74 75 72 6e 20 74 68 65     /* Return the
a920: 20 73 69 7a 65 20 6f 66 20 61 6e 20 61 6c 6c 6f   size of an allo
a930: 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20  cation */.  int 
a940: 28 2a 78 52 6f 75 6e 64 75 70 29 28 69 6e 74 29  (*xRoundup)(int)
a950: 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 52 6f  ;          /* Ro
a960: 75 6e 64 20 75 70 20 72 65 71 75 65 73 74 20 73  und up request s
a970: 69 7a 65 20 74 6f 20 61 6c 6c 6f 63 61 74 69 6f  ize to allocatio
a980: 6e 20 73 69 7a 65 20 2a 2f 0a 20 20 69 6e 74 20  n size */.  int 
a990: 28 2a 78 49 6e 69 74 29 28 76 6f 69 64 2a 29 3b  (*xInit)(void*);
a9a0: 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 49 6e             /* In
a9b0: 69 74 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d  itialize the mem
a9c0: 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f  ory allocator */
a9d0: 0a 20 20 76 6f 69 64 20 28 2a 78 53 68 75 74 64  .  void (*xShutd
a9e0: 6f 77 6e 29 28 76 6f 69 64 2a 29 3b 20 20 20 20  own)(void*);    
a9f0: 20 20 2f 2a 20 44 65 69 6e 69 74 69 61 6c 69 7a    /* Deinitializ
aa00: 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  e the memory all
aa10: 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64  ocator */.  void
aa20: 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20 20   *pAppData;     
aa30: 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 72             /* Ar
aa40: 67 75 6d 65 6e 74 20 74 6f 20 78 49 6e 69 74 28  gument to xInit(
aa50: 29 20 61 6e 64 20 78 53 68 75 74 64 6f 77 6e 28  ) and xShutdown(
aa60: 29 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ) */.};../*.** C
aa70: 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75  API3REF: Configu
aa80: 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 20 7b  ration Options {
aa90: 48 31 30 31 36 30 7d 20 3c 53 32 30 30 30 30 3e  H10160} <S20000>
aaa0: 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c  .** EXPERIMENTAL
aab0: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e  .**.** These con
aac0: 73 74 61 6e 74 73 20 61 72 65 20 74 68 65 20 61  stants are the a
aad0: 76 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 72  vailable integer
aae0: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
aaf0: 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63  ptions that.** c
ab00: 61 6e 20 62 65 20 70 61 73 73 65 64 20 61 73 20  an be passed as 
ab10: 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
ab20: 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  nt to the [sqlit
ab30: 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74  e3_config()] int
ab40: 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65  erface..**.** Ne
ab50: 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  w configuration 
ab60: 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61  options may be a
ab70: 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72  dded in future r
ab80: 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74  eleases of SQLit
ab90: 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63  e..** Existing c
aba0: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
abb0: 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 64 69  ions might be di
abc0: 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70  scontinued.  App
abd0: 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f  lications.** sho
abe0: 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72 65  uld check the re
abf0: 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b  turn code from [
ac00: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
ac10: 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74  ] to make sure t
ac20: 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20  hat.** the call 
ac30: 77 6f 72 6b 65 64 2e 20 20 54 68 65 20 5b 73 71  worked.  The [sq
ac40: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
ac50: 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72  interface will r
ac60: 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a  eturn a.** non-z
ac70: 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  ero [error code]
ac80: 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75   if a discontinu
ac90: 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65  ed or unsupporte
aca0: 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  d configuration 
acb0: 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76  option.** is inv
acc0: 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e  oked..**.** <dl>
acd0: 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  .** <dt>SQLITE_C
ace0: 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45  ONFIG_SINGLETHRE
acf0: 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  AD</dt>.** <dd>T
ad00: 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75  here are no argu
ad10: 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70  ments to this op
ad20: 74 69 6f 6e 2e 20 20 54 68 69 73 20 6f 70 74 69  tion.  This opti
ad30: 6f 6e 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20 61  on disables.** a
ad40: 6c 6c 20 6d 75 74 65 78 69 6e 67 20 61 6e 64 20  ll mutexing and 
ad50: 70 75 74 73 20 53 51 4c 69 74 65 20 69 6e 74 6f  puts SQLite into
ad60: 20 61 20 6d 6f 64 65 20 77 68 65 72 65 20 69 74   a mode where it
ad70: 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 75 73 65   can only be use
ad80: 64 0a 2a 2a 20 62 79 20 61 20 73 69 6e 67 6c 65  d.** by a single
ad90: 20 74 68 72 65 61 64 2e 3c 2f 64 64 3e 0a 2a 2a   thread.</dd>.**
ada0: 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  .** <dt>SQLITE_C
adb0: 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41  ONFIG_MULTITHREA
adc0: 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  D</dt>.** <dd>Th
add0: 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d  ere are no argum
ade0: 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74  ents to this opt
adf0: 69 6f 6e 2e 20 20 54 68 69 73 20 6f 70 74 69 6f  ion.  This optio
ae00: 6e 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20 6d 75  n disables.** mu
ae10: 74 65 78 69 6e 67 20 6f 6e 20 5b 64 61 74 61 62  texing on [datab
ae20: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
ae30: 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74  and [prepared st
ae40: 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73  atement] objects
ae50: 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  ..** The applica
ae60: 74 69 6f 6e 20 69 73 20 72 65 73 70 6f 6e 73 69  tion is responsi
ae70: 62 6c 65 20 66 6f 72 20 73 65 72 69 61 6c 69 7a  ble for serializ
ae80: 69 6e 67 20 61 63 63 65 73 73 20 74 6f 0a 2a 2a  ing access to.**
ae90: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
aea0: 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65  ctions] and [pre
aeb0: 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73  pared statements
aec0: 5d 2e 20 20 42 75 74 20 6f 74 68 65 72 20 6d 75  ].  But other mu
aed0: 74 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61  texes.** are ena
aee0: 62 6c 65 64 20 73 6f 20 74 68 61 74 20 53 51 4c  bled so that SQL
aef0: 69 74 65 20 77 69 6c 6c 20 62 65 20 73 61 66 65  ite will be safe
af00: 20 74 6f 20 75 73 65 20 69 6e 20 61 20 6d 75 6c   to use in a mul
af10: 74 69 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 65  ti-threaded.** e
af20: 6e 76 69 72 6f 6e 6d 65 6e 74 20 61 73 20 6c 6f  nvironment as lo
af30: 6e 67 20 61 73 20 6e 6f 20 74 77 6f 20 74 68 72  ng as no two thr
af40: 65 61 64 73 20 61 74 74 65 6d 70 74 20 74 6f 20  eads attempt to 
af50: 75 73 65 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20  use the same.** 
af60: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
af70: 74 69 6f 6e 5d 20 61 74 20 74 68 65 20 73 61 6d  tion] at the sam
af80: 65 20 74 69 6d 65 2e 20 20 53 65 65 20 74 68 65  e time.  See the
af90: 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
afa0: 5d 0a 2a 2a 20 64 6f 63 75 6d 65 6e 74 61 74 69  ].** documentati
afb0: 6f 6e 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61  on for additiona
afc0: 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 3c 2f  l information.</
afd0: 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51  dd>.**.** <dt>SQ
afe0: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49  LITE_CONFIG_SERI
aff0: 41 4c 49 5a 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c  ALIZED</dt>.** <
b000: 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20  dd>There are no 
b010: 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69  arguments to thi
b020: 73 20 6f 70 74 69 6f 6e 2e 20 20 54 68 69 73 20  s option.  This 
b030: 6f 70 74 69 6f 6e 20 65 6e 61 62 6c 65 73 0a 2a  option enables.*
b040: 2a 20 61 6c 6c 20 6d 75 74 65 78 65 73 20 69 6e  * all mutexes in
b050: 63 6c 75 64 69 6e 67 20 74 68 65 20 72 65 63 75  cluding the recu
b060: 72 73 69 76 65 0a 2a 2a 20 6d 75 74 65 78 65 73  rsive.** mutexes
b070: 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f   on [database co
b080: 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70  nnection] and [p
b090: 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
b0a0: 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 49  t] objects..** I
b0b0: 6e 20 74 68 69 73 20 6d 6f 64 65 20 28 77 68 69  n this mode (whi
b0c0: 63 68 20 69 73 20 74 68 65 20 64 65 66 61 75 6c  ch is the defaul
b0d0: 74 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73  t when SQLite is
b0e0: 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a   compiled with.*
b0f0: 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  * [SQLITE_THREAD
b100: 53 41 46 45 3d 31 5d 29 20 74 68 65 20 53 51 4c  SAFE=1]) the SQL
b110: 69 74 65 20 6c 69 62 72 61 72 79 20 77 69 6c 6c  ite library will
b120: 20 69 74 73 65 6c 66 20 73 65 72 69 61 6c 69 7a   itself serializ
b130: 65 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 5b  e access.** to [
b140: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
b150: 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 61  ions] and [prepa
b160: 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 20  red statements] 
b170: 73 6f 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 61  so that the.** a
b180: 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 20 66 72  pplication is fr
b190: 65 65 20 74 6f 20 75 73 65 20 74 68 65 20 73 61  ee to use the sa
b1a0: 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  me [database con
b1b0: 6e 65 63 74 69 6f 6e 5d 20 6f 72 20 74 68 65 0a  nection] or the.
b1c0: 2a 2a 20 73 61 6d 65 20 5b 70 72 65 70 61 72 65  ** same [prepare
b1d0: 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20  d statement] in 
b1e0: 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64  different thread
b1f0: 73 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69  s at the same ti
b200: 6d 65 2e 0a 2a 2a 20 53 65 65 20 74 68 65 20 5b  me..** See the [
b210: 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
b220: 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f  documentation fo
b230: 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66  r additional inf
b240: 6f 72 6d 61 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a  ormation.</dd>.*
b250: 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
b260: 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 3c 2f 64  CONFIG_MALLOC</d
b270: 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f  t>.** <dd>This o
b280: 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
b290: 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68  ngle argument wh
b2a0: 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ich is a pointer
b2b0: 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e   to an.** instan
b2c0: 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ce of the [sqlit
b2d0: 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20  e3_mem_methods] 
b2e0: 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 20  structure.  The 
b2f0: 61 72 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69  argument specifi
b300: 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76  es.** alternativ
b310: 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f  e low-level memo
b320: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f  ry allocation ro
b330: 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65  utines to be use
b340: 64 20 69 6e 20 70 6c 61 63 65 20 6f 66 0a 2a 2a  d in place of.**
b350: 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f   the memory allo
b360: 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20  cation routines 
b370: 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74  built into SQLit
b380: 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  e.</dd>.**.** <d
b390: 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
b3a0: 47 45 54 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a  GETMALLOC</dt>.*
b3b0: 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f  * <dd>This optio
b3c0: 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  n takes a single
b3d0: 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20   argument which 
b3e0: 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
b3f0: 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f  an.** instance o
b400: 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  f the [sqlite3_m
b410: 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75  em_methods] stru
b420: 63 74 75 72 65 2e 20 20 54 68 65 20 5b 73 71 6c  cture.  The [sql
b430: 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
b440: 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 69  ].** structure i
b450: 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68  s filled with th
b460: 65 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69  e currently defi
b470: 6e 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ned memory alloc
b480: 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 0a  ation routines..
b490: 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63  ** This option c
b4a0: 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76  an be used to ov
b4b0: 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75  erload the defau
b4c0: 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  lt memory alloca
b4d0: 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73  tion.** routines
b4e0: 20 77 69 74 68 20 61 20 77 72 61 70 70 65 72 20   with a wrapper 
b4f0: 74 68 61 74 20 73 69 6d 75 6c 61 74 69 6f 6e 73  that simulations
b500: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
b510: 6f 6e 20 66 61 69 6c 75 72 65 20 6f 72 0a 2a 2a  on failure or.**
b520: 20 74 72 61 63 6b 73 20 6d 65 6d 6f 72 79 20 75   tracks memory u
b530: 73 61 67 65 2c 20 66 6f 72 20 65 78 61 6d 70 6c  sage, for exampl
b540: 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  e.</dd>.**.** <d
b550: 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
b560: 4d 45 4d 53 54 41 54 55 53 3c 2f 64 74 3e 0a 2a  MEMSTATUS</dt>.*
b570: 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f  * <dd>This optio
b580: 6e 20 74 61 6b 65 73 20 73 69 6e 67 6c 65 20 61  n takes single a
b590: 72 67 75 6d 65 6e 74 20 6f 66 20 74 79 70 65 20  rgument of type 
b5a0: 69 6e 74 2c 20 69 6e 74 65 72 70 72 65 74 65 64  int, interpreted
b5b0: 20 61 73 20 61 20 0a 2a 2a 20 62 6f 6f 6c 65 61   as a .** boolea
b5c0: 6e 2c 20 77 68 69 63 68 20 65 6e 61 62 6c 65 73  n, which enables
b5d0: 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68 65   or disables the
b5e0: 20 63 6f 6c 6c 65 63 74 69 6f 6e 20 6f 66 20 6d   collection of m
b5f0: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
b600: 20 0a 2a 2a 20 73 74 61 74 69 73 74 69 63 73 2e   .** statistics.
b610: 20 57 68 65 6e 20 64 69 73 61 62 6c 65 64 2c 20   When disabled, 
b620: 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51  the following SQ
b630: 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20  Lite interfaces 
b640: 62 65 63 6f 6d 65 20 0a 2a 2a 20 6e 6f 6e 2d 6f  become .** non-o
b650: 70 65 72 61 74 69 6f 6e 61 6c 3a 0a 2a 2a 20 20  perational:.**  
b660: 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20   <ul>.**   <li> 
b670: 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
b680: 75 73 65 64 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69  used()].**   <li
b690: 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  > [sqlite3_memor
b6a0: 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 0a 2a  y_highwater()].*
b6b0: 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65  *   <li> [sqlite
b6c0: 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69  3_soft_heap_limi
b6d0: 74 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b  t()].**   <li> [
b6e0: 73 71 6c 69 74 65 33 5f 73 74 61 74 75 73 28 29  sqlite3_status()
b6f0: 5d 0a 2a 2a 20 20 20 3c 2f 75 6c 3e 0a 2a 2a 20  ].**   </ul>.** 
b700: 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
b710: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43  SQLITE_CONFIG_SC
b720: 52 41 54 43 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  RATCH</dt>.** <d
b730: 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 70  d>This option sp
b740: 65 63 69 66 69 65 73 20 61 20 73 74 61 74 69 63  ecifies a static
b750: 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74   memory buffer t
b760: 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20 75  hat SQLite can u
b770: 73 65 20 66 6f 72 0a 2a 2a 20 73 63 72 61 74 63  se for.** scratc
b780: 68 20 6d 65 6d 6f 72 79 2e 20 20 54 68 65 72 65  h memory.  There
b790: 20 61 72 65 20 74 68 72 65 65 20 61 72 67 75 6d   are three argum
b7a0: 65 6e 74 73 3a 20 20 41 20 70 6f 69 6e 74 65 72  ents:  A pointer
b7b0: 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 61 6c   an 8-byte.** al
b7c0: 69 67 6e 65 64 20 6d 65 6d 6f 72 79 20 62 75 66  igned memory buf
b7d0: 66 65 72 20 66 72 6f 6d 20 77 68 69 63 68 20 74  fer from which t
b7e0: 68 65 20 73 63 72 61 63 68 20 61 6c 6c 6f 63 61  he scrach alloca
b7f0: 74 69 6f 6e 73 20 77 69 6c 6c 20 62 65 0a 2a 2a  tions will be.**
b800: 20 64 72 61 77 6e 2c 20 74 68 65 20 73 69 7a 65   drawn, the size
b810: 20 6f 66 20 65 61 63 68 20 73 63 72 61 74 63 68   of each scratch
b820: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 28 73 7a 29   allocation (sz)
b830: 2c 0a 2a 2a 20 61 6e 64 20 74 68 65 20 6d 61 78  ,.** and the max
b840: 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 73  imum number of s
b850: 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f  cratch allocatio
b860: 6e 73 20 28 4e 29 2e 20 20 54 68 65 20 73 7a 0a  ns (N).  The sz.
b870: 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74  ** argument must
b880: 20 62 65 20 61 20 6d 75 6c 74 69 70 6c 65 20 6f   be a multiple o
b890: 66 20 31 36 2e 20 54 68 65 20 73 7a 20 70 61 72  f 16. The sz par
b8a0: 61 6d 65 74 65 72 20 73 68 6f 75 6c 64 20 62 65  ameter should be
b8b0: 20 61 20 66 65 77 20 62 79 74 65 73 0a 2a 2a 20   a few bytes.** 
b8c0: 6c 61 72 67 65 72 20 74 68 61 6e 20 74 68 65 20  larger than the 
b8d0: 61 63 74 75 61 6c 20 73 63 72 61 74 63 68 20 73  actual scratch s
b8e0: 70 61 63 65 20 72 65 71 75 69 72 65 64 20 64 75  pace required du
b8f0: 65 20 74 6f 20 69 6e 74 65 72 6e 61 6c 20 6f 76  e to internal ov
b900: 65 72 68 65 61 64 2e 0a 2a 2a 20 54 68 65 20 66  erhead..** The f
b910: 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 73 68  irst argument sh
b920: 6f 75 6c 64 20 70 6f 69 6e 74 65 72 20 74 6f 20  ould pointer to 
b930: 61 6e 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65  an 8-byte aligne
b940: 64 20 62 75 66 66 65 72 0a 2a 2a 20 6f 66 20 61  d buffer.** of a
b950: 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79 74  t least sz*N byt
b960: 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a  es of memory..**
b970: 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65   SQLite will use
b980: 20 6e 6f 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e   no more than on
b990: 65 20 73 63 72 61 74 63 68 20 62 75 66 66 65 72  e scratch buffer
b9a0: 20 61 74 20 6f 6e 63 65 20 70 65 72 20 74 68 72   at once per thr
b9b0: 65 61 64 2c 20 73 6f 0a 2a 2a 20 4e 20 73 68 6f  ead, so.** N sho
b9c0: 75 6c 64 20 62 65 20 73 65 74 20 74 6f 20 74 68  uld be set to th
b9d0: 65 20 65 78 70 65 63 74 65 64 20 6d 61 78 69 6d  e expected maxim
b9e0: 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74 68 72  um number of thr
b9f0: 65 61 64 73 2e 20 20 54 68 65 20 73 7a 0a 2a 2a  eads.  The sz.**
ba00: 20 70 61 72 61 6d 65 74 65 72 20 73 68 6f 75 6c   parameter shoul
ba10: 64 20 62 65 20 36 20 74 69 6d 65 73 20 74 68 65  d be 6 times the
ba20: 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6c 61 72   size of the lar
ba30: 67 65 73 74 20 64 61 74 61 62 61 73 65 20 70 61  gest database pa
ba40: 67 65 20 73 69 7a 65 2e 0a 2a 2a 20 53 63 72 61  ge size..** Scra
ba50: 74 63 68 20 62 75 66 66 65 72 73 20 61 72 65 20  tch buffers are 
ba60: 75 73 65 64 20 61 73 20 70 61 72 74 20 6f 66 20  used as part of 
ba70: 74 68 65 20 62 74 72 65 65 20 62 61 6c 61 6e 63  the btree balanc
ba80: 65 20 6f 70 65 72 61 74 69 6f 6e 2e 20 20 49 66  e operation.  If
ba90: 0a 2a 2a 20 54 68 65 20 62 74 72 65 65 20 62 61  .** The btree ba
baa0: 6c 61 6e 63 65 72 20 6e 65 65 64 73 20 61 64 64  lancer needs add
bab0: 69 74 69 6f 6e 61 6c 20 6d 65 6d 6f 72 79 20 62  itional memory b
bac0: 65 79 6f 6e 64 20 77 68 61 74 20 69 73 20 70 72  eyond what is pr
bad0: 6f 76 69 64 65 64 20 62 79 0a 2a 2a 20 73 63 72  ovided by.** scr
bae0: 61 74 63 68 20 62 75 66 66 65 72 73 20 6f 72 20  atch buffers or 
baf0: 69 66 20 6e 6f 20 73 63 72 61 74 63 68 20 62 75  if no scratch bu
bb00: 66 66 65 72 20 73 70 61 63 65 20 69 73 20 73 70  ffer space is sp
bb10: 65 63 69 66 69 65 64 2c 20 74 68 65 6e 20 53 51  ecified, then SQ
bb20: 4c 69 74 65 0a 2a 2a 20 67 6f 65 73 20 74 6f 20  Lite.** goes to 
bb30: 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
bb40: 29 5d 20 74 6f 20 6f 62 74 61 69 6e 20 74 68 65  )] to obtain the
bb50: 20 6d 65 6d 6f 72 79 20 69 74 20 6e 65 65 64 73   memory it needs
bb60: 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74  .</dd>.**.** <dt
bb70: 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  >SQLITE_CONFIG_P
bb80: 41 47 45 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a  AGECACHE</dt>.**
bb90: 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e   <dd>This option
bba0: 20 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61   specifies a sta
bbb0: 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65  tic memory buffe
bbc0: 72 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 61  r that SQLite ca
bbd0: 6e 20 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68 65  n use for.** the
bbe0: 20 64 61 74 61 62 61 73 65 20 70 61 67 65 20 63   database page c
bbf0: 61 63 68 65 20 77 69 74 68 20 74 68 65 20 64 65  ache with the de
bc00: 66 61 75 6c 74 20 70 61 67 65 20 63 61 63 68 65  fault page cache
bc10: 20 69 6d 70 6c 65 6d 65 6e 61 74 69 6f 6e 2e 20   implemenation. 
bc20: 20 0a 2a 2a 20 54 68 69 73 20 63 6f 6e 66 69 67   .** This config
bc30: 75 72 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e  uration should n
bc40: 6f 74 20 62 65 20 75 73 65 64 20 69 66 20 61 6e  ot be used if an
bc50: 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
bc60: 69 6e 65 20 70 61 67 65 0a 2a 2a 20 63 61 63 68  ine page.** cach
bc70: 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
bc80: 20 69 73 20 6c 6f 61 64 65 64 20 75 73 69 6e 67   is loaded using
bc90: 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46   the SQLITE_CONF
bca0: 49 47 5f 50 43 41 43 48 45 20 6f 70 74 69 6f 6e  IG_PCACHE option
bcb0: 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74  ..** There are t
bcc0: 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 20 74  hree arguments t
bcd0: 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 3a 20 41  o this option: A
bce0: 20 70 6f 69 6e 74 65 72 20 74 6f 20 38 2d 62 79   pointer to 8-by
bcf0: 74 65 20 61 6c 69 67 6e 65 64 0a 2a 2a 20 6d 65  te aligned.** me
bd00: 6d 6f 72 79 2c 20 74 68 65 20 73 69 7a 65 20 6f  mory, the size o
bd10: 66 20 65 61 63 68 20 70 61 67 65 20 62 75 66 66  f each page buff
bd20: 65 72 20 28 73 7a 29 2c 20 61 6e 64 20 74 68 65  er (sz), and the
bd30: 20 6e 75 6d 62 65 72 20 6f 66 20 70 61 67 65 73   number of pages
bd40: 20 28 4e 29 2e 0a 2a 2a 20 54 68 65 20 73 7a 20   (N)..** The sz 
bd50: 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20  argument should 
bd60: 62 65 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74  be the size of t
bd70: 68 65 20 6c 61 72 67 65 73 74 20 64 61 74 61 62  he largest datab
bd80: 61 73 65 20 70 61 67 65 0a 2a 2a 20 28 61 20 70  ase page.** (a p
bd90: 6f 77 65 72 20 6f 66 20 74 77 6f 20 62 65 74 77  ower of two betw
bda0: 65 65 6e 20 35 31 32 20 61 6e 64 20 33 32 37 36  een 512 and 3276
bdb0: 38 29 20 70 6c 75 73 20 61 20 6c 69 74 74 6c 65  8) plus a little
bdc0: 20 65 78 74 72 61 20 66 6f 72 20 65 61 63 68 0a   extra for each.
bdd0: 2a 2a 20 70 61 67 65 20 68 65 61 64 65 72 2e 20  ** page header. 
bde0: 20 54 68 65 20 70 61 67 65 20 68 65 61 64 65 72   The page header
bdf0: 20 73 69 7a 65 20 69 73 20 32 30 20 74 6f 20 34   size is 20 to 4
be00: 30 20 62 79 74 65 73 20 64 65 70 65 6e 64 69 6e  0 bytes dependin
be10: 67 20 6f 6e 0a 2a 2a 20 74 68 65 20 68 6f 73 74  g on.** the host
be20: 20 61 72 63 68 69 74 65 63 74 75 72 65 2e 20 20   architecture.  
be30: 49 74 20 69 73 20 68 61 72 6d 6c 65 73 73 2c 20  It is harmless, 
be40: 61 70 61 72 74 20 66 72 6f 6d 20 74 68 65 20 77  apart from the w
be50: 61 73 74 65 64 20 6d 65 6d 6f 72 79 2c 0a 2a 2a  asted memory,.**
be60: 20 74 6f 20 6d 61 6b 65 20 73 7a 20 61 20 6c 69   to make sz a li
be70: 74 74 6c 65 20 74 6f 6f 20 6c 61 72 67 65 2e 20  ttle too large. 
be80: 20 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 61 72   The first.** ar
be90: 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 70 6f  gument should po
bea0: 69 6e 74 20 74 6f 20 61 6e 20 61 6c 6c 6f 63 61  int to an alloca
beb0: 74 69 6f 6e 20 6f 66 20 61 74 20 6c 65 61 73 74  tion of at least
bec0: 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d   sz*N bytes of m
bed0: 65 6d 6f 72 79 2e 0a 2a 2a 20 53 51 4c 69 74 65  emory..** SQLite
bee0: 20 77 69 6c 6c 20 75 73 65 20 74 68 65 20 6d 65   will use the me
bef0: 6d 6f 72 79 20 70 72 6f 76 69 64 65 64 20 62 79  mory provided by
bf00: 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
bf10: 65 6e 74 20 74 6f 20 73 61 74 69 73 66 79 20 69  ent to satisfy i
bf20: 74 73 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6e 65 65  ts.** memory nee
bf30: 64 73 20 66 6f 72 20 74 68 65 20 66 69 72 73 74  ds for the first
bf40: 20 4e 20 70 61 67 65 73 20 74 68 61 74 20 69 74   N pages that it
bf50: 20 61 64 64 73 20 74 6f 20 63 61 63 68 65 2e 20   adds to cache. 
bf60: 20 49 66 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a   If additional.*
bf70: 2a 20 70 61 67 65 20 63 61 63 68 65 20 6d 65 6d  * page cache mem
bf80: 6f 72 79 20 69 73 20 6e 65 65 64 65 64 20 62 65  ory is needed be
bf90: 79 6f 6e 64 20 77 68 61 74 20 69 73 20 70 72 6f  yond what is pro
bfa0: 76 69 64 65 64 20 62 79 20 74 68 69 73 20 6f 70  vided by this op
bfb0: 74 69 6f 6e 2c 20 74 68 65 6e 0a 2a 2a 20 53 51  tion, then.** SQ
bfc0: 4c 69 74 65 20 67 6f 65 73 20 74 6f 20 5b 73 71  Lite goes to [sq
bfd0: 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
bfe0: 66 6f 72 20 74 68 65 20 61 64 64 69 74 69 6f 6e  for the addition
bff0: 61 6c 20 73 74 6f 72 61 67 65 20 73 70 61 63 65  al storage space
c000: 2e 0a 2a 2a 20 54 68 65 20 69 6d 70 6c 65 6d 65  ..** The impleme
c010: 6e 74 61 74 69 6f 6e 20 6d 69 67 68 74 20 75 73  ntation might us
c020: 65 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66  e one or more of
c030: 20 74 68 65 20 4e 20 62 75 66 66 65 72 73 20 74   the N buffers t
c040: 6f 20 68 6f 6c 64 20 0a 2a 2a 20 6d 65 6d 6f 72  o hold .** memor
c050: 79 20 61 63 63 6f 75 6e 74 69 6e 67 20 69 6e 66  y accounting inf
c060: 6f 72 6d 61 74 69 6f 6e 2e 20 54 68 65 20 70 6f  ormation. The po
c070: 69 6e 74 65 72 20 69 6e 20 74 68 65 20 66 69 72  inter in the fir
c080: 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74  st argument must
c090: 0a 2a 2a 20 62 65 20 61 6c 69 67 6e 65 64 20 74  .** be aligned t
c0a0: 6f 20 61 6e 20 38 2d 62 79 74 65 20 62 6f 75 6e  o an 8-byte boun
c0b0: 64 61 72 79 20 6f 72 20 73 75 62 73 65 71 75 65  dary or subseque
c0c0: 6e 74 20 62 65 68 61 76 69 6f 72 20 6f 66 20 53  nt behavior of S
c0d0: 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 62 65  QLite.** will be
c0e0: 20 75 6e 64 65 66 69 6e 65 64 2e 3c 2f 64 64 3e   undefined.</dd>
c0f0: 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
c100: 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 3c 2f 64  E_CONFIG_HEAP</d
c110: 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f  t>.** <dd>This o
c120: 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20  ption specifies 
c130: 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20  a static memory 
c140: 62 75 66 66 65 72 20 74 68 61 74 20 53 51 4c 69  buffer that SQLi
c150: 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 66  te will use.** f
c160: 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 64 79  or all of its dy
c170: 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 61 6c 6c  namic memory all
c180: 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 20 62 65  ocation needs be
c190: 79 6f 6e 64 20 74 68 6f 73 65 20 70 72 6f 76 69  yond those provi
c1a0: 64 65 64 0a 2a 2a 20 66 6f 72 20 62 79 20 5b 53  ded.** for by [S
c1b0: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52  QLITE_CONFIG_SCR
c1c0: 41 54 43 48 5d 20 61 6e 64 20 5b 53 51 4c 49 54  ATCH] and [SQLIT
c1d0: 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43  E_CONFIG_PAGECAC
c1e0: 48 45 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72  HE]..** There ar
c1f0: 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74  e three argument
c200: 73 3a 20 41 6e 20 38 2d 62 79 74 65 20 61 6c 69  s: An 8-byte ali
c210: 67 6e 65 64 20 70 6f 69 6e 74 65 72 20 74 6f 20  gned pointer to 
c220: 74 68 65 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 74  the memory,.** t
c230: 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
c240: 65 73 20 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79  es in the memory
c250: 20 62 75 66 66 65 72 2c 20 61 6e 64 20 74 68 65   buffer, and the
c260: 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74   minimum allocat
c270: 69 6f 6e 20 73 69 7a 65 2e 0a 2a 2a 20 49 66 20  ion size..** If 
c280: 74 68 65 20 66 69 72 73 74 20 70 6f 69 6e 74 65  the first pointe
c290: 72 20 28 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f  r (the memory po
c2a0: 69 6e 74 65 72 29 20 69 73 20 4e 55 4c 4c 2c 20  inter) is NULL, 
c2b0: 74 68 65 6e 20 53 51 4c 69 74 65 20 72 65 76 65  then SQLite reve
c2c0: 72 74 73 0a 2a 2a 20 74 6f 20 75 73 69 6e 67 20  rts.** to using 
c2d0: 69 74 73 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f  its default memo
c2e0: 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 28 74 68  ry allocator (th
c2f0: 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28  e system malloc(
c300: 29 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  ) implementation
c310: 29 2c 0a 2a 2a 20 75 6e 64 6f 69 6e 67 20 61 6e  ),.** undoing an
c320: 79 20 70 72 69 6f 72 20 69 6e 76 6f 63 61 74 69  y prior invocati
c330: 6f 6e 20 6f 66 20 5b 53 51 4c 49 54 45 5f 43 4f  on of [SQLITE_CO
c340: 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 2e 20 20 49  NFIG_MALLOC].  I
c350: 66 20 74 68 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20  f the.** memory 
c360: 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e  pointer is not N
c370: 55 4c 4c 20 61 6e 64 20 65 69 74 68 65 72 20 5b  ULL and either [
c380: 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45  SQLITE_ENABLE_ME
c390: 4d 53 59 53 33 5d 20 6f 72 0a 2a 2a 20 5b 53 51  MSYS3] or.** [SQ
c3a0: 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53  LITE_ENABLE_MEMS
c3b0: 59 53 35 5d 20 61 72 65 20 64 65 66 69 6e 65 64  YS5] are defined
c3c0: 2c 20 74 68 65 6e 20 74 68 65 20 61 6c 74 65 72  , then the alter
c3d0: 6e 61 74 69 76 65 20 6d 65 6d 6f 72 79 0a 2a 2a  native memory.**
c3e0: 20 61 6c 6c 6f 63 61 74 6f 72 20 69 73 20 65 6e   allocator is en
c3f0: 67 61 67 65 64 20 74 6f 20 68 61 6e 64 6c 65 20  gaged to handle 
c400: 61 6c 6c 20 6f 66 20 53 51 4c 69 74 65 73 20 6d  all of SQLites m
c410: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
c420: 20 6e 65 65 64 73 2e 0a 2a 2a 20 54 68 65 20 66   needs..** The f
c430: 69 72 73 74 20 70 6f 69 6e 74 65 72 20 28 74 68  irst pointer (th
c440: 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72  e memory pointer
c450: 29 20 6d 75 73 74 20 62 65 20 61 6c 69 67 6e 65  ) must be aligne
c460: 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 0a 2a  d to an 8-byte.*
c470: 2a 20 62 6f 75 6e 64 61 72 79 20 6f 72 20 73 75  * boundary or su
c480: 62 73 65 71 75 65 6e 74 20 62 65 68 61 76 69 6f  bsequent behavio
c490: 72 20 6f 66 20 53 51 4c 69 74 65 20 77 69 6c 6c  r of SQLite will
c4a0: 20 62 65 20 75 6e 64 65 66 69 6e 65 64 2e 3c 2f   be undefined.</
c4b0: 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51  dd>.**.** <dt>SQ
c4c0: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45  LITE_CONFIG_MUTE
c4d0: 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  X</dt>.** <dd>Th
c4e0: 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  is option takes 
c4f0: 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
c500: 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69  t which is a poi
c510: 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e  nter to an.** in
c520: 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73  stance of the [s
c530: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74  qlite3_mutex_met
c540: 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e  hods] structure.
c550: 20 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 73    The argument s
c560: 70 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65  pecifies.** alte
c570: 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65  rnative low-leve
c580: 6c 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73  l mutex routines
c590: 20 74 6f 20 62 65 20 75 73 65 64 20 69 6e 20 70   to be used in p
c5a0: 6c 61 63 65 0a 2a 2a 20 74 68 65 20 6d 75 74 65  lace.** the mute
c5b0: 78 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74  x routines built
c5c0: 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e 3c 2f 64   into SQLite.</d
c5d0: 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
c5e0: 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55  ITE_CONFIG_GETMU
c5f0: 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  TEX</dt>.** <dd>
c600: 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65  This option take
c610: 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  s a single argum
c620: 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70  ent which is a p
c630: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20  ointer to an.** 
c640: 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20  instance of the 
c650: 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d  [sqlite3_mutex_m
c660: 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72  ethods] structur
c670: 65 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c 69  e.  The.** [sqli
c680: 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64  te3_mutex_method
c690: 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20  s].** structure 
c6a0: 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74  is filled with t
c6b0: 68 65 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66  he currently def
c6c0: 69 6e 65 64 20 6d 75 74 65 78 20 72 6f 75 74 69  ined mutex routi
c6d0: 6e 65 73 2e 0a 2a 2a 20 54 68 69 73 20 6f 70 74  nes..** This opt
c6e0: 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20  ion can be used 
c6f0: 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68 65 20  to overload the 
c700: 64 65 66 61 75 6c 74 20 6d 75 74 65 78 20 61 6c  default mutex al
c710: 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74  location.** rout
c720: 69 6e 65 73 20 77 69 74 68 20 61 20 77 72 61 70  ines with a wrap
c730: 70 65 72 20 75 73 65 64 20 74 6f 20 74 72 61 63  per used to trac
c740: 6b 20 6d 75 74 65 78 20 75 73 61 67 65 20 66 6f  k mutex usage fo
c750: 72 20 70 65 72 66 6f 72 6d 61 6e 63 65 0a 2a 2a  r performance.**
c760: 20 70 72 6f 66 69 6c 69 6e 67 20 6f 72 20 74 65   profiling or te
c770: 73 74 69 6e 67 2c 20 66 6f 72 20 65 78 61 6d 70  sting, for examp
c780: 6c 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  le.</dd>.**.** <
c790: 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
c7a0: 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a  _LOOKASIDE</dt>.
c7b0: 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69  ** <dd>This opti
c7c0: 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20 61 72 67  on takes two arg
c7d0: 75 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74 65  uments that dete
c7e0: 72 6d 69 6e 65 20 74 68 65 20 64 65 66 61 75 6c  rmine the defaul
c7f0: 74 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 63  t.** memory allc
c800: 61 74 69 6f 6e 20 6c 6f 6f 6b 61 73 69 64 65 20  ation lookaside 
c810: 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 2e 20 20 54  optimization.  T
c820: 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
c830: 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65  t is the.** size
c840: 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69   of each lookasi
c850: 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74 20 61  de buffer slot a
c860: 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 69 73  nd the second is
c870: 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a   the number of.*
c880: 2a 20 73 6c 6f 74 73 20 61 6c 6c 6f 63 61 74 65  * slots allocate
c890: 64 20 74 6f 20 65 61 63 68 20 64 61 74 61 62 61  d to each databa
c8a0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 3c 2f  se connection.</
c8b0: 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51  dd>.**.** <dt>SQ
c8c0: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
c8d0: 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  HE</dt>.** <dd>T
c8e0: 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  his option takes
c8f0: 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65   a single argume
c900: 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f  nt which is a po
c910: 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 61 6e 20 5b  inter to.** an [
c920: 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d  sqlite3_pcache_m
c930: 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e 20  ethods] object. 
c940: 20 54 68 69 73 20 6f 62 6a 65 63 74 20 73 70 65   This object spe
c950: 63 69 66 69 65 73 20 74 68 65 20 69 6e 74 65 72  cifies the inter
c960: 66 61 63 65 0a 2a 2a 20 74 6f 20 61 20 63 75 73  face.** to a cus
c970: 74 6f 6d 20 70 61 67 65 20 63 61 63 68 65 20 69  tom page cache i
c980: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20  mplementation.  
c990: 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63  SQLite makes a c
c9a0: 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 62  opy of the.** ob
c9b0: 6a 65 63 74 20 61 6e 64 20 75 73 65 73 20 69 74  ject and uses it
c9c0: 20 66 6f 72 20 70 61 67 65 20 63 61 63 68 65 20   for page cache 
c9d0: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
c9e0: 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  ns.</dd>.**.** <
c9f0: 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
ca00: 5f 47 45 54 50 43 41 43 48 45 3c 2f 64 74 3e 0a  _GETPCACHE</dt>.
ca10: 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69  ** <dd>This opti
ca20: 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
ca30: 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  e argument which
ca40: 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
ca50: 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   an.** [sqlite3_
ca60: 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 5d 20  pcache_methods] 
ca70: 6f 62 6a 65 63 74 2e 20 20 53 51 4c 69 74 65 20  object.  SQLite 
ca80: 63 6f 70 69 65 73 20 6f 66 20 74 68 65 20 63 75  copies of the cu
ca90: 72 72 65 6e 74 0a 2a 2a 20 70 61 67 65 20 63 61  rrent.** page ca
caa0: 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  che implementati
cab0: 6f 6e 20 69 6e 74 6f 20 74 68 61 74 20 6f 62 6a  on into that obj
cac0: 65 63 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ect.</dd>.**.** 
cad0: 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65  </dl>.*/.#define
cae0: 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53   SQLITE_CONFIG_S
caf0: 49 4e 47 4c 45 54 48 52 45 41 44 20 20 31 20 20  INGLETHREAD  1  
cb00: 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e  /* nil */.#defin
cb10: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
cb20: 4d 55 4c 54 49 54 48 52 45 41 44 20 20 20 32 20  MULTITHREAD   2 
cb30: 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69   /* nil */.#defi
cb40: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
cb50: 5f 53 45 52 49 41 4c 49 5a 45 44 20 20 20 20 33  _SERIALIZED    3
cb60: 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66    /* nil */.#def
cb70: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
cb80: 47 5f 4d 41 4c 4c 4f 43 20 20 20 20 20 20 20 20  G_MALLOC        
cb90: 34 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65  4  /* sqlite3_me
cba0: 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64  m_methods* */.#d
cbb0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
cbc0: 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 20 20  FIG_GETMALLOC   
cbd0: 20 20 35 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f    5  /* sqlite3_
cbe0: 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a  mem_methods* */.
cbf0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
cc00: 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 20 20 20  ONFIG_SCRATCH   
cc10: 20 20 20 20 36 20 20 2f 2a 20 76 6f 69 64 2a 2c      6  /* void*,
cc20: 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a   int sz, int N *
cc30: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
cc40: 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48  _CONFIG_PAGECACH
cc50: 45 20 20 20 20 20 37 20 20 2f 2a 20 76 6f 69 64  E     7  /* void
cc60: 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e  *, int sz, int N
cc70: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
cc80: 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20 20  TE_CONFIG_HEAP  
cc90: 20 20 20 20 20 20 20 20 38 20 20 2f 2a 20 76 6f          8  /* vo
cca0: 69 64 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20  id*, int nByte, 
ccb0: 69 6e 74 20 6d 69 6e 20 2a 2f 0a 23 64 65 66 69  int min */.#defi
ccc0: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
ccd0: 5f 4d 45 4d 53 54 41 54 55 53 20 20 20 20 20 39  _MEMSTATUS     9
cce0: 20 20 2f 2a 20 62 6f 6f 6c 65 61 6e 20 2a 2f 0a    /* boolean */.
ccf0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
cd00: 4f 4e 46 49 47 5f 4d 55 54 45 58 20 20 20 20 20  ONFIG_MUTEX     
cd10: 20 20 20 31 30 20 20 2f 2a 20 73 71 6c 69 74 65     10  /* sqlite
cd20: 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a  3_mutex_methods*
cd30: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
cd40: 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54  TE_CONFIG_GETMUT
cd50: 45 58 20 20 20 20 20 31 31 20 20 2f 2a 20 73 71  EX     11  /* sq
cd60: 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68  lite3_mutex_meth
cd70: 6f 64 73 2a 20 2a 2f 0a 2f 2a 20 70 72 65 76 69  ods* */./* previ
cd80: 6f 75 73 6c 79 20 53 51 4c 49 54 45 5f 43 4f 4e  ously SQLITE_CON
cd90: 46 49 47 5f 43 48 55 4e 4b 41 4c 4c 4f 43 20 31  FIG_CHUNKALLOC 1
cda0: 32 20 77 68 69 63 68 20 69 73 20 6e 6f 77 20 75  2 which is now u
cdb0: 6e 75 73 65 64 2e 20 2a 2f 20 0a 23 64 65 66 69  nused. */ .#defi
cdc0: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
cdd0: 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 31 33  _LOOKASIDE    13
cde0: 20 20 2f 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a    /* int int */.
cdf0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
ce00: 4f 4e 46 49 47 5f 50 43 41 43 48 45 20 20 20 20  ONFIG_PCACHE    
ce10: 20 20 20 31 34 20 20 2f 2a 20 73 71 6c 69 74 65     14  /* sqlite
ce20: 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73  3_pcache_methods
ce30: 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
ce40: 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43  ITE_CONFIG_GETPC
ce50: 41 43 48 45 20 20 20 20 31 35 20 20 2f 2a 20 73  ACHE    15  /* s
ce60: 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65  qlite3_pcache_me
ce70: 74 68 6f 64 73 2a 20 2a 2f 0a 0a 2f 2a 0a 2a 2a  thods* */../*.**
ce80: 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69   CAPI3REF: Confi
ce90: 67 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73  guration Options
cea0: 20 7b 48 31 30 31 37 30 7d 20 3c 53 32 30 30 30   {H10170} <S2000
ceb0: 30 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54  0>.** EXPERIMENT
cec0: 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63  AL.**.** These c
ced0: 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 74 68 65  onstants are the
cee0: 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 74 65 67   available integ
cef0: 65 72 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  er configuration
cf00: 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a   options that.**
cf10: 20 63 61 6e 20 62 65 20 70 61 73 73 65 64 20 61   can be passed a
cf20: 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  s the second arg
cf30: 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 71  ument to the [sq
cf40: 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
cf50: 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  )] interface..**
cf60: 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75 72  .** New configur
cf70: 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61  ation options ma
cf80: 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75  y be added in fu
cf90: 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66  ture releases of
cfa0: 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73   SQLite..** Exis
cfb0: 74 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69  ting configurati
cfc0: 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74  on options might
cfd0: 20 62 65 20 64 69 73 63 6f 6e 74 69 6e 75 65 64   be discontinued
cfe0: 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a  .  Applications.
cff0: 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65 63 6b 20  ** should check 
d000: 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65 20  the return code 
d010: 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 64 62  from [sqlite3_db
d020: 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61  _config()] to ma
d030: 6b 65 20 73 75 72 65 20 74 68 61 74 0a 2a 2a 20  ke sure that.** 
d040: 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e  the call worked.
d050: 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 64    The [sqlite3_d
d060: 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65  b_config()] inte
d070: 72 66 61 63 65 20 77 69 6c 6c 20 72 65 74 75 72  rface will retur
d080: 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20  n a.** non-zero 
d090: 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20  [error code] if 
d0a0: 61 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f  a discontinued o
d0b0: 72 20 75 6e 73 75 70 70 6f 72 74 65 64 20 63 6f  r unsupported co
d0c0: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
d0d0: 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64  on.** is invoked
d0e0: 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20  ..**.** <dl>.** 
d0f0: 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e  <dt>SQLITE_DBCON
d100: 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64  FIG_LOOKASIDE</d
d110: 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f  t>.** <dd>This o
d120: 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 68 72 65  ption takes thre
d130: 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67  e additional arg
d140: 75 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74 65  uments that dete
d150: 72 6d 69 6e 65 20 74 68 65 20 0a 2a 2a 20 5b 6c  rmine the .** [l
d160: 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20  ookaside memory 
d170: 61 6c 6c 6f 63 61 74 6f 72 5d 20 63 6f 6e 66 69  allocator] confi
d180: 67 75 72 61 74 69 6f 6e 20 66 6f 72 20 74 68 65  guration for the
d190: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
d1a0: 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 54 68 65 20 66  ction]..** The f
d1b0: 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 28 74  irst argument (t
d1c0: 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
d1d0: 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64  er to [sqlite3_d
d1e0: 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 73 20 61  b_config()] is a
d1f0: 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  .** pointer to a
d200: 6e 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64  n 8-byte aligned
d210: 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74   memory buffer t
d220: 6f 20 75 73 65 20 66 6f 72 20 6c 6f 6f 6b 61 73  o use for lookas
d230: 69 64 65 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 54  ide memory..** T
d240: 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
d250: 74 20 6d 61 79 20 62 65 20 4e 55 4c 4c 20 69 6e  t may be NULL in
d260: 20 77 68 69 63 68 20 63 61 73 65 20 53 51 4c 69   which case SQLi
d270: 74 65 20 77 69 6c 6c 20 61 6c 6c 6f 63 61 74 65  te will allocate
d280: 20 74 68 65 0a 2a 2a 20 6c 6f 6f 6b 61 73 69 64   the.** lookasid
d290: 65 20 62 75 66 66 65 72 20 69 74 73 65 6c 66 20  e buffer itself 
d2a0: 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d  using [sqlite3_m
d2b0: 61 6c 6c 6f 63 28 29 5d 2e 20 20 54 68 65 20 73  alloc()].  The s
d2c0: 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69  econd argument i
d2d0: 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66  s the.** size of
d2e0: 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20   each lookaside 
d2f0: 62 75 66 66 65 72 20 73 6c 6f 74 20 61 6e 64 20  buffer slot and 
d300: 74 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65  the third argume
d310: 6e 74 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72  nt is the number
d320: 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 2e 20 20 54   of.** slots.  T
d330: 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62  he size of the b
d340: 75 66 66 65 72 20 69 6e 20 74 68 65 20 66 69 72  uffer in the fir
d350: 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74  st argument must
d360: 20 62 65 20 67 72 65 61 74 65 72 20 74 68 61 6e   be greater than
d370: 0a 2a 2a 20 6f 72 20 65 71 75 61 6c 20 74 6f 20  .** or equal to 
d380: 74 68 65 20 70 72 6f 64 75 63 74 20 6f 66 20 74  the product of t
d390: 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68  he second and th
d3a0: 69 72 64 20 61 72 67 75 6d 65 6e 74 73 2e 3c 2f  ird arguments.</
d3b0: 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a  dd>.**.** </dl>.
d3c0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
d3d0: 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  E_DBCONFIG_LOOKA
d3e0: 53 49 44 45 20 20 20 20 31 30 30 31 20 20 2f 2a  SIDE    1001  /*
d3f0: 20 76 6f 69 64 2a 20 69 6e 74 20 69 6e 74 20 2a   void* int int *
d400: 2f 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  /.../*.** CAPI3R
d410: 45 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44 69  EF: Enable Or Di
d420: 73 61 62 6c 65 20 45 78 74 65 6e 64 65 64 20 52  sable Extended R
d430: 65 73 75 6c 74 20 43 6f 64 65 73 20 7b 48 31 32  esult Codes {H12
d440: 32 30 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 2a  200} <S10700>.**
d450: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
d460: 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f  extended_result_
d470: 63 6f 64 65 73 28 29 20 72 6f 75 74 69 6e 65 20  codes() routine 
d480: 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62  enables or disab
d490: 6c 65 73 20 74 68 65 0a 2a 2a 20 5b 65 78 74 65  les the.** [exte
d4a0: 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
d4b0: 73 5d 20 66 65 61 74 75 72 65 20 6f 66 20 53 51  s] feature of SQ
d4c0: 4c 69 74 65 2e 20 54 68 65 20 65 78 74 65 6e 64  Lite. The extend
d4d0: 65 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 64  ed result.** cod
d4e0: 65 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 20  es are disabled 
d4f0: 62 79 20 64 65 66 61 75 6c 74 20 66 6f 72 20 68  by default for h
d500: 69 73 74 6f 72 69 63 61 6c 20 63 6f 6d 70 61 74  istorical compat
d510: 69 62 69 6c 69 74 79 20 63 6f 6e 73 69 64 65 72  ibility consider
d520: 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 52 65  ations..**.** Re
d530: 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b  quirements:.** [
d540: 48 31 32 32 30 31 5d 20 5b 48 31 32 32 30 32 5d  H12201] [H12202]
d550: 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
d560: 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f  extended_result_
d570: 63 6f 64 65 73 28 73 71 6c 69 74 65 33 2a 2c 20  codes(sqlite3*, 
d580: 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a  int onoff);../*.
d590: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4c 61 73  ** CAPI3REF: Las
d5a0: 74 20 49 6e 73 65 72 74 20 52 6f 77 69 64 20 7b  t Insert Rowid {
d5b0: 48 31 32 32 32 30 7d 20 3c 53 31 30 37 30 30 3e  H12220} <S10700>
d5c0: 0a 2a 2a 0a 2a 2a 20 45 61 63 68 20 65 6e 74 72  .**.** Each entr
d5d0: 79 20 69 6e 20 61 6e 20 53 51 4c 69 74 65 20 74  y in an SQLite t
d5e0: 61 62 6c 65 20 68 61 73 20 61 20 75 6e 69 71 75  able has a uniqu
d5f0: 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 0a  e 64-bit signed.
d600: 2a 2a 20 69 6e 74 65 67 65 72 20 6b 65 79 20 63  ** integer key c
d610: 61 6c 6c 65 64 20 74 68 65 20 5b 52 4f 57 49 44  alled the [ROWID
d620: 20 7c 20 22 72 6f 77 69 64 22 5d 2e 20 54 68 65   | "rowid"]. The
d630: 20 72 6f 77 69 64 20 69 73 20 61 6c 77 61 79 73   rowid is always
d640: 20 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 61 73   available.** as
d650: 20 61 6e 20 75 6e 64 65 63 6c 61 72 65 64 20 63   an undeclared c
d660: 6f 6c 75 6d 6e 20 6e 61 6d 65 64 20 52 4f 57 49  olumn named ROWI
d670: 44 2c 20 4f 49 44 2c 20 6f 72 20 5f 52 4f 57 49  D, OID, or _ROWI
d680: 44 5f 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68  D_ as long as th
d690: 6f 73 65 0a 2a 2a 20 6e 61 6d 65 73 20 61 72 65  ose.** names are
d6a0: 20 6e 6f 74 20 61 6c 73 6f 20 75 73 65 64 20 62   not also used b
d6b0: 79 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63  y explicitly dec
d6c0: 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 73 2e 20 49  lared columns. I
d6d0: 66 0a 2a 2a 20 74 68 65 20 74 61 62 6c 65 20 68  f.** the table h
d6e0: 61 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 74  as a column of t
d6f0: 79 70 65 20 5b 49 4e 54 45 47 45 52 20 50 52 49  ype [INTEGER PRI
d700: 4d 41 52 59 20 4b 45 59 5d 20 74 68 65 6e 20 74  MARY KEY] then t
d710: 68 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73  hat column.** is
d720: 20 61 6e 6f 74 68 65 72 20 61 6c 69 61 73 20 66   another alias f
d730: 6f 72 20 74 68 65 20 72 6f 77 69 64 2e 0a 2a 2a  or the rowid..**
d740: 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65  .** This routine
d750: 20 72 65 74 75 72 6e 73 20 74 68 65 20 5b 72 6f   returns the [ro
d760: 77 69 64 5d 20 6f 66 20 74 68 65 20 6d 6f 73 74  wid] of the most
d770: 20 72 65 63 65 6e 74 0a 2a 2a 20 73 75 63 63 65   recent.** succe
d780: 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 69  ssful [INSERT] i
d790: 6e 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65  nto the database
d7a0: 20 66 72 6f 6d 20 74 68 65 20 5b 64 61 74 61 62   from the [datab
d7b0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a  ase connection].
d7c0: 2a 2a 20 69 6e 20 74 68 65 20 66 69 72 73 74 20  ** in the first 
d7d0: 61 72 67 75 6d 65 6e 74 2e 20 20 49 66 20 6e 6f  argument.  If no
d7e0: 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53   successful [INS
d7f0: 45 52 54 5d 73 0a 2a 2a 20 68 61 76 65 20 65 76  ERT]s.** have ev
d800: 65 72 20 6f 63 63 75 72 72 65 64 20 6f 6e 20 74  er occurred on t
d810: 68 61 74 20 64 61 74 61 62 61 73 65 20 63 6f 6e  hat database con
d820: 6e 65 63 74 69 6f 6e 2c 20 7a 65 72 6f 20 69 73  nection, zero is
d830: 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
d840: 20 49 66 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20   If an [INSERT] 
d850: 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20 61 20  occurs within a 
d860: 74 72 69 67 67 65 72 2c 20 74 68 65 6e 20 74 68  trigger, then th
d870: 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 65  e [rowid] of the
d880: 20 69 6e 73 65 72 74 65 64 0a 2a 2a 20 72 6f 77   inserted.** row
d890: 20 69 73 20 72 65 74 75 72 6e 65 64 20 62 79 20   is returned by 
d8a0: 74 68 69 73 20 72 6f 75 74 69 6e 65 20 61 73 20  this routine as 
d8b0: 6c 6f 6e 67 20 61 73 20 74 68 65 20 74 72 69 67  long as the trig
d8c0: 67 65 72 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a  ger is running..
d8d0: 2a 2a 20 42 75 74 20 6f 6e 63 65 20 74 68 65 20  ** But once the 
d8e0: 74 72 69 67 67 65 72 20 74 65 72 6d 69 6e 61 74  trigger terminat
d8f0: 65 73 2c 20 74 68 65 20 76 61 6c 75 65 20 72 65  es, the value re
d900: 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 20 72  turned by this r
d910: 6f 75 74 69 6e 65 0a 2a 2a 20 72 65 76 65 72 74  outine.** revert
d920: 73 20 74 6f 20 74 68 65 20 6c 61 73 74 20 76 61  s to the last va
d930: 6c 75 65 20 69 6e 73 65 72 74 65 64 20 62 65 66  lue inserted bef
d940: 6f 72 65 20 74 68 65 20 74 72 69 67 67 65 72 20  ore the trigger 
d950: 66 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20  fired..**.** An 
d960: 5b 49 4e 53 45 52 54 5d 20 74 68 61 74 20 66 61  [INSERT] that fa
d970: 69 6c 73 20 64 75 65 20 74 6f 20 61 20 63 6f 6e  ils due to a con
d980: 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f  straint violatio
d990: 6e 20 69 73 20 6e 6f 74 20 61 0a 2a 2a 20 73 75  n is not a.** su
d9a0: 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54  ccessful [INSERT
d9b0: 5d 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 63  ] and does not c
d9c0: 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65 20  hange the value 
d9d0: 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 69 73  returned by this
d9e0: 0a 2a 2a 20 72 6f 75 74 69 6e 65 2e 20 20 54 68  .** routine.  Th
d9f0: 75 73 20 49 4e 53 45 52 54 20 4f 52 20 46 41 49  us INSERT OR FAI
da00: 4c 2c 20 49 4e 53 45 52 54 20 4f 52 20 49 47 4e  L, INSERT OR IGN
da10: 4f 52 45 2c 20 49 4e 53 45 52 54 20 4f 52 20 52  ORE, INSERT OR R
da20: 4f 4c 4c 42 41 43 4b 2c 0a 2a 2a 20 61 6e 64 20  OLLBACK,.** and 
da30: 49 4e 53 45 52 54 20 4f 52 20 41 42 4f 52 54 20  INSERT OR ABORT 
da40: 6d 61 6b 65 20 6e 6f 20 63 68 61 6e 67 65 73 20  make no changes 
da50: 74 6f 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  to the return va
da60: 6c 75 65 20 6f 66 20 74 68 69 73 0a 2a 2a 20 72  lue of this.** r
da70: 6f 75 74 69 6e 65 20 77 68 65 6e 20 74 68 65 69  outine when thei
da80: 72 20 69 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c  r insertion fail
da90: 73 2e 20 20 57 68 65 6e 20 49 4e 53 45 52 54 20  s.  When INSERT 
daa0: 4f 52 20 52 45 50 4c 41 43 45 0a 2a 2a 20 65 6e  OR REPLACE.** en
dab0: 63 6f 75 6e 74 65 72 73 20 61 20 63 6f 6e 73 74  counters a const
dac0: 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 2c  raint violation,
dad0: 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 66 61 69   it does not fai
dae0: 6c 2e 20 20 54 68 65 0a 2a 2a 20 49 4e 53 45 52  l.  The.** INSER
daf0: 54 20 63 6f 6e 74 69 6e 75 65 73 20 74 6f 20 63  T continues to c
db00: 6f 6d 70 6c 65 74 69 6f 6e 20 61 66 74 65 72 20  ompletion after 
db10: 64 65 6c 65 74 69 6e 67 20 72 6f 77 73 20 74 68  deleting rows th
db20: 61 74 20 63 61 75 73 65 64 0a 2a 2a 20 74 68 65  at caused.** the
db30: 20 63 6f 6e 73 74 72 61 69 6e 74 20 70 72 6f 62   constraint prob
db40: 6c 65 6d 20 73 6f 20 49 4e 53 45 52 54 20 4f 52  lem so INSERT OR
db50: 20 52 45 50 4c 41 43 45 20 77 69 6c 6c 20 61 6c   REPLACE will al
db60: 77 61 79 73 20 63 68 61 6e 67 65 0a 2a 2a 20 74  ways change.** t
db70: 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
db80: 6f 66 20 74 68 69 73 20 69 6e 74 65 72 66 61 63  of this interfac
db90: 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 74 68 65  e..**.** For the
dba0: 20 70 75 72 70 6f 73 65 73 20 6f 66 20 74 68 69   purposes of thi
dbb0: 73 20 72 6f 75 74 69 6e 65 2c 20 61 6e 20 5b 49  s routine, an [I
dbc0: 4e 53 45 52 54 5d 20 69 73 20 63 6f 6e 73 69 64  NSERT] is consid
dbd0: 65 72 65 64 20 74 6f 0a 2a 2a 20 62 65 20 73 75  ered to.** be su
dbe0: 63 63 65 73 73 66 75 6c 20 65 76 65 6e 20 69 66  ccessful even if
dbf0: 20 69 74 20 69 73 20 73 75 62 73 65 71 75 65 6e   it is subsequen
dc00: 74 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e  tly rolled back.
dc10: 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65  .**.** Requireme
dc20: 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 32 32 31 5d  nts:.** [H12221]
dc30: 20 5b 48 31 32 32 32 33 5d 0a 2a 2a 0a 2a 2a 20   [H12223].**.** 
dc40: 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68  If a separate th
dc50: 72 65 61 64 20 70 65 72 66 6f 72 6d 73 20 61 20  read performs a 
dc60: 6e 65 77 20 5b 49 4e 53 45 52 54 5d 20 6f 6e 20  new [INSERT] on 
dc70: 74 68 65 20 73 61 6d 65 0a 2a 2a 20 64 61 74 61  the same.** data
dc80: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
dc90: 77 68 69 6c 65 20 74 68 65 20 5b 73 71 6c 69 74  while the [sqlit
dca0: 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72  e3_last_insert_r
dcb0: 6f 77 69 64 28 29 5d 0a 2a 2a 20 66 75 6e 63 74  owid()].** funct
dcc0: 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 20 61  ion is running a
dcd0: 6e 64 20 74 68 75 73 20 63 68 61 6e 67 65 73 20  nd thus changes 
dce0: 74 68 65 20 6c 61 73 74 20 69 6e 73 65 72 74 20  the last insert 
dcf0: 5b 72 6f 77 69 64 5d 2c 0a 2a 2a 20 74 68 65 6e  [rowid],.** then
dd00: 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
dd10: 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ned by [sqlite3_
dd20: 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69  last_insert_rowi
dd30: 64 28 29 5d 20 69 73 0a 2a 2a 20 75 6e 70 72 65  d()] is.** unpre
dd40: 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6d 69 67  dictable and mig
dd50: 68 74 20 6e 6f 74 20 65 71 75 61 6c 20 65 69 74  ht not equal eit
dd60: 68 65 72 20 74 68 65 20 6f 6c 64 20 6f 72 20 74  her the old or t
dd70: 68 65 20 6e 65 77 0a 2a 2a 20 6c 61 73 74 20 69  he new.** last i
dd80: 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d 2e 0a 2a  nsert [rowid]..*
dd90: 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  /.sqlite3_int64 
dda0: 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73  sqlite3_last_ins
ddb0: 65 72 74 5f 72 6f 77 69 64 28 73 71 6c 69 74 65  ert_rowid(sqlite
ddc0: 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  3*);../*.** CAPI
ddd0: 33 52 45 46 3a 20 43 6f 75 6e 74 20 54 68 65 20  3REF: Count The 
dde0: 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d  Number Of Rows M
ddf0: 6f 64 69 66 69 65 64 20 7b 48 31 32 32 34 30 7d  odified {H12240}
de00: 20 3c 53 31 30 36 30 30 3e 0a 2a 2a 0a 2a 2a 20   <S10600>.**.** 
de10: 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65  This function re
de20: 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
de30: 20 6f 66 20 64 61 74 61 62 61 73 65 20 72 6f 77   of database row
de40: 73 20 74 68 61 74 20 77 65 72 65 20 63 68 61 6e  s that were chan
de50: 67 65 64 0a 2a 2a 20 6f 72 20 69 6e 73 65 72 74  ged.** or insert
de60: 65 64 20 6f 72 20 64 65 6c 65 74 65 64 20 62 79  ed or deleted by
de70: 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
de80: 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20 53 51 4c  ly completed SQL
de90: 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 6f 6e   statement.** on
dea0: 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
deb0: 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63 69  onnection] speci
dec0: 66 69 65 64 20 62 79 20 74 68 65 20 66 69 72 73  fied by the firs
ded0: 74 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20  t parameter..** 
dee0: 4f 6e 6c 79 20 63 68 61 6e 67 65 73 20 74 68 61  Only changes tha
def0: 74 20 61 72 65 20 64 69 72 65 63 74 6c 79 20 73  t are directly s
df00: 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20  pecified by the 
df10: 5b 49 4e 53 45 52 54 5d 2c 20 5b 55 50 44 41 54  [INSERT], [UPDAT
df20: 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 44 45 4c 45 54  E],.** or [DELET
df30: 45 5d 20 73 74 61 74 65 6d 65 6e 74 20 61 72 65  E] statement are
df40: 20 63 6f 75 6e 74 65 64 2e 20 20 41 75 78 69 6c   counted.  Auxil
df50: 69 61 72 79 20 63 68 61 6e 67 65 73 20 63 61 75  iary changes cau
df60: 73 65 64 20 62 79 0a 2a 2a 20 74 72 69 67 67 65  sed by.** trigge
df70: 72 73 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74  rs are not count
df80: 65 64 2e 20 55 73 65 20 74 68 65 20 5b 73 71 6c  ed. Use the [sql
df90: 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67  ite3_total_chang
dfa0: 65 73 28 29 5d 20 66 75 6e 63 74 69 6f 6e 0a 2a  es()] function.*
dfb0: 2a 20 74 6f 20 66 69 6e 64 20 74 68 65 20 74 6f  * to find the to
dfc0: 74 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 63 68  tal number of ch
dfd0: 61 6e 67 65 73 20 69 6e 63 6c 75 64 69 6e 67 20  anges including 
dfe0: 63 68 61 6e 67 65 73 20 63 61 75 73 65 64 20 62  changes caused b
dff0: 79 20 74 72 69 67 67 65 72 73 2e 0a 2a 2a 0a 2a  y triggers..**.*
e000: 2a 20 43 68 61 6e 67 65 73 20 74 6f 20 61 20 76  * Changes to a v
e010: 69 65 77 20 74 68 61 74 20 61 72 65 20 73 69 6d  iew that are sim
e020: 75 6c 61 74 65 64 20 62 79 20 61 6e 20 5b 49 4e  ulated by an [IN
e030: 53 54 45 41 44 20 4f 46 20 74 72 69 67 67 65 72  STEAD OF trigger
e040: 5d 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 63 6f 75  ].** are not cou
e050: 6e 74 65 64 2e 20 20 4f 6e 6c 79 20 72 65 61 6c  nted.  Only real
e060: 20 74 61 62 6c 65 20 63 68 61 6e 67 65 73 20 61   table changes a
e070: 72 65 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 0a 2a  re counted..**.*
e080: 2a 20 41 20 22 72 6f 77 20 63 68 61 6e 67 65 22  * A "row change"
e090: 20 69 73 20 61 20 63 68 61 6e 67 65 20 74 6f 20   is a change to 
e0a0: 61 20 73 69 6e 67 6c 65 20 72 6f 77 20 6f 66 20  a single row of 
e0b0: 61 20 73 69 6e 67 6c 65 20 74 61 62 6c 65 0a 2a  a single table.*
e0c0: 2a 20 63 61 75 73 65 64 20 62 79 20 61 6e 20 49  * caused by an I
e0d0: 4e 53 45 52 54 2c 20 44 45 4c 45 54 45 2c 20 6f  NSERT, DELETE, o
e0e0: 72 20 55 50 44 41 54 45 20 73 74 61 74 65 6d 65  r UPDATE stateme
e0f0: 6e 74 2e 20 20 52 6f 77 73 20 74 68 61 74 0a 2a  nt.  Rows that.*
e100: 2a 20 61 72 65 20 63 68 61 6e 67 65 64 20 61 73  * are changed as
e110: 20 73 69 64 65 20 65 66 66 65 63 74 73 20 6f 66   side effects of
e120: 20 5b 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74   [REPLACE] const
e130: 72 61 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e  raint resolution
e140: 2c 0a 2a 2a 20 72 6f 6c 6c 62 61 63 6b 2c 20 41  ,.** rollback, A
e150: 42 4f 52 54 20 70 72 6f 63 65 73 73 69 6e 67 2c  BORT processing,
e160: 20 5b 44 52 4f 50 20 54 41 42 4c 45 5d 2c 20 6f   [DROP TABLE], o
e170: 72 20 62 79 20 61 6e 79 20 6f 74 68 65 72 0a 2a  r by any other.*
e180: 2a 20 6d 65 63 68 61 6e 69 73 6d 73 20 64 6f 20  * mechanisms do 
e190: 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20 64 69 72  not count as dir
e1a0: 65 63 74 20 72 6f 77 20 63 68 61 6e 67 65 73 2e  ect row changes.
e1b0: 0a 2a 2a 0a 2a 2a 20 41 20 22 74 72 69 67 67 65  .**.** A "trigge
e1c0: 72 20 63 6f 6e 74 65 78 74 22 20 69 73 20 61 20  r context" is a 
e1d0: 73 63 6f 70 65 20 6f 66 20 65 78 65 63 75 74 69  scope of executi
e1e0: 6f 6e 20 74 68 61 74 20 62 65 67 69 6e 73 20 61  on that begins a
e1f0: 6e 64 0a 2a 2a 20 65 6e 64 73 20 77 69 74 68 20  nd.** ends with 
e200: 74 68 65 20 73 63 72 69 70 74 20 6f 66 20 61 20  the script of a 
e210: 5b 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20  [CREATE TRIGGER 
e220: 7c 20 74 72 69 67 67 65 72 5d 2e 20 0a 2a 2a 20  | trigger]. .** 
e230: 4d 6f 73 74 20 53 51 4c 20 73 74 61 74 65 6d 65  Most SQL stateme
e240: 6e 74 73 20 61 72 65 0a 2a 2a 20 65 76 61 6c 75  nts are.** evalu
e250: 61 74 65 64 20 6f 75 74 73 69 64 65 20 6f 66 20  ated outside of 
e260: 61 6e 79 20 74 72 69 67 67 65 72 2e 20 20 54 68  any trigger.  Th
e270: 69 73 20 69 73 20 74 68 65 20 22 74 6f 70 20 6c  is is the "top l
e280: 65 76 65 6c 22 0a 2a 2a 20 74 72 69 67 67 65 72  evel".** trigger
e290: 20 63 6f 6e 74 65 78 74 2e 20 20 49 66 20 61 20   context.  If a 
e2a0: 74 72 69 67 67 65 72 20 66 69 72 65 73 20 66 72  trigger fires fr
e2b0: 6f 6d 20 74 68 65 20 74 6f 70 20 6c 65 76 65 6c  om the top level
e2c0: 2c 20 61 0a 2a 2a 20 6e 65 77 20 74 72 69 67 67  , a.** new trigg
e2d0: 65 72 20 63 6f 6e 74 65 78 74 20 69 73 20 65 6e  er context is en
e2e0: 74 65 72 65 64 20 66 6f 72 20 74 68 65 20 64 75  tered for the du
e2f0: 72 61 74 69 6f 6e 20 6f 66 20 74 68 61 74 20 6f  ration of that o
e300: 6e 65 0a 2a 2a 20 74 72 69 67 67 65 72 2e 20 20  ne.** trigger.  
e310: 53 75 62 74 72 69 67 67 65 72 73 20 63 72 65 61  Subtriggers crea
e320: 74 65 20 73 75 62 63 6f 6e 74 65 78 74 73 20 66  te subcontexts f
e330: 6f 72 20 74 68 65 69 72 20 64 75 72 61 74 69 6f  or their duratio
e340: 6e 2e 0a 2a 2a 0a 2a 2a 20 43 61 6c 6c 69 6e 67  n..**.** Calling
e350: 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29   [sqlite3_exec()
e360: 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73 74  ] or [sqlite3_st
e370: 65 70 28 29 5d 20 72 65 63 75 72 73 69 76 65 6c  ep()] recursivel
e380: 79 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 63 72  y does.** not cr
e390: 65 61 74 65 20 61 20 6e 65 77 20 74 72 69 67 67  eate a new trigg
e3a0: 65 72 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a  er context..**.*
e3b0: 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20  * This function 
e3c0: 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
e3d0: 65 72 20 6f 66 20 64 69 72 65 63 74 20 72 6f 77  er of direct row
e3e0: 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 0a   changes in the.
e3f0: 2a 2a 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 49  ** most recent I
e400: 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f  NSERT, UPDATE, o
e410: 72 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65  r DELETE stateme
e420: 6e 74 20 77 69 74 68 69 6e 20 74 68 65 20 73 61  nt within the sa
e430: 6d 65 0a 2a 2a 20 74 72 69 67 67 65 72 20 63 6f  me.** trigger co
e440: 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 75  ntext..**.** Thu
e450: 73 2c 20 77 68 65 6e 20 63 61 6c 6c 65 64 20 66  s, when called f
e460: 72 6f 6d 20 74 68 65 20 74 6f 70 20 6c 65 76 65  rom the top leve
e470: 6c 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e  l, this function
e480: 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20   returns the.** 
e490: 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 6e 67 65  number of change
e4a0: 73 20 69 6e 20 74 68 65 20 6d 6f 73 74 20 72 65  s in the most re
e4b0: 63 65 6e 74 20 49 4e 53 45 52 54 2c 20 55 50 44  cent INSERT, UPD
e4c0: 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a  ATE, or DELETE.*
e4d0: 2a 20 74 68 61 74 20 61 6c 73 6f 20 6f 63 63 75  * that also occu
e4e0: 72 72 65 64 20 61 74 20 74 68 65 20 74 6f 70 20  rred at the top 
e4f0: 6c 65 76 65 6c 2e 20 20 57 69 74 68 69 6e 20 74  level.  Within t
e500: 68 65 20 62 6f 64 79 20 6f 66 20 61 20 74 72 69  he body of a tri
e510: 67 67 65 72 2c 0a 2a 2a 20 74 68 65 20 73 71 6c  gger,.** the sql
e520: 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 69  ite3_changes() i
e530: 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20  nterface can be 
e540: 63 61 6c 6c 65 64 20 74 6f 20 66 69 6e 64 20 74  called to find t
e550: 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20  he number of.** 
e560: 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 6d  changes in the m
e570: 6f 73 74 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d  ost recently com
e580: 70 6c 65 74 65 64 20 49 4e 53 45 52 54 2c 20 55  pleted INSERT, U
e590: 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45  PDATE, or DELETE
e5a0: 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 77 69  .** statement wi
e5b0: 74 68 69 6e 20 74 68 65 20 62 6f 64 79 20 6f 66  thin the body of
e5c0: 20 74 68 65 20 73 61 6d 65 20 74 72 69 67 67 65   the same trigge
e5d0: 72 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74  r..** However, t
e5e0: 68 65 20 6e 75 6d 62 65 72 20 72 65 74 75 72 6e  he number return
e5f0: 65 64 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c  ed does not incl
e600: 75 64 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 63  ude changes.** c
e610: 61 75 73 65 64 20 62 79 20 73 75 62 74 72 69 67  aused by subtrig
e620: 67 65 72 73 20 73 69 6e 63 65 20 74 68 6f 73 65  gers since those
e630: 20 68 61 76 65 20 74 68 65 69 72 20 6f 77 6e 20   have their own 
e640: 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 53  context..**.** S
e650: 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c  ee also the [sql
e660: 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67  ite3_total_chang
e670: 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  es()] interface 
e680: 61 6e 64 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e  and the.** [coun
e690: 74 5f 63 68 61 6e 67 65 73 20 70 72 61 67 6d 61  t_changes pragma
e6a0: 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65  ]..**.** Require
e6b0: 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 32 34  ments:.** [H1224
e6c0: 31 5d 20 5b 48 31 32 32 34 33 5d 0a 2a 2a 0a 2a  1] [H12243].**.*
e6d0: 2a 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20  * If a separate 
e6e0: 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61  thread makes cha
e6f0: 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65  nges on the same
e700: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
e710: 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73  tion.** while [s
e720: 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29  qlite3_changes()
e730: 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65  ] is running the
e740: 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  n the value retu
e750: 72 6e 65 64 0a 2a 2a 20 69 73 20 75 6e 70 72 65  rned.** is unpre
e760: 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74  dictable and not
e770: 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a   meaningful..*/.
e780: 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 68 61 6e  int sqlite3_chan
e790: 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a  ges(sqlite3*);..
e7a0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
e7b0: 54 6f 74 61 6c 20 4e 75 6d 62 65 72 20 4f 66 20  Total Number Of 
e7c0: 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 20 7b 48  Rows Modified {H
e7d0: 31 32 32 36 30 7d 20 3c 53 31 30 36 30 30 3e 0a  12260} <S10600>.
e7e0: 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74  **.** This funct
e7f0: 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20  ion returns the 
e800: 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 20 63 68  number of row ch
e810: 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 20  anges caused by 
e820: 5b 49 4e 53 45 52 54 5d 2c 0a 2a 2a 20 5b 55 50  [INSERT],.** [UP
e830: 44 41 54 45 5d 20 6f 72 20 5b 44 45 4c 45 54 45  DATE] or [DELETE
e840: 5d 20 73 74 61 74 65 6d 65 6e 74 73 20 73 69 6e  ] statements sin
e850: 63 65 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  ce the [database
e860: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 61 73   connection] was
e870: 20 6f 70 65 6e 65 64 2e 0a 2a 2a 20 54 68 65 20   opened..** The 
e880: 63 6f 75 6e 74 20 69 6e 63 6c 75 64 65 73 20 61  count includes a
e890: 6c 6c 20 63 68 61 6e 67 65 73 20 66 72 6f 6d 20  ll changes from 
e8a0: 61 6c 6c 20 0a 2a 2a 20 5b 43 52 45 41 54 45 20  all .** [CREATE 
e8b0: 54 52 49 47 47 45 52 20 7c 20 74 72 69 67 67 65  TRIGGER | trigge
e8c0: 72 5d 20 63 6f 6e 74 65 78 74 73 2e 20 20 48 6f  r] contexts.  Ho
e8d0: 77 65 76 65 72 2c 0a 2a 2a 20 74 68 65 20 63 6f  wever,.** the co
e8e0: 75 6e 74 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63  unt does not inc
e8f0: 6c 75 64 65 20 63 68 61 6e 67 65 73 20 75 73 65  lude changes use
e900: 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 5b  d to implement [
e910: 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74 72 61  REPLACE] constra
e920: 69 6e 74 73 2c 0a 2a 2a 20 64 6f 20 72 6f 6c 6c  ints,.** do roll
e930: 62 61 63 6b 73 20 6f 72 20 41 42 4f 52 54 20 70  backs or ABORT p
e940: 72 6f 63 65 73 73 69 6e 67 2c 20 6f 72 20 5b 44  rocessing, or [D
e950: 52 4f 50 20 54 41 42 4c 45 5d 20 70 72 6f 63 65  ROP TABLE] proce
e960: 73 73 69 6e 67 2e 20 20 54 68 65 0a 2a 2a 20 63  ssing.  The.** c
e970: 6f 75 6e 74 20 64 6f 65 73 20 6e 6f 74 20 69 6e  ount does not in
e980: 63 6c 75 64 65 20 72 6f 77 73 20 6f 66 20 76 69  clude rows of vi
e990: 65 77 73 20 74 68 61 74 20 66 69 72 65 20 61 6e  ews that fire an
e9a0: 20 5b 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69   [INSTEAD OF tri
e9b0: 67 67 65 72 5d 2c 0a 2a 2a 20 74 68 6f 75 67 68  gger],.** though
e9c0: 20 69 66 20 74 68 65 20 49 4e 53 54 45 41 44 20   if the INSTEAD 
e9d0: 4f 46 20 74 72 69 67 67 65 72 20 6d 61 6b 65 73  OF trigger makes
e9e0: 20 63 68 61 6e 67 65 73 20 6f 66 20 69 74 73 20   changes of its 
e9f0: 6f 77 6e 2c 20 74 68 6f 73 65 20 63 68 61 6e 67  own, those chang
ea00: 65 73 20 0a 2a 2a 20 61 72 65 20 63 6f 75 6e 74  es .** are count
ea10: 65 64 2e 0a 2a 2a 20 54 68 65 20 63 68 61 6e 67  ed..** The chang
ea20: 65 73 20 61 72 65 20 63 6f 75 6e 74 65 64 20 61  es are counted a
ea30: 73 20 73 6f 6f 6e 20 61 73 20 74 68 65 20 73 74  s soon as the st
ea40: 61 74 65 6d 65 6e 74 20 74 68 61 74 20 6d 61 6b  atement that mak
ea50: 65 73 20 74 68 65 6d 20 69 73 0a 2a 2a 20 63 6f  es them is.** co
ea60: 6d 70 6c 65 74 65 64 20 28 77 68 65 6e 20 74 68  mpleted (when th
ea70: 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61 6e 64  e statement hand
ea80: 6c 65 20 69 73 20 70 61 73 73 65 64 20 74 6f 20  le is passed to 
ea90: 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
eaa0: 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ] or.** [sqlite3
eab0: 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 29 2e 0a 2a  _finalize()])..*
eac0: 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68  *.** See also th
ead0: 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  e [sqlite3_chang
eae0: 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  es()] interface 
eaf0: 61 6e 64 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e  and the.** [coun
eb00: 74 5f 63 68 61 6e 67 65 73 20 70 72 61 67 6d 61  t_changes pragma
eb10: 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65  ]..**.** Require
eb20: 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 32 36  ments:.** [H1226
eb30: 31 5d 20 5b 48 31 32 32 36 33 5d 0a 2a 2a 0a 2a  1] [H12263].**.*
eb40: 2a 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20  * If a separate 
eb50: 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61  thread makes cha
eb60: 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65  nges on the same
eb70: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
eb80: 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73  tion.** while [s
eb90: 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61  qlite3_total_cha
eba0: 6e 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69  nges()] is runni
ebb0: 6e 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75  ng then the valu
ebc0: 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 73  e.** returned is
ebd0: 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61   unpredictable a
ebe0: 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75  nd not meaningfu
ebf0: 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  l..*/.int sqlite
ec00: 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28  3_total_changes(
ec10: 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a  sqlite3*);../*.*
ec20: 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 74 65  * CAPI3REF: Inte
ec30: 72 72 75 70 74 20 41 20 4c 6f 6e 67 2d 52 75 6e  rrupt A Long-Run
ec40: 6e 69 6e 67 20 51 75 65 72 79 20 7b 48 31 32 32  ning Query {H122
ec50: 37 30 7d 20 3c 53 33 30 35 30 30 3e 0a 2a 2a 0a  70} <S30500>.**.
ec60: 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e  ** This function
ec70: 20 63 61 75 73 65 73 20 61 6e 79 20 70 65 6e 64   causes any pend
ec80: 69 6e 67 20 64 61 74 61 62 61 73 65 20 6f 70 65  ing database ope
ec90: 72 61 74 69 6f 6e 20 74 6f 20 61 62 6f 72 74 20  ration to abort 
eca0: 61 6e 64 0a 2a 2a 20 72 65 74 75 72 6e 20 61 74  and.** return at
ecb0: 20 69 74 73 20 65 61 72 6c 69 65 73 74 20 6f 70   its earliest op
ecc0: 70 6f 72 74 75 6e 69 74 79 2e 20 54 68 69 73 20  portunity. This 
ecd0: 72 6f 75 74 69 6e 65 20 69 73 20 74 79 70 69 63  routine is typic
ece0: 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 69  ally.** called i
ecf0: 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f 20 61 20  n response to a 
ed00: 75 73 65 72 20 61 63 74 69 6f 6e 20 73 75 63 68  user action such
ed10: 20 61 73 20 70 72 65 73 73 69 6e 67 20 22 43 61   as pressing "Ca
ed20: 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20 43 74 72 6c  ncel".** or Ctrl
ed30: 2d 43 20 77 68 65 72 65 20 74 68 65 20 75 73 65  -C where the use
ed40: 72 20 77 61 6e 74 73 20 61 20 6c 6f 6e 67 20 71  r wants a long q
ed50: 75 65 72 79 20 6f 70 65 72 61 74 69 6f 6e 20 74  uery operation t
ed60: 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d 6d 65 64 69  o halt.** immedi
ed70: 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 49 74 20  ately..**.** It 
ed80: 69 73 20 73 61 66 65 20 74 6f 20 63 61 6c 6c 20  is safe to call 
ed90: 74 68 69 73 20 72 6f 75 74 69 6e 65 20 66 72 6f  this routine fro
eda0: 6d 20 61 20 74 68 72 65 61 64 20 64 69 66 66 65  m a thread diffe
edb0: 72 65 6e 74 20 66 72 6f 6d 20 74 68 65 0a 2a 2a  rent from the.**
edc0: 20 74 68 72 65 61 64 20 74 68 61 74 20 69 73 20   thread that is 
edd0: 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e  currently runnin
ede0: 67 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6f  g the database o
edf0: 70 65 72 61 74 69 6f 6e 2e 20 20 42 75 74 20 69  peration.  But i
ee00: 74 0a 2a 2a 20 69 73 20 6e 6f 74 20 73 61 66 65  t.** is not safe
ee10: 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f   to call this ro
ee20: 75 74 69 6e 65 20 77 69 74 68 20 61 20 5b 64 61  utine with a [da
ee30: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
ee40: 6e 5d 20 74 68 61 74 0a 2a 2a 20 69 73 20 63 6c  n] that.** is cl
ee50: 6f 73 65 64 20 6f 72 20 6d 69 67 68 74 20 63 6c  osed or might cl
ee60: 6f 73 65 20 62 65 66 6f 72 65 20 73 71 6c 69 74  ose before sqlit
ee70: 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 72  e3_interrupt() r
ee80: 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 66  eturns..**.** If
ee90: 20 61 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f   an SQL operatio
eea0: 6e 20 69 73 20 76 65 72 79 20 6e 65 61 72 6c 79  n is very nearly
eeb0: 20 66 69 6e 69 73 68 65 64 20 61 74 20 74 68 65   finished at the
eec0: 20 74 69 6d 65 20 77 68 65 6e 0a 2a 2a 20 73 71   time when.** sq
eed0: 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
eee0: 29 20 69 73 20 63 61 6c 6c 65 64 2c 20 74 68 65  ) is called, the
eef0: 6e 20 69 74 20 6d 69 67 68 74 20 6e 6f 74 20 68  n it might not h
ef00: 61 76 65 20 61 6e 20 6f 70 70 6f 72 74 75 6e 69  ave an opportuni
ef10: 74 79 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 74 65  ty.** to be inte
ef20: 72 72 75 70 74 65 64 20 61 6e 64 20 6d 69 67 68  rrupted and migh
ef30: 74 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 63 6f  t continue to co
ef40: 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  mpletion..**.** 
ef50: 41 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e  An SQL operation
ef60: 20 74 68 61 74 20 69 73 20 69 6e 74 65 72 72 75   that is interru
ef70: 70 74 65 64 20 77 69 6c 6c 20 72 65 74 75 72 6e  pted will return
ef80: 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55   [SQLITE_INTERRU
ef90: 50 54 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20 69  PT]..** If the i
efa0: 6e 74 65 72 72 75 70 74 65 64 20 53 51 4c 20 6f  nterrupted SQL o
efb0: 70 65 72 61 74 69 6f 6e 20 69 73 20 61 6e 20 49  peration is an I
efc0: 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f  NSERT, UPDATE, o
efd0: 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74  r DELETE.** that
efe0: 20 69 73 20 69 6e 73 69 64 65 20 61 6e 20 65 78   is inside an ex
eff0: 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69  plicit transacti
f000: 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 65 6e 74  on, then the ent
f010: 69 72 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 0a  ire transaction.
f020: 2a 2a 20 77 69 6c 6c 20 62 65 20 72 6f 6c 6c 65  ** will be rolle
f030: 64 20 62 61 63 6b 20 61 75 74 6f 6d 61 74 69 63  d back automatic
f040: 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ally..**.** The 
f050: 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
f060: 74 28 44 29 20 63 61 6c 6c 20 69 73 20 69 6e 20  t(D) call is in 
f070: 65 66 66 65 63 74 20 75 6e 74 69 6c 20 61 6c 6c  effect until all
f080: 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69   currently runni
f090: 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d  ng.** SQL statem
f0a0: 65 6e 74 73 20 6f 6e 20 5b 64 61 74 61 62 61 73  ents on [databas
f0b0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20  e connection] D 
f0c0: 63 6f 6d 70 6c 65 74 65 2e 20 20 41 6e 79 20 6e  complete.  Any n
f0d0: 65 77 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ew SQL statement
f0e0: 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74  s.** that are st
f0f0: 61 72 74 65 64 20 61 66 74 65 72 20 74 68 65 20  arted after the 
f100: 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
f110: 74 28 29 20 63 61 6c 6c 20 61 6e 64 20 62 65 66  t() call and bef
f120: 6f 72 65 20 74 68 65 20 0a 2a 2a 20 72 75 6e 6e  ore the .** runn
f130: 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 73 20 72  ing statements r
f140: 65 61 63 68 65 73 20 7a 65 72 6f 20 61 72 65 20  eaches zero are 
f150: 69 6e 74 65 72 72 75 70 74 65 64 20 61 73 20 69  interrupted as i
f160: 66 20 74 68 65 79 20 68 61 64 20 62 65 65 6e 0a  f they had been.
f170: 2a 2a 20 72 75 6e 6e 69 6e 67 20 70 72 69 6f 72  ** running prior
f180: 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
f190: 69 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c  interrupt() call
f1a0: 2e 20 20 4e 65 77 20 53 51 4c 20 73 74 61 74 65  .  New SQL state
f1b0: 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72  ments.** that ar
f1c0: 65 20 73 74 61 72 74 65 64 20 61 66 74 65 72 20  e started after 
f1d0: 74 68 65 20 72 75 6e 6e 69 6e 67 20 73 74 61 74  the running stat
f1e0: 65 6d 65 6e 74 20 63 6f 75 6e 74 20 72 65 61 63  ement count reac
f1f0: 68 65 73 20 7a 65 72 6f 20 61 72 65 0a 2a 2a 20  hes zero are.** 
f200: 6e 6f 74 20 65 66 66 65 63 74 65 64 20 62 79 20  not effected by 
f210: 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  the sqlite3_inte
f220: 72 72 75 70 74 28 29 2e 0a 2a 2a 20 41 20 63 61  rrupt()..** A ca
f230: 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e  ll to sqlite3_in
f240: 74 65 72 72 75 70 74 28 44 29 20 74 68 61 74 20  terrupt(D) that 
f250: 6f 63 63 75 72 73 20 77 68 65 6e 20 74 68 65 72  occurs when ther
f260: 65 20 61 72 65 20 6e 6f 20 72 75 6e 6e 69 6e 67  e are no running
f270: 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  .** SQL statemen
f280: 74 73 20 69 73 20 61 20 6e 6f 2d 6f 70 20 61 6e  ts is a no-op an
f290: 64 20 68 61 73 20 6e 6f 20 65 66 66 65 63 74 20  d has no effect 
f2a0: 6f 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  on SQL statement
f2b0: 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74  s.** that are st
f2c0: 61 72 74 65 64 20 61 66 74 65 72 20 74 68 65 20  arted after the 
f2d0: 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
f2e0: 74 28 29 20 63 61 6c 6c 20 72 65 74 75 72 6e 73  t() call returns
f2f0: 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d  ..**.** Requirem
f300: 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 32 37 31  ents:.** [H12271
f310: 5d 20 5b 48 31 32 32 37 32 5d 0a 2a 2a 0a 2a 2a  ] [H12272].**.**
f320: 20 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65   If the database
f330: 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73   connection clos
f340: 65 73 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65  es while [sqlite
f350: 33 5f 69 6e 74 65 72 72 75 70 74 28 29 5d 0a 2a  3_interrupt()].*
f360: 2a 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65  * is running the
f370: 6e 20 62 61 64 20 74 68 69 6e 67 73 20 77 69 6c  n bad things wil
f380: 6c 20 6c 69 6b 65 6c 79 20 68 61 70 70 65 6e 2e  l likely happen.
f390: 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  .*/.void sqlite3
f3a0: 5f 69 6e 74 65 72 72 75 70 74 28 73 71 6c 69 74  _interrupt(sqlit
f3b0: 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  e3*);../*.** CAP
f3c0: 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65  I3REF: Determine
f3d0: 20 49 66 20 41 6e 20 53 51 4c 20 53 74 61 74 65   If An SQL State
f3e0: 6d 65 6e 74 20 49 73 20 43 6f 6d 70 6c 65 74 65  ment Is Complete
f3f0: 20 7b 48 31 30 35 31 30 7d 20 3c 53 37 30 32 30   {H10510} <S7020
f400: 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  0>.**.** These r
f410: 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 66  outines are usef
f420: 75 6c 20 64 75 72 69 6e 67 20 63 6f 6d 6d 61 6e  ul during comman
f430: 64 2d 6c 69 6e 65 20 69 6e 70 75 74 20 74 6f 20  d-line input to 
f440: 64 65 74 65 72 6d 69 6e 65 20 69 66 20 74 68 65  determine if the
f450: 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20 65 6e  .** currently en
f460: 74 65 72 65 64 20 74 65 78 74 20 73 65 65 6d 73  tered text seems
f470: 20 74 6f 20 66 6f 72 6d 20 61 20 63 6f 6d 70 6c   to form a compl
f480: 65 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ete SQL statemen
f490: 74 20 6f 72 0a 2a 2a 20 69 66 20 61 64 64 69 74  t or.** if addit
f4a0: 69 6f 6e 61 6c 20 69 6e 70 75 74 20 69 73 20 6e  ional input is n
f4b0: 65 65 64 65 64 20 62 65 66 6f 72 65 20 73 65 6e  eeded before sen
f4c0: 64 69 6e 67 20 74 68 65 20 74 65 78 74 20 69 6e  ding the text in
f4d0: 74 6f 0a 2a 2a 20 53 51 4c 69 74 65 20 66 6f 72  to.** SQLite for
f4e0: 20 70 61 72 73 69 6e 67 2e 20 20 54 68 65 73 65   parsing.  These
f4f0: 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
f500: 20 31 20 69 66 20 74 68 65 20 69 6e 70 75 74 20   1 if the input 
f510: 73 74 72 69 6e 67 0a 2a 2a 20 61 70 70 65 61 72  string.** appear
f520: 73 20 74 6f 20 62 65 20 61 20 63 6f 6d 70 6c 65  s to be a comple
f530: 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  te SQL statement
f540: 2e 20 20 41 20 73 74 61 74 65 6d 65 6e 74 20 69  .  A statement i
f550: 73 20 6a 75 64 67 65 64 20 74 6f 20 62 65 0a 2a  s judged to be.*
f560: 2a 20 63 6f 6d 70 6c 65 74 65 20 69 66 20 69 74  * complete if it
f570: 20 65 6e 64 73 20 77 69 74 68 20 61 20 73 65 6d   ends with a sem
f580: 69 63 6f 6c 6f 6e 20 74 6f 6b 65 6e 20 61 6e 64  icolon token and
f590: 20 69 73 20 6e 6f 74 20 61 20 70 72 65 66 69 78   is not a prefix
f5a0: 20 6f 66 20 61 0a 2a 2a 20 77 65 6c 6c 2d 66 6f   of a.** well-fo
f5b0: 72 6d 65 64 20 43 52 45 41 54 45 20 54 52 49 47  rmed CREATE TRIG
f5c0: 47 45 52 20 73 74 61 74 65 6d 65 6e 74 2e 20 20  GER statement.  
f5d0: 53 65 6d 69 63 6f 6c 6f 6e 73 20 74 68 61 74 20  Semicolons that 
f5e0: 61 72 65 20 65 6d 62 65 64 64 65 64 20 77 69 74  are embedded wit
f5f0: 68 69 6e 0a 2a 2a 20 73 74 72 69 6e 67 20 6c 69  hin.** string li
f600: 74 65 72 61 6c 73 20 6f 72 20 71 75 6f 74 65 64  terals or quoted
f610: 20 69 64 65 6e 74 69 66 69 65 72 20 6e 61 6d 65   identifier name
f620: 73 20 6f 72 20 63 6f 6d 6d 65 6e 74 73 20 61 72  s or comments ar
f630: 65 20 6e 6f 74 0a 2a 2a 20 69 6e 64 65 70 65 6e  e not.** indepen
f640: 64 65 6e 74 20 74 6f 6b 65 6e 73 20 28 74 68 65  dent tokens (the
f650: 79 20 61 72 65 20 70 61 72 74 20 6f 66 20 74 68  y are part of th
f660: 65 20 74 6f 6b 65 6e 20 69 6e 20 77 68 69 63 68  e token in which
f670: 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 65 6d 62   they are.** emb
f680: 65 64 64 65 64 29 20 61 6e 64 20 74 68 75 73 20  edded) and thus 
f690: 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20  do not count as 
f6a0: 61 20 73 74 61 74 65 6d 65 6e 74 20 74 65 72 6d  a statement term
f6b0: 69 6e 61 74 6f 72 2e 20 20 57 68 69 74 65 73 70  inator.  Whitesp
f6c0: 61 63 65 0a 2a 2a 20 61 6e 64 20 63 6f 6d 6d 65  ace.** and comme
f6d0: 6e 74 73 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20  nts that follow 
f6e0: 74 68 65 20 66 69 6e 61 6c 20 73 65 6d 69 63 6f  the final semico
f6f0: 6c 6f 6e 20 61 72 65 20 69 67 6e 6f 72 65 64 2e  lon are ignored.
f700: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
f710: 74 69 6e 65 73 20 72 65 74 75 72 6e 20 30 20 69  tines return 0 i
f720: 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  f the statement 
f730: 69 73 20 69 6e 63 6f 6d 70 6c 65 74 65 2e 20 20  is incomplete.  
f740: 49 66 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61  If a.** memory a
f750: 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 73 2c  llocation fails,
f760: 20 74 68 65 6e 20 53 51 4c 49 54 45 5f 4e 4f 4d   then SQLITE_NOM
f770: 45 4d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  EM is returned..
f780: 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
f790: 69 6e 65 73 20 64 6f 20 6e 6f 74 20 70 61 72 73  ines do not pars
f7a0: 65 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  e the SQL statem
f7b0: 65 6e 74 73 20 74 68 75 73 0a 2a 2a 20 77 69 6c  ents thus.** wil
f7c0: 6c 20 6e 6f 74 20 64 65 74 65 63 74 20 73 79 6e  l not detect syn
f7d0: 74 61 63 74 69 63 61 6c 6c 79 20 69 6e 63 6f 72  tactically incor
f7e0: 72 65 63 74 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20  rect SQL..**.** 
f7f0: 49 66 20 53 51 4c 69 74 65 20 68 61 73 20 6e 6f  If SQLite has no
f800: 74 20 62 65 65 6e 20 69 6e 69 74 69 61 6c 69 7a  t been initializ
f810: 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ed using [sqlite
f820: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20  3_initialize()] 
f830: 70 72 69 6f 72 20 0a 2a 2a 20 74 6f 20 69 6e 76  prior .** to inv
f840: 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f 63 6f  oking sqlite3_co
f850: 6d 70 6c 65 74 65 31 36 28 29 20 74 68 65 6e 20  mplete16() then 
f860: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
f870: 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a  ze() is invoked.
f880: 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ** automatically
f890: 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70   by sqlite3_comp
f8a0: 6c 65 74 65 31 36 28 29 2e 20 20 49 66 20 74 68  lete16().  If th
f8b0: 61 74 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f  at initializatio
f8c0: 6e 20 66 61 69 6c 73 2c 0a 2a 2a 20 74 68 65 6e  n fails,.** then
f8d0: 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
f8e0: 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63  e from sqlite3_c
f8f0: 6f 6d 70 6c 65 74 65 31 36 28 29 20 77 69 6c 6c  omplete16() will
f900: 20 62 65 20 6e 6f 6e 2d 7a 65 72 6f 0a 2a 2a 20   be non-zero.** 
f910: 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68  regardless of wh
f920: 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65  ether or not the
f930: 20 69 6e 70 75 74 20 53 51 4c 20 69 73 20 63 6f   input SQL is co
f940: 6d 70 6c 65 74 65 2e 0a 2a 2a 0a 2a 2a 20 52 65  mplete..**.** Re
f950: 71 75 69 72 65 6d 65 6e 74 73 3a 20 5b 48 31 30  quirements: [H10
f960: 35 31 31 5d 20 5b 48 31 30 35 31 32 5d 0a 2a 2a  511] [H10512].**
f970: 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74 6f  .** The input to
f980: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65   [sqlite3_comple
f990: 74 65 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20  te()] must be a 
f9a0: 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a  zero-terminated.
f9b0: 2a 2a 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2e  ** UTF-8 string.
f9c0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74  .**.** The input
f9d0: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d   to [sqlite3_com
f9e0: 70 6c 65 74 65 31 36 28 29 5d 20 6d 75 73 74 20  plete16()] must 
f9f0: 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  be a zero-termin
fa00: 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73  ated.** UTF-16 s
fa10: 74 72 69 6e 67 20 69 6e 20 6e 61 74 69 76 65 20  tring in native 
fa20: 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2f 0a 69  byte order..*/.i
fa30: 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c  nt sqlite3_compl
fa40: 65 74 65 28 63 6f 6e 73 74 20 63 68 61 72 20 2a  ete(const char *
fa50: 73 71 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  sql);.int sqlite
fa60: 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 63 6f 6e  3_complete16(con
fa70: 73 74 20 76 6f 69 64 20 2a 73 71 6c 29 3b 0a 0a  st void *sql);..
fa80: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
fa90: 52 65 67 69 73 74 65 72 20 41 20 43 61 6c 6c 62  Register A Callb
faa0: 61 63 6b 20 54 6f 20 48 61 6e 64 6c 65 20 53 51  ack To Handle SQ
fab0: 4c 49 54 45 5f 42 55 53 59 20 45 72 72 6f 72 73  LITE_BUSY Errors
fac0: 20 7b 48 31 32 33 31 30 7d 20 3c 53 34 30 34 30   {H12310} <S4040
fad0: 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f  0>.**.** This ro
fae0: 75 74 69 6e 65 20 73 65 74 73 20 61 20 63 61 6c  utine sets a cal
faf0: 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 74  lback function t
fb00: 68 61 74 20 6d 69 67 68 74 20 62 65 20 69 6e 76  hat might be inv
fb10: 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 0a 2a 2a  oked whenever.**
fb20: 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73 20 6d   an attempt is m
fb30: 61 64 65 20 74 6f 20 6f 70 65 6e 20 61 20 64 61  ade to open a da
fb40: 74 61 62 61 73 65 20 74 61 62 6c 65 20 74 68 61  tabase table tha
fb50: 74 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64  t another thread
fb60: 0a 2a 2a 20 6f 72 20 70 72 6f 63 65 73 73 20 68  .** or process h
fb70: 61 73 20 6c 6f 63 6b 65 64 2e 0a 2a 2a 0a 2a 2a  as locked..**.**
fb80: 20 49 66 20 74 68 65 20 62 75 73 79 20 63 61 6c   If the busy cal
fb90: 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2c 20 74  lback is NULL, t
fba0: 68 65 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  hen [SQLITE_BUSY
fbb0: 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45  ] or [SQLITE_IOE
fbc0: 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 69  RR_BLOCKED].** i
fbd0: 73 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64  s returned immed
fbe0: 69 61 74 65 6c 79 20 75 70 6f 6e 20 65 6e 63 6f  iately upon enco
fbf0: 75 6e 74 65 72 69 6e 67 20 74 68 65 20 6c 6f 63  untering the loc
fc00: 6b 2e 20 49 66 20 74 68 65 20 62 75 73 79 20 63  k. If the busy c
fc10: 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 6e 6f  allback.** is no
fc20: 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65  t NULL, then the
fc30: 20 63 61 6c 6c 62 61 63 6b 20 77 69 6c 6c 20 62   callback will b
fc40: 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 74  e invoked with t
fc50: 77 6f 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a  wo arguments..**
fc60: 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72  .** The first ar
fc70: 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 68 61  gument to the ha
fc80: 6e 64 6c 65 72 20 69 73 20 61 20 63 6f 70 79 20  ndler is a copy 
fc90: 6f 66 20 74 68 65 20 76 6f 69 64 2a 20 70 6f 69  of the void* poi
fca0: 6e 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73  nter which.** is
fcb0: 20 74 68 65 20 74 68 69 72 64 20 61 72 67 75 6d   the third argum
fcc0: 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62  ent to sqlite3_b
fcd0: 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 2e 20 20  usy_handler().  
fce0: 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  The second argum
fcf0: 65 6e 74 20 74 6f 0a 2a 2a 20 74 68 65 20 68 61  ent to.** the ha
fd00: 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  ndler callback i
fd10: 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
fd20: 74 69 6d 65 73 20 74 68 61 74 20 74 68 65 20 62  times that the b
fd30: 75 73 79 20 68 61 6e 64 6c 65 72 20 68 61 73 0a  usy handler has.
fd40: 2a 2a 20 62 65 65 6e 20 69 6e 76 6f 6b 65 64 20  ** been invoked 
fd50: 66 6f 72 20 74 68 69 73 20 6c 6f 63 6b 69 6e 67  for this locking
fd60: 20 65 76 65 6e 74 2e 20 20 49 66 20 74 68 65 0a   event.  If the.
fd70: 2a 2a 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b  ** busy callback
fd80: 20 72 65 74 75 72 6e 73 20 30 2c 20 74 68 65 6e   returns 0, then
fd90: 20 6e 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61   no additional a
fda0: 74 74 65 6d 70 74 73 20 61 72 65 20 6d 61 64 65  ttempts are made
fdb0: 20 74 6f 0a 2a 2a 20 61 63 63 65 73 73 20 74 68   to.** access th
fdc0: 65 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 5b  e database and [
fdd0: 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20  SQLITE_BUSY] or 
fde0: 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c  [SQLITE_IOERR_BL
fdf0: 4f 43 4b 45 44 5d 20 69 73 20 72 65 74 75 72 6e  OCKED] is return
fe00: 65 64 2e 0a 2a 2a 20 49 66 20 74 68 65 20 63 61  ed..** If the ca
fe10: 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e  llback returns n
fe20: 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 61 6e  on-zero, then an
fe30: 6f 74 68 65 72 20 61 74 74 65 6d 70 74 0a 2a 2a  other attempt.**
fe40: 20 69 73 20 6d 61 64 65 20 74 6f 20 6f 70 65 6e   is made to open
fe50: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 6f   the database fo
fe60: 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 74 68  r reading and th
fe70: 65 20 63 79 63 6c 65 20 72 65 70 65 61 74 73 2e  e cycle repeats.
fe80: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 65 73 65  .**.** The prese
fe90: 6e 63 65 20 6f 66 20 61 20 62 75 73 79 20 68 61  nce of a busy ha
fea0: 6e 64 6c 65 72 20 64 6f 65 73 20 6e 6f 74 20 67  ndler does not g
feb0: 75 61 72 61 6e 74 65 65 20 74 68 61 74 20 69 74  uarantee that it
fec0: 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64   will be invoked
fed0: 0a 2a 2a 20 77 68 65 6e 20 74 68 65 72 65 20 69  .** when there i
fee0: 73 20 6c 6f 63 6b 20 63 6f 6e 74 65 6e 74 69 6f  s lock contentio
fef0: 6e 2e 20 49 66 20 53 51 4c 69 74 65 20 64 65 74  n. If SQLite det
ff00: 65 72 6d 69 6e 65 73 20 74 68 61 74 20 69 6e 76  ermines that inv
ff10: 6f 6b 69 6e 67 20 74 68 65 20 62 75 73 79 0a 2a  oking the busy.*
ff20: 2a 20 68 61 6e 64 6c 65 72 20 63 6f 75 6c 64 20  * handler could 
ff30: 72 65 73 75 6c 74 20 69 6e 20 61 20 64 65 61 64  result in a dead
ff40: 6c 6f 63 6b 2c 20 69 74 20 77 69 6c 6c 20 67 6f  lock, it will go
ff50: 20 61 68 65 61 64 20 61 6e 64 20 72 65 74 75 72   ahead and retur
ff60: 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a  n [SQLITE_BUSY].
ff70: 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f  ** or [SQLITE_IO
ff80: 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 69 6e 73  ERR_BLOCKED] ins
ff90: 74 65 61 64 20 6f 66 20 69 6e 76 6f 6b 69 6e 67  tead of invoking
ffa0: 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
ffb0: 72 2e 0a 2a 2a 20 43 6f 6e 73 69 64 65 72 20 61  r..** Consider a
ffc0: 20 73 63 65 6e 61 72 69 6f 20 77 68 65 72 65 20   scenario where 
ffd0: 6f 6e 65 20 70 72 6f 63 65 73 73 20 69 73 20 68  one process is h
ffe0: 6f 6c 64 69 6e 67 20 61 20 72 65 61 64 20 6c 6f  olding a read lo
fff0: 63 6b 20 74 68 61 74 0a 2a 2a 20 69 74 20 69 73  ck that.** it is
10000 20 74 72 79 69 6e 67 20 74 6f 20 70 72 6f 6d 6f   trying to promo
10010 74 65 20 74 6f 20 61 20 72 65 73 65 72 76 65 64  te to a reserved
10020 20 6c 6f 63 6b 20 61 6e 64 0a 2a 2a 20 61 20 73   lock and.** a s
10030 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 69 73  econd process is
10040 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 73 65 72   holding a reser
10050 76 65 64 20 6c 6f 63 6b 20 74 68 61 74 20 69 74  ved lock that it
10060 20 69 73 20 74 72 79 69 6e 67 0a 2a 2a 20 74 6f   is trying.** to
10070 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 6e 20 65   promote to an e
10080 78 63 6c 75 73 69 76 65 20 6c 6f 63 6b 2e 20 20  xclusive lock.  
10090 54 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73  The first proces
100a0 73 20 63 61 6e 6e 6f 74 20 70 72 6f 63 65 65 64  s cannot proceed
100b0 0a 2a 2a 20 62 65 63 61 75 73 65 20 69 74 20 69  .** because it i
100c0 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65  s blocked by the
100d0 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 65 20   second and the 
100e0 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 63  second process c
100f0 61 6e 6e 6f 74 0a 2a 2a 20 70 72 6f 63 65 65 64  annot.** proceed
10100 20 62 65 63 61 75 73 65 20 69 74 20 69 73 20 62   because it is b
10110 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20 66 69  locked by the fi
10120 72 73 74 2e 20 20 49 66 20 62 6f 74 68 20 70 72  rst.  If both pr
10130 6f 63 65 73 73 65 73 0a 2a 2a 20 69 6e 76 6f 6b  ocesses.** invok
10140 65 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  e the busy handl
10150 65 72 73 2c 20 6e 65 69 74 68 65 72 20 77 69 6c  ers, neither wil
10160 6c 20 6d 61 6b 65 20 61 6e 79 20 70 72 6f 67 72  l make any progr
10170 65 73 73 2e 20 20 54 68 65 72 65 66 6f 72 65 2c  ess.  Therefore,
10180 0a 2a 2a 20 53 51 4c 69 74 65 20 72 65 74 75 72  .** SQLite retur
10190 6e 73 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  ns [SQLITE_BUSY]
101a0 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 70   for the first p
101b0 72 6f 63 65 73 73 2c 20 68 6f 70 69 6e 67 20 74  rocess, hoping t
101c0 68 61 74 20 74 68 69 73 0a 2a 2a 20 77 69 6c 6c  hat this.** will
101d0 20 69 6e 64 75 63 65 20 74 68 65 20 66 69 72 73   induce the firs
101e0 74 20 70 72 6f 63 65 73 73 20 74 6f 20 72 65 6c  t process to rel
101f0 65 61 73 65 20 69 74 73 20 72 65 61 64 20 6c 6f  ease its read lo
10200 63 6b 20 61 6e 64 20 61 6c 6c 6f 77 0a 2a 2a 20  ck and allow.** 
10210 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65  the second proce
10220 73 73 20 74 6f 20 70 72 6f 63 65 65 64 2e 0a 2a  ss to proceed..*
10230 2a 0a 2a 2a 20 54 68 65 20 64 65 66 61 75 6c 74  *.** The default
10240 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69   busy callback i
10250 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68  s NULL..**.** Th
10260 65 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20  e [SQLITE_BUSY] 
10270 65 72 72 6f 72 20 69 73 20 63 6f 6e 76 65 72 74  error is convert
10280 65 64 20 74 6f 20 5b 53 51 4c 49 54 45 5f 49 4f  ed to [SQLITE_IO
10290 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20  ERR_BLOCKED].** 
102a0 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 69  when SQLite is i
102b0 6e 20 74 68 65 20 6d 69 64 64 6c 65 20 6f 66 20  n the middle of 
102c0 61 20 6c 61 72 67 65 20 74 72 61 6e 73 61 63 74  a large transact
102d0 69 6f 6e 20 77 68 65 72 65 20 61 6c 6c 20 74 68  ion where all th
102e0 65 0a 2a 2a 20 63 68 61 6e 67 65 73 20 77 69 6c  e.** changes wil
102f0 6c 20 6e 6f 74 20 66 69 74 20 69 6e 74 6f 20 74  l not fit into t
10300 68 65 20 69 6e 2d 6d 65 6d 6f 72 79 20 63 61 63  he in-memory cac
10310 68 65 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c  he.  SQLite will
10320 0a 2a 2a 20 61 6c 72 65 61 64 79 20 68 6f 6c 64  .** already hold
10330 20 61 20 52 45 53 45 52 56 45 44 20 6c 6f 63 6b   a RESERVED lock
10340 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73 65   on the database
10350 20 66 69 6c 65 2c 20 62 75 74 20 69 74 20 6e 65   file, but it ne
10360 65 64 73 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74  eds.** to promot
10370 65 20 74 68 69 73 20 6c 6f 63 6b 20 74 6f 20 45  e this lock to E
10380 58 43 4c 55 53 49 56 45 20 73 6f 20 74 68 61 74  XCLUSIVE so that
10390 20 69 74 20 63 61 6e 20 73 70 69 6c 6c 20 63 61   it can spill ca
103a0 63 68 65 0a 2a 2a 20 70 61 67 65 73 20 69 6e 74  che.** pages int
103b0 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  o the database f
103c0 69 6c 65 20 77 69 74 68 6f 75 74 20 68 61 72 6d  ile without harm
103d0 20 74 6f 20 63 6f 6e 63 75 72 72 65 6e 74 0a 2a   to concurrent.*
103e0 2a 20 72 65 61 64 65 72 73 2e 20 20 49 66 20 69  * readers.  If i
103f0 74 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 70  t is unable to p
10400 72 6f 6d 6f 74 65 20 74 68 65 20 6c 6f 63 6b 2c  romote the lock,
10410 20 74 68 65 6e 20 74 68 65 20 69 6e 2d 6d 65 6d   then the in-mem
10420 6f 72 79 0a 2a 2a 20 63 61 63 68 65 20 77 69 6c  ory.** cache wil
10430 6c 20 62 65 20 6c 65 66 74 20 69 6e 20 61 6e 20  l be left in an 
10440 69 6e 63 6f 6e 73 69 73 74 65 6e 74 20 73 74 61  inconsistent sta
10450 74 65 20 61 6e 64 20 73 6f 20 74 68 65 20 65 72  te and so the er
10460 72 6f 72 0a 2a 2a 20 63 6f 64 65 20 69 73 20 70  ror.** code is p
10470 72 6f 6d 6f 74 65 64 20 66 72 6f 6d 20 74 68 65  romoted from the
10480 20 72 65 6c 61 74 69 76 65 6c 79 20 62 65 6e 69   relatively beni
10490 67 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  gn [SQLITE_BUSY]
104a0 20 74 6f 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20   to.** the more 
104b0 73 65 76 65 72 65 20 5b 53 51 4c 49 54 45 5f 49  severe [SQLITE_I
104c0 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e 20 20  OERR_BLOCKED].  
104d0 54 68 69 73 20 65 72 72 6f 72 20 63 6f 64 65 20  This error code 
104e0 70 72 6f 6d 6f 74 69 6f 6e 0a 2a 2a 20 66 6f 72  promotion.** for
104f0 63 65 73 20 61 6e 20 61 75 74 6f 6d 61 74 69 63  ces an automatic
10500 20 72 6f 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65   rollback of the
10510 20 63 68 61 6e 67 65 73 2e 20 20 53 65 65 20 74   changes.  See t
10520 68 65 0a 2a 2a 20 3c 61 20 68 72 65 66 3d 22 2f  he.** <a href="/
10530 63 76 73 74 72 61 63 2f 77 69 6b 69 3f 70 3d 43  cvstrac/wiki?p=C
10540 6f 72 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69  orruptionFollowi
10550 6e 67 42 75 73 79 45 72 72 6f 72 22 3e 0a 2a 2a  ngBusyError">.**
10560 20 43 6f 72 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f   CorruptionFollo
10570 77 69 6e 67 42 75 73 79 45 72 72 6f 72 3c 2f 61  wingBusyError</a
10580 3e 20 77 69 6b 69 20 70 61 67 65 20 66 6f 72 20  > wiki page for 
10590 61 20 64 69 73 63 75 73 73 69 6f 6e 20 6f 66 20  a discussion of 
105a0 77 68 79 0a 2a 2a 20 74 68 69 73 20 69 73 20 69  why.** this is i
105b0 6d 70 6f 72 74 61 6e 74 2e 0a 2a 2a 0a 2a 2a 20  mportant..**.** 
105c0 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62  There can only b
105d0 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73 79 20  e a single busy 
105e0 68 61 6e 64 6c 65 72 20 64 65 66 69 6e 65 64 20  handler defined 
105f0 66 6f 72 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74  for each.** [dat
10600 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
10610 5d 2e 20 20 53 65 74 74 69 6e 67 20 61 20 6e 65  ].  Setting a ne
10620 77 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 63  w busy handler c
10630 6c 65 61 72 73 20 61 6e 79 0a 2a 2a 20 70 72 65  lears any.** pre
10640 76 69 6f 75 73 6c 79 20 73 65 74 20 68 61 6e 64  viously set hand
10650 6c 65 72 2e 20 20 4e 6f 74 65 20 74 68 61 74 20  ler.  Note that 
10660 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  calling [sqlite3
10670 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d  _busy_timeout()]
10680 0a 2a 2a 20 77 69 6c 6c 20 61 6c 73 6f 20 73 65  .** will also se
10690 74 20 6f 72 20 63 6c 65 61 72 20 74 68 65 20 62  t or clear the b
106a0 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a  usy handler..**.
106b0 2a 2a 20 54 68 65 20 62 75 73 79 20 63 61 6c 6c  ** The busy call
106c0 62 61 63 6b 20 73 68 6f 75 6c 64 20 6e 6f 74 20  back should not 
106d0 74 61 6b 65 20 61 6e 79 20 61 63 74 69 6f 6e 73  take any actions
106e0 20 77 68 69 63 68 20 6d 6f 64 69 66 79 20 74 68   which modify th
106f0 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f  e.** database co
10700 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e  nnection that in
10710 76 6f 6b 65 64 20 74 68 65 20 62 75 73 79 20 68  voked the busy h
10720 61 6e 64 6c 65 72 2e 20 20 41 6e 79 20 73 75 63  andler.  Any suc
10730 68 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 72 65 73  h actions.** res
10740 75 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e 65 64  ult in undefined
10750 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 20 0a 2a   behavior..** .*
10760 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a  * Requirements:.
10770 2a 2a 20 5b 48 31 32 33 31 31 5d 20 5b 48 31 32  ** [H12311] [H12
10780 33 31 32 5d 20 5b 48 31 32 33 31 34 5d 20 5b 48  312] [H12314] [H
10790 31 32 33 31 36 5d 20 5b 48 31 32 33 31 38 5d 0a  12316] [H12318].
107a0 2a 2a 0a 2a 2a 20 41 20 62 75 73 79 20 68 61 6e  **.** A busy han
107b0 64 6c 65 72 20 6d 75 73 74 20 6e 6f 74 20 63 6c  dler must not cl
107c0 6f 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65  ose the database
107d0 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f   connection.** o
107e0 72 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  r [prepared stat
107f0 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 6e 76 6f  ement] that invo
10800 6b 65 64 20 74 68 65 20 62 75 73 79 20 68 61 6e  ked the busy han
10810 64 6c 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  dler..*/.int sql
10820 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65  ite3_busy_handle
10830 72 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28  r(sqlite3*, int(
10840 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 29 2c 20 76  *)(void*,int), v
10850 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  oid*);../*.** CA
10860 50 49 33 52 45 46 3a 20 53 65 74 20 41 20 42 75  PI3REF: Set A Bu
10870 73 79 20 54 69 6d 65 6f 75 74 20 7b 48 31 32 33  sy Timeout {H123
10880 34 30 7d 20 3c 53 34 30 34 31 30 3e 0a 2a 2a 0a  40} <S40410>.**.
10890 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  ** This routine 
108a0 73 65 74 73 20 61 20 5b 73 71 6c 69 74 65 33 5f  sets a [sqlite3_
108b0 62 75 73 79 5f 68 61 6e 64 6c 65 72 20 7c 20 62  busy_handler | b
108c0 75 73 79 20 68 61 6e 64 6c 65 72 5d 20 74 68 61  usy handler] tha
108d0 74 20 73 6c 65 65 70 73 0a 2a 2a 20 66 6f 72 20  t sleeps.** for 
108e0 61 20 73 70 65 63 69 66 69 65 64 20 61 6d 6f 75  a specified amou
108f0 6e 74 20 6f 66 20 74 69 6d 65 20 77 68 65 6e 20  nt of time when 
10900 61 20 74 61 62 6c 65 20 69 73 20 6c 6f 63 6b 65  a table is locke
10910 64 2e 20 20 54 68 65 20 68 61 6e 64 6c 65 72 0a  d.  The handler.
10920 2a 2a 20 77 69 6c 6c 20 73 6c 65 65 70 20 6d 75  ** will sleep mu
10930 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 75 6e 74  ltiple times unt
10940 69 6c 20 61 74 20 6c 65 61 73 74 20 22 6d 73 22  il at least "ms"
10950 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66   milliseconds of
10960 20 73 6c 65 65 70 69 6e 67 0a 2a 2a 20 68 61 76   sleeping.** hav
10970 65 20 61 63 63 75 6d 75 6c 61 74 65 64 2e 20 7b  e accumulated. {
10980 48 31 32 33 34 33 7d 20 41 66 74 65 72 20 22 6d  H12343} After "m
10990 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20  s" milliseconds 
109a0 6f 66 20 73 6c 65 65 70 69 6e 67 2c 0a 2a 2a 20  of sleeping,.** 
109b0 74 68 65 20 68 61 6e 64 6c 65 72 20 72 65 74 75  the handler retu
109c0 72 6e 73 20 30 20 77 68 69 63 68 20 63 61 75 73  rns 0 which caus
109d0 65 73 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  es [sqlite3_step
109e0 28 29 5d 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a  ()] to return.**
109f0 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f   [SQLITE_BUSY] o
10a00 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  r [SQLITE_IOERR_
10a10 42 4c 4f 43 4b 45 44 5d 2e 0a 2a 2a 0a 2a 2a 20  BLOCKED]..**.** 
10a20 43 61 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f 75  Calling this rou
10a30 74 69 6e 65 20 77 69 74 68 20 61 6e 20 61 72 67  tine with an arg
10a40 75 6d 65 6e 74 20 6c 65 73 73 20 74 68 61 6e 20  ument less than 
10a50 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f  or equal to zero
10a60 0a 2a 2a 20 74 75 72 6e 73 20 6f 66 66 20 61 6c  .** turns off al
10a70 6c 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2e  l busy handlers.
10a80 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 63 61 6e  .**.** There can
10a90 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c   only be a singl
10aa0 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 66  e busy handler f
10ab0 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a  or a particular.
10ac0 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
10ad0 6e 65 63 74 69 6f 6e 5d 20 61 6e 79 20 61 6e 79  nection] any any
10ae0 20 67 69 76 65 6e 20 6d 6f 6d 65 6e 74 2e 20 20   given moment.  
10af0 49 66 20 61 6e 6f 74 68 65 72 20 62 75 73 79 20  If another busy 
10b00 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 61 73 20 64  handler.** was d
10b10 65 66 69 6e 65 64 20 20 28 75 73 69 6e 67 20 5b  efined  (using [
10b20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e  sqlite3_busy_han
10b30 64 6c 65 72 28 29 5d 29 20 70 72 69 6f 72 20 74  dler()]) prior t
10b40 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 74 68 69  o calling.** thi
10b50 73 20 72 6f 75 74 69 6e 65 2c 20 74 68 61 74 20  s routine, that 
10b60 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c  other busy handl
10b70 65 72 20 69 73 20 63 6c 65 61 72 65 64 2e 0a 2a  er is cleared..*
10b80 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74  *.** Requirement
10b90 73 3a 0a 2a 2a 20 5b 48 31 32 33 34 31 5d 20 5b  s:.** [H12341] [
10ba0 48 31 32 33 34 33 5d 20 5b 48 31 32 33 34 34 5d  H12343] [H12344]
10bb0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
10bc0 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 73 71 6c  busy_timeout(sql
10bd0 69 74 65 33 2a 2c 20 69 6e 74 20 6d 73 29 3b 0a  ite3*, int ms);.
10be0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
10bf0 20 43 6f 6e 76 65 6e 69 65 6e 63 65 20 52 6f 75   Convenience Rou
10c00 74 69 6e 65 73 20 46 6f 72 20 52 75 6e 6e 69 6e  tines For Runnin
10c10 67 20 51 75 65 72 69 65 73 20 7b 48 31 32 33 37  g Queries {H1237
10c20 30 7d 20 3c 53 31 30 30 30 30 3e 0a 2a 2a 0a 2a  0} <S10000>.**.*
10c30 2a 20 44 65 66 69 6e 69 74 69 6f 6e 3a 20 41 20  * Definition: A 
10c40 3c 62 3e 72 65 73 75 6c 74 20 74 61 62 6c 65 3c  <b>result table<
10c50 2f 62 3e 20 69 73 20 6d 65 6d 6f 72 79 20 64 61  /b> is memory da
10c60 74 61 20 73 74 72 75 63 74 75 72 65 20 63 72 65  ta structure cre
10c70 61 74 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b  ated by the.** [
10c80 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
10c90 65 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 20  e()] interface. 
10ca0 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20   A result table 
10cb0 72 65 63 6f 72 64 73 20 74 68 65 0a 2a 2a 20 63  records the.** c
10cc0 6f 6d 70 6c 65 74 65 20 71 75 65 72 79 20 72 65  omplete query re
10cd0 73 75 6c 74 73 20 66 72 6f 6d 20 6f 6e 65 20 6f  sults from one o
10ce0 72 20 6d 6f 72 65 20 71 75 65 72 69 65 73 2e 0a  r more queries..
10cf0 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65 20  **.** The table 
10d00 63 6f 6e 63 65 70 74 75 61 6c 6c 79 20 68 61 73  conceptually has
10d10 20 61 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77   a number of row
10d20 73 20 61 6e 64 20 63 6f 6c 75 6d 6e 73 2e 20 20  s and columns.  
10d30 42 75 74 0a 2a 2a 20 74 68 65 73 65 20 6e 75 6d  But.** these num
10d40 62 65 72 73 20 61 72 65 20 6e 6f 74 20 70 61 72  bers are not par
10d50 74 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  t of the result 
10d60 74 61 62 6c 65 20 69 74 73 65 6c 66 2e 20 20 54  table itself.  T
10d70 68 65 73 65 0a 2a 2a 20 6e 75 6d 62 65 72 73 20  hese.** numbers 
10d80 61 72 65 20 6f 62 74 61 69 6e 65 64 20 73 65 70  are obtained sep
10d90 61 72 61 74 65 6c 79 2e 20 20 4c 65 74 20 4e 20  arately.  Let N 
10da0 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  be the number of
10db0 20 72 6f 77 73 0a 2a 2a 20 61 6e 64 20 4d 20 62   rows.** and M b
10dc0 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  e the number of 
10dd0 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20 41  columns..**.** A
10de0 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 73   result table is
10df0 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69   an array of poi
10e00 6e 74 65 72 73 20 74 6f 20 7a 65 72 6f 2d 74 65  nters to zero-te
10e10 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73  rminated UTF-8 s
10e20 74 72 69 6e 67 73 2e 0a 2a 2a 20 54 68 65 72 65  trings..** There
10e30 20 61 72 65 20 28 4e 2b 31 29 2a 4d 20 65 6c 65   are (N+1)*M ele
10e40 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 61 72 72  ments in the arr
10e50 61 79 2e 20 20 54 68 65 20 66 69 72 73 74 20 4d  ay.  The first M
10e60 20 70 6f 69 6e 74 65 72 73 20 70 6f 69 6e 74 0a   pointers point.
10e70 2a 2a 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69  ** to zero-termi
10e80 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20 74 68  nated strings th
10e90 61 74 20 20 63 6f 6e 74 61 69 6e 20 74 68 65 20  at  contain the 
10ea0 6e 61 6d 65 73 20 6f 66 20 74 68 65 20 63 6f 6c  names of the col
10eb0 75 6d 6e 73 2e 0a 2a 2a 20 54 68 65 20 72 65 6d  umns..** The rem
10ec0 61 69 6e 69 6e 67 20 65 6e 74 72 69 65 73 20 61  aining entries a
10ed0 6c 6c 20 70 6f 69 6e 74 20 74 6f 20 71 75 65 72  ll point to quer
10ee0 79 20 72 65 73 75 6c 74 73 2e 20 20 4e 55 4c 4c  y results.  NULL
10ef0 20 76 61 6c 75 65 73 20 72 65 73 75 6c 74 0a 2a   values result.*
10f00 2a 20 69 6e 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  * in NULL pointe
10f10 72 73 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 76  rs.  All other v
10f20 61 6c 75 65 73 20 61 72 65 20 69 6e 20 74 68 65  alues are in the
10f30 69 72 20 55 54 46 2d 38 20 7a 65 72 6f 2d 74 65  ir UTF-8 zero-te
10f40 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69  rminated.** stri
10f50 6e 67 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f  ng representatio
10f60 6e 20 61 73 20 72 65 74 75 72 6e 65 64 20 62 79  n as returned by
10f70 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
10f80 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  _text()]..**.** 
10f90 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 6d  A result table m
10fa0 69 67 68 74 20 63 6f 6e 73 69 73 74 20 6f 66 20  ight consist of 
10fb0 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6d 65 6d 6f  one or more memo
10fc0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 0a  ry allocations..
10fd0 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66  ** It is not saf
10fe0 65 20 74 6f 20 70 61 73 73 20 61 20 72 65 73 75  e to pass a resu
10ff0 6c 74 20 74 61 62 6c 65 20 64 69 72 65 63 74 6c  lt table directl
11000 79 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72  y to [sqlite3_fr
11010 65 65 28 29 5d 2e 0a 2a 2a 20 41 20 72 65 73 75  ee()]..** A resu
11020 6c 74 20 74 61 62 6c 65 20 73 68 6f 75 6c 64 20  lt table should 
11030 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 75  be deallocated u
11040 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72  sing [sqlite3_fr
11050 65 65 5f 74 61 62 6c 65 28 29 5d 2e 0a 2a 2a 0a  ee_table()]..**.
11060 2a 2a 20 41 73 20 61 6e 20 65 78 61 6d 70 6c 65  ** As an example
11070 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 74   of the result t
11080 61 62 6c 65 20 66 6f 72 6d 61 74 2c 20 73 75 70  able format, sup
11090 70 6f 73 65 20 61 20 71 75 65 72 79 20 72 65 73  pose a query res
110a0 75 6c 74 0a 2a 2a 20 69 73 20 61 73 20 66 6f 6c  ult.** is as fol
110b0 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  lows:.**.** <blo
110c0 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
110d0 20 20 20 20 20 20 20 20 4e 61 6d 65 20 20 20 20          Name    
110e0 20 20 20 20 7c 20 41 67 65 0a 2a 2a 20 20 20 20      | Age.**    
110f0 20 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d      ------------
11100 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20  -----------.**  
11110 20 20 20 20 20 20 41 6c 69 63 65 20 20 20 20 20        Alice     
11120 20 20 7c 20 34 33 0a 2a 2a 20 20 20 20 20 20 20    | 43.**       
11130 20 42 6f 62 20 20 20 20 20 20 20 20 20 7c 20 32   Bob         | 2
11140 38 0a 2a 2a 20 20 20 20 20 20 20 20 43 69 6e 64  8.**        Cind
11150 79 20 20 20 20 20 20 20 7c 20 32 31 0a 2a 2a 20  y       | 21.** 
11160 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
11170 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20  te>.**.** There 
11180 61 72 65 20 74 77 6f 20 63 6f 6c 75 6d 6e 20 28  are two column (
11190 4d 3d 3d 32 29 20 61 6e 64 20 74 68 72 65 65 20  M==2) and three 
111a0 72 6f 77 73 20 28 4e 3d 3d 33 29 2e 20 20 54 68  rows (N==3).  Th
111b0 75 73 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74  us the.** result
111c0 20 74 61 62 6c 65 20 68 61 73 20 38 20 65 6e 74   table has 8 ent
111d0 72 69 65 73 2e 20 20 53 75 70 70 6f 73 65 20 74  ries.  Suppose t
111e0 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20  he result table 
111f0 69 73 20 73 74 6f 72 65 64 0a 2a 2a 20 69 6e 20  is stored.** in 
11200 61 6e 20 61 72 72 61 79 20 6e 61 6d 65 73 20 61  an array names a
11210 7a 52 65 73 75 6c 74 2e 20 20 54 68 65 6e 20 61  zResult.  Then a
11220 7a 52 65 73 75 6c 74 20 68 6f 6c 64 73 20 74 68  zResult holds th
11230 69 73 20 63 6f 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a  is content:.**.*
11240 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
11250 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  re>.**        az
11260 52 65 73 75 6c 74 26 23 39 31 3b 30 5d 20 3d 20  Result&#91;0] = 
11270 22 4e 61 6d 65 22 3b 0a 2a 2a 20 20 20 20 20 20  "Name";.**      
11280 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 31    azResult&#91;1
11290 5d 20 3d 20 22 41 67 65 22 3b 0a 2a 2a 20 20 20  ] = "Age";.**   
112a0 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
112b0 31 3b 32 5d 20 3d 20 22 41 6c 69 63 65 22 3b 0a  1;2] = "Alice";.
112c0 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
112d0 6c 74 26 23 39 31 3b 33 5d 20 3d 20 22 34 33 22  lt&#91;3] = "43"
112e0 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
112f0 73 75 6c 74 26 23 39 31 3b 34 5d 20 3d 20 22 42  sult&#91;4] = "B
11300 6f 62 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  ob";.**        a
11310 7a 52 65 73 75 6c 74 26 23 39 31 3b 35 5d 20 3d  zResult&#91;5] =
11320 20 22 32 38 22 3b 0a 2a 2a 20 20 20 20 20 20 20   "28";.**       
11330 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 36 5d   azResult&#91;6]
11340 20 3d 20 22 43 69 6e 64 79 22 3b 0a 2a 2a 20 20   = "Cindy";.**  
11350 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
11360 39 31 3b 37 5d 20 3d 20 22 32 31 22 3b 0a 2a 2a  91;7] = "21";.**
11370 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
11380 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ote>.**.** The s
11390 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
113a0 28 29 20 66 75 6e 63 74 69 6f 6e 20 65 76 61 6c  () function eval
113b0 75 61 74 65 73 20 6f 6e 65 20 6f 72 20 6d 6f 72  uates one or mor
113c0 65 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73  e.** semicolon-s
113d0 65 70 61 72 61 74 65 64 20 53 51 4c 20 73 74 61  eparated SQL sta
113e0 74 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 7a  tements in the z
113f0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55  ero-terminated U
11400 54 46 2d 38 0a 2a 2a 20 73 74 72 69 6e 67 20 6f  TF-8.** string o
11410 66 20 69 74 73 20 32 6e 64 20 70 61 72 61 6d 65  f its 2nd parame
11420 74 65 72 2e 20 20 49 74 20 72 65 74 75 72 6e 73  ter.  It returns
11430 20 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20   a result table 
11440 74 6f 20 74 68 65 0a 2a 2a 20 70 6f 69 6e 74 65  to the.** pointe
11450 72 20 67 69 76 65 6e 20 69 6e 20 69 74 73 20 33  r given in its 3
11460 72 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  rd parameter..**
11470 0a 2a 2a 20 41 66 74 65 72 20 74 68 65 20 63 61  .** After the ca
11480 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 68  lling function h
11490 61 73 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e  as finished usin
114a0 67 20 74 68 65 20 72 65 73 75 6c 74 2c 20 69 74  g the result, it
114b0 20 73 68 6f 75 6c 64 0a 2a 2a 20 70 61 73 73 20   should.** pass 
114c0 74 68 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  the pointer to t
114d0 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20  he result table 
114e0 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f  to sqlite3_free_
114f0 74 61 62 6c 65 28 29 20 69 6e 20 6f 72 64 65 72  table() in order
11500 20 74 6f 0a 2a 2a 20 72 65 6c 65 61 73 65 20 74   to.** release t
11510 68 65 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 77  he memory that w
11520 61 73 20 6d 61 6c 6c 6f 63 65 64 2e 20 20 42 65  as malloced.  Be
11530 63 61 75 73 65 20 6f 66 20 74 68 65 20 77 61 79  cause of the way
11540 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
11550 5f 6d 61 6c 6c 6f 63 28 29 5d 20 68 61 70 70 65  _malloc()] happe
11560 6e 73 20 77 69 74 68 69 6e 20 73 71 6c 69 74 65  ns within sqlite
11570 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c 20 74  3_get_table(), t
11580 68 65 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 66 75  he calling.** fu
11590 6e 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20  nction must not 
115a0 74 72 79 20 74 6f 20 63 61 6c 6c 20 5b 73 71 6c  try to call [sql
115b0 69 74 65 33 5f 66 72 65 65 28 29 5d 20 64 69 72  ite3_free()] dir
115c0 65 63 74 6c 79 2e 20 20 4f 6e 6c 79 0a 2a 2a 20  ectly.  Only.** 
115d0 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61  [sqlite3_free_ta
115e0 62 6c 65 28 29 5d 20 69 73 20 61 62 6c 65 20 74  ble()] is able t
115f0 6f 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65  o release the me
11600 6d 6f 72 79 20 70 72 6f 70 65 72 6c 79 20 61 6e  mory properly an
11610 64 20 73 61 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20  d safely..**.** 
11620 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  The sqlite3_get_
11630 74 61 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63  table() interfac
11640 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64  e is implemented
11650 20 61 73 20 61 20 77 72 61 70 70 65 72 20 61 72   as a wrapper ar
11660 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ound.** [sqlite3
11670 5f 65 78 65 63 28 29 5d 2e 20 20 54 68 65 20 73  _exec()].  The s
11680 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
11690 28 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20  () routine does 
116a0 6e 6f 74 20 68 61 76 65 20 61 63 63 65 73 73 0a  not have access.
116b0 2a 2a 20 74 6f 20 61 6e 79 20 69 6e 74 65 72 6e  ** to any intern
116c0 61 6c 20 64 61 74 61 20 73 74 72 75 63 74 75 72  al data structur
116d0 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 49  es of SQLite.  I
116e0 74 20 75 73 65 73 20 6f 6e 6c 79 20 74 68 65 20  t uses only the 
116f0 70 75 62 6c 69 63 0a 2a 2a 20 69 6e 74 65 72 66  public.** interf
11700 61 63 65 20 64 65 66 69 6e 65 64 20 68 65 72 65  ace defined here
11710 2e 20 20 41 73 20 61 20 63 6f 6e 73 65 71 75 65  .  As a conseque
11720 6e 63 65 2c 20 65 72 72 6f 72 73 20 74 68 61 74  nce, errors that
11730 20 6f 63 63 75 72 20 69 6e 20 74 68 65 0a 2a 2a   occur in the.**
11740 20 77 72 61 70 70 65 72 20 6c 61 79 65 72 20 6f   wrapper layer o
11750 75 74 73 69 64 65 20 6f 66 20 74 68 65 20 69 6e  utside of the in
11760 74 65 72 6e 61 6c 20 5b 73 71 6c 69 74 65 33 5f  ternal [sqlite3_
11770 65 78 65 63 28 29 5d 20 63 61 6c 6c 20 61 72 65  exec()] call are
11780 20 6e 6f 74 0a 2a 2a 20 72 65 66 6c 65 63 74 65   not.** reflecte
11790 64 20 69 6e 20 73 75 62 73 65 71 75 65 6e 74 20  d in subsequent 
117a0 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  calls to [sqlite
117b0 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 6f 72 20  3_errcode()] or 
117c0 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28  [sqlite3_errmsg(
117d0 29 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72  )]..**.** Requir
117e0 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 33  ements:.** [H123
117f0 37 31 5d 20 5b 48 31 32 33 37 33 5d 20 5b 48 31  71] [H12373] [H1
11800 32 33 37 34 5d 20 5b 48 31 32 33 37 36 5d 20 5b  2374] [H12376] [
11810 48 31 32 33 37 39 5d 20 5b 48 31 32 33 38 32 5d  H12379] [H12382]
11820 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
11830 67 65 74 5f 74 61 62 6c 65 28 0a 20 20 73 71 6c  get_table(.  sql
11840 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
11850 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61     /* An open da
11860 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73  tabase */.  cons
11870 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20  t char *zSql,   
11880 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65    /* SQL to be e
11890 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 63 68  valuated */.  ch
118a0 61 72 20 2a 2a 2a 70 61 7a 52 65 73 75 6c 74 2c  ar ***pazResult,
118b0 20 20 20 20 2f 2a 20 52 65 73 75 6c 74 73 20 6f      /* Results o
118c0 66 20 74 68 65 20 71 75 65 72 79 20 2a 2f 0a 20  f the query */. 
118d0 20 69 6e 74 20 2a 70 6e 52 6f 77 2c 20 20 20 20   int *pnRow,    
118e0 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72         /* Number
118f0 20 6f 66 20 72 65 73 75 6c 74 20 72 6f 77 73 20   of result rows 
11900 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a  written here */.
11910 20 20 69 6e 74 20 2a 70 6e 43 6f 6c 75 6d 6e 2c    int *pnColumn,
11920 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65          /* Numbe
11930 72 20 6f 66 20 72 65 73 75 6c 74 20 63 6f 6c 75  r of result colu
11940 6d 6e 73 20 77 72 69 74 74 65 6e 20 68 65 72 65  mns written here
11950 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 70 7a 45   */.  char **pzE
11960 72 72 6d 73 67 20 20 20 20 20 20 20 2f 2a 20 45  rrmsg       /* E
11970 72 72 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e  rror msg written
11980 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 76 6f 69 64   here */.);.void
11990 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61   sqlite3_free_ta
119a0 62 6c 65 28 63 68 61 72 20 2a 2a 72 65 73 75 6c  ble(char **resul
119b0 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
119c0 52 45 46 3a 20 46 6f 72 6d 61 74 74 65 64 20 53  REF: Formatted S
119d0 74 72 69 6e 67 20 50 72 69 6e 74 69 6e 67 20 46  tring Printing F
119e0 75 6e 63 74 69 6f 6e 73 20 7b 48 31 37 34 30 30  unctions {H17400
119f0 7d 20 3c 53 37 30 30 30 30 3e 3c 53 32 30 30 30  } <S70000><S2000
11a00 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  0>.**.** These r
11a10 6f 75 74 69 6e 65 73 20 61 72 65 20 77 6f 72 6b  outines are work
11a20 61 6c 69 6b 65 73 20 6f 66 20 74 68 65 20 22 70  alikes of the "p
11a30 72 69 6e 74 66 28 29 22 20 66 61 6d 69 6c 79 20  rintf()" family 
11a40 6f 66 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20  of functions.** 
11a50 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 72  from the standar
11a60 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 0a  d C library..**.
11a70 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6d  ** The sqlite3_m
11a80 70 72 69 6e 74 66 28 29 20 61 6e 64 20 73 71 6c  printf() and sql
11a90 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 29 20  ite3_vmprintf() 
11aa0 72 6f 75 74 69 6e 65 73 20 77 72 69 74 65 20 74  routines write t
11ab0 68 65 69 72 0a 2a 2a 20 72 65 73 75 6c 74 73 20  heir.** results 
11ac0 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61  into memory obta
11ad0 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74  ined from [sqlit
11ae0 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a  e3_malloc()]..**
11af0 20 54 68 65 20 73 74 72 69 6e 67 73 20 72 65 74   The strings ret
11b00 75 72 6e 65 64 20 62 79 20 74 68 65 73 65 20 74  urned by these t
11b10 77 6f 20 72 6f 75 74 69 6e 65 73 20 73 68 6f 75  wo routines shou
11b20 6c 64 20 62 65 0a 2a 2a 20 72 65 6c 65 61 73 65  ld be.** release
11b30 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 72  d by [sqlite3_fr
11b40 65 65 28 29 5d 2e 20 20 42 6f 74 68 20 72 6f 75  ee()].  Both rou
11b50 74 69 6e 65 73 20 72 65 74 75 72 6e 20 61 0a 2a  tines return a.*
11b60 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69  * NULL pointer i
11b70 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  f [sqlite3_mallo
11b80 63 28 29 5d 20 69 73 20 75 6e 61 62 6c 65 20 74  c()] is unable t
11b90 6f 20 61 6c 6c 6f 63 61 74 65 20 65 6e 6f 75 67  o allocate enoug
11ba0 68 0a 2a 2a 20 6d 65 6d 6f 72 79 20 74 6f 20 68  h.** memory to h
11bb0 6f 6c 64 20 74 68 65 20 72 65 73 75 6c 74 69 6e  old the resultin
11bc0 67 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  g string..**.** 
11bd0 49 6e 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  In sqlite3_snpri
11be0 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 20 69 73  ntf() routine is
11bf0 20 73 69 6d 69 6c 61 72 20 74 6f 20 22 73 6e 70   similar to "snp
11c00 72 69 6e 74 66 28 29 22 20 66 72 6f 6d 0a 2a 2a  rintf()" from.**
11c10 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20   the standard C 
11c20 6c 69 62 72 61 72 79 2e 20 20 54 68 65 20 72 65  library.  The re
11c30 73 75 6c 74 20 69 73 20 77 72 69 74 74 65 6e 20  sult is written 
11c40 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 62 75 66 66  into the.** buff
11c50 65 72 20 73 75 70 70 6c 69 65 64 20 61 73 20 74  er supplied as t
11c60 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
11c70 74 65 72 20 77 68 6f 73 65 20 73 69 7a 65 20 69  ter whose size i
11c80 73 20 67 69 76 65 6e 20 62 79 0a 2a 2a 20 74 68  s given by.** th
11c90 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
11ca0 72 2e 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65  r. Note that the
11cb0 20 6f 72 64 65 72 20 6f 66 20 74 68 65 0a 2a 2a   order of the.**
11cc0 20 66 69 72 73 74 20 74 77 6f 20 70 61 72 61 6d   first two param
11cd0 65 74 65 72 73 20 69 73 20 72 65 76 65 72 73 65  eters is reverse
11ce0 64 20 66 72 6f 6d 20 73 6e 70 72 69 6e 74 66 28  d from snprintf(
11cf0 29 2e 20 20 54 68 69 73 20 69 73 20 61 6e 0a 2a  ).  This is an.*
11d00 2a 20 68 69 73 74 6f 72 69 63 61 6c 20 61 63 63  * historical acc
11d10 69 64 65 6e 74 20 74 68 61 74 20 63 61 6e 6e 6f  ident that canno
11d20 74 20 62 65 20 66 69 78 65 64 20 77 69 74 68 6f  t be fixed witho
11d30 75 74 20 62 72 65 61 6b 69 6e 67 0a 2a 2a 20 62  ut breaking.** b
11d40 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69  ackwards compati
11d50 62 69 6c 69 74 79 2e 20 20 4e 6f 74 65 20 61 6c  bility.  Note al
11d60 73 6f 20 74 68 61 74 20 73 71 6c 69 74 65 33 5f  so that sqlite3_
11d70 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 72 65  snprintf().** re
11d80 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
11d90 74 6f 20 69 74 73 20 62 75 66 66 65 72 20 69 6e  to its buffer in
11da0 73 74 65 61 64 20 6f 66 20 74 68 65 20 6e 75 6d  stead of the num
11db0 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61 72 61 63  ber of.** charac
11dc0 74 65 72 73 20 61 63 74 75 61 6c 6c 79 20 77 72  ters actually wr
11dd0 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 20 62  itten into the b
11de0 75 66 66 65 72 2e 20 20 57 65 20 61 64 6d 69 74  uffer.  We admit
11df0 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e 75 6d   that.** the num
11e00 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72  ber of character
11e10 73 20 77 72 69 74 74 65 6e 20 77 6f 75 6c 64 20  s written would 
11e20 62 65 20 61 20 6d 6f 72 65 20 75 73 65 66 75 6c  be a more useful
11e30 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65   return.** value
11e40 20 62 75 74 20 77 65 20 63 61 6e 6e 6f 74 20 63   but we cannot c
11e50 68 61 6e 67 65 20 74 68 65 20 69 6d 70 6c 65 6d  hange the implem
11e60 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69  entation of sqli
11e70 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a  te3_snprintf().*
11e80 2a 20 6e 6f 77 20 77 69 74 68 6f 75 74 20 62 72  * now without br
11e90 65 61 6b 69 6e 67 20 63 6f 6d 70 61 74 69 62 69  eaking compatibi
11ea0 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 41 73 20 6c  lity..**.** As l
11eb0 6f 6e 67 20 61 73 20 74 68 65 20 62 75 66 66 65  ong as the buffe
11ec0 72 20 73 69 7a 65 20 69 73 20 67 72 65 61 74 65  r size is greate
11ed0 72 20 74 68 61 6e 20 7a 65 72 6f 2c 20 73 71 6c  r than zero, sql
11ee0 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a  ite3_snprintf().
11ef0 2a 2a 20 67 75 61 72 61 6e 74 65 65 73 20 74 68  ** guarantees th
11f00 61 74 20 74 68 65 20 62 75 66 66 65 72 20 69 73  at the buffer is
11f10 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65 72   always zero-ter
11f20 6d 69 6e 61 74 65 64 2e 20 20 54 68 65 20 66 69  minated.  The fi
11f30 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  rst.** parameter
11f40 20 22 6e 22 20 69 73 20 74 68 65 20 74 6f 74 61   "n" is the tota
11f50 6c 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75  l size of the bu
11f60 66 66 65 72 2c 20 69 6e 63 6c 75 64 69 6e 67 20  ffer, including 
11f70 73 70 61 63 65 20 66 6f 72 0a 2a 2a 20 74 68 65  space for.** the
11f80 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72   zero terminator
11f90 2e 20 20 53 6f 20 74 68 65 20 6c 6f 6e 67 65 73  .  So the longes
11fa0 74 20 73 74 72 69 6e 67 20 74 68 61 74 20 63 61  t string that ca
11fb0 6e 20 62 65 20 63 6f 6d 70 6c 65 74 65 6c 79 0a  n be completely.
11fc0 2a 2a 20 77 72 69 74 74 65 6e 20 77 69 6c 6c 20  ** written will 
11fd0 62 65 20 6e 2d 31 20 63 68 61 72 61 63 74 65 72  be n-1 character
11fe0 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  s..**.** These r
11ff0 6f 75 74 69 6e 65 73 20 61 6c 6c 20 69 6d 70 6c  outines all impl
12000 65 6d 65 6e 74 20 73 6f 6d 65 20 61 64 64 69 74  ement some addit
12010 69 6f 6e 61 6c 20 66 6f 72 6d 61 74 74 69 6e 67  ional formatting
12020 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20 74 68 61 74  .** options that
12030 20 61 72 65 20 75 73 65 66 75 6c 20 66 6f 72 20   are useful for 
12040 63 6f 6e 73 74 72 75 63 74 69 6e 67 20 53 51 4c  constructing SQL
12050 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20   statements..** 
12060 41 6c 6c 20 6f 66 20 74 68 65 20 75 73 75 61 6c  All of the usual
12070 20 70 72 69 6e 74 66 28 29 20 66 6f 72 6d 61 74   printf() format
12080 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20 61 70 70  ting options app
12090 6c 79 2e 20 20 49 6e 20 61 64 64 69 74 69 6f 6e  ly.  In addition
120a0 2c 20 74 68 65 72 65 0a 2a 2a 20 69 73 20 61 72  , there.** is ar
120b0 65 20 22 25 71 22 2c 20 22 25 51 22 2c 20 61 6e  e "%q", "%Q", an
120c0 64 20 22 25 7a 22 20 6f 70 74 69 6f 6e 73 2e 0a  d "%z" options..
120d0 2a 2a 0a 2a 2a 20 54 68 65 20 25 71 20 6f 70 74  **.** The %q opt
120e0 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25  ion works like %
120f0 73 20 69 6e 20 74 68 61 74 20 69 74 20 73 75 62  s in that it sub
12100 73 74 69 74 75 74 65 73 20 61 20 6e 75 6c 6c 2d  stitutes a null-
12110 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74  terminated.** st
12120 72 69 6e 67 20 66 72 6f 6d 20 74 68 65 20 61 72  ring from the ar
12130 67 75 6d 65 6e 74 20 6c 69 73 74 2e 20 20 42 75  gument list.  Bu
12140 74 20 25 71 20 61 6c 73 6f 20 64 6f 75 62 6c 65  t %q also double
12150 73 20 65 76 65 72 79 20 27 5c 27 27 20 63 68 61  s every '\'' cha
12160 72 61 63 74 65 72 2e 0a 2a 2a 20 25 71 20 69 73  racter..** %q is
12170 20 64 65 73 69 67 6e 65 64 20 66 6f 72 20 75 73   designed for us
12180 65 20 69 6e 73 69 64 65 20 61 20 73 74 72 69 6e  e inside a strin
12190 67 20 6c 69 74 65 72 61 6c 2e 20 20 42 79 20 64  g literal.  By d
121a0 6f 75 62 6c 69 6e 67 20 65 61 63 68 20 27 5c 27  oubling each '\'
121b0 27 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 20 69  '.** character i
121c0 74 20 65 73 63 61 70 65 73 20 74 68 61 74 20 63  t escapes that c
121d0 68 61 72 61 63 74 65 72 20 61 6e 64 20 61 6c 6c  haracter and all
121e0 6f 77 73 20 69 74 20 74 6f 20 62 65 20 69 6e 73  ows it to be ins
121f0 65 72 74 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68  erted into.** th
12200 65 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  e string..**.** 
12210 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 73 73  For example, ass
12220 75 6d 65 20 74 68 65 20 73 74 72 69 6e 67 20 76  ume the string v
12230 61 72 69 61 62 6c 65 20 7a 54 65 78 74 20 63 6f  ariable zText co
12240 6e 74 61 69 6e 73 20 74 65 78 74 20 61 73 20 66  ntains text as f
12250 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62  ollows:.**.** <b
12260 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
12270 2a 2a 20 20 63 68 61 72 20 2a 7a 54 65 78 74 20  **  char *zText 
12280 3d 20 22 49 74 27 73 20 61 20 68 61 70 70 79 20  = "It's a happy 
12290 64 61 79 21 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e  day!";.** </pre>
122a0 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
122b0 0a 2a 2a 20 4f 6e 65 20 63 61 6e 20 75 73 65 20  .** One can use 
122c0 74 68 69 73 20 74 65 78 74 20 69 6e 20 61 6e 20  this text in an 
122d0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 73  SQL statement as
122e0 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20   follows:.**.** 
122f0 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
12300 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c  >.**  char *zSQL
12310 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e   = sqlite3_mprin
12320 74 66 28 22 49 4e 53 45 52 54 20 49 4e 54 4f 20  tf("INSERT INTO 
12330 74 61 62 6c 65 20 56 41 4c 55 45 53 28 27 25 71  table VALUES('%q
12340 27 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20  ')", zText);.** 
12350 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 64 62   sqlite3_exec(db
12360 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29  , zSQL, 0, 0, 0)
12370 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66 72  ;.**  sqlite3_fr
12380 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70  ee(zSQL);.** </p
12390 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
123a0 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74  .**.** Because t
123b0 68 65 20 25 71 20 66 6f 72 6d 61 74 20 73 74 72  he %q format str
123c0 69 6e 67 20 69 73 20 75 73 65 64 2c 20 74 68 65  ing is used, the
123d0 20 27 5c 27 27 20 63 68 61 72 61 63 74 65 72 20   '\'' character 
123e0 69 6e 20 7a 54 65 78 74 0a 2a 2a 20 69 73 20 65  in zText.** is e
123f0 73 63 61 70 65 64 20 61 6e 64 20 74 68 65 20 53  scaped and the S
12400 51 4c 20 67 65 6e 65 72 61 74 65 64 20 69 73 20  QL generated is 
12410 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a  as follows:.**.*
12420 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
12430 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49  re>.**  INSERT I
12440 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45  NTO table1 VALUE
12450 53 28 27 49 74 27 27 73 20 61 20 68 61 70 70 79  S('It''s a happy
12460 20 64 61 79 21 27 29 0a 2a 2a 20 3c 2f 70 72 65   day!').** </pre
12470 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
12480 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 63 6f 72  *.** This is cor
12490 72 65 63 74 2e 20 20 48 61 64 20 77 65 20 75 73  rect.  Had we us
124a0 65 64 20 25 73 20 69 6e 73 74 65 61 64 20 6f 66  ed %s instead of
124b0 20 25 71 2c 20 74 68 65 20 67 65 6e 65 72 61 74   %q, the generat
124c0 65 64 20 53 51 4c 0a 2a 2a 20 77 6f 75 6c 64 20  ed SQL.** would 
124d0 68 61 76 65 20 6c 6f 6f 6b 65 64 20 6c 69 6b 65  have looked like
124e0 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c   this:.**.** <bl
124f0 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
12500 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 74  *  INSERT INTO t
12510 61 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49 74  able1 VALUES('It
12520 27 73 20 61 20 68 61 70 70 79 20 64 61 79 21 27  's a happy day!'
12530 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  );.** </pre></bl
12540 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
12550 54 68 69 73 20 73 65 63 6f 6e 64 20 65 78 61 6d  This second exam
12560 70 6c 65 20 69 73 20 61 6e 20 53 51 4c 20 73 79  ple is an SQL sy
12570 6e 74 61 78 20 65 72 72 6f 72 2e 20 20 41 73 20  ntax error.  As 
12580 61 20 67 65 6e 65 72 61 6c 20 72 75 6c 65 20 79  a general rule y
12590 6f 75 20 73 68 6f 75 6c 64 0a 2a 2a 20 61 6c 77  ou should.** alw
125a0 61 79 73 20 75 73 65 20 25 71 20 69 6e 73 74 65  ays use %q inste
125b0 61 64 20 6f 66 20 25 73 20 77 68 65 6e 20 69 6e  ad of %s when in
125c0 73 65 72 74 69 6e 67 20 74 65 78 74 20 69 6e 74  serting text int
125d0 6f 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72  o a string liter
125e0 61 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 25 51  al..**.** The %Q
125f0 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69   option works li
12600 6b 65 20 25 71 20 65 78 63 65 70 74 20 69 74 20  ke %q except it 
12610 61 6c 73 6f 20 61 64 64 73 20 73 69 6e 67 6c 65  also adds single
12620 20 71 75 6f 74 65 73 20 61 72 6f 75 6e 64 0a 2a   quotes around.*
12630 2a 20 74 68 65 20 6f 75 74 73 69 64 65 20 6f 66  * the outside of
12640 20 74 68 65 20 74 6f 74 61 6c 20 73 74 72 69 6e   the total strin
12650 67 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c 6c 79  g.  Additionally
12660 2c 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74  , if the paramet
12670 65 72 20 69 6e 20 74 68 65 0a 2a 2a 20 61 72 67  er in the.** arg
12680 75 6d 65 6e 74 20 6c 69 73 74 20 69 73 20 61 20  ument list is a 
12690 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 25 51  NULL pointer, %Q
126a0 20 73 75 62 73 74 69 74 75 74 65 73 20 74 68 65   substitutes the
126b0 20 74 65 78 74 20 22 4e 55 4c 4c 22 20 28 77 69   text "NULL" (wi
126c0 74 68 6f 75 74 0a 2a 2a 20 73 69 6e 67 6c 65 20  thout.** single 
126d0 71 75 6f 74 65 73 29 20 69 6e 20 70 6c 61 63 65  quotes) in place
126e0 20 6f 66 20 74 68 65 20 25 51 20 6f 70 74 69 6f   of the %Q optio
126f0 6e 2e 20 20 53 6f 2c 20 66 6f 72 20 65 78 61 6d  n.  So, for exam
12700 70 6c 65 2c 20 6f 6e 65 20 63 6f 75 6c 64 20 73  ple, one could s
12710 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ay:.**.** <block
12720 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
12730 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c  char *zSQL = sql
12740 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e  ite3_mprintf("IN
12750 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20  SERT INTO table 
12760 56 41 4c 55 45 53 28 25 51 29 22 2c 20 7a 54 65  VALUES(%Q)", zTe
12770 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33  xt);.**  sqlite3
12780 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20  _exec(db, zSQL, 
12790 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71  0, 0, 0);.**  sq
127a0 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29  lite3_free(zSQL)
127b0 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ;.** </pre></blo
127c0 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54  ckquote>.**.** T
127d0 68 65 20 63 6f 64 65 20 61 62 6f 76 65 20 77 69  he code above wi
127e0 6c 6c 20 72 65 6e 64 65 72 20 61 20 63 6f 72 72  ll render a corr
127f0 65 63 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ect SQL statemen
12800 74 20 69 6e 20 74 68 65 20 7a 53 51 4c 0a 2a 2a  t in the zSQL.**
12810 20 76 61 72 69 61 62 6c 65 20 65 76 65 6e 20 69   variable even i
12820 66 20 74 68 65 20 7a 54 65 78 74 20 76 61 72 69  f the zText vari
12830 61 62 6c 65 20 69 73 20 61 20 4e 55 4c 4c 20 70  able is a NULL p
12840 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68  ointer..**.** Th
12850 65 20 22 25 7a 22 20 66 6f 72 6d 61 74 74 69 6e  e "%z" formattin
12860 67 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 65  g option works e
12870 78 61 63 74 6c 79 20 6c 69 6b 65 20 22 25 73 22  xactly like "%s"
12880 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 61 64 64   with the.** add
12890 69 74 69 6f 6e 20 74 68 61 74 20 61 66 74 65 72  ition that after
128a0 20 74 68 65 20 73 74 72 69 6e 67 20 68 61 73 20   the string has 
128b0 62 65 65 6e 20 72 65 61 64 20 61 6e 64 20 63 6f  been read and co
128c0 70 69 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65  pied into.** the
128d0 20 72 65 73 75 6c 74 2c 20 5b 73 71 6c 69 74 65   result, [sqlite
128e0 33 5f 66 72 65 65 28 29 5d 20 69 73 20 63 61 6c  3_free()] is cal
128f0 6c 65 64 20 6f 6e 20 74 68 65 20 69 6e 70 75 74  led on the input
12900 20 73 74 72 69 6e 67 2e 20 7b 45 4e 44 7d 0a 2a   string. {END}.*
12910 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74  *.** Requirement
12920 73 3a 0a 2a 2a 20 5b 48 31 37 34 30 33 5d 20 5b  s:.** [H17403] [
12930 48 31 37 34 30 36 5d 20 5b 48 31 37 34 30 37 5d  H17406] [H17407]
12940 0a 2a 2f 0a 63 68 61 72 20 2a 73 71 6c 69 74 65  .*/.char *sqlite
12950 33 5f 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20  3_mprintf(const 
12960 63 68 61 72 2a 2c 2e 2e 2e 29 3b 0a 63 68 61 72  char*,...);.char
12970 20 2a 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e   *sqlite3_vmprin
12980 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20  tf(const char*, 
12990 76 61 5f 6c 69 73 74 29 3b 0a 63 68 61 72 20 2a  va_list);.char *
129a0 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
129b0 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74  (int,char*,const
129c0 20 63 68 61 72 2a 2c 20 2e 2e 2e 29 3b 0a 0a 2f   char*, ...);../
129d0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d  *.** CAPI3REF: M
129e0 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e  emory Allocation
129f0 20 53 75 62 73 79 73 74 65 6d 20 7b 48 31 37 33   Subsystem {H173
12a00 30 30 7d 20 3c 53 32 30 30 30 30 3e 0a 2a 2a 0a  00} <S20000>.**.
12a10 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f  ** The SQLite co
12a20 72 65 20 20 75 73 65 73 20 74 68 65 73 65 20 74  re  uses these t
12a30 68 72 65 65 20 72 6f 75 74 69 6e 65 73 20 66 6f  hree routines fo
12a40 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 6f 77 6e  r all of its own
12a50 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 20 6d 65 6d  .** internal mem
12a60 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e  ory allocation n
12a70 65 65 64 73 2e 20 22 43 6f 72 65 22 20 69 6e 20  eeds. "Core" in 
12a80 74 68 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e  the previous sen
12a90 74 65 6e 63 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f  tence.** does no
12aa0 74 20 69 6e 63 6c 75 64 65 20 6f 70 65 72 61 74  t include operat
12ab0 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69  ing-system speci
12ac0 66 69 63 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e  fic VFS implemen
12ad0 74 61 74 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20  tation.  The.** 
12ae0 57 69 6e 64 6f 77 73 20 56 46 53 20 75 73 65 73  Windows VFS uses
12af0 20 6e 61 74 69 76 65 20 6d 61 6c 6c 6f 63 28 29   native malloc()
12b00 20 61 6e 64 20 66 72 65 65 28 29 20 66 6f 72 20   and free() for 
12b10 73 6f 6d 65 20 6f 70 65 72 61 74 69 6f 6e 73 2e  some operations.
12b20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
12b30 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 6f 75 74  e3_malloc() rout
12b40 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f  ine returns a po
12b50 69 6e 74 65 72 20 74 6f 20 61 20 62 6c 6f 63 6b  inter to a block
12b60 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 61 74  .** of memory at
12b70 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20 69   least N bytes i
12b80 6e 20 6c 65 6e 67 74 68 2c 20 77 68 65 72 65 20  n length, where 
12b90 4e 20 69 73 20 74 68 65 20 70 61 72 61 6d 65 74  N is the paramet
12ba0 65 72 2e 0a 2a 2a 20 49 66 20 73 71 6c 69 74 65  er..** If sqlite
12bb0 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 75 6e  3_malloc() is un
12bc0 61 62 6c 65 20 74 6f 20 6f 62 74 61 69 6e 20 73  able to obtain s
12bd0 75 66 66 69 63 69 65 6e 74 20 66 72 65 65 0a 2a  ufficient free.*
12be0 2a 20 6d 65 6d 6f 72 79 2c 20 69 74 20 72 65 74  * memory, it ret
12bf0 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  urns a NULL poin
12c00 74 65 72 2e 20 20 49 66 20 74 68 65 20 70 61 72  ter.  If the par
12c10 61 6d 65 74 65 72 20 4e 20 74 6f 0a 2a 2a 20 73  ameter N to.** s
12c20 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
12c30 69 73 20 7a 65 72 6f 20 6f 72 20 6e 65 67 61 74  is zero or negat
12c40 69 76 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33  ive then sqlite3
12c50 5f 6d 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e  _malloc() return
12c60 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  s.** a NULL poin
12c70 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 43 61 6c 6c 69  ter..**.** Calli
12c80 6e 67 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  ng sqlite3_free(
12c90 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72  ) with a pointer
12ca0 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75   previously retu
12cb0 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74  rned.** by sqlit
12cc0 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73  e3_malloc() or s
12cd0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
12ce0 20 72 65 6c 65 61 73 65 73 20 74 68 61 74 20 6d   releases that m
12cf0 65 6d 6f 72 79 20 73 6f 0a 2a 2a 20 74 68 61 74  emory so.** that
12d00 20 69 74 20 6d 69 67 68 74 20 62 65 20 72 65 75   it might be reu
12d10 73 65 64 2e 20 20 54 68 65 20 73 71 6c 69 74 65  sed.  The sqlite
12d20 33 5f 66 72 65 65 28 29 20 72 6f 75 74 69 6e 65  3_free() routine
12d30 20 69 73 0a 2a 2a 20 61 20 6e 6f 2d 6f 70 20 69   is.** a no-op i
12d40 66 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68  f is called with
12d50 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
12d60 20 20 50 61 73 73 69 6e 67 20 61 20 4e 55 4c 4c    Passing a NULL
12d70 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 73   pointer.** to s
12d80 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69 73  qlite3_free() is
12d90 20 68 61 72 6d 6c 65 73 73 2e 20 20 41 66 74 65   harmless.  Afte
12da0 72 20 62 65 69 6e 67 20 66 72 65 65 64 2c 20 6d  r being freed, m
12db0 65 6d 6f 72 79 0a 2a 2a 20 73 68 6f 75 6c 64 20  emory.** should 
12dc0 6e 65 69 74 68 65 72 20 62 65 20 72 65 61 64 20  neither be read 
12dd0 6e 6f 72 20 77 72 69 74 74 65 6e 2e 20 20 45 76  nor written.  Ev
12de0 65 6e 20 72 65 61 64 69 6e 67 20 70 72 65 76 69  en reading previ
12df0 6f 75 73 6c 79 20 66 72 65 65 64 0a 2a 2a 20 6d  ously freed.** m
12e00 65 6d 6f 72 79 20 6d 69 67 68 74 20 72 65 73 75  emory might resu
12e10 6c 74 20 69 6e 20 61 20 73 65 67 6d 65 6e 74 61  lt in a segmenta
12e20 74 69 6f 6e 20 66 61 75 6c 74 20 6f 72 20 6f 74  tion fault or ot
12e30 68 65 72 20 73 65 76 65 72 65 20 65 72 72 6f 72  her severe error
12e40 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 63 6f 72 72  ..** Memory corr
12e50 75 70 74 69 6f 6e 2c 20 61 20 73 65 67 6d 65 6e  uption, a segmen
12e60 74 61 74 69 6f 6e 20 66 61 75 6c 74 2c 20 6f 72  tation fault, or
12e70 20 6f 74 68 65 72 20 73 65 76 65 72 65 20 65 72   other severe er
12e80 72 6f 72 0a 2a 2a 20 6d 69 67 68 74 20 72 65 73  ror.** might res
12e90 75 6c 74 20 69 66 20 73 71 6c 69 74 65 33 5f 66  ult if sqlite3_f
12ea0 72 65 65 28 29 20 69 73 20 63 61 6c 6c 65 64 20  ree() is called 
12eb0 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20  with a non-NULL 
12ec0 70 6f 69 6e 74 65 72 20 74 68 61 74 0a 2a 2a 20  pointer that.** 
12ed0 77 61 73 20 6e 6f 74 20 6f 62 74 61 69 6e 65 64  was not obtained
12ee0 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61   from sqlite3_ma
12ef0 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65  lloc() or sqlite
12f00 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 0a  3_realloc()..**.
12f10 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72  ** The sqlite3_r
12f20 65 61 6c 6c 6f 63 28 29 20 69 6e 74 65 72 66 61  ealloc() interfa
12f30 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20 72  ce attempts to r
12f40 65 73 69 7a 65 20 61 0a 2a 2a 20 70 72 69 6f 72  esize a.** prior
12f50 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
12f60 6f 6e 20 74 6f 20 62 65 20 61 74 20 6c 65 61 73  on to be at leas
12f70 74 20 4e 20 62 79 74 65 73 2c 20 77 68 65 72 65  t N bytes, where
12f80 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20 73 65 63   N is the.** sec
12f90 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20  ond parameter.  
12fa0 54 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  The memory alloc
12fb0 61 74 69 6f 6e 20 74 6f 20 62 65 20 72 65 73 69  ation to be resi
12fc0 7a 65 64 20 69 73 20 74 68 65 20 66 69 72 73 74  zed is the first
12fd0 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e 20 20  .** parameter.  
12fe0 49 66 20 74 68 65 20 66 69 72 73 74 20 70 61 72  If the first par
12ff0 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
13000 33 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69  3_realloc().** i
13010 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
13020 20 74 68 65 6e 20 69 74 73 20 62 65 68 61 76 69   then its behavi
13030 6f 72 20 69 73 20 69 64 65 6e 74 69 63 61 6c 20  or is identical 
13040 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71  to calling.** sq
13050 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 20  lite3_malloc(N) 
13060 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 73  where N is the s
13070 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
13080 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  to sqlite3_reall
13090 6f 63 28 29 2e 0a 2a 2a 20 49 66 20 74 68 65 20  oc()..** If the 
130a0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
130b0 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   to sqlite3_real
130c0 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f 20 6f 72  loc() is zero or
130d0 0a 2a 2a 20 6e 65 67 61 74 69 76 65 20 74 68 65  .** negative the
130e0 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69  n the behavior i
130f0 73 20 65 78 61 63 74 6c 79 20 74 68 65 20 73 61  s exactly the sa
13100 6d 65 20 61 73 20 63 61 6c 6c 69 6e 67 0a 2a 2a  me as calling.**
13110 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 50 29   sqlite3_free(P)
13120 20 77 68 65 72 65 20 50 20 69 73 20 74 68 65 20   where P is the 
13130 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
13140 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  to sqlite3_reall
13150 6f 63 28 29 2e 0a 2a 2a 20 73 71 6c 69 74 65 33  oc()..** sqlite3
13160 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 74 75 72  _realloc() retur
13170 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
13180 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  a memory allocat
13190 69 6f 6e 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61  ion.** of at lea
131a0 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69  st N bytes in si
131b0 7a 65 20 6f 72 20 4e 55 4c 4c 20 69 66 20 73 75  ze or NULL if su
131c0 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79 20  fficient memory 
131d0 69 73 20 75 6e 61 76 61 69 6c 61 62 6c 65 2e 0a  is unavailable..
131e0 2a 2a 20 49 66 20 4d 20 69 73 20 74 68 65 20 73  ** If M is the s
131f0 69 7a 65 20 6f 66 20 74 68 65 20 70 72 69 6f 72  ize of the prior
13200 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68 65   allocation, the
13210 6e 20 6d 69 6e 28 4e 2c 4d 29 20 62 79 74 65 73  n min(N,M) bytes
13220 0a 2a 2a 20 6f 66 20 74 68 65 20 70 72 69 6f 72  .** of the prior
13230 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61 72 65 20   allocation are 
13240 63 6f 70 69 65 64 20 69 6e 74 6f 20 74 68 65 20  copied into the 
13250 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 62 75 66  beginning of buf
13260 66 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  fer returned.** 
13270 62 79 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  by sqlite3_reall
13280 6f 63 28 29 20 61 6e 64 20 74 68 65 20 70 72 69  oc() and the pri
13290 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73  or allocation is
132a0 20 66 72 65 65 64 2e 0a 2a 2a 20 49 66 20 73 71   freed..** If sq
132b0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20  lite3_realloc() 
132c0 72 65 74 75 72 6e 73 20 4e 55 4c 4c 2c 20 74 68  returns NULL, th
132d0 65 6e 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c  en the prior all
132e0 6f 63 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6e 6f  ocation.** is no
132f0 74 20 66 72 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  t freed..**.** T
13300 68 65 20 6d 65 6d 6f 72 79 20 72 65 74 75 72 6e  he memory return
13310 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61  ed by sqlite3_ma
13320 6c 6c 6f 63 28 29 20 61 6e 64 20 73 71 6c 69 74  lloc() and sqlit
13330 65 33 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20  e3_realloc().** 
13340 69 73 20 61 6c 77 61 79 73 20 61 6c 69 67 6e 65  is always aligne
13350 64 20 74 6f 20 61 74 20 6c 65 61 73 74 20 61 6e  d to at least an
13360 20 38 20 62 79 74 65 20 62 6f 75 6e 64 61 72 79   8 byte boundary
13370 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68  . {END}.**.** Th
13380 65 20 64 65 66 61 75 6c 74 20 69 6d 70 6c 65 6d  e default implem
13390 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 20  entation of the 
133a0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
133b0 6e 20 73 75 62 73 79 73 74 65 6d 20 75 73 65 73  n subsystem uses
133c0 0a 2a 2a 20 74 68 65 20 6d 61 6c 6c 6f 63 28 29  .** the malloc()
133d0 2c 20 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64 20  , realloc() and 
133e0 66 72 65 65 28 29 20 70 72 6f 76 69 64 65 64 20  free() provided 
133f0 62 79 20 74 68 65 20 73 74 61 6e 64 61 72 64 20  by the standard 
13400 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 20 7b 48  C library..** {H
13410 31 37 33 38 32 7d 20 48 6f 77 65 76 65 72 2c 20  17382} However, 
13420 69 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  if SQLite is com
13430 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a  piled with the.*
13440 2a 20 53 51 4c 49 54 45 5f 4d 45 4d 4f 52 59 5f  * SQLITE_MEMORY_
13450 53 49 5a 45 3d 3c 69 3e 4e 4e 4e 3c 2f 69 3e 20  SIZE=<i>NNN</i> 
13460 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
13470 61 63 72 6f 20 28 77 68 65 72 65 20 3c 69 3e 4e  acro (where <i>N
13480 4e 4e 3c 2f 69 3e 0a 2a 2a 20 69 73 20 61 6e 20  NN</i>.** is an 
13490 69 6e 74 65 67 65 72 29 2c 20 74 68 65 6e 20 53  integer), then S
134a0 51 4c 69 74 65 20 63 72 65 61 74 65 20 61 20 73  QLite create a s
134b0 74 61 74 69 63 20 61 72 72 61 79 20 6f 66 20 61  tatic array of a
134c0 74 20 6c 65 61 73 74 0a 2a 2a 20 3c 69 3e 4e 4e  t least.** <i>NN
134d0 4e 3c 2f 69 3e 20 62 79 74 65 73 20 69 6e 20 73  N</i> bytes in s
134e0 69 7a 65 20 61 6e 64 20 75 73 65 73 20 74 68 61  ize and uses tha
134f0 74 20 61 72 72 61 79 20 66 6f 72 20 61 6c 6c 20  t array for all 
13500 6f 66 20 69 74 73 20 64 79 6e 61 6d 69 63 0a 2a  of its dynamic.*
13510 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  * memory allocat
13520 69 6f 6e 20 6e 65 65 64 73 2e 20 7b 45 4e 44 7d  ion needs. {END}
13530 20 20 41 64 64 69 74 69 6f 6e 61 6c 20 6d 65 6d    Additional mem
13540 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 6f 70  ory allocator op
13550 74 69 6f 6e 73 0a 2a 2a 20 6d 61 79 20 62 65 20  tions.** may be 
13560 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20  added in future 
13570 72 65 6c 65 61 73 65 73 2e 0a 2a 2a 0a 2a 2a 20  releases..**.** 
13580 49 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  In SQLite versio
13590 6e 20 33 2e 35 2e 30 20 61 6e 64 20 33 2e 35 2e  n 3.5.0 and 3.5.
135a0 31 2c 20 69 74 20 77 61 73 20 70 6f 73 73 69 62  1, it was possib
135b0 6c 65 20 74 6f 20 64 65 66 69 6e 65 0a 2a 2a 20  le to define.** 
135c0 74 68 65 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  the SQLITE_OMIT_
135d0 4d 45 4d 4f 52 59 5f 41 4c 4c 4f 43 41 54 49 4f  MEMORY_ALLOCATIO
135e0 4e 20 77 68 69 63 68 20 77 6f 75 6c 64 20 63 61  N which would ca
135f0 75 73 65 20 74 68 65 20 62 75 69 6c 74 2d 69 6e  use the built-in
13600 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
13610 6f 6e 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  on of these rout
13620 69 6e 65 73 20 74 6f 20 62 65 20 6f 6d 69 74 74  ines to be omitt
13630 65 64 2e 20 20 54 68 61 74 20 63 61 70 61 62 69  ed.  That capabi
13640 6c 69 74 79 0a 2a 2a 20 69 73 20 6e 6f 20 6c 6f  lity.** is no lo
13650 6e 67 65 72 20 70 72 6f 76 69 64 65 64 2e 20 20  nger provided.  
13660 4f 6e 6c 79 20 62 75 69 6c 74 2d 69 6e 20 6d 65  Only built-in me
13670 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73 20  mory allocators 
13680 63 61 6e 20 62 65 20 75 73 65 64 2e 0a 2a 2a 0a  can be used..**.
13690 2a 2a 20 54 68 65 20 57 69 6e 64 6f 77 73 20 4f  ** The Windows O
136a0 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65  S interface laye
136b0 72 20 63 61 6c 6c 73 0a 2a 2a 20 74 68 65 20 73  r calls.** the s
136c0 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 61  ystem malloc() a
136d0 6e 64 20 66 72 65 65 28 29 20 64 69 72 65 63 74  nd free() direct
136e0 6c 79 20 77 68 65 6e 20 63 6f 6e 76 65 72 74 69  ly when converti
136f0 6e 67 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 73 20  ng.** filenames 
13700 62 65 74 77 65 65 6e 20 74 68 65 20 55 54 46 2d  between the UTF-
13710 38 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20  8 encoding used 
13720 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64  by SQLite.** and
13730 20 77 68 61 74 65 76 65 72 20 66 69 6c 65 6e 61   whatever filena
13740 6d 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 75  me encoding is u
13750 73 65 64 20 62 79 20 74 68 65 20 70 61 72 74 69  sed by the parti
13760 63 75 6c 61 72 20 57 69 6e 64 6f 77 73 0a 2a 2a  cular Windows.**
13770 20 69 6e 73 74 61 6c 6c 61 74 69 6f 6e 2e 20 20   installation.  
13780 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  Memory allocatio
13790 6e 20 65 72 72 6f 72 73 20 61 72 65 20 64 65 74  n errors are det
137a0 65 63 74 65 64 2c 20 62 75 74 0a 2a 2a 20 74 68  ected, but.** th
137b0 65 79 20 61 72 65 20 72 65 70 6f 72 74 65 64 20  ey are reported 
137c0 62 61 63 6b 20 61 73 20 5b 53 51 4c 49 54 45 5f  back as [SQLITE_
137d0 43 41 4e 54 4f 50 45 4e 5d 20 6f 72 0a 2a 2a 20  CANTOPEN] or.** 
137e0 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d 20 72  [SQLITE_IOERR] r
137f0 61 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49  ather than [SQLI
13800 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a  TE_NOMEM]..**.**
13810 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a   Requirements:.*
13820 2a 20 5b 48 31 37 33 30 33 5d 20 5b 48 31 37 33  * [H17303] [H173
13830 30 34 5d 20 5b 48 31 37 33 30 35 5d 20 5b 48 31  04] [H17305] [H1
13840 37 33 30 36 5d 20 5b 48 31 37 33 31 30 5d 20 5b  7306] [H17310] [
13850 48 31 37 33 31 32 5d 20 5b 48 31 37 33 31 35 5d  H17312] [H17315]
13860 20 5b 48 31 37 33 31 38 5d 0a 2a 2a 20 5b 48 31   [H17318].** [H1
13870 37 33 32 31 5d 20 5b 48 31 37 33 32 32 5d 20 5b  7321] [H17322] [
13880 48 31 37 33 32 33 5d 0a 2a 2a 0a 2a 2a 20 54 68  H17323].**.** Th
13890 65 20 70 6f 69 6e 74 65 72 20 61 72 67 75 6d 65  e pointer argume
138a0 6e 74 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  nts to [sqlite3_
138b0 66 72 65 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c  free()] and [sql
138c0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a  ite3_realloc()].
138d0 2a 2a 20 6d 75 73 74 20 62 65 20 65 69 74 68 65  ** must be eithe
138e0 72 20 4e 55 4c 4c 20 6f 72 20 65 6c 73 65 20 70  r NULL or else p
138f0 6f 69 6e 74 65 72 73 20 6f 62 74 61 69 6e 65 64  ointers obtained
13900 20 66 72 6f 6d 20 61 20 70 72 69 6f 72 0a 2a 2a   from a prior.**
13910 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b   invocation of [
13920 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
13930 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  ] or [sqlite3_re
13940 61 6c 6c 6f 63 28 29 5d 20 74 68 61 74 20 68 61  alloc()] that ha
13950 76 65 0a 2a 2a 20 6e 6f 74 20 79 65 74 20 62 65  ve.** not yet be
13960 65 6e 20 72 65 6c 65 61 73 65 64 2e 0a 2a 2a 0a  en released..**.
13970 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  ** The applicati
13980 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 72 65 61 64  on must not read
13990 20 6f 72 20 77 72 69 74 65 20 61 6e 79 20 70 61   or write any pa
139a0 72 74 20 6f 66 0a 2a 2a 20 61 20 62 6c 6f 63 6b  rt of.** a block
139b0 20 6f 66 20 6d 65 6d 6f 72 79 20 61 66 74 65 72   of memory after
139c0 20 69 74 20 68 61 73 20 62 65 65 6e 20 72 65 6c   it has been rel
139d0 65 61 73 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b  eased using.** [
139e0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20  sqlite3_free()] 
139f0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c  or [sqlite3_real
13a00 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 76 6f 69 64 20  loc()]..*/.void 
13a10 2a 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  *sqlite3_malloc(
13a20 69 6e 74 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69  int);.void *sqli
13a30 74 65 33 5f 72 65 61 6c 6c 6f 63 28 76 6f 69 64  te3_realloc(void
13a40 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71  *, int);.void sq
13a50 6c 69 74 65 33 5f 66 72 65 65 28 76 6f 69 64 2a  lite3_free(void*
13a60 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
13a70 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63  EF: Memory Alloc
13a80 61 74 6f 72 20 53 74 61 74 69 73 74 69 63 73 20  ator Statistics 
13a90 7b 48 31 37 33 37 30 7d 20 3c 53 33 30 32 31 30  {H17370} <S30210
13aa0 3e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 70  >.**.** SQLite p
13ab0 72 6f 76 69 64 65 73 20 74 68 65 73 65 20 74 77  rovides these tw
13ac0 6f 20 69 6e 74 65 72 66 61 63 65 73 20 66 6f 72  o interfaces for
13ad0 20 72 65 70 6f 72 74 69 6e 67 20 6f 6e 20 74 68   reporting on th
13ae0 65 20 73 74 61 74 75 73 0a 2a 2a 20 6f 66 20 74  e status.** of t
13af0 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  he [sqlite3_mall
13b00 6f 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  oc()], [sqlite3_
13b10 66 72 65 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71  free()], and [sq
13b20 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d  lite3_realloc()]
13b30 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 2c 20 77 68  .** routines, wh
13b40 69 63 68 20 66 6f 72 6d 20 74 68 65 20 62 75 69  ich form the bui
13b50 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c  lt-in memory all
13b60 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65  ocation subsyste
13b70 6d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65  m..**.** Require
13b80 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 37 33 37  ments:.** [H1737
13b90 31 5d 20 5b 48 31 37 33 37 33 5d 20 5b 48 31 37  1] [H17373] [H17
13ba0 33 37 34 5d 20 5b 48 31 37 33 37 35 5d 0a 2a 2f  374] [H17375].*/
13bb0 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73  .sqlite3_int64 s
13bc0 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73  qlite3_memory_us
13bd0 65 64 28 76 6f 69 64 29 3b 0a 73 71 6c 69 74 65  ed(void);.sqlite
13be0 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f  3_int64 sqlite3_
13bf0 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72  memory_highwater
13c00 28 69 6e 74 20 72 65 73 65 74 46 6c 61 67 29 3b  (int resetFlag);
13c10 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
13c20 3a 20 50 73 65 75 64 6f 2d 52 61 6e 64 6f 6d 20  : Pseudo-Random 
13c30 4e 75 6d 62 65 72 20 47 65 6e 65 72 61 74 6f 72  Number Generator
13c40 20 7b 48 31 37 33 39 30 7d 20 3c 53 32 30 30 30   {H17390} <S2000
13c50 30 3e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  0>.**.** SQLite 
13c60 63 6f 6e 74 61 69 6e 73 20 61 20 68 69 67 68 2d  contains a high-
13c70 71 75 61 6c 69 74 79 20 70 73 65 75 64 6f 2d 72  quality pseudo-r
13c80 61 6e 64 6f 6d 20 6e 75 6d 62 65 72 20 67 65 6e  andom number gen
13c90 65 72 61 74 6f 72 20 28 50 52 4e 47 29 20 75 73  erator (PRNG) us
13ca0 65 64 20 74 6f 0a 2a 2a 20 73 65 6c 65 63 74 20  ed to.** select 
13cb0 72 61 6e 64 6f 6d 20 5b 52 4f 57 49 44 20 7c 20  random [ROWID | 
13cc0 52 4f 57 49 44 73 5d 20 77 68 65 6e 20 69 6e 73  ROWIDs] when ins
13cd0 65 72 74 69 6e 67 20 6e 65 77 20 72 65 63 6f 72  erting new recor
13ce0 64 73 20 69 6e 74 6f 20 61 20 74 61 62 6c 65 20  ds into a table 
13cf0 74 68 61 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20  that.** already 
13d00 75 73 65 73 20 74 68 65 20 6c 61 72 67 65 73 74  uses the largest
13d10 20 70 6f 73 73 69 62 6c 65 20 5b 52 4f 57 49 44   possible [ROWID
13d20 5d 2e 20 20 54 68 65 20 50 52 4e 47 20 69 73 20  ].  The PRNG is 
13d30 61 6c 73 6f 20 75 73 65 64 20 66 6f 72 0a 2a 2a  also used for.**
13d40 20 74 68 65 20 62 75 69 6c 64 2d 69 6e 20 72 61   the build-in ra
13d50 6e 64 6f 6d 28 29 20 61 6e 64 20 72 61 6e 64 6f  ndom() and rando
13d60 6d 62 6c 6f 62 28 29 20 53 51 4c 20 66 75 6e 63  mblob() SQL func
13d70 74 69 6f 6e 73 2e 20 20 54 68 69 73 20 69 6e 74  tions.  This int
13d80 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 0a 2a 2a  erface allows.**
13d90 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 6f   applications to
13da0 20 61 63 63 65 73 73 20 74 68 65 20 73 61 6d 65   access the same
13db0 20 50 52 4e 47 20 66 6f 72 20 6f 74 68 65 72 20   PRNG for other 
13dc0 70 75 72 70 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a 20  purposes..**.** 
13dd0 41 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20 72  A call to this r
13de0 6f 75 74 69 6e 65 20 73 74 6f 72 65 73 20 4e 20  outine stores N 
13df0 62 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e  bytes of randomn
13e00 65 73 73 20 69 6e 74 6f 20 62 75 66 66 65 72 20  ess into buffer 
13e10 50 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72  P..**.** The fir
13e20 73 74 20 74 69 6d 65 20 74 68 69 73 20 72 6f 75  st time this rou
13e30 74 69 6e 65 20 69 73 20 69 6e 76 6f 6b 65 64 20  tine is invoked 
13e40 28 65 69 74 68 65 72 20 69 6e 74 65 72 6e 61 6c  (either internal
13e50 6c 79 20 6f 72 20 62 79 0a 2a 2a 20 74 68 65 20  ly or by.** the 
13e60 61 70 70 6c 69 63 61 74 69 6f 6e 29 20 74 68 65  application) the
13e70 20 50 52 4e 47 20 69 73 20 73 65 65 64 65 64 20   PRNG is seeded 
13e80 75 73 69 6e 67 20 72 61 6e 64 6f 6d 6e 65 73 73  using randomness
13e90 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f   obtained.** fro
13ea0 6d 20 74 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73  m the xRandomnes
13eb0 73 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20  s method of the 
13ec0 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33  default [sqlite3
13ed0 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a  _vfs] object..**
13ee0 20 4f 6e 20 61 6c 6c 20 73 75 62 73 65 71 75 65   On all subseque
13ef0 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e 73 2c 20  nt invocations, 
13f00 74 68 65 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f  the pseudo-rando
13f10 6d 6e 65 73 73 20 69 73 20 67 65 6e 65 72 61 74  mness is generat
13f20 65 64 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 6c 79  ed.** internally
13f30 20 61 6e 64 20 77 69 74 68 6f 75 74 20 72 65 63   and without rec
13f40 6f 75 72 73 65 20 74 6f 20 74 68 65 20 5b 73 71  ourse to the [sq
13f50 6c 69 74 65 33 5f 76 66 73 5d 20 78 52 61 6e 64  lite3_vfs] xRand
13f60 6f 6d 6e 65 73 73 0a 2a 2a 20 6d 65 74 68 6f 64  omness.** method
13f70 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d  ..**.** Requirem
13f80 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 37 33 39 32  ents:.** [H17392
13f90 5d 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65  ].*/.void sqlite
13fa0 33 5f 72 61 6e 64 6f 6d 6e 65 73 73 28 69 6e 74  3_randomness(int
13fb0 20 4e 2c 20 76 6f 69 64 20 2a 50 29 3b 0a 0a 2f   N, void *P);../
13fc0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
13fd0 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 41 75 74 68  ompile-Time Auth
13fe0 6f 72 69 7a 61 74 69 6f 6e 20 43 61 6c 6c 62 61  orization Callba
13ff0 63 6b 73 20 7b 48 31 32 35 30 30 7d 20 3c 53 37  cks {H12500} <S7
14000 30 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  0100>.**.** This
14010 20 72 6f 75 74 69 6e 65 20 72 65 67 69 73 74 65   routine registe
14020 72 73 20 61 20 61 75 74 68 6f 72 69 7a 65 72 20  rs a authorizer 
14030 63 61 6c 6c 62 61 63 6b 20 77 69 74 68 20 61 20  callback with a 
14040 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64  particular.** [d
14050 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
14060 6f 6e 5d 2c 20 73 75 70 70 6c 69 65 64 20 69 6e  on], supplied in
14070 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
14080 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 61 75 74 68  ent..** The auth
14090 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
140a0 69 73 20 69 6e 76 6f 6b 65 64 20 61 73 20 53 51  is invoked as SQ
140b0 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65  L statements are
140c0 20 62 65 69 6e 67 20 63 6f 6d 70 69 6c 65 64 0a   being compiled.
140d0 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 70  ** by [sqlite3_p
140e0 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73  repare()] or its
140f0 20 76 61 72 69 61 6e 74 73 20 5b 73 71 6c 69 74   variants [sqlit
14100 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
14110 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  ,.** [sqlite3_pr
14120 65 70 61 72 65 31 36 28 29 5d 20 61 6e 64 20 5b  epare16()] and [
14130 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
14140 36 5f 76 32 28 29 5d 2e 20 20 41 74 20 76 61 72  6_v2()].  At var
14150 69 6f 75 73 0a 2a 2a 20 70 6f 69 6e 74 73 20 64  ious.** points d
14160 75 72 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c  uring the compil
14170 61 74 69 6f 6e 20 70 72 6f 63 65 73 73 2c 20 61  ation process, a
14180 73 20 6c 6f 67 69 63 20 69 73 20 62 65 69 6e 67  s logic is being
14190 20 63 72 65 61 74 65 64 0a 2a 2a 20 74 6f 20 70   created.** to p
141a0 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 61  erform various a
141b0 63 74 69 6f 6e 73 2c 20 74 68 65 20 61 75 74 68  ctions, the auth
141c0 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
141d0 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 0a 2a 2a  is invoked to.**
141e0 20 73 65 65 20 69 66 20 74 68 6f 73 65 20 61 63   see if those ac
141f0 74 69 6f 6e 73 20 61 72 65 20 61 6c 6c 6f 77 65  tions are allowe
14200 64 2e 20 20 54 68 65 20 61 75 74 68 6f 72 69 7a  d.  The authoriz
14210 65 72 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75  er callback shou
14220 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51  ld.** return [SQ
14230 4c 49 54 45 5f 4f 4b 5d 20 74 6f 20 61 6c 6c 6f  LITE_OK] to allo
14240 77 20 74 68 65 20 61 63 74 69 6f 6e 2c 20 5b 53  w the action, [S
14250 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 6f  QLITE_IGNORE] to
14260 20 64 69 73 61 6c 6c 6f 77 20 74 68 65 0a 2a 2a   disallow the.**
14270 20 73 70 65 63 69 66 69 63 20 61 63 74 69 6f 6e   specific action
14280 20 62 75 74 20 61 6c 6c 6f 77 20 74 68 65 20 53   but allow the S
14290 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20  QL statement to 
142a0 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 0a 2a  continue to be.*
142b0 2a 20 63 6f 6d 70 69 6c 65 64 2c 20 6f 72 20 5b  * compiled, or [
142c0 53 51 4c 49 54 45 5f 44 45 4e 59 5d 20 74 6f 20  SQLITE_DENY] to 
142d0 63 61 75 73 65 20 74 68 65 20 65 6e 74 69 72 65  cause the entire
142e0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74   SQL statement t
142f0 6f 20 62 65 0a 2a 2a 20 72 65 6a 65 63 74 65 64  o be.** rejected
14300 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 2e 20   with an error. 
14310 20 49 66 20 74 68 65 20 61 75 74 68 6f 72 69 7a   If the authoriz
14320 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  er callback retu
14330 72 6e 73 0a 2a 2a 20 61 6e 79 20 76 61 6c 75 65  rns.** any value
14340 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c   other than [SQL
14350 49 54 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53 51  ITE_IGNORE], [SQ
14360 4c 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 51  LITE_OK], or [SQ
14370 4c 49 54 45 5f 44 45 4e 59 5d 0a 2a 2a 20 74 68  LITE_DENY].** th
14380 65 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  en the [sqlite3_
14390 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
143a0 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c   equivalent call
143b0 20 74 68 61 74 20 74 72 69 67 67 65 72 65 64 0a   that triggered.
143c0 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  ** the authorize
143d0 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68  r will fail with
143e0 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67   an error messag
143f0 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68  e..**.** When th
14400 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  e callback retur
14410 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20  ns [SQLITE_OK], 
14420 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20 6f  that means the o
14430 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 72 65 71 75  peration.** requ
14440 65 73 74 65 64 20 69 73 20 6f 6b 2e 20 20 57 68  ested is ok.  Wh
14450 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  en the callback 
14460 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
14470 44 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20 5b 73  DENY], the.** [s
14480 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
14490 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65  2()] or equivale
144a0 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69  nt call that tri
144b0 67 67 65 72 65 64 20 74 68 65 0a 2a 2a 20 61 75  ggered the.** au
144c0 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61  thorizer will fa
144d0 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72  il with an error
144e0 20 6d 65 73 73 61 67 65 20 65 78 70 6c 61 69 6e   message explain
144f0 69 6e 67 20 74 68 61 74 0a 2a 2a 20 61 63 63 65  ing that.** acce
14500 73 73 20 69 73 20 64 65 6e 69 65 64 2e 20 0a 2a  ss is denied. .*
14510 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70  *.** The first p
14520 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
14530 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
14540 61 63 6b 20 69 73 20 61 20 63 6f 70 79 20 6f 66  ack is a copy of
14550 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 70 61   the third.** pa
14560 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73  rameter to the s
14570 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
14580 72 69 7a 65 72 28 29 20 69 6e 74 65 72 66 61 63  rizer() interfac
14590 65 2e 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61  e. The second pa
145a0 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68  rameter.** to th
145b0 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e  e callback is an
145c0 20 69 6e 74 65 67 65 72 20 5b 53 51 4c 49 54 45   integer [SQLITE
145d0 5f 43 4f 50 59 20 7c 20 61 63 74 69 6f 6e 20 63  _COPY | action c
145e0 6f 64 65 5d 20 74 68 61 74 20 73 70 65 63 69 66  ode] that specif
145f0 69 65 73 0a 2a 2a 20 74 68 65 20 70 61 72 74 69  ies.** the parti
14600 63 75 6c 61 72 20 61 63 74 69 6f 6e 20 74 6f 20  cular action to 
14610 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 54  be authorized. T
14620 68 65 20 74 68 69 72 64 20 74 68 72 6f 75 67 68  he third through
14630 20 73 69 78 74 68 20 70 61 72 61 6d 65 74 65 72   sixth parameter
14640 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c  s.** to the call
14650 62 61 63 6b 20 61 72 65 20 7a 65 72 6f 2d 74 65  back are zero-te
14660 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73  rminated strings
14670 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 20 61 64   that contain ad
14680 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 64 65 74 61  ditional.** deta
14690 69 6c 73 20 61 62 6f 75 74 20 74 68 65 20 61 63  ils about the ac
146a0 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f  tion to be autho
146b0 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  rized..**.** If 
146c0 74 68 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20  the action code 
146d0 69 73 20 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d  is [SQLITE_READ]
146e0 0a 2a 2a 20 61 6e 64 20 74 68 65 20 63 61 6c 6c  .** and the call
146f0 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51  back returns [SQ
14700 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65  LITE_IGNORE] the
14710 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72  n the.** [prepar
14720 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 73 74  ed statement] st
14730 61 74 65 6d 65 6e 74 20 69 73 20 63 6f 6e 73 74  atement is const
14740 72 75 63 74 65 64 20 74 6f 20 73 75 62 73 74 69  ructed to substi
14750 74 75 74 65 0a 2a 2a 20 61 20 4e 55 4c 4c 20 76  tute.** a NULL v
14760 61 6c 75 65 20 69 6e 20 70 6c 61 63 65 20 6f 66  alue in place of
14770 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d   the table colum
14780 6e 20 74 68 61 74 20 77 6f 75 6c 64 20 68 61 76  n that would hav
14790 65 0a 2a 2a 20 62 65 65 6e 20 72 65 61 64 20 69  e.** been read i
147a0 66 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 68 61  f [SQLITE_OK] ha
147b0 64 20 62 65 65 6e 20 72 65 74 75 72 6e 65 64 2e  d been returned.
147c0 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 47    The [SQLITE_IG
147d0 4e 4f 52 45 5d 0a 2a 2a 20 72 65 74 75 72 6e 20  NORE].** return 
147e0 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 64  can be used to d
147f0 65 6e 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64  eny an untrusted
14800 20 75 73 65 72 20 61 63 63 65 73 73 20 74 6f 20   user access to 
14810 69 6e 64 69 76 69 64 75 61 6c 0a 2a 2a 20 63 6f  individual.** co
14820 6c 75 6d 6e 73 20 6f 66 20 61 20 74 61 62 6c 65  lumns of a table
14830 2e 0a 2a 2a 20 49 66 20 74 68 65 20 61 63 74 69  ..** If the acti
14840 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53 51 4c 49  on code is [SQLI
14850 54 45 5f 44 45 4c 45 54 45 5d 20 61 6e 64 20 74  TE_DELETE] and t
14860 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  he callback retu
14870 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49  rns.** [SQLITE_I
14880 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 20  GNORE] then the 
14890 5b 44 45 4c 45 54 45 5d 20 6f 70 65 72 61 74 69  [DELETE] operati
148a0 6f 6e 20 70 72 6f 63 65 65 64 73 20 62 75 74 20  on proceeds but 
148b0 74 68 65 0a 2a 2a 20 5b 74 72 75 6e 63 61 74 65  the.** [truncate
148c0 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 5d 20 69   optimization] i
148d0 73 20 64 69 73 61 62 6c 65 64 20 61 6e 64 20 61  s disabled and a
148e0 6c 6c 20 72 6f 77 73 20 61 72 65 20 64 65 6c 65  ll rows are dele
148f0 74 65 64 20 69 6e 64 69 76 69 64 75 61 6c 6c 79  ted individually
14900 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74 68 6f  ..**.** An autho
14910 72 69 7a 65 72 20 69 73 20 75 73 65 64 20 77 68  rizer is used wh
14920 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  en [sqlite3_prep
14930 61 72 65 20 7c 20 70 72 65 70 61 72 69 6e 67 5d  are | preparing]
14940 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  .** SQL statemen
14950 74 73 20 66 72 6f 6d 20 61 6e 20 75 6e 74 72 75  ts from an untru
14960 73 74 65 64 20 73 6f 75 72 63 65 2c 20 74 6f 20  sted source, to 
14970 65 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 20  ensure that the 
14980 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a  SQL statements.*
14990 2a 20 64 6f 20 6e 6f 74 20 74 72 79 20 74 6f 20  * do not try to 
149a0 61 63 63 65 73 73 20 64 61 74 61 20 74 68 65 79  access data they
149b0 20 61 72 65 20 6e 6f 74 20 61 6c 6c 6f 77 65 64   are not allowed
149c0 20 74 6f 20 73 65 65 2c 20 6f 72 20 74 68 61 74   to see, or that
149d0 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20   they do not.** 
149e0 74 72 79 20 74 6f 20 65 78 65 63 75 74 65 20 6d  try to execute m
149f0 61 6c 69 63 69 6f 75 73 20 73 74 61 74 65 6d 65  alicious stateme
14a00 6e 74 73 20 74 68 61 74 20 64 61 6d 61 67 65 20  nts that damage 
14a10 74 68 65 20 64 61 74 61 62 61 73 65 2e 20 20 46  the database.  F
14a20 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 61  or.** example, a
14a30 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61  n application ma
14a40 79 20 61 6c 6c 6f 77 20 61 20 75 73 65 72 20 74  y allow a user t
14a50 6f 20 65 6e 74 65 72 20 61 72 62 69 74 72 61 72  o enter arbitrar
14a60 79 0a 2a 2a 20 53 51 4c 20 71 75 65 72 69 65 73  y.** SQL queries
14a70 20 66 6f 72 20 65 76 61 6c 75 61 74 69 6f 6e 20   for evaluation 
14a80 62 79 20 61 20 64 61 74 61 62 61 73 65 2e 20 20  by a database.  
14a90 42 75 74 20 74 68 65 20 61 70 70 6c 69 63 61 74  But the applicat
14aa0 69 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20  ion does.** not 
14ab0 77 61 6e 74 20 74 68 65 20 75 73 65 72 20 74 6f  want the user to
14ac0 20 62 65 20 61 62 6c 65 20 74 6f 20 6d 61 6b 65   be able to make
14ad0 20 61 72 62 69 74 72 61 72 79 20 63 68 61 6e 67   arbitrary chang
14ae0 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74  es to the.** dat
14af0 61 62 61 73 65 2e 20 20 41 6e 20 61 75 74 68 6f  abase.  An autho
14b00 72 69 7a 65 72 20 63 6f 75 6c 64 20 74 68 65 6e  rizer could then
14b10 20 62 65 20 70 75 74 20 69 6e 20 70 6c 61 63 65   be put in place
14b20 20 77 68 69 6c 65 20 74 68 65 0a 2a 2a 20 75 73   while the.** us
14b30 65 72 2d 65 6e 74 65 72 65 64 20 53 51 4c 20 69  er-entered SQL i
14b40 73 20 62 65 69 6e 67 20 5b 73 71 6c 69 74 65 33  s being [sqlite3
14b50 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65 70 61  _prepare | prepa
14b60 72 65 64 5d 20 74 68 61 74 0a 2a 2a 20 64 69 73  red] that.** dis
14b70 61 6c 6c 6f 77 73 20 65 76 65 72 79 74 68 69 6e  allows everythin
14b80 67 20 65 78 63 65 70 74 20 5b 53 45 4c 45 43 54  g except [SELECT
14b90 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a  ] statements..**
14ba0 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  .** Applications
14bb0 20 74 68 61 74 20 6e 65 65 64 20 74 6f 20 70 72   that need to pr
14bc0 6f 63 65 73 73 20 53 51 4c 20 66 72 6f 6d 20 75  ocess SQL from u
14bd0 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63 65 73  ntrusted sources
14be0 0a 2a 2a 20 6d 69 67 68 74 20 61 6c 73 6f 20 63  .** might also c
14bf0 6f 6e 73 69 64 65 72 20 6c 6f 77 65 72 69 6e 67  onsider lowering
14c00 20 72 65 73 6f 75 72 63 65 20 6c 69 6d 69 74 73   resource limits
14c10 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
14c20 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 61 6e 64 20  limit()].** and 
14c30 6c 69 6d 69 74 69 6e 67 20 64 61 74 61 62 61 73  limiting databas
14c40 65 20 73 69 7a 65 20 75 73 69 6e 67 20 74 68 65  e size using the
14c50 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74   [max_page_count
14c60 5d 20 5b 50 52 41 47 4d 41 5d 0a 2a 2a 20 69 6e  ] [PRAGMA].** in
14c70 20 61 64 64 69 74 69 6f 6e 20 74 6f 20 75 73 69   addition to usi
14c80 6e 67 20 61 6e 20 61 75 74 68 6f 72 69 7a 65 72  ng an authorizer
14c90 2e 0a 2a 2a 0a 2a 2a 20 4f 6e 6c 79 20 61 20 73  ..**.** Only a s
14ca0 69 6e 67 6c 65 20 61 75 74 68 6f 72 69 7a 65 72  ingle authorizer
14cb0 20 63 61 6e 20 62 65 20 69 6e 20 70 6c 61 63 65   can be in place
14cc0 20 6f 6e 20 61 20 64 61 74 61 62 61 73 65 20 63   on a database c
14cd0 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 61 74 20  onnection.** at 
14ce0 61 20 74 69 6d 65 2e 20 20 45 61 63 68 20 63 61  a time.  Each ca
14cf0 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65  ll to sqlite3_se
14d00 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 6f 76 65  t_authorizer ove
14d10 72 72 69 64 65 73 20 74 68 65 0a 2a 2a 20 70 72  rrides the.** pr
14d20 65 76 69 6f 75 73 20 63 61 6c 6c 2e 20 20 44 69  evious call.  Di
14d30 73 61 62 6c 65 20 74 68 65 20 61 75 74 68 6f 72  sable the author
14d40 69 7a 65 72 20 62 79 20 69 6e 73 74 61 6c 6c 69  izer by installi
14d50 6e 67 20 61 20 4e 55 4c 4c 20 63 61 6c 6c 62 61  ng a NULL callba
14d60 63 6b 2e 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f  ck..** The autho
14d70 72 69 7a 65 72 20 69 73 20 64 69 73 61 62 6c 65  rizer is disable
14d80 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a  d by default..**
14d90 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a  .** The authoriz
14da0 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73 74  er callback must
14db0 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67   not do anything
14dc0 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66   that will modif
14dd0 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73  y.** the databas
14de0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61  e connection tha
14df0 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 61 75  t invoked the au
14e00 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
14e10 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  k..** Note that 
14e20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
14e30 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  _v2()] and [sqli
14e40 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68  te3_step()] both
14e50 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a   modify their.**
14e60 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
14e70 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65  tions for the me
14e80 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79  aning of "modify
14e90 22 20 69 6e 20 74 68 69 73 20 70 61 72 61 67 72  " in this paragr
14ea0 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20  aph..**.** When 
14eb0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
14ec0 5f 76 32 28 29 5d 20 69 73 20 75 73 65 64 20 74  _v2()] is used t
14ed0 6f 20 70 72 65 70 61 72 65 20 61 20 73 74 61 74  o prepare a stat
14ee0 65 6d 65 6e 74 2c 20 74 68 65 0a 2a 2a 20 73 74  ement, the.** st
14ef0 61 74 65 6d 65 6e 74 20 6d 69 67 68 74 20 62 65  atement might be
14f00 20 72 65 70 72 65 70 61 72 65 64 20 64 75 72 69   reprepared duri
14f10 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ng [sqlite3_step
14f20 28 29 5d 20 64 75 65 20 74 6f 20 61 20 0a 2a 2a  ()] due to a .**
14f30 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2e 20   schema change. 
14f40 20 48 65 6e 63 65 2c 20 74 68 65 20 61 70 70 6c   Hence, the appl
14f50 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 65  ication should e
14f60 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 0a 2a  nsure that the.*
14f70 2a 20 63 6f 72 72 65 63 74 20 61 75 74 68 6f 72  * correct author
14f80 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65  izer callback re
14f90 6d 61 69 6e 73 20 69 6e 20 70 6c 61 63 65 20 64  mains in place d
14fa0 75 72 69 6e 67 20 74 68 65 20 5b 73 71 6c 69 74  uring the [sqlit
14fb0 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 0a 2a  e3_step()]..**.*
14fc0 2a 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20  * Note that the 
14fd0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
14fe0 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f  ack is invoked o
14ff0 6e 6c 79 20 64 75 72 69 6e 67 0a 2a 2a 20 5b 73  nly during.** [s
15000 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
15010 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74  ] or its variant
15020 73 2e 20 20 41 75 74 68 6f 72 69 7a 61 74 69 6f  s.  Authorizatio
15030 6e 20 69 73 20 6e 6f 74 0a 2a 2a 20 70 65 72 66  n is not.** perf
15040 6f 72 6d 65 64 20 64 75 72 69 6e 67 20 73 74 61  ormed during sta
15050 74 65 6d 65 6e 74 20 65 76 61 6c 75 61 74 69 6f  tement evaluatio
15060 6e 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 73 74  n in [sqlite3_st
15070 65 70 28 29 5d 2c 20 75 6e 6c 65 73 73 0a 2a 2a  ep()], unless.**
15080 20 61 73 20 73 74 61 74 65 64 20 69 6e 20 74 68   as stated in th
15090 65 20 70 72 65 76 69 6f 75 73 20 70 61 72 61 67  e previous parag
150a0 72 61 70 68 2c 20 73 71 6c 69 74 65 33 5f 73 74  raph, sqlite3_st
150b0 65 70 28 29 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20  ep() invokes.** 
150c0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
150d0 76 32 28 29 20 74 6f 20 72 65 70 72 65 70 61 72  v2() to reprepar
150e0 65 20 61 20 73 74 61 74 65 6d 65 6e 74 20 61 66  e a statement af
150f0 74 65 72 20 61 20 73 63 68 65 6d 61 20 63 68 61  ter a schema cha
15100 6e 67 65 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69  nge..**.** Requi
15110 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32  rements:.** [H12
15120 35 30 31 5d 20 5b 48 31 32 35 30 32 5d 20 5b 48  501] [H12502] [H
15130 31 32 35 30 33 5d 20 5b 48 31 32 35 30 34 5d 20  12503] [H12504] 
15140 5b 48 31 32 35 30 35 5d 20 5b 48 31 32 35 30 36  [H12505] [H12506
15150 5d 20 5b 48 31 32 35 30 37 5d 20 5b 48 31 32 35  ] [H12507] [H125
15160 31 30 5d 0a 2a 2a 20 5b 48 31 32 35 31 31 5d 20  10].** [H12511] 
15170 5b 48 31 32 35 31 32 5d 20 5b 48 31 32 35 32 30  [H12512] [H12520
15180 5d 20 5b 48 31 32 35 32 31 5d 20 5b 48 31 32 35  ] [H12521] [H125
15190 32 32 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  22].*/.int sqlit
151a0 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
151b0 72 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20  r(.  sqlite3*,. 
151c0 20 69 6e 74 20 28 2a 78 41 75 74 68 29 28 76 6f   int (*xAuth)(vo
151d0 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68  id*,int,const ch
151e0 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c  ar*,const char*,
151f0 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73  const char*,cons
15200 74 20 63 68 61 72 2a 29 2c 0a 20 20 76 6f 69 64  t char*),.  void
15210 20 2a 70 55 73 65 72 44 61 74 61 0a 29 3b 0a 0a   *pUserData.);..
15220 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
15230 41 75 74 68 6f 72 69 7a 65 72 20 52 65 74 75 72  Authorizer Retur
15240 6e 20 43 6f 64 65 73 20 7b 48 31 32 35 39 30 7d  n Codes {H12590}
15250 20 3c 48 31 32 35 30 30 3e 0a 2a 2a 0a 2a 2a 20   <H12500>.**.** 
15260 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74  The [sqlite3_set
15270 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75  _authorizer | au
15280 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
15290 6b 20 66 75 6e 63 74 69 6f 6e 5d 20 6d 75 73 74  k function] must
152a0 0a 2a 2a 20 72 65 74 75 72 6e 20 65 69 74 68 65  .** return eithe
152b0 72 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72  r [SQLITE_OK] or
152c0 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 74 77   one of these tw
152d0 6f 20 63 6f 6e 73 74 61 6e 74 73 20 69 6e 20 6f  o constants in o
152e0 72 64 65 72 0a 2a 2a 20 74 6f 20 73 69 67 6e 61  rder.** to signa
152f0 6c 20 53 51 4c 69 74 65 20 77 68 65 74 68 65 72  l SQLite whether
15300 20 6f 72 20 6e 6f 74 20 74 68 65 20 61 63 74 69   or not the acti
15310 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64 2e  on is permitted.
15320 20 20 53 65 65 20 74 68 65 0a 2a 2a 20 5b 73 71    See the.** [sq
15330 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
15340 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65  izer | authorize
15350 72 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d  r documentation]
15360 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a   for additional.
15370 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a  ** information..
15380 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
15390 45 5f 44 45 4e 59 20 20 20 31 20 20 20 2f 2a 20  E_DENY   1   /* 
153a0 41 62 6f 72 74 20 74 68 65 20 53 51 4c 20 73 74  Abort the SQL st
153b0 61 74 65 6d 65 6e 74 20 77 69 74 68 20 61 6e 20  atement with an 
153c0 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65  error */.#define
153d0 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20 32   SQLITE_IGNORE 2
153e0 20 20 20 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f     /* Don't allo
153f0 77 20 61 63 63 65 73 73 2c 20 62 75 74 20 64 6f  w access, but do
15400 6e 27 74 20 67 65 6e 65 72 61 74 65 20 61 6e 20  n't generate an 
15410 65 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20  error */../*.** 
15420 43 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72  CAPI3REF: Author
15430 69 7a 65 72 20 41 63 74 69 6f 6e 20 43 6f 64 65  izer Action Code
15440 73 20 7b 48 31 32 35 35 30 7d 20 3c 48 31 32 35  s {H12550} <H125
15450 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73  00>.**.** The [s
15460 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
15470 72 69 7a 65 72 28 29 5d 20 69 6e 74 65 72 66 61  rizer()] interfa
15480 63 65 20 72 65 67 69 73 74 65 72 73 20 61 20 63  ce registers a c
15490 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
154a0 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 76 6f  .** that is invo
154b0 6b 65 64 20 74 6f 20 61 75 74 68 6f 72 69 7a 65  ked to authorize
154c0 20 63 65 72 74 61 69 6e 20 53 51 4c 20 73 74 61   certain SQL sta
154d0 74 65 6d 65 6e 74 20 61 63 74 69 6f 6e 73 2e 20  tement actions. 
154e0 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70   The.** second p
154f0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
15500 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69  callback is an i
15510 6e 74 65 67 65 72 20 63 6f 64 65 20 74 68 61 74  nteger code that
15520 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68   specifies.** wh
15530 61 74 20 61 63 74 69 6f 6e 20 69 73 20 62 65 69  at action is bei
15540 6e 67 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20  ng authorized.  
15550 54 68 65 73 65 20 61 72 65 20 74 68 65 20 69 6e  These are the in
15560 74 65 67 65 72 20 61 63 74 69 6f 6e 20 63 6f 64  teger action cod
15570 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 61  es that.** the a
15580 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
15590 63 6b 20 6d 61 79 20 62 65 20 70 61 73 73 65 64  ck may be passed
155a0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 63  ..**.** These ac
155b0 74 69 6f 6e 20 63 6f 64 65 20 76 61 6c 75 65 73  tion code values
155c0 20 73 69 67 6e 69 66 79 20 77 68 61 74 20 6b 69   signify what ki
155d0 6e 64 20 6f 66 20 6f 70 65 72 61 74 69 6f 6e 20  nd of operation 
155e0 69 73 20 74 6f 20 62 65 0a 2a 2a 20 61 75 74 68  is to be.** auth
155f0 6f 72 69 7a 65 64 2e 20 20 54 68 65 20 33 72 64  orized.  The 3rd
15600 20 61 6e 64 20 34 74 68 20 70 61 72 61 6d 65 74   and 4th paramet
15610 65 72 73 20 74 6f 20 74 68 65 20 61 75 74 68 6f  ers to the autho
15620 72 69 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c  rization.** call
15630 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 77 69  back function wi
15640 6c 6c 20 62 65 20 70 61 72 61 6d 65 74 65 72 73  ll be parameters
15650 20 6f 72 20 4e 55 4c 4c 20 64 65 70 65 6e 64 69   or NULL dependi
15660 6e 67 20 6f 6e 20 77 68 69 63 68 20 6f 66 20 74  ng on which of t
15670 68 65 73 65 0a 2a 2a 20 63 6f 64 65 73 20 69 73  hese.** codes is
15680 20 75 73 65 64 20 61 73 20 74 68 65 20 73 65 63   used as the sec
15690 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20  ond parameter.  
156a0 54 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65  The 5th paramete
156b0 72 20 74 6f 20 74 68 65 0a 2a 2a 20 61 75 74 68  r to the.** auth
156c0 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
156d0 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  is the name of t
156e0 68 65 20 64 61 74 61 62 61 73 65 20 28 22 6d 61  he database ("ma
156f0 69 6e 22 2c 20 22 74 65 6d 70 22 2c 0a 2a 2a 20  in", "temp",.** 
15700 65 74 63 2e 29 20 69 66 20 61 70 70 6c 69 63 61  etc.) if applica
15710 62 6c 65 2e 20 20 54 68 65 20 36 74 68 20 70 61  ble.  The 6th pa
15720 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61  rameter to the a
15730 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
15740 63 6b 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d  ck.** is the nam
15750 65 20 6f 66 20 74 68 65 20 69 6e 6e 65 72 2d 6d  e of the inner-m
15760 6f 73 74 20 74 72 69 67 67 65 72 20 6f 72 20 76  ost trigger or v
15770 69 65 77 20 74 68 61 74 20 69 73 20 72 65 73 70  iew that is resp
15780 6f 6e 73 69 62 6c 65 20 66 6f 72 0a 2a 2a 20 74  onsible for.** t
15790 68 65 20 61 63 63 65 73 73 20 61 74 74 65 6d 70  he access attemp
157a0 74 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 69  t or NULL if thi
157b0 73 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 74  s access attempt
157c0 20 69 73 20 64 69 72 65 63 74 6c 79 20 66 72 6f   is directly fro
157d0 6d 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c 20 53  m.** top-level S
157e0 51 4c 20 63 6f 64 65 2e 0a 2a 2a 0a 2a 2a 20 52  QL code..**.** R
157f0 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20  equirements:.** 
15800 5b 48 31 32 35 35 31 5d 20 5b 48 31 32 35 35 32  [H12551] [H12552
15810 5d 20 5b 48 31 32 35 35 33 5d 20 5b 48 31 32 35  ] [H12553] [H125
15820 35 34 5d 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a  54].*/./********
15830 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
15840 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
15850 2a 2a 2a 20 33 72 64 20 2a 2a 2a 2a 2a 2a 2a 2a  *** 3rd ********
15860 2a 2a 2a 2a 20 34 74 68 20 2a 2a 2a 2a 2a 2a 2a  **** 4th *******
15870 2a 2a 2a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ****/.#define SQ
15880 4c 49 54 45 5f 43 52 45 41 54 45 5f 49 4e 44 45  LITE_CREATE_INDE
15890 58 20 20 20 20 20 20 20 20 20 20 31 20 20 20 2f  X          1   /
158a0 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20  * Index Name    
158b0 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
158c0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
158d0 49 54 45 5f 43 52 45 41 54 45 5f 54 41 42 4c 45  ITE_CREATE_TABLE
158e0 20 20 20 20 20 20 20 20 20 20 32 20 20 20 2f 2a            2   /*
158f0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
15900 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
15910 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
15920 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 49  TE_CREATE_TEMP_I
15930 4e 44 45 58 20 20 20 20 20 33 20 20 20 2f 2a 20  NDEX     3   /* 
15940 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20  Index Name      
15950 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
15960 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
15970 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 41  E_CREATE_TEMP_TA
15980 42 4c 45 20 20 20 20 20 34 20 20 20 2f 2a 20 54  BLE     4   /* T
15990 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
159a0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
159b0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
159c0 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 52 49  _CREATE_TEMP_TRI
159d0 47 47 45 52 20 20 20 35 20 20 20 2f 2a 20 54 72  GGER   5   /* Tr
159e0 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61  igger Name    Ta
159f0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
15a00 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
15a10 43 52 45 41 54 45 5f 54 45 4d 50 5f 56 49 45 57  CREATE_TEMP_VIEW
15a20 20 20 20 20 20 20 36 20 20 20 2f 2a 20 56 69 65        6   /* Vie
15a30 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c  w Name       NUL
15a40 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
15a50 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
15a60 52 45 41 54 45 5f 54 52 49 47 47 45 52 20 20 20  REATE_TRIGGER   
15a70 20 20 20 20 20 37 20 20 20 2f 2a 20 54 72 69 67       7   /* Trig
15a80 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c  ger Name    Tabl
15a90 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
15aa0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
15ab0 45 41 54 45 5f 56 49 45 57 20 20 20 20 20 20 20  EATE_VIEW       
15ac0 20 20 20 20 38 20 20 20 2f 2a 20 56 69 65 77 20      8   /* View 
15ad0 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20  Name       NULL 
15ae0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
15af0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4c  efine SQLITE_DEL
15b00 45 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20  ETE             
15b10 20 20 20 39 20 20 20 2f 2a 20 54 61 62 6c 65 20     9   /* Table 
15b20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
15b30 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
15b40 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
15b50 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20  _INDEX          
15b60 20 31 30 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e   10   /* Index N
15b70 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e  ame      Table N
15b80 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
15b90 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
15ba0 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 20  TABLE           
15bb0 31 31 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  11   /* Table Na
15bc0 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
15bd0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
15be0 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54  ne SQLITE_DROP_T
15bf0 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 20 31  EMP_INDEX      1
15c00 32 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d  2   /* Index Nam
15c10 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  e      Table Nam
15c20 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
15c30 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45  e SQLITE_DROP_TE
15c40 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 20 31 33  MP_TABLE      13
15c50 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
15c60 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
15c70 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
15c80 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d   SQLITE_DROP_TEM
15c90 50 5f 54 52 49 47 47 45 52 20 20 20 20 31 34 20  P_TRIGGER    14 
15ca0 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d    /* Trigger Nam
15cb0 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20  e    Table Name 
15cc0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
15cd0 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50  SQLITE_DROP_TEMP
15ce0 5f 56 49 45 57 20 20 20 20 20 20 20 31 35 20 20  _VIEW       15  
15cf0 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20   /* View Name   
15d00 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
15d10 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
15d20 51 4c 49 54 45 5f 44 52 4f 50 5f 54 52 49 47 47  QLITE_DROP_TRIGG
15d30 45 52 20 20 20 20 20 20 20 20 20 31 36 20 20 20  ER         16   
15d40 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20  /* Trigger Name 
15d50 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
15d60 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
15d70 4c 49 54 45 5f 44 52 4f 50 5f 56 49 45 57 20 20  LITE_DROP_VIEW  
15d80 20 20 20 20 20 20 20 20 20 20 31 37 20 20 20 2f            17   /
15d90 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20  * View Name     
15da0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
15db0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
15dc0 49 54 45 5f 49 4e 53 45 52 54 20 20 20 20 20 20  ITE_INSERT      
15dd0 20 20 20 20 20 20 20 20 20 31 38 20 20 20 2f 2a           18   /*
15de0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
15df0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
15e00 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
15e10 54 45 5f 50 52 41 47 4d 41 20 20 20 20 20 20 20  TE_PRAGMA       
15e20 20 20 20 20 20 20 20 20 31 39 20 20 20 2f 2a 20          19   /* 
15e30 50 72 61 67 6d 61 20 4e 61 6d 65 20 20 20 20 20  Pragma Name     
15e40 31 73 74 20 61 72 67 20 6f 72 20 4e 55 4c 4c 20  1st arg or NULL 
15e50 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
15e60 45 5f 52 45 41 44 20 20 20 20 20 20 20 20 20 20  E_READ          
15e70 20 20 20 20 20 20 20 32 30 20 20 20 2f 2a 20 54         20   /* T
15e80 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43  able Name      C
15e90 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a  olumn Name     *
15ea0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
15eb0 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20 20 20  _SELECT         
15ec0 20 20 20 20 20 20 32 31 20 20 20 2f 2a 20 4e 55        21   /* NU
15ed0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 4e 55  LL            NU
15ee0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
15ef0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
15f00 54 52 41 4e 53 41 43 54 49 4f 4e 20 20 20 20 20  TRANSACTION     
15f10 20 20 20 20 20 32 32 20 20 20 2f 2a 20 4f 70 65       22   /* Ope
15f20 72 61 74 69 6f 6e 20 20 20 20 20 20 20 4e 55 4c  ration       NUL
15f30 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
15f40 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55  #define SQLITE_U
15f50 50 44 41 54 45 20 20 20 20 20 20 20 20 20 20 20  PDATE           
15f60 20 20 20 20 32 33 20 20 20 2f 2a 20 54 61 62 6c      23   /* Tabl
15f70 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c 75  e Name      Colu
15f80 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23  mn Name     */.#
15f90 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 54  define SQLITE_AT
15fa0 54 41 43 48 20 20 20 20 20 20 20 20 20 20 20 20  TACH            
15fb0 20 20 20 32 34 20 20 20 2f 2a 20 46 69 6c 65 6e     24   /* Filen
15fc0 61 6d 65 20 20 20 20 20 20 20 20 4e 55 4c 4c 20  ame        NULL 
15fd0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
15fe0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 54  efine SQLITE_DET
15ff0 41 43 48 20 20 20 20 20 20 20 20 20 20 20 20 20  ACH             
16000 20 20 32 35 20 20 20 2f 2a 20 44 61 74 61 62 61    25   /* Databa
16010 73 65 20 4e 61 6d 65 20 20 20 4e 55 4c 4c 20 20  se Name   NULL  
16020 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
16030 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4c 54 45  fine SQLITE_ALTE
16040 52 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20  R_TABLE         
16050 20 32 36 20 20 20 2f 2a 20 44 61 74 61 62 61 73   26   /* Databas
16060 65 20 4e 61 6d 65 20 20 20 54 61 62 6c 65 20 4e  e Name   Table N
16070 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
16080 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 49 4e 44  ine SQLITE_REIND
16090 45 58 20 20 20 20 20 20 20 20 20 20 20 20 20 20  EX              
160a0 32 37 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61  27   /* Index Na
160b0 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
160c0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
160d0 6e 65 20 53 51 4c 49 54 45 5f 41 4e 41 4c 59 5a  ne SQLITE_ANALYZ
160e0 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32  E              2
160f0 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  8   /* Table Nam
16100 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
16110 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
16120 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
16130 56 54 41 42 4c 45 20 20 20 20 20 20 20 20 32 39  VTABLE        29
16140 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
16150 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d        Module Nam
16160 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65  e     */.#define
16170 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 54 41   SQLITE_DROP_VTA
16180 42 4c 45 20 20 20 20 20 20 20 20 20 20 33 30 20  BLE          30 
16190 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
161a0 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65       Module Name
161b0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
161c0 53 51 4c 49 54 45 5f 46 55 4e 43 54 49 4f 4e 20  SQLITE_FUNCTION 
161d0 20 20 20 20 20 20 20 20 20 20 20 20 33 31 20 20              31  
161e0 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20   /* NULL        
161f0 20 20 20 20 46 75 6e 63 74 69 6f 6e 20 4e 61 6d      Function Nam
16200 65 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  e   */.#define S
16210 51 4c 49 54 45 5f 53 41 56 45 50 4f 49 4e 54 20  QLITE_SAVEPOINT 
16220 20 20 20 20 20 20 20 20 20 20 20 33 32 20 20 20             32   
16230 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20 20 20  /* Operation    
16240 20 20 20 53 61 76 65 70 6f 69 6e 74 20 4e 61 6d     Savepoint Nam
16250 65 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  e  */.#define SQ
16260 4c 49 54 45 5f 43 4f 50 59 20 20 20 20 20 20 20  LITE_COPY       
16270 20 20 20 20 20 20 20 20 20 20 20 30 20 20 20 2f             0   /
16280 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 75 73 65 64  * No longer used
16290 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   */../*.** CAPI3
162a0 52 45 46 3a 20 54 72 61 63 69 6e 67 20 41 6e 64  REF: Tracing And
162b0 20 50 72 6f 66 69 6c 69 6e 67 20 46 75 6e 63 74   Profiling Funct
162c0 69 6f 6e 73 20 7b 48 31 32 32 38 30 7d 20 3c 53  ions {H12280} <S
162d0 36 30 34 30 30 3e 0a 2a 2a 20 45 58 50 45 52 49  60400>.** EXPERI
162e0 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 65  MENTAL.**.** The
162f0 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 67 69  se routines regi
16300 73 74 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75  ster callback fu
16310 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 63 61 6e  nctions that can
16320 20 62 65 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20   be used for.** 
16330 74 72 61 63 69 6e 67 20 61 6e 64 20 70 72 6f 66  tracing and prof
16340 69 6c 69 6e 67 20 74 68 65 20 65 78 65 63 75 74  iling the execut
16350 69 6f 6e 20 6f 66 20 53 51 4c 20 73 74 61 74 65  ion of SQL state
16360 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ments..**.** The
16370 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
16380 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 62 79  on registered by
16390 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29   sqlite3_trace()
163a0 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 74 0a 2a   is invoked at.*
163b0 2a 20 76 61 72 69 6f 75 73 20 74 69 6d 65 73 20  * various times 
163c0 77 68 65 6e 20 61 6e 20 53 51 4c 20 73 74 61 74  when an SQL stat
163d0 65 6d 65 6e 74 20 69 73 20 62 65 69 6e 67 20 72  ement is being r
163e0 75 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73  un by [sqlite3_s
163f0 74 65 70 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 63  tep()]..** The c
16400 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
16410 61 20 55 54 46 2d 38 20 72 65 6e 64 65 72 69 6e  a UTF-8 renderin
16420 67 20 6f 66 20 74 68 65 20 53 51 4c 20 73 74 61  g of the SQL sta
16430 74 65 6d 65 6e 74 20 74 65 78 74 0a 2a 2a 20 61  tement text.** a
16440 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  s the statement 
16450 66 69 72 73 74 20 62 65 67 69 6e 73 20 65 78 65  first begins exe
16460 63 75 74 69 6e 67 2e 20 20 41 64 64 69 74 69 6f  cuting.  Additio
16470 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 73 20 6f 63  nal callbacks oc
16480 63 75 72 0a 2a 2a 20 61 73 20 65 61 63 68 20 74  cur.** as each t
16490 72 69 67 67 65 72 65 64 20 73 75 62 70 72 6f 67  riggered subprog
164a0 72 61 6d 20 69 73 20 65 6e 74 65 72 65 64 2e 20  ram is entered. 
164b0 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 73 20 66   The callbacks f
164c0 6f 72 20 74 72 69 67 67 65 72 73 0a 2a 2a 20 63  or triggers.** c
164d0 6f 6e 74 61 69 6e 20 61 20 55 54 46 2d 38 20 53  ontain a UTF-8 S
164e0 51 4c 20 63 6f 6d 6d 65 6e 74 20 74 68 61 74 20  QL comment that 
164f0 69 64 65 6e 74 69 66 69 65 73 20 74 68 65 20 74  identifies the t
16500 72 69 67 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68  rigger..**.** Th
16510 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  e callback funct
16520 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 62  ion registered b
16530 79 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c  y sqlite3_profil
16540 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a  e() is invoked.*
16550 2a 20 61 73 20 65 61 63 68 20 53 51 4c 20 73 74  * as each SQL st
16560 61 74 65 6d 65 6e 74 20 66 69 6e 69 73 68 65 73  atement finishes
16570 2e 20 20 54 68 65 20 70 72 6f 66 69 6c 65 20 63  .  The profile c
16580 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e 73  allback contains
16590 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 61 6c  .** the original
165a0 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20   statement text 
165b0 61 6e 64 20 61 6e 20 65 73 74 69 6d 61 74 65 20  and an estimate 
165c0 6f 66 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74 69  of wall-clock ti
165d0 6d 65 0a 2a 2a 20 6f 66 20 68 6f 77 20 6c 6f 6e  me.** of how lon
165e0 67 20 74 68 61 74 20 73 74 61 74 65 6d 65 6e 74  g that statement
165f0 20 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e 0a 2a 2a   took to run..**
16600 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73  .** Requirements
16610 3a 0a 2a 2a 20 5b 48 31 32 32 38 31 5d 20 5b 48  :.** [H12281] [H
16620 31 32 32 38 32 5d 20 5b 48 31 32 32 38 33 5d 20  12282] [H12283] 
16630 5b 48 31 32 32 38 34 5d 20 5b 48 31 32 32 38 35  [H12284] [H12285
16640 5d 20 5b 48 31 32 32 38 37 5d 20 5b 48 31 32 32  ] [H12287] [H122
16650 38 38 5d 20 5b 48 31 32 32 38 39 5d 0a 2a 2a 20  88] [H12289].** 
16660 5b 48 31 32 32 39 30 5d 0a 2a 2f 0a 53 51 4c 49  [H12290].*/.SQLI
16670 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 20  TE_EXPERIMENTAL 
16680 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 74 72  void *sqlite3_tr
16690 61 63 65 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f  ace(sqlite3*, vo
166a0 69 64 28 2a 78 54 72 61 63 65 29 28 76 6f 69 64  id(*xTrace)(void
166b0 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20  *,const char*), 
166c0 76 6f 69 64 2a 29 3b 0a 53 51 4c 49 54 45 5f 45  void*);.SQLITE_E
166d0 58 50 45 52 49 4d 45 4e 54 41 4c 20 76 6f 69 64  XPERIMENTAL void
166e0 20 2a 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c   *sqlite3_profil
166f0 65 28 73 71 6c 69 74 65 33 2a 2c 0a 20 20 20 76  e(sqlite3*,.   v
16700 6f 69 64 28 2a 78 50 72 6f 66 69 6c 65 29 28 76  oid(*xProfile)(v
16710 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  oid*,const char*
16720 2c 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 29  ,sqlite3_uint64)
16730 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  , void*);../*.**
16740 20 43 41 50 49 33 52 45 46 3a 20 51 75 65 72 79   CAPI3REF: Query
16750 20 50 72 6f 67 72 65 73 73 20 43 61 6c 6c 62 61   Progress Callba
16760 63 6b 73 20 7b 48 31 32 39 31 30 7d 20 3c 53 36  cks {H12910} <S6
16770 30 34 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  0400>.**.** This
16780 20 72 6f 75 74 69 6e 65 20 63 6f 6e 66 69 67 75   routine configu
16790 72 65 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66  res a callback f
167a0 75 6e 63 74 69 6f 6e 20 2d 20 74 68 65 0a 2a 2a  unction - the.**
167b0 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61   progress callba
167c0 63 6b 20 2d 20 74 68 61 74 20 69 73 20 69 6e 76  ck - that is inv
167d0 6f 6b 65 64 20 70 65 72 69 6f 64 69 63 61 6c 6c  oked periodicall
167e0 79 20 64 75 72 69 6e 67 20 6c 6f 6e 67 0a 2a 2a  y during long.**
167f0 20 72 75 6e 6e 69 6e 67 20 63 61 6c 6c 73 20 74   running calls t
16800 6f 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28  o [sqlite3_exec(
16810 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  )], [sqlite3_ste
16820 70 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  p()] and.** [sql
16830 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
16840 5d 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 75  ].  An example u
16850 73 65 20 66 6f 72 20 74 68 69 73 0a 2a 2a 20 69  se for this.** i
16860 6e 74 65 72 66 61 63 65 20 69 73 20 74 6f 20 6b  nterface is to k
16870 65 65 70 20 61 20 47 55 49 20 75 70 64 61 74 65  eep a GUI update
16880 64 20 64 75 72 69 6e 67 20 61 20 6c 61 72 67 65  d during a large
16890 20 71 75 65 72 79 2e 0a 2a 2a 0a 2a 2a 20 49 66   query..**.** If
168a0 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 63 61   the progress ca
168b0 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e  llback returns n
168c0 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 6f 70 65  on-zero, the ope
168d0 72 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 69 6e 74  ration is.** int
168e0 65 72 72 75 70 74 65 64 2e 20 20 54 68 69 73 20  errupted.  This 
168f0 66 65 61 74 75 72 65 20 63 61 6e 20 62 65 20 75  feature can be u
16900 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74  sed to implement
16910 20 61 0a 2a 2a 20 22 43 61 6e 63 65 6c 22 20 62   a.** "Cancel" b
16920 75 74 74 6f 6e 20 6f 6e 20 61 20 47 55 49 20 70  utton on a GUI p
16930 72 6f 67 72 65 73 73 20 64 69 61 6c 6f 67 20 62  rogress dialog b
16940 6f 78 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72  ox..**.** The pr
16950 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 6d  ogress handler m
16960 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68  ust not do anyth
16970 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f  ing that will mo
16980 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61  dify.** the data
16990 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
169a0 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65  that invoked the
169b0 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65   progress handle
169c0 72 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  r..** Note that 
169d0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
169e0 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  _v2()] and [sqli
169f0 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68  te3_step()] both
16a00 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a   modify their.**
16a10 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
16a20 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65  tions for the me
16a30 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79  aning of "modify
16a40 22 20 69 6e 20 74 68 69 73 20 70 61 72 61 67 72  " in this paragr
16a50 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69  aph..**.** Requi
16a60 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32  rements:.** [H12
16a70 39 31 31 5d 20 5b 48 31 32 39 31 32 5d 20 5b 48  911] [H12912] [H
16a80 31 32 39 31 33 5d 20 5b 48 31 32 39 31 34 5d 20  12913] [H12914] 
16a90 5b 48 31 32 39 31 35 5d 20 5b 48 31 32 39 31 36  [H12915] [H12916
16aa0 5d 20 5b 48 31 32 39 31 37 5d 20 5b 48 31 32 39  ] [H12917] [H129
16ab0 31 38 5d 0a 2a 2a 0a 2a 2f 0a 76 6f 69 64 20 73  18].**.*/.void s
16ac0 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f  qlite3_progress_
16ad0 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a  handler(sqlite3*
16ae0 2c 20 69 6e 74 2c 20 69 6e 74 28 2a 29 28 76 6f  , int, int(*)(vo
16af0 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f  id*), void*);../
16b00 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
16b10 70 65 6e 69 6e 67 20 41 20 4e 65 77 20 44 61 74  pening A New Dat
16b20 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e  abase Connection
16b30 20 7b 48 31 32 37 30 30 7d 20 3c 53 34 30 32 30   {H12700} <S4020
16b40 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  0>.**.** These r
16b50 6f 75 74 69 6e 65 73 20 6f 70 65 6e 20 61 6e 20  outines open an 
16b60 53 51 4c 69 74 65 20 64 61 74 61 62 61 73 65 20  SQLite database 
16b70 66 69 6c 65 20 77 68 6f 73 65 20 6e 61 6d 65 20  file whose name 
16b80 69 73 20 67 69 76 65 6e 20 62 79 20 74 68 65 0a  is given by the.
16b90 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75  ** filename argu
16ba0 6d 65 6e 74 2e 20 54 68 65 20 66 69 6c 65 6e 61  ment. The filena
16bb0 6d 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 69  me argument is i
16bc0 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 55 54  nterpreted as UT
16bd0 46 2d 38 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74  F-8 for.** sqlit
16be0 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71  e3_open() and sq
16bf0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
16c00 61 6e 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e  and as UTF-16 in
16c10 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65   the native byte
16c20 0a 2a 2a 20 6f 72 64 65 72 20 66 6f 72 20 73 71  .** order for sq
16c30 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 20  lite3_open16(). 
16c40 41 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  A [database conn
16c50 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 69  ection] handle i
16c60 73 20 75 73 75 61 6c 6c 79 0a 2a 2a 20 72 65 74  s usually.** ret
16c70 75 72 6e 65 64 20 69 6e 20 2a 70 70 44 62 2c 20  urned in *ppDb, 
16c80 65 76 65 6e 20 69 66 20 61 6e 20 65 72 72 6f 72  even if an error
16c90 20 6f 63 63 75 72 73 2e 20 20 54 68 65 20 6f 6e   occurs.  The on
16ca0 6c 79 20 65 78 63 65 70 74 69 6f 6e 20 69 73 20  ly exception is 
16cb0 74 68 61 74 0a 2a 2a 20 69 66 20 53 51 4c 69 74  that.** if SQLit
16cc0 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61  e is unable to a
16cd0 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 74  llocate memory t
16ce0 6f 20 68 6f 6c 64 20 74 68 65 20 5b 73 71 6c 69  o hold the [sqli
16cf0 74 65 33 5d 20 6f 62 6a 65 63 74 2c 0a 2a 2a 20  te3] object,.** 
16d00 61 20 4e 55 4c 4c 20 77 69 6c 6c 20 62 65 20 77  a NULL will be w
16d10 72 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70 70 44  ritten into *ppD
16d20 62 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20 70  b instead of a p
16d30 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73  ointer to the [s
16d40 71 6c 69 74 65 33 5d 0a 2a 2a 20 6f 62 6a 65 63  qlite3].** objec
16d50 74 2e 20 49 66 20 74 68 65 20 64 61 74 61 62 61  t. If the databa
16d60 73 65 20 69 73 20 6f 70 65 6e 65 64 20 28 61 6e  se is opened (an
16d70 64 2f 6f 72 20 63 72 65 61 74 65 64 29 20 73 75  d/or created) su
16d80 63 63 65 73 73 66 75 6c 6c 79 2c 20 74 68 65 6e  ccessfully, then
16d90 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  .** [SQLITE_OK] 
16da0 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 4f 74  is returned.  Ot
16db0 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f  herwise an [erro
16dc0 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72  r code] is retur
16dd0 6e 65 64 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71  ned.  The.** [sq
16de0 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 20  lite3_errmsg()] 
16df0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d  or [sqlite3_errm
16e00 73 67 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73  sg16()] routines
16e10 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
16e20 6f 62 74 61 69 6e 0a 2a 2a 20 61 6e 20 45 6e 67  obtain.** an Eng
16e30 6c 69 73 68 20 6c 61 6e 67 75 61 67 65 20 64 65  lish language de
16e40 73 63 72 69 70 74 69 6f 6e 20 6f 66 20 74 68 65  scription of the
16e50 20 65 72 72 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68   error..**.** Th
16e60 65 20 64 65 66 61 75 6c 74 20 65 6e 63 6f 64 69  e default encodi
16e70 6e 67 20 66 6f 72 20 74 68 65 20 64 61 74 61 62  ng for the datab
16e80 61 73 65 20 77 69 6c 6c 20 62 65 20 55 54 46 2d  ase will be UTF-
16e90 38 20 69 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  8 if.** sqlite3_
16ea0 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65  open() or sqlite
16eb0 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 63  3_open_v2() is c
16ec0 61 6c 6c 65 64 20 61 6e 64 0a 2a 2a 20 55 54 46  alled and.** UTF
16ed0 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76  -16 in the nativ
16ee0 65 20 62 79 74 65 20 6f 72 64 65 72 20 69 66 20  e byte order if 
16ef0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
16f00 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20   is used..**.** 
16f10 57 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 61  Whether or not a
16f20 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77  n error occurs w
16f30 68 65 6e 20 69 74 20 69 73 20 6f 70 65 6e 65 64  hen it is opened
16f40 2c 20 72 65 73 6f 75 72 63 65 73 0a 2a 2a 20 61  , resources.** a
16f50 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74  ssociated with t
16f60 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
16f70 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20  nection] handle 
16f80 73 68 6f 75 6c 64 20 62 65 20 72 65 6c 65 61 73  should be releas
16f90 65 64 20 62 79 0a 2a 2a 20 70 61 73 73 69 6e 67  ed by.** passing
16fa0 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f   it to [sqlite3_
16fb0 63 6c 6f 73 65 28 29 5d 20 77 68 65 6e 20 69 74  close()] when it
16fc0 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 72 65   is no longer re
16fd0 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  quired..**.** Th
16fe0 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  e sqlite3_open_v
16ff0 32 28 29 20 69 6e 74 65 72 66 61 63 65 20 77 6f  2() interface wo
17000 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74 65 33  rks like sqlite3
17010 5f 6f 70 65 6e 28 29 0a 2a 2a 20 65 78 63 65 70  _open().** excep
17020 74 20 74 68 61 74 20 69 74 20 61 63 63 65 70 74  t that it accept
17030 73 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c  s two additional
17040 20 70 61 72 61 6d 65 74 65 72 73 20 66 6f 72 20   parameters for 
17050 61 64 64 69 74 69 6f 6e 61 6c 20 63 6f 6e 74 72  additional contr
17060 6f 6c 0a 2a 2a 20 6f 76 65 72 20 74 68 65 20 6e  ol.** over the n
17070 65 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ew database conn
17080 65 63 74 69 6f 6e 2e 20 20 54 68 65 20 66 6c 61  ection.  The fla
17090 67 73 20 70 61 72 61 6d 65 74 65 72 20 63 61 6e  gs parameter can
170a0 20 74 61 6b 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20   take one of.** 
170b0 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68  the following th
170c0 72 65 65 20 76 61 6c 75 65 73 2c 20 6f 70 74 69  ree values, opti
170d0 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20  onally combined 
170e0 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 5b 53 51  with the .** [SQ
170f0 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45  LITE_OPEN_NOMUTE
17100 58 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50  X] or [SQLITE_OP
17110 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 20 66 6c  EN_FULLMUTEX] fl
17120 61 67 73 3a 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a  ags:.**.** <dl>.
17130 2a 2a 20 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f  ** <dt>[SQLITE_O
17140 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 3c 2f 64  PEN_READONLY]</d
17150 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61  t>.** <dd>The da
17160 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64  tabase is opened
17170 20 69 6e 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 6f   in read-only mo
17180 64 65 2e 20 20 49 66 20 74 68 65 20 64 61 74 61  de.  If the data
17190 62 61 73 65 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a  base does not.**
171a0 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 2c 20   already exist, 
171b0 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74 75  an error is retu
171c0 72 6e 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  rned.</dd>.**.**
171d0 20 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45   <dt>[SQLITE_OPE
171e0 4e 5f 52 45 41 44 57 52 49 54 45 5d 3c 2f 64 74  N_READWRITE]</dt
171f0 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74  >.** <dd>The dat
17200 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20  abase is opened 
17210 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20  for reading and 
17220 77 72 69 74 69 6e 67 20 69 66 20 70 6f 73 73 69  writing if possi
17230 62 6c 65 2c 20 6f 72 20 72 65 61 64 69 6e 67 0a  ble, or reading.
17240 2a 2a 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 66  ** only if the f
17250 69 6c 65 20 69 73 20 77 72 69 74 65 20 70 72 6f  ile is write pro
17260 74 65 63 74 65 64 20 62 79 20 74 68 65 20 6f 70  tected by the op
17270 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20  erating system. 
17280 20 49 6e 20 65 69 74 68 65 72 0a 2a 2a 20 63 61   In either.** ca
17290 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  se the database 
172a0 6d 75 73 74 20 61 6c 72 65 61 64 79 20 65 78 69  must already exi
172b0 73 74 2c 20 6f 74 68 65 72 77 69 73 65 20 61 6e  st, otherwise an
172c0 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e   error is return
172d0 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  ed.</dd>.**.** <
172e0 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  dt>[SQLITE_OPEN_
172f0 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51  READWRITE] | [SQ
17300 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45  LITE_OPEN_CREATE
17310 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  ]</dt>.** <dd>Th
17320 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70  e database is op
17330 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e 67  ened for reading
17340 20 61 6e 64 20 77 72 69 74 69 6e 67 2c 20 61 6e   and writing, an
17350 64 20 69 73 20 63 72 65 61 74 65 73 20 69 74 20  d is creates it 
17360 69 66 0a 2a 2a 20 69 74 20 64 6f 65 73 20 6e 6f  if.** it does no
17370 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 2e  t already exist.
17380 20 54 68 69 73 20 69 73 20 74 68 65 20 62 65 68   This is the beh
17390 61 76 69 6f 72 20 74 68 61 74 20 69 73 20 61 6c  avior that is al
173a0 77 61 79 73 20 75 73 65 64 20 66 6f 72 0a 2a 2a  ways used for.**
173b0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20   sqlite3_open() 
173c0 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  and sqlite3_open
173d0 31 36 28 29 2e 3c 2f 64 64 3e 0a 2a 2a 20 3c 2f  16().</dd>.** </
173e0 64 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  dl>.**.** If the
173f0 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74   3rd parameter t
17400 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  o sqlite3_open_v
17410 32 28 29 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f  2() is not one o
17420 66 20 74 68 65 0a 2a 2a 20 63 6f 6d 62 69 6e 61  f the.** combina
17430 74 69 6f 6e 73 20 73 68 6f 77 6e 20 61 62 6f 76  tions shown abov
17440 65 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 20  e or one of the 
17450 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 73 68 6f  combinations sho
17460 77 6e 20 61 62 6f 76 65 20 63 6f 6d 62 69 6e 65  wn above combine
17470 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 53  d.** with the [S
17480 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54  QLITE_OPEN_NOMUT
17490 45 58 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4f  EX] or [SQLITE_O
174a0 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 20 66  PEN_FULLMUTEX] f
174b0 6c 61 67 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68  lags,.** then th
174c0 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e  e behavior is un
174d0 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49  defined..**.** I
174e0 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50  f the [SQLITE_OP
174f0 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20 66 6c 61 67  EN_NOMUTEX] flag
17500 20 69 73 20 73 65 74 2c 20 74 68 65 6e 20 74 68   is set, then th
17510 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
17520 63 74 69 6f 6e 0a 2a 2a 20 6f 70 65 6e 73 20 69  ction.** opens i
17530 6e 20 74 68 65 20 6d 75 6c 74 69 2d 74 68 72 65  n the multi-thre
17540 61 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  ad [threading mo
17550 64 65 5d 20 61 73 20 6c 6f 6e 67 20 61 73 20 74  de] as long as t
17560 68 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64  he single-thread
17570 0a 2a 2a 20 6d 6f 64 65 20 68 61 73 20 6e 6f 74  .** mode has not
17580 20 62 65 65 6e 20 73 65 74 20 61 74 20 63 6f 6d   been set at com
17590 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74 61  pile-time or sta
175a0 72 74 2d 74 69 6d 65 2e 20 20 49 66 20 74 68 65  rt-time.  If the
175b0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  .** [SQLITE_OPEN
175c0 5f 46 55 4c 4c 4d 55 54 45 58 5d 20 66 6c 61 67  _FULLMUTEX] flag
175d0 20 69 73 20 73 65 74 20 74 68 65 6e 20 74 68 65   is set then the
175e0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
175f0 74 69 6f 6e 20 6f 70 65 6e 73 0a 2a 2a 20 69 6e  tion opens.** in
17600 20 74 68 65 20 73 65 72 69 61 6c 69 7a 65 64 20   the serialized 
17610 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
17620 20 75 6e 6c 65 73 73 20 73 69 6e 67 6c 65 2d 74   unless single-t
17630 68 72 65 61 64 20 77 61 73 0a 2a 2a 20 70 72 65  hread was.** pre
17640 76 69 6f 75 73 6c 79 20 73 65 6c 65 63 74 65 64  viously selected
17650 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65   at compile-time
17660 20 6f 72 20 73 74 61 72 74 2d 74 69 6d 65 2e 0a   or start-time..
17670 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 66 69 6c  **.** If the fil
17680 65 6e 61 6d 65 20 69 73 20 22 3a 6d 65 6d 6f 72  ename is ":memor
17690 79 3a 22 2c 20 74 68 65 6e 20 61 20 70 72 69 76  y:", then a priv
176a0 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 20 69  ate, temporary i
176b0 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73  n-memory databas
176c0 65 0a 2a 2a 20 69 73 20 63 72 65 61 74 65 64 20  e.** is created 
176d0 66 6f 72 20 74 68 65 20 63 6f 6e 6e 65 63 74 69  for the connecti
176e0 6f 6e 2e 20 20 54 68 69 73 20 69 6e 2d 6d 65 6d  on.  This in-mem
176f0 6f 72 79 20 64 61 74 61 62 61 73 65 20 77 69 6c  ory database wil
17700 6c 20 76 61 6e 69 73 68 20 77 68 65 6e 0a 2a 2a  l vanish when.**
17710 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
17720 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73  nnection is clos
17730 65 64 2e 20 20 46 75 74 75 72 65 20 76 65 72 73  ed.  Future vers
17740 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d  ions of SQLite m
17750 69 67 68 74 0a 2a 2a 20 6d 61 6b 65 20 75 73 65  ight.** make use
17760 20 6f 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 73   of additional s
17770 70 65 63 69 61 6c 20 66 69 6c 65 6e 61 6d 65 73  pecial filenames
17780 20 74 68 61 74 20 62 65 67 69 6e 20 77 69 74 68   that begin with
17790 20 74 68 65 20 22 3a 22 20 63 68 61 72 61 63 74   the ":" charact
177a0 65 72 2e 0a 2a 2a 20 49 74 20 69 73 20 72 65 63  er..** It is rec
177b0 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 77 68  ommended that wh
177c0 65 6e 20 61 20 64 61 74 61 62 61 73 65 20 66 69  en a database fi
177d0 6c 65 6e 61 6d 65 20 61 63 74 75 61 6c 6c 79 20  lename actually 
177e0 64 6f 65 73 20 62 65 67 69 6e 20 77 69 74 68 0a  does begin with.
177f0 2a 2a 20 61 20 22 3a 22 20 63 68 61 72 61 63 74  ** a ":" charact
17800 65 72 20 79 6f 75 20 73 68 6f 75 6c 64 20 70 72  er you should pr
17810 65 66 69 78 20 74 68 65 20 66 69 6c 65 6e 61 6d  efix the filenam
17820 65 20 77 69 74 68 20 61 20 70 61 74 68 6e 61 6d  e with a pathnam
17830 65 20 73 75 63 68 20 61 73 0a 2a 2a 20 22 2e 2f  e such as.** "./
17840 22 20 74 6f 20 61 76 6f 69 64 20 61 6d 62 69 67  " to avoid ambig
17850 75 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  uity..**.** If t
17860 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 61  he filename is a
17870 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 20  n empty string, 
17880 74 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20  then a private, 
17890 74 65 6d 70 6f 72 61 72 79 0a 2a 2a 20 6f 6e 2d  temporary.** on-
178a0 64 69 73 6b 20 64 61 74 61 62 61 73 65 20 77 69  disk database wi
178b0 6c 6c 20 62 65 20 63 72 65 61 74 65 64 2e 20 20  ll be created.  
178c0 54 68 69 73 20 70 72 69 76 61 74 65 20 64 61 74  This private dat
178d0 61 62 61 73 65 20 77 69 6c 6c 20 62 65 0a 2a 2a  abase will be.**
178e0 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64   automatically d
178f0 65 6c 65 74 65 64 20 61 73 20 73 6f 6f 6e 20 61  eleted as soon a
17900 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  s the database c
17910 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f  onnection is clo
17920 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  sed..**.** The f
17930 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
17940 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  to sqlite3_open_
17950 76 32 28 29 20 69 73 20 74 68 65 20 6e 61 6d 65  v2() is the name
17960 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69   of the.** [sqli
17970 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20  te3_vfs] object 
17980 74 68 61 74 20 64 65 66 69 6e 65 73 20 74 68 65  that defines the
17990 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65   operating syste
179a0 6d 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74  m interface that
179b0 0a 2a 2a 20 74 68 65 20 6e 65 77 20 64 61 74 61  .** the new data
179c0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
179d0 73 68 6f 75 6c 64 20 75 73 65 2e 20 20 49 66 20  should use.  If 
179e0 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  the fourth param
179f0 65 74 65 72 20 69 73 0a 2a 2a 20 61 20 4e 55 4c  eter is.** a NUL
17a00 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 74  L pointer then t
17a10 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69  he default [sqli
17a20 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20  te3_vfs] object 
17a30 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c  is used..**.** <
17a40 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77  b>Note to Window
17a50 73 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68  s users:</b>  Th
17a60 65 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20  e encoding used 
17a70 66 6f 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65  for the filename
17a80 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 6f 66 20   argument.** of 
17a90 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61  sqlite3_open() a
17aa0 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  nd sqlite3_open_
17ab0 76 32 28 29 20 6d 75 73 74 20 62 65 20 55 54 46  v2() must be UTF
17ac0 2d 38 2c 20 6e 6f 74 20 77 68 61 74 65 76 65 72  -8, not whatever
17ad0 0a 2a 2a 20 63 6f 64 65 70 61 67 65 20 69 73 20  .** codepage is 
17ae0 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65  currently define
17af0 64 2e 20 20 46 69 6c 65 6e 61 6d 65 73 20 63 6f  d.  Filenames co
17b00 6e 74 61 69 6e 69 6e 67 20 69 6e 74 65 72 6e 61  ntaining interna
17b10 74 69 6f 6e 61 6c 0a 2a 2a 20 63 68 61 72 61 63  tional.** charac
17b20 74 65 72 73 20 6d 75 73 74 20 62 65 20 63 6f 6e  ters must be con
17b30 76 65 72 74 65 64 20 74 6f 20 55 54 46 2d 38 20  verted to UTF-8 
17b40 70 72 69 6f 72 20 74 6f 20 70 61 73 73 69 6e 67  prior to passing
17b50 20 74 68 65 6d 20 69 6e 74 6f 0a 2a 2a 20 73 71   them into.** sq
17b60 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20  lite3_open() or 
17b70 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
17b80 29 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65  )..**.** Require
17b90 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 37 30  ments:.** [H1270
17ba0 31 5d 20 5b 48 31 32 37 30 32 5d 20 5b 48 31 32  1] [H12702] [H12
17bb0 37 30 33 5d 20 5b 48 31 32 37 30 34 5d 20 5b 48  703] [H12704] [H
17bc0 31 32 37 30 36 5d 20 5b 48 31 32 37 30 37 5d 20  12706] [H12707] 
17bd0 5b 48 31 32 37 30 39 5d 20 5b 48 31 32 37 31 31  [H12709] [H12711
17be0 5d 0a 2a 2a 20 5b 48 31 32 37 31 32 5d 20 5b 48  ].** [H12712] [H
17bf0 31 32 37 31 33 5d 20 5b 48 31 32 37 31 34 5d 20  12713] [H12714] 
17c00 5b 48 31 32 37 31 37 5d 20 5b 48 31 32 37 31 39  [H12717] [H12719
17c10 5d 20 5b 48 31 32 37 32 31 5d 20 5b 48 31 32 37  ] [H12721] [H127
17c20 32 33 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  23].*/.int sqlit
17c30 65 33 5f 6f 70 65 6e 28 0a 20 20 63 6f 6e 73 74  e3_open(.  const
17c40 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c   char *filename,
17c50 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66     /* Database f
17c60 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20  ilename (UTF-8) 
17c70 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70  */.  sqlite3 **p
17c80 70 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20  pDb          /* 
17c90 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68  OUT: SQLite db h
17ca0 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20  andle */.);.int 
17cb0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 0a  sqlite3_open16(.
17cc0 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 66 69    const void *fi
17cd0 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74  lename,   /* Dat
17ce0 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28  abase filename (
17cf0 55 54 46 2d 31 36 29 20 2a 2f 0a 20 20 73 71 6c  UTF-16) */.  sql
17d00 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20  ite3 **ppDb     
17d10 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c       /* OUT: SQL
17d20 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f  ite db handle */
17d30 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
17d40 6f 70 65 6e 5f 76 32 28 0a 20 20 63 6f 6e 73 74  open_v2(.  const
17d50 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c   char *filename,
17d60 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66     /* Database f
17d70 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20  ilename (UTF-8) 
17d80 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70  */.  sqlite3 **p
17d90 70 44 62 2c 20 20 20 20 20 20 20 20 20 2f 2a 20  pDb,         /* 
17da0 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68  OUT: SQLite db h
17db0 61 6e 64 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 66  andle */.  int f
17dc0 6c 61 67 73 2c 20 20 20 20 20 20 20 20 20 20 20  lags,           
17dd0 20 20 20 2f 2a 20 46 6c 61 67 73 20 2a 2f 0a 20     /* Flags */. 
17de0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 56 66   const char *zVf
17df0 73 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65  s        /* Name
17e00 20 6f 66 20 56 46 53 20 6d 6f 64 75 6c 65 20 74   of VFS module t
17e10 6f 20 75 73 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a  o use */.);../*.
17e20 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 72 72  ** CAPI3REF: Err
17e30 6f 72 20 43 6f 64 65 73 20 41 6e 64 20 4d 65 73  or Codes And Mes
17e40 73 61 67 65 73 20 7b 48 31 32 38 30 30 7d 20 3c  sages {H12800} <
17e50 53 36 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68  S60200>.**.** Th
17e60 65 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64  e sqlite3_errcod
17e70 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  e() interface re
17e80 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 65 72 69  turns the numeri
17e90 63 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 20  c [result code] 
17ea0 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20  or.** [extended 
17eb0 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 66 6f 72  result code] for
17ec0 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
17ed0 20 66 61 69 6c 65 64 20 73 71 6c 69 74 65 33 5f   failed sqlite3_
17ee0 2a 20 41 50 49 20 63 61 6c 6c 0a 2a 2a 20 61 73  * API call.** as
17ef0 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 61 20  sociated with a 
17f00 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
17f10 74 69 6f 6e 5d 2e 20 49 66 20 61 20 70 72 69 6f  tion]. If a prio
17f20 72 20 41 50 49 20 63 61 6c 6c 20 66 61 69 6c 65  r API call faile
17f30 64 0a 2a 2a 20 62 75 74 20 74 68 65 20 6d 6f 73  d.** but the mos
17f40 74 20 72 65 63 65 6e 74 20 41 50 49 20 63 61 6c  t recent API cal
17f50 6c 20 73 75 63 63 65 65 64 65 64 2c 20 74 68 65  l succeeded, the
17f60 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72   return value fr
17f70 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 72  om.** sqlite3_er
17f80 72 63 6f 64 65 28 29 20 69 73 20 75 6e 64 65 66  rcode() is undef
17f90 69 6e 65 64 2e 20 20 54 68 65 20 73 71 6c 69 74  ined.  The sqlit
17fa0 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63  e3_extended_errc
17fb0 6f 64 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61  ode().** interfa
17fc0 63 65 20 69 73 20 74 68 65 20 73 61 6d 65 20 65  ce is the same e
17fd0 78 63 65 70 74 20 74 68 61 74 20 69 74 20 61 6c  xcept that it al
17fe0 77 61 79 73 20 72 65 74 75 72 6e 73 20 74 68 65  ways returns the
17ff0 20 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72   .** [extended r
18000 65 73 75 6c 74 20 63 6f 64 65 5d 20 65 76 65 6e  esult code] even
18010 20 77 68 65 6e 20 65 78 74 65 6e 64 65 64 20 72   when extended r
18020 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 0a  esult codes are.
18030 2a 2a 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a  ** disabled..**.
18040 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 65  ** The sqlite3_e
18050 72 72 6d 73 67 28 29 20 61 6e 64 20 73 71 6c 69  rrmsg() and sqli
18060 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 20 72  te3_errmsg16() r
18070 65 74 75 72 6e 20 45 6e 67 6c 69 73 68 2d 6c 61  eturn English-la
18080 6e 67 75 61 67 65 0a 2a 2a 20 74 65 78 74 20 74  nguage.** text t
18090 68 61 74 20 64 65 73 63 72 69 62 65 73 20 74 68  hat describes th
180a0 65 20 65 72 72 6f 72 2c 20 61 73 20 65 69 74 68  e error, as eith
180b0 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d  er UTF-8 or UTF-
180c0 31 36 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e  16 respectively.
180d0 0a 2a 2a 20 4d 65 6d 6f 72 79 20 74 6f 20 68 6f  .** Memory to ho
180e0 6c 64 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73  ld the error mes
180f0 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 20 6d  sage string is m
18100 61 6e 61 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c  anaged internall
18110 79 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63  y..** The applic
18120 61 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 6e  ation does not n
18130 65 65 64 20 74 6f 20 77 6f 72 72 79 20 61 62 6f  eed to worry abo
18140 75 74 20 66 72 65 65 69 6e 67 20 74 68 65 20 72  ut freeing the r
18150 65 73 75 6c 74 2e 0a 2a 2a 20 48 6f 77 65 76 65  esult..** Howeve
18160 72 2c 20 74 68 65 20 65 72 72 6f 72 20 73 74 72  r, the error str
18170 69 6e 67 20 6d 69 67 68 74 20 62 65 20 6f 76 65  ing might be ove
18180 72 77 72 69 74 74 65 6e 20 6f 72 20 64 65 61 6c  rwritten or deal
18190 6c 6f 63 61 74 65 64 20 62 79 0a 2a 2a 20 73 75  located by.** su
181a0 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74  bsequent calls t
181b0 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69  o other SQLite i
181c0 6e 74 65 72 66 61 63 65 20 66 75 6e 63 74 69 6f  nterface functio
181d0 6e 73 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74  ns..**.** When t
181e0 68 65 20 73 65 72 69 61 6c 69 7a 65 64 20 5b 74  he serialized [t
181f0 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 69  hreading mode] i
18200 73 20 69 6e 20 75 73 65 2c 20 69 74 20 6d 69 67  s in use, it mig
18210 68 74 20 62 65 20 74 68 65 0a 2a 2a 20 63 61 73  ht be the.** cas
18220 65 20 74 68 61 74 20 61 20 73 65 63 6f 6e 64 20  e that a second 
18230 65 72 72 6f 72 20 6f 63 63 75 72 73 20 6f 6e 20  error occurs on 
18240 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61  a separate threa
18250 64 20 69 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20  d in between.** 
18260 74 68 65 20 74 69 6d 65 20 6f 66 20 74 68 65 20  the time of the 
18270 66 69 72 73 74 20 65 72 72 6f 72 20 61 6e 64 20  first error and 
18280 74 68 65 20 63 61 6c 6c 20 74 6f 20 74 68 65 73  the call to thes
18290 65 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a  e interfaces..**
182a0 20 57 68 65 6e 20 74 68 61 74 20 68 61 70 70 65   When that happe
182b0 6e 73 2c 20 74 68 65 20 73 65 63 6f 6e 64 20 65  ns, the second e
182c0 72 72 6f 72 20 77 69 6c 6c 20 62 65 20 72 65 70  rror will be rep
182d0 6f 72 74 65 64 20 73 69 6e 63 65 20 74 68 65 73  orted since thes
182e0 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  e.** interfaces 
182f0 61 6c 77 61 79 73 20 72 65 70 6f 72 74 20 74 68  always report th
18300 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 72 65  e most recent re
18310 73 75 6c 74 2e 20 20 54 6f 20 61 76 6f 69 64 0a  sult.  To avoid.
18320 2a 2a 20 74 68 69 73 2c 20 65 61 63 68 20 74 68  ** this, each th
18330 72 65 61 64 20 63 61 6e 20 6f 62 74 61 69 6e 20  read can obtain 
18340 65 78 63 6c 75 73 69 76 65 20 75 73 65 20 6f 66  exclusive use of
18350 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
18360 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a 2a 20  onnection] D.** 
18370 62 79 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c  by invoking [sql
18380 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72  ite3_mutex_enter
18390 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75  ]([sqlite3_db_mu
183a0 74 65 78 5d 28 44 29 29 20 62 65 66 6f 72 65 20  tex](D)) before 
183b0 62 65 67 69 6e 6e 69 6e 67 0a 2a 2a 20 74 6f 20  beginning.** to 
183c0 75 73 65 20 44 20 61 6e 64 20 69 6e 76 6f 6b 69  use D and invoki
183d0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  ng [sqlite3_mute
183e0 78 5f 6c 65 61 76 65 5d 28 5b 73 71 6c 69 74 65  x_leave]([sqlite
183f0 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 29 20  3_db_mutex](D)) 
18400 61 66 74 65 72 0a 2a 2a 20 61 6c 6c 20 63 61 6c  after.** all cal
18410 6c 73 20 74 6f 20 74 68 65 20 69 6e 74 65 72 66  ls to the interf
18420 61 63 65 73 20 6c 69 73 74 65 64 20 68 65 72 65  aces listed here
18430 20 61 72 65 20 63 6f 6d 70 6c 65 74 65 64 2e 0a   are completed..
18440 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 69 6e 74 65  **.** If an inte
18450 72 66 61 63 65 20 66 61 69 6c 73 20 77 69 74 68  rface fails with
18460 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 2c 20   SQLITE_MISUSE, 
18470 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20 69  that means the i
18480 6e 74 65 72 66 61 63 65 0a 2a 2a 20 77 61 73 20  nterface.** was 
18490 69 6e 76 6f 6b 65 64 20 69 6e 63 6f 72 72 65 63  invoked incorrec
184a0 74 6c 79 20 62 79 20 74 68 65 20 61 70 70 6c 69  tly by the appli
184b0 63 61 74 69 6f 6e 2e 20 20 49 6e 20 74 68 61 74  cation.  In that
184c0 20 63 61 73 65 2c 20 74 68 65 0a 2a 2a 20 65 72   case, the.** er
184d0 72 6f 72 20 63 6f 64 65 20 61 6e 64 20 6d 65 73  ror code and mes
184e0 73 61 67 65 20 6d 61 79 20 6f 72 20 6d 61 79 20  sage may or may 
184f0 6e 6f 74 20 62 65 20 73 65 74 2e 0a 2a 2a 0a 2a  not be set..**.*
18500 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a  * Requirements:.
18510 2a 2a 20 5b 48 31 32 38 30 31 5d 20 5b 48 31 32  ** [H12801] [H12
18520 38 30 32 5d 20 5b 48 31 32 38 30 33 5d 20 5b 48  802] [H12803] [H
18530 31 32 38 30 37 5d 20 5b 48 31 32 38 30 38 5d 20  12807] [H12808] 
18540 5b 48 31 32 38 30 39 5d 0a 2a 2f 0a 69 6e 74 20  [H12809].*/.int 
18550 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28  sqlite3_errcode(
18560 73 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a 69 6e  sqlite3 *db);.in
18570 74 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64  t sqlite3_extend
18580 65 64 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 74  ed_errcode(sqlit
18590 65 33 20 2a 64 62 29 3b 0a 63 6f 6e 73 74 20 63  e3 *db);.const c
185a0 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 65 72 72  har *sqlite3_err
185b0 6d 73 67 28 73 71 6c 69 74 65 33 2a 29 3b 0a 63  msg(sqlite3*);.c
185c0 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
185d0 65 33 5f 65 72 72 6d 73 67 31 36 28 73 71 6c 69  e3_errmsg16(sqli
185e0 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  te3*);../*.** CA
185f0 50 49 33 52 45 46 3a 20 53 51 4c 20 53 74 61 74  PI3REF: SQL Stat
18600 65 6d 65 6e 74 20 4f 62 6a 65 63 74 20 7b 48 31  ement Object {H1
18610 33 30 30 30 7d 20 3c 48 31 33 30 31 30 3e 0a 2a  3000} <H13010>.*
18620 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 65  * KEYWORDS: {pre
18630 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 7d  pared statement}
18640 20 7b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   {prepared state
18650 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20  ments}.**.** An 
18660 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73  instance of this
18670 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e   object represen
18680 74 73 20 61 20 73 69 6e 67 6c 65 20 53 51 4c 20  ts a single SQL 
18690 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 54 68  statement..** Th
186a0 69 73 20 6f 62 6a 65 63 74 20 69 73 20 76 61 72  is object is var
186b0 69 6f 75 73 6c 79 20 6b 6e 6f 77 6e 20 61 73 20  iously known as 
186c0 61 20 22 70 72 65 70 61 72 65 64 20 73 74 61 74  a "prepared stat
186d0 65 6d 65 6e 74 22 20 6f 72 20 61 0a 2a 2a 20 22  ement" or a.** "
186e0 63 6f 6d 70 69 6c 65 64 20 53 51 4c 20 73 74 61  compiled SQL sta
186f0 74 65 6d 65 6e 74 22 20 6f 72 20 73 69 6d 70 6c  tement" or simpl
18700 79 20 61 73 20 61 20 22 73 74 61 74 65 6d 65 6e  y as a "statemen
18710 74 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6c 69  t"..**.** The li
18720 66 65 20 6f 66 20 61 20 73 74 61 74 65 6d 65 6e  fe of a statemen
18730 74 20 6f 62 6a 65 63 74 20 67 6f 65 73 20 73 6f  t object goes so
18740 6d 65 74 68 69 6e 67 20 6c 69 6b 65 20 74 68 69  mething like thi
18750 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a  s:.**.** <ol>.**
18760 20 3c 6c 69 3e 20 43 72 65 61 74 65 20 74 68 65   <li> Create the
18770 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73   object using [s
18780 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
18790 32 28 29 5d 20 6f 72 20 61 20 72 65 6c 61 74 65  2()] or a relate
187a0 64 0a 2a 2a 20 20 20 20 20 20 66 75 6e 63 74 69  d.**      functi
187b0 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e 20 42 69 6e 64  on..** <li> Bind
187c0 20 76 61 6c 75 65 73 20 74 6f 20 5b 68 6f 73 74   values to [host
187d0 20 70 61 72 61 6d 65 74 65 72 73 5d 20 75 73 69   parameters] usi
187e0 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62  ng the sqlite3_b
187f0 69 6e 64 5f 2a 28 29 0a 2a 2a 20 20 20 20 20 20  ind_*().**      
18800 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 3c  interfaces..** <
18810 6c 69 3e 20 52 75 6e 20 74 68 65 20 53 51 4c 20  li> Run the SQL 
18820 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  by calling [sqli
18830 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 6e 65 20  te3_step()] one 
18840 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a  or more times..*
18850 2a 20 3c 6c 69 3e 20 52 65 73 65 74 20 74 68 65  * <li> Reset the
18860 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67   statement using
18870 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
18880 29 5d 20 74 68 65 6e 20 67 6f 20 62 61 63 6b 0a  )] then go back.
18890 2a 2a 20 20 20 20 20 20 74 6f 20 73 74 65 70 20  **      to step 
188a0 32 2e 20 20 44 6f 20 74 68 69 73 20 7a 65 72 6f  2.  Do this zero
188b0 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a   or more times..
188c0 2a 2a 20 3c 6c 69 3e 20 44 65 73 74 72 6f 79 20  ** <li> Destroy 
188d0 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69 6e 67  the object using
188e0 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
188f0 7a 65 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a  ze()]..** </ol>.
18900 2a 2a 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20 64  **.** Refer to d
18910 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 6f 6e 20  ocumentation on 
18920 69 6e 64 69 76 69 64 75 61 6c 20 6d 65 74 68 6f  individual metho
18930 64 73 20 61 62 6f 76 65 20 66 6f 72 20 61 64 64  ds above for add
18940 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72  itional.** infor
18950 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64  mation..*/.typed
18960 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
18970 33 5f 73 74 6d 74 20 73 71 6c 69 74 65 33 5f 73  3_stmt sqlite3_s
18980 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  tmt;../*.** CAPI
18990 33 52 45 46 3a 20 52 75 6e 2d 74 69 6d 65 20 4c  3REF: Run-time L
189a0 69 6d 69 74 73 20 7b 48 31 32 37 36 30 7d 20 3c  imits {H12760} <
189b0 53 32 30 36 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68  S20600>.**.** Th
189c0 69 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c 6c  is interface all
189d0 6f 77 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20  ows the size of 
189e0 76 61 72 69 6f 75 73 20 63 6f 6e 73 74 72 75 63  various construc
189f0 74 73 20 74 6f 20 62 65 20 6c 69 6d 69 74 65 64  ts to be limited
18a00 0a 2a 2a 20 6f 6e 20 61 20 63 6f 6e 6e 65 63 74  .** on a connect
18a10 69 6f 6e 20 62 79 20 63 6f 6e 6e 65 63 74 69 6f  ion by connectio
18a20 6e 20 62 61 73 69 73 2e 20 20 54 68 65 20 66 69  n basis.  The fi
18a30 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73  rst parameter is
18a40 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73   the.** [databas
18a50 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 68  e connection] wh
18a60 6f 73 65 20 6c 69 6d 69 74 20 69 73 20 74 6f 20  ose limit is to 
18a70 62 65 20 73 65 74 20 6f 72 20 71 75 65 72 69 65  be set or querie
18a80 64 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e  d.  The.** secon
18a90 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6f  d parameter is o
18aa0 6e 65 20 6f 66 20 74 68 65 20 5b 6c 69 6d 69 74  ne of the [limit
18ab0 20 63 61 74 65 67 6f 72 69 65 73 5d 20 74 68 61   categories] tha
18ac0 74 20 64 65 66 69 6e 65 20 61 0a 2a 2a 20 63 6c  t define a.** cl
18ad0 61 73 73 20 6f 66 20 63 6f 6e 73 74 72 75 63 74  ass of construct
18ae0 73 20 74 6f 20 62 65 20 73 69 7a 65 20 6c 69 6d  s to be size lim
18af0 69 74 65 64 2e 20 20 54 68 65 20 74 68 69 72 64  ited.  The third
18b00 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
18b10 65 0a 2a 2a 20 6e 65 77 20 6c 69 6d 69 74 20 66  e.** new limit f
18b20 6f 72 20 74 68 61 74 20 63 6f 6e 73 74 72 75 63  or that construc
18b30 74 2e 20 20 54 68 65 20 66 75 6e 63 74 69 6f 6e  t.  The function
18b40 20 72 65 74 75 72 6e 73 20 74 68 65 20 6f 6c 64   returns the old
18b50 20 6c 69 6d 69 74 2e 0a 2a 2a 0a 2a 2a 20 49 66   limit..**.** If
18b60 20 74 68 65 20 6e 65 77 20 6c 69 6d 69 74 20 69   the new limit i
18b70 73 20 61 20 6e 65 67 61 74 69 76 65 20 6e 75 6d  s a negative num
18b80 62 65 72 2c 20 74 68 65 20 6c 69 6d 69 74 20 69  ber, the limit i
18b90 73 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20  s unchanged..** 
18ba0 46 6f 72 20 74 68 65 20 6c 69 6d 69 74 20 63 61  For the limit ca
18bb0 74 65 67 6f 72 79 20 6f 66 20 53 51 4c 49 54 45  tegory of SQLITE
18bc0 5f 4c 49 4d 49 54 5f 58 59 5a 20 74 68 65 72 65  _LIMIT_XYZ there
18bd0 20 69 73 20 61 20 0a 2a 2a 20 5b 6c 69 6d 69 74   is a .** [limit
18be0 73 20 7c 20 68 61 72 64 20 75 70 70 65 72 20 62  s | hard upper b
18bf0 6f 75 6e 64 5d 0a 2a 2a 20 73 65 74 20 62 79 20  ound].** set by 
18c00 61 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 43  a compile-time C
18c10 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61   preprocessor ma
18c20 63 72 6f 20 6e 61 6d 65 64 20 0a 2a 2a 20 5b 6c  cro named .** [l
18c30 69 6d 69 74 73 20 7c 20 53 51 4c 49 54 45 5f 4d  imits | SQLITE_M
18c40 41 58 5f 58 59 5a 5d 2e 0a 2a 2a 20 28 54 68 65  AX_XYZ]..** (The
18c50 20 22 5f 4c 49 4d 49 54 5f 22 20 69 6e 20 74 68   "_LIMIT_" in th
18c60 65 20 6e 61 6d 65 20 69 73 20 63 68 61 6e 67 65  e name is change
18c70 64 20 74 6f 20 22 5f 4d 41 58 5f 22 2e 29 0a 2a  d to "_MAX_".).*
18c80 2a 20 41 74 74 65 6d 70 74 73 20 74 6f 20 69 6e  * Attempts to in
18c90 63 72 65 61 73 65 20 61 20 6c 69 6d 69 74 20 61  crease a limit a
18ca0 62 6f 76 65 20 69 74 73 20 68 61 72 64 20 75 70  bove its hard up
18cb0 70 65 72 20 62 6f 75 6e 64 20 61 72 65 0a 2a 2a  per bound are.**
18cc0 20 73 69 6c 65 6e 74 6c 79 20 74 72 75 6e 63 61   silently trunca
18cd0 74 65 64 20 74 6f 20 74 68 65 20 68 61 72 64 20  ted to the hard 
18ce0 75 70 70 65 72 20 6c 69 6d 69 74 2e 0a 2a 2a 0a  upper limit..**.
18cf0 2a 2a 20 52 75 6e 20 74 69 6d 65 20 6c 69 6d 69  ** Run time limi
18d00 74 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20  ts are intended 
18d10 66 6f 72 20 75 73 65 20 69 6e 20 61 70 70 6c 69  for use in appli
18d20 63 61 74 69 6f 6e 73 20 74 68 61 74 20 6d 61 6e  cations that man
18d30 61 67 65 0a 2a 2a 20 62 6f 74 68 20 74 68 65 69  age.** both thei
18d40 72 20 6f 77 6e 20 69 6e 74 65 72 6e 61 6c 20 64  r own internal d
18d50 61 74 61 62 61 73 65 20 61 6e 64 20 61 6c 73 6f  atabase and also
18d60 20 64 61 74 61 62 61 73 65 73 20 74 68 61 74 20   databases that 
18d70 61 72 65 20 63 6f 6e 74 72 6f 6c 6c 65 64 0a 2a  are controlled.*
18d80 2a 20 62 79 20 75 6e 74 72 75 73 74 65 64 20 65  * by untrusted e
18d90 78 74 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 2e  xternal sources.
18da0 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 61 70 70    An example app
18db0 6c 69 63 61 74 69 6f 6e 20 6d 69 67 68 74 20 62  lication might b
18dc0 65 20 61 0a 2a 2a 20 77 65 62 20 62 72 6f 77 73  e a.** web brows
18dd0 65 72 20 74 68 61 74 20 68 61 73 20 69 74 73 20  er that has its 
18de0 6f 77 6e 20 64 61 74 61 62 61 73 65 73 20 66 6f  own databases fo
18df0 72 20 73 74 6f 72 69 6e 67 20 68 69 73 74 6f 72  r storing histor
18e00 79 20 61 6e 64 0a 2a 2a 20 73 65 70 61 72 61 74  y and.** separat
18e10 65 20 64 61 74 61 62 61 73 65 73 20 63 6f 6e 74  e databases cont
18e20 72 6f 6c 6c 65 64 20 62 79 20 4a 61 76 61 53 63  rolled by JavaSc
18e30 72 69 70 74 20 61 70 70 6c 69 63 61 74 69 6f 6e  ript application
18e40 73 20 64 6f 77 6e 6c 6f 61 64 65 64 0a 2a 2a 20  s downloaded.** 
18e50 6f 66 66 20 74 68 65 20 49 6e 74 65 72 6e 65 74  off the Internet
18e60 2e 20 20 54 68 65 20 69 6e 74 65 72 6e 61 6c 20  .  The internal 
18e70 64 61 74 61 62 61 73 65 73 20 63 61 6e 20 62 65  databases can be
18e80 20 67 69 76 65 6e 20 74 68 65 0a 2a 2a 20 6c 61   given the.** la
18e90 72 67 65 2c 20 64 65 66 61 75 6c 74 20 6c 69 6d  rge, default lim
18ea0 69 74 73 2e 20 20 44 61 74 61 62 61 73 65 73 20  its.  Databases 
18eb0 6d 61 6e 61 67 65 64 20 62 79 20 65 78 74 65 72  managed by exter
18ec0 6e 61 6c 20 73 6f 75 72 63 65 73 20 63 61 6e 0a  nal sources can.
18ed0 2a 2a 20 62 65 20 67 69 76 65 6e 20 6d 75 63 68  ** be given much
18ee0 20 73 6d 61 6c 6c 65 72 20 6c 69 6d 69 74 73 20   smaller limits 
18ef0 64 65 73 69 67 6e 65 64 20 74 6f 20 70 72 65 76  designed to prev
18f00 65 6e 74 20 61 20 64 65 6e 69 61 6c 20 6f 66 20  ent a denial of 
18f10 73 65 72 76 69 63 65 0a 2a 2a 20 61 74 74 61 63  service.** attac
18f20 6b 2e 20 20 44 65 76 65 6c 6f 70 65 72 73 20 6d  k.  Developers m
18f30 69 67 68 74 20 61 6c 73 6f 20 77 61 6e 74 20 74  ight also want t
18f40 6f 20 75 73 65 20 74 68 65 20 5b 73 71 6c 69 74  o use the [sqlit
18f50 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
18f60 72 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63  r()].** interfac
18f70 65 20 74 6f 20 66 75 72 74 68 65 72 20 63 6f 6e  e to further con
18f80 74 72 6f 6c 20 75 6e 74 72 75 73 74 65 64 20 53  trol untrusted S
18f90 51 4c 2e 20 20 54 68 65 20 73 69 7a 65 20 6f 66  QL.  The size of
18fa0 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a   the database.**
18fb0 20 63 72 65 61 74 65 64 20 62 79 20 61 6e 20 75   created by an u
18fc0 6e 74 72 75 73 74 65 64 20 73 63 72 69 70 74 20  ntrusted script 
18fd0 63 61 6e 20 62 65 20 63 6f 6e 74 61 69 6e 65 64  can be contained
18fe0 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 6d   using the.** [m
18ff0 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b  ax_page_count] [
19000 50 52 41 47 4d 41 5d 2e 0a 2a 2a 0a 2a 2a 20 4e  PRAGMA]..**.** N
19010 65 77 20 72 75 6e 2d 74 69 6d 65 20 6c 69 6d 69  ew run-time limi
19020 74 20 63 61 74 65 67 6f 72 69 65 73 20 6d 61 79  t categories may
19030 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74   be added in fut
19040 75 72 65 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2a  ure releases..**
19050 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73  .** Requirements
19060 3a 0a 2a 2a 20 5b 48 31 32 37 36 32 5d 20 5b 48  :.** [H12762] [H
19070 31 32 37 36 36 5d 20 5b 48 31 32 37 36 39 5d 0a  12766] [H12769].
19080 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c  */.int sqlite3_l
19090 69 6d 69 74 28 73 71 6c 69 74 65 33 2a 2c 20 69  imit(sqlite3*, i
190a0 6e 74 20 69 64 2c 20 69 6e 74 20 6e 65 77 56 61  nt id, int newVa
190b0 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  l);../*.** CAPI3
190c0 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69  REF: Run-Time Li
190d0 6d 69 74 20 43 61 74 65 67 6f 72 69 65 73 20 7b  mit Categories {
190e0 48 31 32 37 39 30 7d 20 3c 48 31 32 37 36 30 3e  H12790} <H12760>
190f0 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 6c  .** KEYWORDS: {l
19100 69 6d 69 74 20 63 61 74 65 67 6f 72 79 7d 20 7b  imit category} {
19110 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73  limit categories
19120 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f  }.**.** These co
19130 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20 76  nstants define v
19140 61 72 69 6f 75 73 20 70 65 72 66 6f 72 6d 61 6e  arious performan
19150 63 65 20 6c 69 6d 69 74 73 0a 2a 2a 20 74 68 61  ce limits.** tha
19160 74 20 63 61 6e 20 62 65 20 6c 6f 77 65 72 65 64  t can be lowered
19170 20 61 74 20 72 75 6e 2d 74 69 6d 65 20 75 73 69   at run-time usi
19180 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69  ng [sqlite3_limi
19190 74 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 79 6e  t()]..** The syn
191a0 6f 70 73 69 73 20 6f 66 20 74 68 65 20 6d 65 61  opsis of the mea
191b0 6e 69 6e 67 73 20 6f 66 20 74 68 65 20 76 61 72  nings of the var
191c0 69 6f 75 73 20 6c 69 6d 69 74 73 20 69 73 20 73  ious limits is s
191d0 68 6f 77 6e 20 62 65 6c 6f 77 2e 0a 2a 2a 20 41  hown below..** A
191e0 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d  dditional inform
191f0 61 74 69 6f 6e 20 69 73 20 61 76 61 69 6c 61 62  ation is availab
19200 6c 65 20 61 74 20 5b 6c 69 6d 69 74 73 20 7c 20  le at [limits | 
19210 4c 69 6d 69 74 73 20 69 6e 20 53 51 4c 69 74 65  Limits in SQLite
19220 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a  ]..**.** <dl>.**
19230 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49   <dt>SQLITE_LIMI
19240 54 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a  T_LENGTH</dt>.**
19250 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
19260 20 73 69 7a 65 20 6f 66 20 61 6e 79 20 73 74 72   size of any str
19270 69 6e 67 20 6f 72 20 42 4c 4f 42 20 6f 72 20 74  ing or BLOB or t
19280 61 62 6c 65 20 72 6f 77 2e 3c 64 64 3e 0a 2a 2a  able row.<dd>.**
19290 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  .** <dt>SQLITE_L
192a0 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 3c  IMIT_SQL_LENGTH<
192b0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
192c0 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  maximum length o
192d0 66 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  f an SQL stateme
192e0 6e 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  nt.</dd>.**.** <
192f0 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
19300 43 4f 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c  COLUMN</dt>.** <
19310 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e  dd>The maximum n
19320 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
19330 20 69 6e 20 61 20 74 61 62 6c 65 20 64 65 66 69   in a table defi
19340 6e 69 74 69 6f 6e 20 6f 72 20 69 6e 20 74 68 65  nition or in the
19350 0a 2a 2a 20 72 65 73 75 6c 74 20 73 65 74 20 6f  .** result set o
19360 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 6f 72 20  f a [SELECT] or 
19370 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  the maximum numb
19380 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e  er of columns in
19390 20 61 6e 20 69 6e 64 65 78 0a 2a 2a 20 6f 72 20   an index.** or 
193a0 69 6e 20 61 6e 20 4f 52 44 45 52 20 42 59 20 6f  in an ORDER BY o
193b0 72 20 47 52 4f 55 50 20 42 59 20 63 6c 61 75 73  r GROUP BY claus
193c0 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  e.</dd>.**.** <d
193d0 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45  t>SQLITE_LIMIT_E
193e0 58 50 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a  XPR_DEPTH</dt>.*
193f0 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
19400 6d 20 64 65 70 74 68 20 6f 66 20 74 68 65 20 70  m depth of the p
19410 61 72 73 65 20 74 72 65 65 20 6f 6e 20 61 6e 79  arse tree on any
19420 20 65 78 70 72 65 73 73 69 6f 6e 2e 3c 2f 64 64   expression.</dd
19430 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
19440 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e  TE_LIMIT_COMPOUN
19450 44 5f 53 45 4c 45 43 54 3c 2f 64 74 3e 0a 2a 2a  D_SELECT</dt>.**
19460 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
19470 20 6e 75 6d 62 65 72 20 6f 66 20 74 65 72 6d 73   number of terms
19480 20 69 6e 20 61 20 63 6f 6d 70 6f 75 6e 64 20 53   in a compound S
19490 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74 2e  ELECT statement.
194a0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
194b0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42  SQLITE_LIMIT_VDB
194c0 45 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  E_OP</dt>.** <dd
194d0 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  >The maximum num
194e0 62 65 72 20 6f 66 20 69 6e 73 74 72 75 63 74 69  ber of instructi
194f0 6f 6e 73 20 69 6e 20 61 20 76 69 72 74 75 61 6c  ons in a virtual
19500 20 6d 61 63 68 69 6e 65 20 70 72 6f 67 72 61 6d   machine program
19510 0a 2a 2a 20 75 73 65 64 20 74 6f 20 69 6d 70 6c  .** used to impl
19520 65 6d 65 6e 74 20 61 6e 20 53 51 4c 20 73 74 61  ement an SQL sta
19530 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a  tement.</dd>.**.
19540 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49  ** <dt>SQLITE_LI
19550 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47  MIT_FUNCTION_ARG
19560 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
19570 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
19580 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 6f 6e 20  of arguments on 
19590 61 20 66 75 6e 63 74 69 6f 6e 2e 3c 2f 64 64 3e  a function.</dd>
195a0 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
195b0 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44  E_LIMIT_ATTACHED
195c0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
195d0 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
195e0 6f 66 20 5b 41 54 54 41 43 48 20 7c 20 61 74 74  of [ATTACH | att
195f0 61 63 68 65 64 20 64 61 74 61 62 61 73 65 73 5d  ached databases]
19600 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74  .</dd>.**.** <dt
19610 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49  >SQLITE_LIMIT_LI
19620 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54  KE_PATTERN_LENGT
19630 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  H</dt>.** <dd>Th
19640 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  e maximum length
19650 20 6f 66 20 74 68 65 20 70 61 74 74 65 72 6e 20   of the pattern 
19660 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
19670 5b 4c 49 4b 45 5d 20 6f 72 0a 2a 2a 20 5b 47 4c  [LIKE] or.** [GL
19680 4f 42 5d 20 6f 70 65 72 61 74 6f 72 73 2e 3c 2f  OB] operators.</
19690 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51  dd>.**.** <dt>SQ
196a0 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41  LITE_LIMIT_VARIA
196b0 42 4c 45 5f 4e 55 4d 42 45 52 3c 2f 64 74 3e 0a  BLE_NUMBER</dt>.
196c0 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
196d0 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 76 61 72  um number of var
196e0 69 61 62 6c 65 73 20 69 6e 20 61 6e 20 53 51 4c  iables in an SQL
196f0 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20   statement that 
19700 63 61 6e 0a 2a 2a 20 62 65 20 62 6f 75 6e 64 2e  can.** be bound.
19710 3c 2f 64 64 3e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a  </dd>.** </dl>.*
19720 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
19730 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 20 20 20  _LIMIT_LENGTH   
19740 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
19750 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   0.#define SQLIT
19760 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47  E_LIMIT_SQL_LENG
19770 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20  TH              
19780 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    1.#define SQLI
19790 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 20  TE_LIMIT_COLUMN 
197a0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
197b0 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c     2.#define SQL
197c0 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44  ITE_LIMIT_EXPR_D
197d0 45 50 54 48 20 20 20 20 20 20 20 20 20 20 20 20  EPTH            
197e0 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51      3.#define SQ
197f0 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f  LITE_LIMIT_COMPO
19800 55 4e 44 5f 53 45 4c 45 43 54 20 20 20 20 20 20  UND_SELECT      
19810 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53       4.#define S
19820 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45  QLITE_LIMIT_VDBE
19830 5f 4f 50 20 20 20 20 20 20 20 20 20 20 20 20 20  _OP             
19840 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e 65 20        5.#define 
19850 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e  SQLITE_LIMIT_FUN
19860 43 54 49 4f 4e 5f 41 52 47 20 20 20 20 20 20 20  CTION_ARG       
19870 20 20 20 20 20 20 20 36 0a 23 64 65 66 69 6e 65         6.#define
19880 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54   SQLITE_LIMIT_AT
19890 54 41 43 48 45 44 20 20 20 20 20 20 20 20 20 20  TACHED          
198a0 20 20 20 20 20 20 20 20 37 0a 23 64 65 66 69 6e          7.#defin
198b0 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c  e SQLITE_LIMIT_L
198c0 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47  IKE_PATTERN_LENG
198d0 54 48 20 20 20 20 20 20 20 38 0a 23 64 65 66 69  TH       8.#defi
198e0 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
198f0 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 20  VARIABLE_NUMBER 
19900 20 20 20 20 20 20 20 20 20 20 39 0a 0a 2f 2a 0a            9../*.
19910 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d  ** CAPI3REF: Com
19920 70 69 6c 69 6e 67 20 41 6e 20 53 51 4c 20 53 74  piling An SQL St
19930 61 74 65 6d 65 6e 74 20 7b 48 31 33 30 31 30 7d  atement {H13010}
19940 20 3c 53 31 30 30 30 30 3e 0a 2a 2a 20 4b 45 59   <S10000>.** KEY
19950 57 4f 52 44 53 3a 20 7b 53 51 4c 20 73 74 61 74  WORDS: {SQL stat
19960 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 72 7d 0a  ement compiler}.
19970 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65 63 75 74 65  **.** To execute
19980 20 61 6e 20 53 51 4c 20 71 75 65 72 79 2c 20 69   an SQL query, i
19990 74 20 6d 75 73 74 20 66 69 72 73 74 20 62 65 20  t must first be 
199a0 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20 61 20  compiled into a 
199b0 62 79 74 65 2d 63 6f 64 65 0a 2a 2a 20 70 72 6f  byte-code.** pro
199c0 67 72 61 6d 20 75 73 69 6e 67 20 6f 6e 65 20 6f  gram using one o
199d0 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
199e0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73  ..**.** The firs
199f0 74 20 61 72 67 75 6d 65 6e 74 2c 20 22 64 62 22  t argument, "db"
19a00 2c 20 69 73 20 61 20 5b 64 61 74 61 62 61 73 65  , is a [database
19a10 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62 74   connection] obt
19a20 61 69 6e 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20  ained from a.** 
19a30 70 72 69 6f 72 20 73 75 63 63 65 73 73 66 75 6c  prior successful
19a40 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
19a50 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69  3_open()], [sqli
19a60 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 6f  te3_open_v2()] o
19a70 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70  r.** [sqlite3_op
19a80 65 6e 31 36 28 29 5d 2e 20 20 54 68 65 20 64 61  en16()].  The da
19a90 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
19aa0 6e 20 6d 75 73 74 20 6e 6f 74 20 68 61 76 65 20  n must not have 
19ab0 62 65 65 6e 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a  been closed..**.
19ac0 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72  ** The second ar
19ad0 67 75 6d 65 6e 74 2c 20 22 7a 53 71 6c 22 2c 20  gument, "zSql", 
19ae0 69 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  is the statement
19af0 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 2c   to be compiled,
19b00 20 65 6e 63 6f 64 65 64 0a 2a 2a 20 61 73 20 65   encoded.** as e
19b10 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55  ither UTF-8 or U
19b20 54 46 2d 31 36 2e 20 20 54 68 65 20 73 71 6c 69  TF-16.  The sqli
19b30 74 65 33 5f 70 72 65 70 61 72 65 28 29 20 61 6e  te3_prepare() an
19b40 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  d sqlite3_prepar
19b50 65 5f 76 32 28 29 0a 2a 2a 20 69 6e 74 65 72 66  e_v2().** interf
19b60 61 63 65 73 20 75 73 65 20 55 54 46 2d 38 2c 20  aces use UTF-8, 
19b70 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70  and sqlite3_prep
19b80 61 72 65 31 36 28 29 20 61 6e 64 20 73 71 6c 69  are16() and sqli
19b90 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
19ba0 28 29 0a 2a 2a 20 75 73 65 20 55 54 46 2d 31 36  ().** use UTF-16
19bb0 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 6e  ..**.** If the n
19bc0 42 79 74 65 20 61 72 67 75 6d 65 6e 74 20 69 73  Byte argument is
19bd0 20 6c 65 73 73 20 74 68 61 6e 20 7a 65 72 6f 2c   less than zero,
19be0 20 74 68 65 6e 20 7a 53 71 6c 20 69 73 20 72 65   then zSql is re
19bf0 61 64 20 75 70 20 74 6f 20 74 68 65 0a 2a 2a 20  ad up to the.** 
19c00 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69  first zero termi
19c10 6e 61 74 6f 72 2e 20 49 66 20 6e 42 79 74 65 20  nator. If nByte 
19c20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c  is non-negative,
19c30 20 74 68 65 6e 20 69 74 20 69 73 20 74 68 65 20   then it is the 
19c40 6d 61 78 69 6d 75 6d 0a 2a 2a 20 6e 75 6d 62 65  maximum.** numbe
19c50 72 20 6f 66 20 20 62 79 74 65 73 20 72 65 61 64  r of  bytes read
19c60 20 66 72 6f 6d 20 7a 53 71 6c 2e 20 20 57 68 65   from zSql.  Whe
19c70 6e 20 6e 42 79 74 65 20 69 73 20 6e 6f 6e 2d 6e  n nByte is non-n
19c80 65 67 61 74 69 76 65 2c 20 74 68 65 0a 2a 2a 20  egative, the.** 
19c90 7a 53 71 6c 20 73 74 72 69 6e 67 20 65 6e 64 73  zSql string ends
19ca0 20 61 74 20 65 69 74 68 65 72 20 74 68 65 20 66   at either the f
19cb0 69 72 73 74 20 27 5c 30 30 30 27 20 6f 72 20 27  irst '\000' or '
19cc0 5c 75 30 30 30 30 27 20 63 68 61 72 61 63 74 65  \u0000' characte
19cd0 72 20 6f 72 0a 2a 2a 20 74 68 65 20 6e 42 79 74  r or.** the nByt
19ce0 65 2d 74 68 20 62 79 74 65 2c 20 77 68 69 63 68  e-th byte, which
19cf0 65 76 65 72 20 63 6f 6d 65 73 20 66 69 72 73 74  ever comes first
19d00 2e 20 49 66 20 74 68 65 20 63 61 6c 6c 65 72 20  . If the caller 
19d10 6b 6e 6f 77 73 0a 2a 2a 20 74 68 61 74 20 74 68  knows.** that th
19d20 65 20 73 75 70 70 6c 69 65 64 20 73 74 72 69 6e  e supplied strin
19d30 67 20 69 73 20 6e 75 6c 2d 74 65 72 6d 69 6e 61  g is nul-termina
19d40 74 65 64 2c 20 74 68 65 6e 20 74 68 65 72 65 20  ted, then there 
19d50 69 73 20 61 20 73 6d 61 6c 6c 0a 2a 2a 20 70 65  is a small.** pe
19d60 72 66 6f 72 6d 61 6e 63 65 20 61 64 76 61 6e 74  rformance advant
19d70 61 67 65 20 74 6f 20 62 65 20 67 61 69 6e 65 64  age to be gained
19d80 20 62 79 20 70 61 73 73 69 6e 67 20 61 6e 20 6e   by passing an n
19d90 42 79 74 65 20 70 61 72 61 6d 65 74 65 72 20 74  Byte parameter t
19da0 68 61 74 0a 2a 2a 20 69 73 20 65 71 75 61 6c 20  hat.** is equal 
19db0 74 6f 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  to the number of
19dc0 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 69 6e   bytes in the in
19dd0 70 75 74 20 73 74 72 69 6e 67 20 3c 69 3e 69 6e  put string <i>in
19de0 63 6c 75 64 69 6e 67 3c 2f 69 3e 0a 2a 2a 20 74  cluding</i>.** t
19df0 68 65 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 6f  he nul-terminato
19e00 72 20 62 79 74 65 73 2e 0a 2a 2a 0a 2a 2a 20 49  r bytes..**.** I
19e10 66 20 70 7a 54 61 69 6c 20 69 73 20 6e 6f 74 20  f pzTail is not 
19e20 4e 55 4c 4c 20 74 68 65 6e 20 2a 70 7a 54 61 69  NULL then *pzTai
19e30 6c 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69  l is made to poi
19e40 6e 74 20 74 6f 20 74 68 65 20 66 69 72 73 74 20  nt to the first 
19e50 62 79 74 65 0a 2a 2a 20 70 61 73 74 20 74 68 65  byte.** past the
19e60 20 65 6e 64 20 6f 66 20 74 68 65 20 66 69 72 73   end of the firs
19e70 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  t SQL statement 
19e80 69 6e 20 7a 53 71 6c 2e 20 20 54 68 65 73 65 20  in zSql.  These 
19e90 72 6f 75 74 69 6e 65 73 20 6f 6e 6c 79 0a 2a 2a  routines only.**
19ea0 20 63 6f 6d 70 69 6c 65 20 74 68 65 20 66 69 72   compile the fir
19eb0 73 74 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20  st statement in 
19ec0 7a 53 71 6c 2c 20 73 6f 20 2a 70 7a 54 61 69 6c  zSql, so *pzTail
19ed0 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e   is left pointin
19ee0 67 20 74 6f 0a 2a 2a 20 77 68 61 74 20 72 65 6d  g to.** what rem
19ef0 61 69 6e 73 20 75 6e 63 6f 6d 70 69 6c 65 64 2e  ains uncompiled.
19f00 0a 2a 2a 0a 2a 2a 20 2a 70 70 53 74 6d 74 20 69  .**.** *ppStmt i
19f10 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20  s left pointing 
19f20 74 6f 20 61 20 63 6f 6d 70 69 6c 65 64 20 5b 70  to a compiled [p
19f30 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
19f40 74 5d 20 74 68 61 74 20 63 61 6e 20 62 65 0a 2a  t] that can be.*
19f50 2a 20 65 78 65 63 75 74 65 64 20 75 73 69 6e 67  * executed using
19f60 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
19f70 5d 2e 20 20 49 66 20 74 68 65 72 65 20 69 73 20  ].  If there is 
19f80 61 6e 20 65 72 72 6f 72 2c 20 2a 70 70 53 74 6d  an error, *ppStm
19f90 74 20 69 73 20 73 65 74 0a 2a 2a 20 74 6f 20 4e  t is set.** to N
19fa0 55 4c 4c 2e 20 20 49 66 20 74 68 65 20 69 6e 70  ULL.  If the inp
19fb0 75 74 20 74 65 78 74 20 63 6f 6e 74 61 69 6e 73  ut text contains
19fc0 20 6e 6f 20 53 51 4c 20 28 69 66 20 74 68 65 20   no SQL (if the 
19fd0 69 6e 70 75 74 20 69 73 20 61 6e 20 65 6d 70 74  input is an empt
19fe0 79 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 72 20 61  y.** string or a
19ff0 20 63 6f 6d 6d 65 6e 74 29 20 74 68 65 6e 20 2a   comment) then *
1a000 70 70 53 74 6d 74 20 69 73 20 73 65 74 20 74 6f  ppStmt is set to
1a010 20 4e 55 4c 4c 2e 0a 2a 2a 20 54 68 65 20 63 61   NULL..** The ca
1a020 6c 6c 69 6e 67 20 70 72 6f 63 65 64 75 72 65 20  lling procedure 
1a030 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66  is responsible f
1a040 6f 72 20 64 65 6c 65 74 69 6e 67 20 74 68 65 20  or deleting the 
1a050 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 53 51 4c 20  compiled.** SQL 
1a060 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20  statement using 
1a070 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
1a080 65 28 29 5d 20 61 66 74 65 72 20 69 74 20 68 61  e()] after it ha
1a090 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20  s finished with 
1a0a0 69 74 2e 0a 2a 2a 20 70 70 53 74 6d 74 20 6d 61  it..** ppStmt ma
1a0b0 79 20 6e 6f 74 20 62 65 20 4e 55 4c 4c 2e 0a 2a  y not be NULL..*
1a0c0 2a 0a 2a 2a 20 4f 6e 20 73 75 63 63 65 73 73 2c  *.** On success,
1a0d0 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20   [SQLITE_OK] is 
1a0e0 72 65 74 75 72 6e 65 64 2c 20 6f 74 68 65 72 77  returned, otherw
1a0f0 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f  ise an [error co
1a100 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e  de] is returned.
1a110 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
1a120 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20  e3_prepare_v2() 
1a130 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70  and sqlite3_prep
1a140 61 72 65 31 36 5f 76 32 28 29 20 69 6e 74 65 72  are16_v2() inter
1a150 66 61 63 65 73 20 61 72 65 0a 2a 2a 20 72 65 63  faces are.** rec
1a160 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 61 6c 6c  ommended for all
1a170 20 6e 65 77 20 70 72 6f 67 72 61 6d 73 2e 20 54   new programs. T
1a180 68 65 20 74 77 6f 20 6f 6c 64 65 72 20 69 6e 74  he two older int
1a190 65 72 66 61 63 65 73 20 61 72 65 20 72 65 74 61  erfaces are reta
1a1a0 69 6e 65 64 0a 2a 2a 20 66 6f 72 20 62 61 63 6b  ined.** for back
1a1b0 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c  wards compatibil
1a1c0 69 74 79 2c 20 62 75 74 20 74 68 65 69 72 20 75  ity, but their u
1a1d0 73 65 20 69 73 20 64 69 73 63 6f 75 72 61 67 65  se is discourage
1a1e0 64 2e 0a 2a 2a 20 49 6e 20 74 68 65 20 22 76 32  d..** In the "v2
1a1f0 22 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68  " interfaces, th
1a200 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  e prepared state
1a210 6d 65 6e 74 0a 2a 2a 20 74 68 61 74 20 69 73 20  ment.** that is 
1a220 72 65 74 75 72 6e 65 64 20 28 74 68 65 20 5b 73  returned (the [s
1a230 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a  qlite3_stmt] obj
1a240 65 63 74 29 20 63 6f 6e 74 61 69 6e 73 20 61 20  ect) contains a 
1a250 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 6f  copy of the.** o
1a260 72 69 67 69 6e 61 6c 20 53 51 4c 20 74 65 78 74  riginal SQL text
1a270 2e 20 54 68 69 73 20 63 61 75 73 65 73 20 74 68  . This causes th
1a280 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  e [sqlite3_step(
1a290 29 5d 20 69 6e 74 65 72 66 61 63 65 20 74 6f 0a  )] interface to.
1a2a0 2a 2a 20 62 65 68 61 76 65 20 61 20 64 69 66 66  ** behave a diff
1a2b0 65 72 65 6e 74 6c 79 20 69 6e 20 74 77 6f 20 77  erently in two w
1a2c0 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a  ays:.**.** <ol>.
1a2d0 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 49 66 20 74 68  ** <li>.** If th
1a2e0 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d  e database schem
1a2f0 61 20 63 68 61 6e 67 65 73 2c 20 69 6e 73 74 65  a changes, inste
1a300 61 64 20 6f 66 20 72 65 74 75 72 6e 69 6e 67 20  ad of returning 
1a310 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20  [SQLITE_SCHEMA] 
1a320 61 73 20 69 74 0a 2a 2a 20 61 6c 77 61 79 73 20  as it.** always 
1a330 75 73 65 64 20 74 6f 20 64 6f 2c 20 5b 73 71 6c  used to do, [sql
1a340 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c  ite3_step()] wil
1a350 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  l automatically 
1a360 72 65 63 6f 6d 70 69 6c 65 20 74 68 65 20 53 51  recompile the SQ
1a370 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 61  L.** statement a
1a380 6e 64 20 74 72 79 20 74 6f 20 72 75 6e 20 69 74  nd try to run it
1a390 20 61 67 61 69 6e 2e 20 20 49 66 20 74 68 65 20   again.  If the 
1a3a0 73 63 68 65 6d 61 20 68 61 73 20 63 68 61 6e 67  schema has chang
1a3b0 65 64 20 69 6e 0a 2a 2a 20 61 20 77 61 79 20 74  ed in.** a way t
1a3c0 68 61 74 20 6d 61 6b 65 73 20 74 68 65 20 73 74  hat makes the st
1a3d0 61 74 65 6d 65 6e 74 20 6e 6f 20 6c 6f 6e 67 65  atement no longe
1a3e0 72 20 76 61 6c 69 64 2c 20 5b 73 71 6c 69 74 65  r valid, [sqlite
1a3f0 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 73  3_step()] will s
1a400 74 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b  till.** return [
1a410 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 2e 20  SQLITE_SCHEMA]. 
1a420 20 42 75 74 20 75 6e 6c 69 6b 65 20 74 68 65 20   But unlike the 
1a430 6c 65 67 61 63 79 20 62 65 68 61 76 69 6f 72 2c  legacy behavior,
1a440 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d   [SQLITE_SCHEMA]
1a450 20 69 73 0a 2a 2a 20 6e 6f 77 20 61 20 66 61 74   is.** now a fat
1a460 61 6c 20 65 72 72 6f 72 2e 20 20 43 61 6c 6c 69  al error.  Calli
1a470 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ng [sqlite3_prep
1a480 61 72 65 5f 76 32 28 29 5d 20 61 67 61 69 6e 20  are_v2()] again 
1a490 77 69 6c 6c 20 6e 6f 74 20 6d 61 6b 65 20 74 68  will not make th
1a4a0 65 0a 2a 2a 20 65 72 72 6f 72 20 67 6f 20 61 77  e.** error go aw
1a4b0 61 79 2e 20 20 4e 6f 74 65 3a 20 75 73 65 20 5b  ay.  Note: use [
1a4c0 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29  sqlite3_errmsg()
1a4d0 5d 20 74 6f 20 66 69 6e 64 20 74 68 65 20 74 65  ] to find the te
1a4e0 78 74 0a 2a 2a 20 6f 66 20 74 68 65 20 70 61 72  xt.** of the par
1a4f0 73 69 6e 67 20 65 72 72 6f 72 20 74 68 61 74 20  sing error that 
1a500 72 65 73 75 6c 74 73 20 69 6e 20 61 6e 20 5b 53  results in an [S
1a510 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20 72 65  QLITE_SCHEMA] re
1a520 74 75 72 6e 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a  turn..** </li>.*
1a530 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 57 68 65  *.** <li>.** Whe
1a540 6e 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72  n an error occur
1a550 73 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  s, [sqlite3_step
1a560 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  ()] will return 
1a570 6f 6e 65 20 6f 66 20 74 68 65 20 64 65 74 61 69  one of the detai
1a580 6c 65 64 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f  led.** [error co
1a590 64 65 73 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65  des] or [extende
1a5a0 64 20 65 72 72 6f 72 20 63 6f 64 65 73 5d 2e 20  d error codes]. 
1a5b0 20 54 68 65 20 6c 65 67 61 63 79 20 62 65 68 61   The legacy beha
1a5c0 76 69 6f 72 20 77 61 73 20 74 68 61 74 0a 2a 2a  vior was that.**
1a5d0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
1a5e0 5d 20 77 6f 75 6c 64 20 6f 6e 6c 79 20 72 65 74  ] would only ret
1a5f0 75 72 6e 20 61 20 67 65 6e 65 72 69 63 20 5b 53  urn a generic [S
1a600 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 72 65 73  QLITE_ERROR] res
1a610 75 6c 74 20 63 6f 64 65 0a 2a 2a 20 61 6e 64 20  ult code.** and 
1a620 79 6f 75 20 77 6f 75 6c 64 20 68 61 76 65 20 74  you would have t
1a630 6f 20 6d 61 6b 65 20 61 20 73 65 63 6f 6e 64 20  o make a second 
1a640 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
1a650 5f 72 65 73 65 74 28 29 5d 20 69 6e 20 6f 72 64  _reset()] in ord
1a660 65 72 0a 2a 2a 20 74 6f 20 66 69 6e 64 20 74 68  er.** to find th
1a670 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 63 61 75  e underlying cau
1a680 73 65 20 6f 66 20 74 68 65 20 70 72 6f 62 6c 65  se of the proble
1a690 6d 2e 20 57 69 74 68 20 74 68 65 20 22 76 32 22  m. With the "v2"
1a6a0 20 70 72 65 70 61 72 65 0a 2a 2a 20 69 6e 74 65   prepare.** inte
1a6b0 72 66 61 63 65 73 2c 20 74 68 65 20 75 6e 64 65  rfaces, the unde
1a6c0 72 6c 79 69 6e 67 20 72 65 61 73 6f 6e 20 66 6f  rlying reason fo
1a6d0 72 20 74 68 65 20 65 72 72 6f 72 20 69 73 20 72  r the error is r
1a6e0 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74  eturned immediat
1a6f0 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a  ely..** </li>.**
1a700 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 52 65 71   </ol>.**.** Req
1a710 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48  uirements:.** [H
1a720 31 33 30 31 31 5d 20 5b 48 31 33 30 31 32 5d 20  13011] [H13012] 
1a730 5b 48 31 33 30 31 33 5d 20 5b 48 31 33 30 31 34  [H13013] [H13014
1a740 5d 20 5b 48 31 33 30 31 35 5d 20 5b 48 31 33 30  ] [H13015] [H130
1a750 31 36 5d 20 5b 48 31 33 30 31 39 5d 20 5b 48 31  16] [H13019] [H1
1a760 33 30 32 31 5d 0a 2a 2a 0a 2a 2f 0a 69 6e 74 20  3021].**.*/.int 
1a770 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
1a780 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
1a790 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61             /* Da
1a7a0 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f  tabase handle */
1a7b0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
1a7c0 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51  Sql,       /* SQ
1a7d0 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46  L statement, UTF
1a7e0 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20  -8 encoded */.  
1a7f0 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20  int nByte,      
1a800 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d          /* Maxim
1a810 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71  um length of zSq
1a820 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20  l in bytes. */. 
1a830 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a   sqlite3_stmt **
1a840 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a  ppStmt,  /* OUT:
1a850 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c   Statement handl
1a860 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
1a870 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f  r **pzTail     /
1a880 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74  * OUT: Pointer t
1a890 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e  o unused portion
1a8a0 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69   of zSql */.);.i
1a8b0 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nt sqlite3_prepa
1a8c0 72 65 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33  re_v2(.  sqlite3
1a8d0 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
1a8e0 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e   /* Database han
1a8f0 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  dle */.  const c
1a900 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20  har *zSql,      
1a910 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   /* SQL statemen
1a920 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64  t, UTF-8 encoded
1a930 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c   */.  int nByte,
1a940 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
1a950 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   Maximum length 
1a960 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73  of zSql in bytes
1a970 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73  . */.  sqlite3_s
1a980 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f  tmt **ppStmt,  /
1a990 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74  * OUT: Statement
1a9a0 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
1a9b0 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c  st char **pzTail
1a9c0 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69       /* OUT: Poi
1a9d0 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70  nter to unused p
1a9e0 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a  ortion of zSql *
1a9f0 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  /.);.int sqlite3
1aa00 5f 70 72 65 70 61 72 65 31 36 28 0a 20 20 73 71  _prepare16(.  sq
1aa10 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
1aa20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
1aa30 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  e handle */.  co
1aa40 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20  nst void *zSql, 
1aa50 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61        /* SQL sta
1aa60 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65  tement, UTF-16 e
1aa70 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20  ncoded */.  int 
1aa80 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20  nByte,          
1aa90 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c      /* Maximum l
1aaa0 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e  ength of zSql in
1aab0 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c   bytes. */.  sql
1aac0 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74  ite3_stmt **ppSt
1aad0 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61  mt,  /* OUT: Sta
1aae0 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f  tement handle */
1aaf0 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a  .  const void **
1ab00 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55  pzTail     /* OU
1ab10 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e  T: Pointer to un
1ab20 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20  used portion of 
1ab30 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73  zSql */.);.int s
1ab40 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
1ab50 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  _v2(.  sqlite3 *
1ab60 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f  db,            /
1ab70 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c  * Database handl
1ab80 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69  e */.  const voi
1ab90 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f  d *zSql,       /
1aba0 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c  * SQL statement,
1abb0 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20   UTF-16 encoded 
1abc0 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20  */.  int nByte, 
1abd0 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
1abe0 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  Maximum length o
1abf0 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e  f zSql in bytes.
1ac00 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74   */.  sqlite3_st
1ac10 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a  mt **ppStmt,  /*
1ac20 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20   OUT: Statement 
1ac30 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
1ac40 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20  t void **pzTail 
1ac50 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e      /* OUT: Poin
1ac60 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f  ter to unused po
1ac70 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f  rtion of zSql */
1ac80 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
1ac90 52 45 46 3a 20 52 65 74 72 69 65 76 69 6e 67 20  REF: Retrieving 
1aca0 53 74 61 74 65 6d 65 6e 74 20 53 51 4c 20 7b 48  Statement SQL {H
1acb0 31 33 31 30 30 7d 20 3c 48 31 33 30 30 30 3e 0a  13100} <H13000>.
1acc0 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72  **.** This inter
1acd0 66 61 63 65 20 63 61 6e 20 62 65 20 75 73 65 64  face can be used
1ace0 20 74 6f 20 72 65 74 72 69 65 76 65 20 61 20 73   to retrieve a s
1acf0 61 76 65 64 20 63 6f 70 79 20 6f 66 20 74 68 65  aved copy of the
1ad00 20 6f 72 69 67 69 6e 61 6c 0a 2a 2a 20 53 51 4c   original.** SQL
1ad10 20 74 65 78 74 20 75 73 65 64 20 74 6f 20 63 72   text used to cr
1ad20 65 61 74 65 20 61 20 5b 70 72 65 70 61 72 65 64  eate a [prepared
1ad30 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 66 20 74   statement] if t
1ad40 68 61 74 20 73 74 61 74 65 6d 65 6e 74 20 77 61  hat statement wa
1ad50 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 75 73  s.** compiled us
1ad60 69 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69  ing either [sqli
1ad70 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
1ad80 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72  ] or [sqlite3_pr
1ad90 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a  epare16_v2()]..*
1ada0 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74  *.** Requirement
1adb0 73 3a 0a 2a 2a 20 5b 48 31 33 31 30 31 5d 20 5b  s:.** [H13101] [
1adc0 48 31 33 31 30 32 5d 20 5b 48 31 33 31 30 33 5d  H13102] [H13103]
1add0 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  .*/.const char *
1ade0 73 71 6c 69 74 65 33 5f 73 71 6c 28 73 71 6c 69  sqlite3_sql(sqli
1adf0 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29  te3_stmt *pStmt)
1ae00 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1ae10 46 3a 20 44 79 6e 61 6d 69 63 61 6c 6c 79 20 54  F: Dynamically T
1ae20 79 70 65 64 20 56 61 6c 75 65 20 4f 62 6a 65 63  yped Value Objec
1ae30 74 20 7b 48 31 35 30 30 30 7d 20 3c 53 32 30 32  t {H15000} <S202
1ae40 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  00>.** KEYWORDS:
1ae50 20 7b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69   {protected sqli
1ae60 74 65 33 5f 76 61 6c 75 65 7d 20 7b 75 6e 70 72  te3_value} {unpr
1ae70 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
1ae80 76 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c  value}.**.** SQL
1ae90 69 74 65 20 75 73 65 73 20 74 68 65 20 73 71 6c  ite uses the sql
1aea0 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
1aeb0 74 20 74 6f 20 72 65 70 72 65 73 65 6e 74 20 61  t to represent a
1aec0 6c 6c 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61  ll values.** tha
1aed0 74 20 63 61 6e 20 62 65 20 73 74 6f 72 65 64 20  t can be stored 
1aee0 69 6e 20 61 20 64 61 74 61 62 61 73 65 20 74 61  in a database ta
1aef0 62 6c 65 2e 20 53 51 4c 69 74 65 20 75 73 65 73  ble. SQLite uses
1af00 20 64 79 6e 61 6d 69 63 20 74 79 70 69 6e 67 0a   dynamic typing.
1af10 2a 2a 20 66 6f 72 20 74 68 65 20 76 61 6c 75 65  ** for the value
1af20 73 20 69 74 20 73 74 6f 72 65 73 2e 20 56 61 6c  s it stores. Val
1af30 75 65 73 20 73 74 6f 72 65 64 20 69 6e 20 73 71  ues stored in sq
1af40 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
1af50 63 74 73 0a 2a 2a 20 63 61 6e 20 62 65 20 69 6e  cts.** can be in
1af60 74 65 67 65 72 73 2c 20 66 6c 6f 61 74 69 6e 67  tegers, floating
1af70 20 70 6f 69 6e 74 20 76 61 6c 75 65 73 2c 20 73   point values, s
1af80 74 72 69 6e 67 73 2c 20 42 4c 4f 42 73 2c 20 6f  trings, BLOBs, o
1af90 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e  r NULL..**.** An
1afa0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
1afb0 62 6a 65 63 74 20 6d 61 79 20 62 65 20 65 69 74  bject may be eit
1afc0 68 65 72 20 22 70 72 6f 74 65 63 74 65 64 22 20  her "protected" 
1afd0 6f 72 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22  or "unprotected"
1afe0 2e 0a 2a 2a 20 53 6f 6d 65 20 69 6e 74 65 72 66  ..** Some interf
1aff0 61 63 65 73 20 72 65 71 75 69 72 65 20 61 20 70  aces require a p
1b000 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
1b010 5f 76 61 6c 75 65 2e 20 20 4f 74 68 65 72 20 69  _value.  Other i
1b020 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 77 69 6c  nterfaces.** wil
1b030 6c 20 61 63 63 65 70 74 20 65 69 74 68 65 72 20  l accept either 
1b040 61 20 70 72 6f 74 65 63 74 65 64 20 6f 72 20 61  a protected or a
1b050 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71  n unprotected sq
1b060 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 20  lite3_value..** 
1b070 45 76 65 72 79 20 69 6e 74 65 72 66 61 63 65 20  Every interface 
1b080 74 68 61 74 20 61 63 63 65 70 74 73 20 73 71 6c  that accepts sql
1b090 69 74 65 33 5f 76 61 6c 75 65 20 61 72 67 75 6d  ite3_value argum
1b0a0 65 6e 74 73 20 73 70 65 63 69 66 69 65 73 0a 2a  ents specifies.*
1b0b0 2a 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  * whether or not
1b0c0 20 69 74 20 72 65 71 75 69 72 65 73 20 61 20 70   it requires a p
1b0d0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
1b0e0 5f 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  _value..**.** Th
1b0f0 65 20 74 65 72 6d 73 20 22 70 72 6f 74 65 63 74  e terms "protect
1b100 65 64 22 20 61 6e 64 20 22 75 6e 70 72 6f 74 65  ed" and "unprote
1b110 63 74 65 64 22 20 72 65 66 65 72 20 74 6f 20 77  cted" refer to w
1b120 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 0a 2a 2a  hether or not.**
1b130 20 61 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64   a mutex is held
1b140 2e 20 20 41 20 69 6e 74 65 72 6e 61 6c 20 6d 75  .  A internal mu
1b150 74 65 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20  tex is held for 
1b160 61 20 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73  a protected.** s
1b170 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
1b180 65 63 74 20 62 75 74 20 6e 6f 20 6d 75 74 65 78  ect but no mutex
1b190 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61 6e 20   is held for an 
1b1a0 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73  unprotected.** s
1b1b0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
1b1c0 65 63 74 2e 20 20 49 66 20 53 51 4c 69 74 65 20  ect.  If SQLite 
1b1d0 69 73 20 63 6f 6d 70 69 6c 65 64 20 74 6f 20 62  is compiled to b
1b1e0 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 65  e single-threade
1b1f0 64 0a 2a 2a 20 28 77 69 74 68 20 5b 53 51 4c 49  d.** (with [SQLI
1b200 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d  TE_THREADSAFE=0]
1b210 20 61 6e 64 20 77 69 74 68 20 5b 73 71 6c 69 74   and with [sqlit
1b220 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 5d  e3_threadsafe()]
1b230 20 72 65 74 75 72 6e 69 6e 67 20 30 29 0a 2a 2a   returning 0).**
1b240 20 6f 72 20 69 66 20 53 51 4c 69 74 65 20 69 73   or if SQLite is
1b250 20 72 75 6e 20 69 6e 20 6f 6e 65 20 6f 66 20 72   run in one of r
1b260 65 64 75 63 65 64 20 6d 75 74 65 78 20 6d 6f 64  educed mutex mod
1b270 65 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43  es .** [SQLITE_C
1b280 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45  ONFIG_SINGLETHRE
1b290 41 44 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43  AD] or [SQLITE_C
1b2a0 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41  ONFIG_MULTITHREA
1b2b0 44 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 72 65  D].** then there
1b2c0 20 69 73 20 6e 6f 20 64 69 73 74 69 6e 63 74 69   is no distincti
1b2d0 6f 6e 20 62 65 74 77 65 65 6e 20 70 72 6f 74 65  on between prote
1b2e0 63 74 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 65  cted and unprote
1b2f0 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  cted.** sqlite3_
1b300 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 61 6e  value objects an
1b310 64 20 74 68 65 79 20 63 61 6e 20 62 65 20 75 73  d they can be us
1b320 65 64 20 69 6e 74 65 72 63 68 61 6e 67 65 61 62  ed interchangeab
1b330 6c 79 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a  ly.  However,.**
1b340 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 63 6f 64   for maximum cod
1b350 65 20 70 6f 72 74 61 62 69 6c 69 74 79 20 69 74  e portability it
1b360 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20   is recommended 
1b370 74 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e  that application
1b380 73 0a 2a 2a 20 73 74 69 6c 6c 20 6d 61 6b 65 20  s.** still make 
1b390 74 68 65 20 64 69 73 74 69 6e 63 74 69 6f 6e 20  the distinction 
1b3a0 62 65 74 77 65 65 6e 20 62 65 74 77 65 65 6e 20  between between 
1b3b0 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e  protected and un
1b3c0 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c  protected.** sql
1b3d0 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
1b3e0 74 73 20 65 76 65 6e 20 77 68 65 6e 20 6e 6f 74  ts even when not
1b3f0 20 73 74 72 69 63 74 6c 79 20 72 65 71 75 69 72   strictly requir
1b400 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ed..**.** The sq
1b410 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
1b420 63 74 73 20 74 68 61 74 20 61 72 65 20 70 61 73  cts that are pas
1b430 73 65 64 20 61 73 20 70 61 72 61 6d 65 74 65 72  sed as parameter
1b440 73 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 69 6d  s into the.** im
1b450 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
1b460 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66  [application-def
1b470 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
1b480 6e 73 5d 20 61 72 65 20 70 72 6f 74 65 63 74 65  ns] are protecte
1b490 64 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  d..** The sqlite
1b4a0 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 72  3_value object r
1b4b0 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73  eturned by.** [s
1b4c0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61  qlite3_column_va
1b4d0 6c 75 65 28 29 5d 20 69 73 20 75 6e 70 72 6f 74  lue()] is unprot
1b4e0 65 63 74 65 64 2e 0a 2a 2a 20 55 6e 70 72 6f 74  ected..** Unprot
1b4f0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
1b500 6c 75 65 20 6f 62 6a 65 63 74 73 20 6d 61 79 20  lue objects may 
1b510 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 77 69 74  only be used wit
1b520 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65  h.** [sqlite3_re
1b530 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 20 61 6e  sult_value()] an
1b540 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  d [sqlite3_bind_
1b550 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 54 68 65  value()]..** The
1b560 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
1b570 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 76  blob | sqlite3_v
1b580 61 6c 75 65 5f 74 79 70 65 28 29 5d 20 66 61 6d  alue_type()] fam
1b590 69 6c 79 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66  ily of.** interf
1b5a0 61 63 65 73 20 72 65 71 75 69 72 65 20 70 72 6f  aces require pro
1b5b0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
1b5c0 61 6c 75 65 20 6f 62 6a 65 63 74 73 2e 0a 2a 2f  alue objects..*/
1b5d0 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
1b5e0 4d 65 6d 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  Mem sqlite3_valu
1b5f0 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  e;../*.** CAPI3R
1b600 45 46 3a 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e  EF: SQL Function
1b610 20 43 6f 6e 74 65 78 74 20 4f 62 6a 65 63 74 20   Context Object 
1b620 7b 48 31 36 30 30 31 7d 20 3c 53 32 30 32 30 30  {H16001} <S20200
1b630 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 6e 74  >.**.** The cont
1b640 65 78 74 20 69 6e 20 77 68 69 63 68 20 61 6e 20  ext in which an 
1b650 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 65 78 65  SQL function exe
1b660 63 75 74 65 73 20 69 73 20 73 74 6f 72 65 64 20  cutes is stored 
1b670 69 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33  in an.** sqlite3
1b680 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 2e  _context object.
1b690 20 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 61    A pointer to a
1b6a0 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  n sqlite3_contex
1b6b0 74 20 6f 62 6a 65 63 74 0a 2a 2a 20 69 73 20 61  t object.** is a
1b6c0 6c 77 61 79 73 20 66 69 72 73 74 20 70 61 72 61  lways first para
1b6d0 6d 65 74 65 72 20 74 6f 20 5b 61 70 70 6c 69 63  meter to [applic
1b6e0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51  ation-defined SQ
1b6f0 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a  L functions]..**
1b700 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
1b710 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
1b720 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  ction implementa
1b730 74 69 6f 6e 20 77 69 6c 6c 20 70 61 73 73 20 74  tion will pass t
1b740 68 69 73 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74  his.** pointer t
1b750 68 72 6f 75 67 68 20 69 6e 74 6f 20 63 61 6c 6c  hrough into call
1b760 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65  s to [sqlite3_re
1b770 73 75 6c 74 5f 69 6e 74 20 7c 20 73 71 6c 69 74  sult_int | sqlit
1b780 65 33 5f 72 65 73 75 6c 74 28 29 5d 2c 0a 2a 2a  e3_result()],.**
1b790 20 5b 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67   [sqlite3_aggreg
1b7a0 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 5d 2c 20  ate_context()], 
1b7b0 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61  [sqlite3_user_da
1b7c0 74 61 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  ta()],.** [sqlit
1b7d0 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61  e3_context_db_ha
1b7e0 6e 64 6c 65 28 29 5d 2c 20 5b 73 71 6c 69 74 65  ndle()], [sqlite
1b7f0 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 5d  3_get_auxdata()]
1b800 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b 73 71 6c  ,.** and/or [sql
1b810 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
1b820 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ()]..*/.typedef 
1b830 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 63  struct sqlite3_c
1b840 6f 6e 74 65 78 74 20 73 71 6c 69 74 65 33 5f 63  ontext sqlite3_c
1b850 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ontext;../*.** C
1b860 41 50 49 33 52 45 46 3a 20 42 69 6e 64 69 6e 67  API3REF: Binding
1b870 20 56 61 6c 75 65 73 20 54 6f 20 50 72 65 70 61   Values To Prepa
1b880 72 65 64 20 53 74 61 74 65 6d 65 6e 74 73 20 7b  red Statements {
1b890 48 31 33 35 30 30 7d 20 3c 53 37 30 33 30 30 3e  H13500} <S70300>
1b8a0 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 68  .** KEYWORDS: {h
1b8b0 6f 73 74 20 70 61 72 61 6d 65 74 65 72 7d 20 7b  ost parameter} {
1b8c0 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 7d  host parameters}
1b8d0 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72   {host parameter
1b8e0 20 6e 61 6d 65 7d 0a 2a 2a 20 4b 45 59 57 4f 52   name}.** KEYWOR
1b8f0 44 53 3a 20 7b 53 51 4c 20 70 61 72 61 6d 65 74  DS: {SQL paramet
1b900 65 72 7d 20 7b 53 51 4c 20 70 61 72 61 6d 65 74  er} {SQL paramet
1b910 65 72 73 7d 20 7b 70 61 72 61 6d 65 74 65 72 20  ers} {parameter 
1b920 62 69 6e 64 69 6e 67 7d 0a 2a 2a 0a 2a 2a 20 49  binding}.**.** I
1b930 6e 20 74 68 65 20 53 51 4c 20 73 74 72 69 6e 67  n the SQL string
1b940 73 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69  s input to [sqli
1b950 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
1b960 5d 20 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e  ] and its varian
1b970 74 73 2c 0a 2a 2a 20 6c 69 74 65 72 61 6c 73 20  ts,.** literals 
1b980 6d 61 79 20 62 65 20 72 65 70 6c 61 63 65 64 20  may be replaced 
1b990 62 79 20 61 20 5b 70 61 72 61 6d 65 74 65 72 5d  by a [parameter]
1b9a0 20 69 6e 20 6f 6e 65 20 6f 66 20 74 68 65 73 65   in one of these
1b9b0 20 66 6f 72 6d 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75   forms:.**.** <u
1b9c0 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 0a 2a 2a  l>.** <li>  ?.**
1b9d0 20 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c   <li>  ?NNN.** <
1b9e0 6c 69 3e 20 20 3a 56 56 56 0a 2a 2a 20 3c 6c 69  li>  :VVV.** <li
1b9f0 3e 20 20 40 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20  >  @VVV.** <li> 
1ba00 20 24 56 56 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a   $VVV.** </ul>.*
1ba10 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 70 61 72 61  *.** In the para
1ba20 6d 65 74 65 72 20 66 6f 72 6d 73 20 73 68 6f 77  meter forms show
1ba30 6e 20 61 62 6f 76 65 20 4e 4e 4e 20 69 73 20 61  n above NNN is a
1ba40 6e 20 69 6e 74 65 67 65 72 20 6c 69 74 65 72 61  n integer litera
1ba50 6c 2c 0a 2a 2a 20 61 6e 64 20 56 56 56 20 69 73  l,.** and VVV is
1ba60 20 61 6e 20 61 6c 70 68 61 2d 6e 75 6d 65 72 69   an alpha-numeri
1ba70 63 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65  c parameter name
1ba80 2e 20 54 68 65 20 76 61 6c 75 65 73 20 6f 66 20  . The values of 
1ba90 74 68 65 73 65 0a 2a 2a 20 70 61 72 61 6d 65 74  these.** paramet
1baa0 65 72 73 20 28 61 6c 73 6f 20 63 61 6c 6c 65 64  ers (also called
1bab0 20 22 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72   "host parameter
1bac0 20 6e 61 6d 65 73 22 20 6f 72 20 22 53 51 4c 20   names" or "SQL 
1bad0 70 61 72 61 6d 65 74 65 72 73 22 29 0a 2a 2a 20  parameters").** 
1bae0 63 61 6e 20 62 65 20 73 65 74 20 75 73 69 6e 67  can be set using
1baf0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e   the sqlite3_bin
1bb00 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 64  d_*() routines d
1bb10 65 66 69 6e 65 64 20 68 65 72 65 2e 0a 2a 2a 0a  efined here..**.
1bb20 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67  ** The first arg
1bb30 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c  ument to the sql
1bb40 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f  ite3_bind_*() ro
1bb50 75 74 69 6e 65 73 20 69 73 20 61 6c 77 61 79 73  utines is always
1bb60 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  .** a pointer to
1bb70 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74   the [sqlite3_st
1bb80 6d 74 5d 20 6f 62 6a 65 63 74 20 72 65 74 75 72  mt] object retur
1bb90 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c  ned from.** [sql
1bba0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
1bbb0 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e  )] or its varian
1bbc0 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65  ts..**.** The se
1bbd0 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73  cond argument is
1bbe0 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68   the index of th
1bbf0 65 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20  e SQL parameter 
1bc00 74 6f 20 62 65 20 73 65 74 2e 0a 2a 2a 20 54 68  to be set..** Th
1bc10 65 20 6c 65 66 74 6d 6f 73 74 20 53 51 4c 20 70  e leftmost SQL p
1bc20 61 72 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20  arameter has an 
1bc30 69 6e 64 65 78 20 6f 66 20 31 2e 20 20 57 68 65  index of 1.  Whe
1bc40 6e 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 64  n the same named
1bc50 0a 2a 2a 20 53 51 4c 20 70 61 72 61 6d 65 74 65  .** SQL paramete
1bc60 72 20 69 73 20 75 73 65 64 20 6d 6f 72 65 20 74  r is used more t
1bc70 68 61 6e 20 6f 6e 63 65 2c 20 73 65 63 6f 6e 64  han once, second
1bc80 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74 0a   and subsequent.
1bc90 2a 2a 20 6f 63 63 75 72 72 65 6e 63 65 73 20 68  ** occurrences h
1bca0 61 76 65 20 74 68 65 20 73 61 6d 65 20 69 6e 64  ave the same ind
1bcb0 65 78 20 61 73 20 74 68 65 20 66 69 72 73 74 20  ex as the first 
1bcc0 6f 63 63 75 72 72 65 6e 63 65 2e 0a 2a 2a 20 54  occurrence..** T
1bcd0 68 65 20 69 6e 64 65 78 20 66 6f 72 20 6e 61 6d  he index for nam
1bce0 65 64 20 70 61 72 61 6d 65 74 65 72 73 20 63 61  ed parameters ca
1bcf0 6e 20 62 65 20 6c 6f 6f 6b 65 64 20 75 70 20 75  n be looked up u
1bd00 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  sing the.** [sql
1bd10 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
1bd20 74 65 72 5f 69 6e 64 65 78 28 29 5d 20 41 50 49  ter_index()] API
1bd30 20 69 66 20 64 65 73 69 72 65 64 2e 20 20 54 68   if desired.  Th
1bd40 65 20 69 6e 64 65 78 0a 2a 2a 20 66 6f 72 20 22  e index.** for "
1bd50 3f 4e 4e 4e 22 20 70 61 72 61 6d 65 74 65 72 73  ?NNN" parameters
1bd60 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66   is the value of
1bd70 20 4e 4e 4e 2e 0a 2a 2a 20 54 68 65 20 4e 4e 4e   NNN..** The NNN
1bd80 20 76 61 6c 75 65 20 6d 75 73 74 20 62 65 20 62   value must be b
1bd90 65 74 77 65 65 6e 20 31 20 61 6e 64 20 74 68 65  etween 1 and the
1bda0 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28   [sqlite3_limit(
1bdb0 29 5d 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  )].** parameter 
1bdc0 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41  [SQLITE_LIMIT_VA
1bdd0 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 20 28  RIABLE_NUMBER] (
1bde0 64 65 66 61 75 6c 74 20 76 61 6c 75 65 3a 20 39  default value: 9
1bdf0 39 39 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74  99)..**.** The t
1be00 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73  hird argument is
1be10 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20 62 69   the value to bi
1be20 6e 64 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65  nd to the parame
1be30 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68  ter..**.** In th
1be40 6f 73 65 20 72 6f 75 74 69 6e 65 73 20 74 68 61  ose routines tha
1be50 74 20 68 61 76 65 20 61 20 66 6f 75 72 74 68 20  t have a fourth 
1be60 61 72 67 75 6d 65 6e 74 2c 20 69 74 73 20 76 61  argument, its va
1be70 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75  lue is the.** nu
1be80 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e  mber of bytes in
1be90 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 20   the parameter. 
1bea0 20 54 6f 20 62 65 20 63 6c 65 61 72 3a 20 74 68   To be clear: th
1beb0 65 20 76 61 6c 75 65 20 69 73 20 74 68 65 0a 2a  e value is the.*
1bec0 2a 20 6e 75 6d 62 65 72 20 6f 66 20 3c 75 3e 62  * number of <u>b
1bed0 79 74 65 73 3c 2f 75 3e 20 69 6e 20 74 68 65 20  ytes</u> in the 
1bee0 76 61 6c 75 65 2c 20 6e 6f 74 20 74 68 65 20 6e  value, not the n
1bef0 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74  umber of charact
1bf00 65 72 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20 66  ers..** If the f
1bf10 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
1bf20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65  is negative, the
1bf30 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 73   length of the s
1bf40 74 72 69 6e 67 20 69 73 0a 2a 2a 20 74 68 65 20  tring is.** the 
1bf50 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
1bf60 75 70 20 74 6f 20 74 68 65 20 66 69 72 73 74 20  up to the first 
1bf70 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e  zero terminator.
1bf80 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 66 74 68  .**.** The fifth
1bf90 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
1bfa0 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29  ite3_bind_blob()
1bfb0 2c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  , sqlite3_bind_t
1bfc0 65 78 74 28 29 2c 20 61 6e 64 0a 2a 2a 20 73 71  ext(), and.** sq
1bfd0 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31  lite3_bind_text1
1bfe0 36 28 29 20 69 73 20 61 20 64 65 73 74 72 75 63  6() is a destruc
1bff0 74 6f 72 20 75 73 65 64 20 74 6f 20 64 69 73 70  tor used to disp
1c000 6f 73 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20  ose of the BLOB 
1c010 6f 72 0a 2a 2a 20 73 74 72 69 6e 67 20 61 66 74  or.** string aft
1c020 65 72 20 53 51 4c 69 74 65 20 68 61 73 20 66 69  er SQLite has fi
1c030 6e 69 73 68 65 64 20 77 69 74 68 20 69 74 2e 20  nished with it. 
1c040 49 66 20 74 68 65 20 66 69 66 74 68 20 61 72 67  If the fifth arg
1c050 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 74 68 65 20  ument is.** the 
1c060 73 70 65 63 69 61 6c 20 76 61 6c 75 65 20 5b 53  special value [S
1c070 51 4c 49 54 45 5f 53 54 41 54 49 43 5d 2c 20 74  QLITE_STATIC], t
1c080 68 65 6e 20 53 51 4c 69 74 65 20 61 73 73 75 6d  hen SQLite assum
1c090 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 69  es that the.** i
1c0a0 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 69 6e  nformation is in
1c0b0 20 73 74 61 74 69 63 2c 20 75 6e 6d 61 6e 61 67   static, unmanag
1c0c0 65 64 20 73 70 61 63 65 20 61 6e 64 20 64 6f 65  ed space and doe
1c0d0 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65  s not need to be
1c0e0 20 66 72 65 65 64 2e 0a 2a 2a 20 49 66 20 74 68   freed..** If th
1c0f0 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74  e fifth argument
1c100 20 68 61 73 20 74 68 65 20 76 61 6c 75 65 20 5b   has the value [
1c110 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54  SQLITE_TRANSIENT
1c120 5d 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74  ], then.** SQLit
1c130 65 20 6d 61 6b 65 73 20 69 74 73 20 6f 77 6e 20  e makes its own 
1c140 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20  private copy of 
1c150 74 68 65 20 64 61 74 61 20 69 6d 6d 65 64 69 61  the data immedia
1c160 74 65 6c 79 2c 20 62 65 66 6f 72 65 0a 2a 2a 20  tely, before.** 
1c170 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  the sqlite3_bind
1c180 5f 2a 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74  _*() routine ret
1c190 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  urns..**.** The 
1c1a0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72  sqlite3_bind_zer
1c1b0 6f 62 6c 6f 62 28 29 20 72 6f 75 74 69 6e 65 20  oblob() routine 
1c1c0 62 69 6e 64 73 20 61 20 42 4c 4f 42 20 6f 66 20  binds a BLOB of 
1c1d0 6c 65 6e 67 74 68 20 4e 20 74 68 61 74 0a 2a 2a  length N that.**
1c1e0 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20   is filled with 
1c1f0 7a 65 72 6f 65 73 2e 20 20 41 20 7a 65 72 6f 62  zeroes.  A zerob
1c200 6c 6f 62 20 75 73 65 73 20 61 20 66 69 78 65 64  lob uses a fixed
1c210 20 61 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f 72   amount of memor
1c220 79 0a 2a 2a 20 28 6a 75 73 74 20 61 6e 20 69 6e  y.** (just an in
1c230 74 65 67 65 72 20 74 6f 20 68 6f 6c 64 20 69 74  teger to hold it
1c240 73 20 73 69 7a 65 29 20 77 68 69 6c 65 20 69 74  s size) while it
1c250 20 69 73 20 62 65 69 6e 67 20 70 72 6f 63 65 73   is being proces
1c260 73 65 64 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62  sed..** Zeroblob
1c270 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 74  s are intended t
1c280 6f 20 73 65 72 76 65 20 61 73 20 70 6c 61 63 65  o serve as place
1c290 68 6f 6c 64 65 72 73 20 66 6f 72 20 42 4c 4f 42  holders for BLOB
1c2a0 73 20 77 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65  s whose.** conte
1c2b0 6e 74 20 69 73 20 6c 61 74 65 72 20 77 72 69 74  nt is later writ
1c2c0 74 65 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71  ten using.** [sq
1c2d0 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20  lite3_blob_open 
1c2e0 7c 20 69 6e 63 72 65 6d 65 6e 74 61 6c 20 42 4c  | incremental BL
1c2f0 4f 42 20 49 2f 4f 5d 20 72 6f 75 74 69 6e 65 73  OB I/O] routines
1c300 2e 0a 2a 2a 20 41 20 6e 65 67 61 74 69 76 65 20  ..** A negative 
1c310 76 61 6c 75 65 20 66 6f 72 20 74 68 65 20 7a 65  value for the ze
1c320 72 6f 62 6c 6f 62 20 72 65 73 75 6c 74 73 20 69  roblob results i
1c330 6e 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20  n a zero-length 
1c340 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  BLOB..**.** The 
1c350 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29  sqlite3_bind_*()
1c360 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62   routines must b
1c370 65 20 63 61 6c 6c 65 64 20 61 66 74 65 72 0a 2a  e called after.*
1c380 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
1c390 72 65 5f 76 32 28 29 5d 20 28 61 6e 64 20 69 74  re_v2()] (and it
1c3a0 73 20 76 61 72 69 61 6e 74 73 29 20 6f 72 20 5b  s variants) or [
1c3b0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
1c3c0 20 61 6e 64 0a 2a 2a 20 62 65 66 6f 72 65 20 5b   and.** before [
1c3d0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e  sqlite3_step()].
1c3e0 0a 2a 2a 20 42 69 6e 64 69 6e 67 73 20 61 72 65  .** Bindings are
1c3f0 20 6e 6f 74 20 63 6c 65 61 72 65 64 20 62 79 20   not cleared by 
1c400 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  the [sqlite3_res
1c410 65 74 28 29 5d 20 72 6f 75 74 69 6e 65 2e 0a 2a  et()] routine..*
1c420 2a 20 55 6e 62 6f 75 6e 64 20 70 61 72 61 6d 65  * Unbound parame
1c430 74 65 72 73 20 61 72 65 20 69 6e 74 65 72 70 72  ters are interpr
1c440 65 74 65 64 20 61 73 20 4e 55 4c 4c 2e 0a 2a 2a  eted as NULL..**
1c450 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
1c460 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  es return [SQLIT
1c470 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73  E_OK] on success
1c480 20 6f 72 20 61 6e 20 65 72 72 6f 72 20 63 6f 64   or an error cod
1c490 65 20 69 66 0a 2a 2a 20 61 6e 79 74 68 69 6e 67  e if.** anything
1c4a0 20 67 6f 65 73 20 77 72 6f 6e 67 2e 20 20 5b 53   goes wrong.  [S
1c4b0 51 4c 49 54 45 5f 52 41 4e 47 45 5d 20 69 73 20  QLITE_RANGE] is 
1c4c0 72 65 74 75 72 6e 65 64 20 69 66 20 74 68 65 20  returned if the 
1c4d0 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69 6e 64  parameter.** ind
1c4e0 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e  ex is out of ran
1c4f0 67 65 2e 20 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d  ge.  [SQLITE_NOM
1c500 45 4d 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20  EM] is returned 
1c510 69 66 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c  if malloc() fail
1c520 73 2e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49  s..** [SQLITE_MI
1c530 53 55 53 45 5d 20 6d 69 67 68 74 20 62 65 20 72  SUSE] might be r
1c540 65 74 75 72 6e 65 64 20 69 66 20 74 68 65 73 65  eturned if these
1c550 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61   routines are ca
1c560 6c 6c 65 64 20 6f 6e 20 61 0a 2a 2a 20 76 69 72  lled on a.** vir
1c570 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 74 68 61  tual machine tha
1c580 74 20 69 73 20 74 68 65 20 77 72 6f 6e 67 20 73  t is the wrong s
1c590 74 61 74 65 20 6f 72 20 77 68 69 63 68 20 68 61  tate or which ha
1c5a0 73 20 61 6c 72 65 61 64 79 20 62 65 65 6e 20 66  s already been f
1c5b0 69 6e 61 6c 69 7a 65 64 2e 0a 2a 2a 20 44 65 74  inalized..** Det
1c5c0 65 63 74 69 6f 6e 20 6f 66 20 6d 69 73 75 73 65  ection of misuse
1c5d0 20 69 73 20 75 6e 72 65 6c 69 61 62 6c 65 2e 20   is unreliable. 
1c5e0 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68   Applications sh
1c5f0 6f 75 6c 64 20 6e 6f 74 20 64 65 70 65 6e 64 0a  ould not depend.
1c600 2a 2a 20 6f 6e 20 53 51 4c 49 54 45 5f 4d 49 53  ** on SQLITE_MIS
1c610 55 53 45 20 72 65 74 75 72 6e 73 2e 20 20 53 51  USE returns.  SQ
1c620 4c 49 54 45 5f 4d 49 53 55 53 45 20 69 73 20 69  LITE_MISUSE is i
1c630 6e 74 65 6e 64 65 64 20 74 6f 20 69 6e 64 69 63  ntended to indic
1c640 61 74 65 20 61 0a 2a 2a 20 61 20 6c 6f 67 69 63  ate a.** a logic
1c650 20 65 72 72 6f 72 20 69 6e 20 74 68 65 20 61 70   error in the ap
1c660 70 6c 69 63 61 74 69 6f 6e 2e 20 20 46 75 74 75  plication.  Futu
1c670 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  re versions of S
1c680 51 4c 69 74 65 20 6d 69 67 68 74 0a 2a 2a 20 70  QLite might.** p
1c690 61 6e 69 63 20 72 61 74 68 65 72 20 74 68 61 6e  anic rather than
1c6a0 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4d   return SQLITE_M
1c6b0 49 53 55 53 45 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  ISUSE..**.** See
1c6c0 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
1c6d0 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63  bind_parameter_c
1c6e0 6f 75 6e 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  ount()],.** [sql
1c6f0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
1c700 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64  ter_name()], and
1c710 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
1c720 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29  arameter_index()
1c730 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65  ]..**.** Require
1c740 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 33 35 30  ments:.** [H1350
1c750 36 5d 20 5b 48 31 33 35 30 39 5d 20 5b 48 31 33  6] [H13509] [H13
1c760 35 31 32 5d 20 5b 48 31 33 35 31 35 5d 20 5b 48  512] [H13515] [H
1c770 31 33 35 31 38 5d 20 5b 48 31 33 35 32 31 5d 20  13518] [H13521] 
1c780 5b 48 31 33 35 32 34 5d 20 5b 48 31 33 35 32 37  [H13524] [H13527
1c790 5d 0a 2a 2a 20 5b 48 31 33 35 33 30 5d 20 5b 48  ].** [H13530] [H
1c7a0 31 33 35 33 33 5d 20 5b 48 31 33 35 33 36 5d 20  13533] [H13536] 
1c7b0 5b 48 31 33 35 33 39 5d 20 5b 48 31 33 35 34 32  [H13539] [H13542
1c7c0 5d 20 5b 48 31 33 35 34 35 5d 20 5b 48 31 33 35  ] [H13545] [H135
1c7d0 34 38 5d 20 5b 48 31 33 35 35 31 5d 0a 2a 2a 0a  48] [H13551].**.
1c7e0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  */.int sqlite3_b
1c7f0 69 6e 64 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33  ind_blob(sqlite3
1c800 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e  _stmt*, int, con
1c810 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 2c  st void*, int n,
1c820 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29   void(*)(void*))
1c830 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
1c840 6e 64 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65  nd_double(sqlite
1c850 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 64 6f  3_stmt*, int, do
1c860 75 62 6c 65 29 3b 0a 69 6e 74 20 73 71 6c 69 74  uble);.int sqlit
1c870 65 33 5f 62 69 6e 64 5f 69 6e 74 28 73 71 6c 69  e3_bind_int(sqli
1c880 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
1c890 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  int);.int sqlite
1c8a0 33 5f 62 69 6e 64 5f 69 6e 74 36 34 28 73 71 6c  3_bind_int64(sql
1c8b0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
1c8c0 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b   sqlite3_int64);
1c8d0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
1c8e0 64 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 73  d_null(sqlite3_s
1c8f0 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 69 6e 74 20  tmt*, int);.int 
1c900 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
1c910 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  t(sqlite3_stmt*,
1c920 20 69 6e 74 2c 20 63 6f 6e 73 74 20 63 68 61 72   int, const char
1c930 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a  *, int n, void(*
1c940 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73  )(void*));.int s
1c950 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
1c960 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
1c970 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69  , int, const voi
1c980 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29  d*, int, void(*)
1c990 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71  (void*));.int sq
1c9a0 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65  lite3_bind_value
1c9b0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
1c9c0 69 6e 74 2c 20 63 6f 6e 73 74 20 73 71 6c 69 74  int, const sqlit
1c9d0 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20  e3_value*);.int 
1c9e0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72  sqlite3_bind_zer
1c9f0 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74  oblob(sqlite3_st
1ca00 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 20 6e 29  mt*, int, int n)
1ca10 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1ca20 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 53 51 4c  F: Number Of SQL
1ca30 20 50 61 72 61 6d 65 74 65 72 73 20 7b 48 31 33   Parameters {H13
1ca40 36 30 30 7d 20 3c 53 37 30 33 30 30 3e 0a 2a 2a  600} <S70300>.**
1ca50 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65  .** This routine
1ca60 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
1ca70 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20  find the number 
1ca80 6f 66 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65  of [SQL paramete
1ca90 72 73 5d 0a 2a 2a 20 69 6e 20 61 20 5b 70 72 65  rs].** in a [pre
1caa0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
1cab0 2e 20 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  .  SQL parameter
1cac0 73 20 61 72 65 20 74 6f 6b 65 6e 73 20 6f 66 20  s are tokens of 
1cad0 74 68 65 0a 2a 2a 20 66 6f 72 6d 20 22 3f 22 2c  the.** form "?",
1cae0 20 22 3f 4e 4e 4e 22 2c 20 22 3a 41 41 41 22 2c   "?NNN", ":AAA",
1caf0 20 22 24 41 41 41 22 2c 20 6f 72 20 22 40 41 41   "$AAA", or "@AA
1cb00 41 22 20 74 68 61 74 20 73 65 72 76 65 20 61 73  A" that serve as
1cb10 0a 2a 2a 20 70 6c 61 63 65 68 6f 6c 64 65 72 73  .** placeholders
1cb20 20 66 6f 72 20 76 61 6c 75 65 73 20 74 68 61 74   for values that
1cb30 20 61 72 65 20 5b 73 71 6c 69 74 65 33 5f 62 69   are [sqlite3_bi
1cb40 6e 64 5f 62 6c 6f 62 20 7c 20 62 6f 75 6e 64 5d  nd_blob | bound]
1cb50 0a 2a 2a 20 74 6f 20 74 68 65 20 70 61 72 61 6d  .** to the param
1cb60 65 74 65 72 73 20 61 74 20 61 20 6c 61 74 65 72  eters at a later
1cb70 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 69   time..**.** Thi
1cb80 73 20 72 6f 75 74 69 6e 65 20 61 63 74 75 61 6c  s routine actual
1cb90 6c 79 20 72 65 74 75 72 6e 73 20 74 68 65 20 69  ly returns the i
1cba0 6e 64 65 78 20 6f 66 20 74 68 65 20 6c 61 72 67  ndex of the larg
1cbb0 65 73 74 20 28 72 69 67 68 74 6d 6f 73 74 29 0a  est (rightmost).
1cbc0 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e 20 46 6f  ** parameter. Fo
1cbd0 72 20 61 6c 6c 20 66 6f 72 6d 73 20 65 78 63 65  r all forms exce
1cbe0 70 74 20 3f 4e 4e 4e 2c 20 74 68 69 73 20 77 69  pt ?NNN, this wi
1cbf0 6c 6c 20 63 6f 72 72 65 73 70 6f 6e 64 20 74 6f  ll correspond to
1cc00 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f   the.** number o
1cc10 66 20 75 6e 69 71 75 65 20 70 61 72 61 6d 65 74  f unique paramet
1cc20 65 72 73 2e 20 20 49 66 20 70 61 72 61 6d 65 74  ers.  If paramet
1cc30 65 72 73 20 6f 66 20 74 68 65 20 3f 4e 4e 4e 20  ers of the ?NNN 
1cc40 61 72 65 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65  are used,.** the
1cc50 72 65 20 6d 61 79 20 62 65 20 67 61 70 73 20 69  re may be gaps i
1cc60 6e 20 74 68 65 20 6c 69 73 74 2e 0a 2a 2a 0a 2a  n the list..**.*
1cc70 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
1cc80 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73  ite3_bind_blob|s
1cc90 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a  qlite3_bind()],.
1cca0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
1ccb0 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28  _parameter_name(
1ccc0 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  )], and.** [sqli
1ccd0 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
1cce0 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2a 0a  er_index()]..**.
1ccf0 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a  ** Requirements:
1cd00 0a 2a 2a 20 5b 48 31 33 36 30 31 5d 0a 2a 2f 0a  .** [H13601].*/.
1cd10 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
1cd20 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74  _parameter_count
1cd30 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b  (sqlite3_stmt*);
1cd40 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1cd50 3a 20 4e 61 6d 65 20 4f 66 20 41 20 48 6f 73 74  : Name Of A Host
1cd60 20 50 61 72 61 6d 65 74 65 72 20 7b 48 31 33 36   Parameter {H136
1cd70 32 30 7d 20 3c 53 37 30 33 30 30 3e 0a 2a 2a 0a  20} <S70300>.**.
1cd80 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  ** This routine 
1cd90 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
1cda0 72 20 74 6f 20 74 68 65 20 6e 61 6d 65 20 6f 66  r to the name of
1cdb0 20 74 68 65 20 6e 2d 74 68 0a 2a 2a 20 5b 53 51   the n-th.** [SQ
1cdc0 4c 20 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20  L parameter] in 
1cdd0 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
1cde0 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 53 51 4c 20 70  ement]..** SQL p
1cdf0 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65  arameters of the
1ce00 20 66 6f 72 6d 20 22 3f 4e 4e 4e 22 20 6f 72 20   form "?NNN" or 
1ce10 22 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41 22  ":AAA" or "@AAA"
1ce20 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 68 61   or "$AAA".** ha
1ce30 76 65 20 61 20 6e 61 6d 65 20 77 68 69 63 68 20  ve a name which 
1ce40 69 73 20 74 68 65 20 73 74 72 69 6e 67 20 22 3f  is the string "?
1ce50 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 6f  NNN" or ":AAA" o
1ce60 72 20 22 40 41 41 41 22 20 6f 72 20 22 24 41 41  r "@AAA" or "$AA
1ce70 41 22 0a 2a 2a 20 72 65 73 70 65 63 74 69 76 65  A".** respective
1ce80 6c 79 2e 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20  ly..** In other 
1ce90 77 6f 72 64 73 2c 20 74 68 65 20 69 6e 69 74 69  words, the initi
1cea0 61 6c 20 22 3a 22 20 6f 72 20 22 24 22 20 6f 72  al ":" or "$" or
1ceb0 20 22 40 22 20 6f 72 20 22 3f 22 0a 2a 2a 20 69   "@" or "?".** i
1cec0 73 20 69 6e 63 6c 75 64 65 64 20 61 73 20 70 61  s included as pa
1ced0 72 74 20 6f 66 20 74 68 65 20 6e 61 6d 65 2e 0a  rt of the name..
1cee0 2a 2a 20 50 61 72 61 6d 65 74 65 72 73 20 6f 66  ** Parameters of
1cef0 20 74 68 65 20 66 6f 72 6d 20 22 3f 22 20 77 69   the form "?" wi
1cf00 74 68 6f 75 74 20 61 20 66 6f 6c 6c 6f 77 69 6e  thout a followin
1cf10 67 20 69 6e 74 65 67 65 72 20 68 61 76 65 20 6e  g integer have n
1cf20 6f 20 6e 61 6d 65 0a 2a 2a 20 61 6e 64 20 61 72  o name.** and ar
1cf30 65 20 61 6c 73 6f 20 72 65 66 65 72 72 65 64 20  e also referred 
1cf40 74 6f 20 61 73 20 22 61 6e 6f 6e 79 6d 6f 75 73  to as "anonymous
1cf50 20 70 61 72 61 6d 65 74 65 72 73 22 2e 0a 2a 2a   parameters"..**
1cf60 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 68 6f  .** The first ho
1cf70 73 74 20 70 61 72 61 6d 65 74 65 72 20 68 61 73  st parameter has
1cf80 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2c 20   an index of 1, 
1cf90 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  not 0..**.** If 
1cfa0 74 68 65 20 76 61 6c 75 65 20 6e 20 69 73 20 6f  the value n is o
1cfb0 75 74 20 6f 66 20 72 61 6e 67 65 20 6f 72 20 69  ut of range or i
1cfc0 66 20 74 68 65 20 6e 2d 74 68 20 70 61 72 61 6d  f the n-th param
1cfd0 65 74 65 72 20 69 73 0a 2a 2a 20 6e 61 6d 65 6c  eter is.** namel
1cfe0 65 73 73 2c 20 74 68 65 6e 20 4e 55 4c 4c 20 69  ess, then NULL i
1cff0 73 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65  s returned.  The
1d000 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67   returned string
1d010 20 69 73 0a 2a 2a 20 61 6c 77 61 79 73 20 69 6e   is.** always in
1d020 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20   UTF-8 encoding 
1d030 65 76 65 6e 20 69 66 20 74 68 65 20 6e 61 6d 65  even if the name
1d040 64 20 70 61 72 61 6d 65 74 65 72 20 77 61 73 0a  d parameter was.
1d050 2a 2a 20 6f 72 69 67 69 6e 61 6c 6c 79 20 73 70  ** originally sp
1d060 65 63 69 66 69 65 64 20 61 73 20 55 54 46 2d 31  ecified as UTF-1
1d070 36 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72  6 in [sqlite3_pr
1d080 65 70 61 72 65 31 36 28 29 5d 20 6f 72 0a 2a 2a  epare16()] or.**
1d090 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1d0a0 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a  e16_v2()]..**.**
1d0b0 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
1d0c0 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71  te3_bind_blob|sq
1d0d0 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a  lite3_bind()],.*
1d0e0 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
1d0f0 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28  parameter_count(
1d100 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  )], and.** [sqli
1d110 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
1d120 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2a 0a  er_index()]..**.
1d130 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a  ** Requirements:
1d140 0a 2a 2a 20 5b 48 31 33 36 32 31 5d 0a 2a 2f 0a  .** [H13621].*/.
1d150 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
1d160 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
1d170 65 72 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f  er_name(sqlite3_
1d180 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a  stmt*, int);../*
1d190 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e  .** CAPI3REF: In
1d1a0 64 65 78 20 4f 66 20 41 20 50 61 72 61 6d 65 74  dex Of A Paramet
1d1b0 65 72 20 57 69 74 68 20 41 20 47 69 76 65 6e 20  er With A Given 
1d1c0 4e 61 6d 65 20 7b 48 31 33 36 34 30 7d 20 3c 53  Name {H13640} <S
1d1d0 37 30 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 52 65 74  70300>.**.** Ret
1d1e0 75 72 6e 20 74 68 65 20 69 6e 64 65 78 20 6f 66  urn the index of
1d1f0 20 61 6e 20 53 51 4c 20 70 61 72 61 6d 65 74 65   an SQL paramete
1d200 72 20 67 69 76 65 6e 20 69 74 73 20 6e 61 6d 65  r given its name
1d210 2e 20 20 54 68 65 0a 2a 2a 20 69 6e 64 65 78 20  .  The.** index 
1d220 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 69  value returned i
1d230 73 20 73 75 69 74 61 62 6c 65 20 66 6f 72 20 75  s suitable for u
1d240 73 65 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  se as the second
1d250 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 74 6f  .** parameter to
1d260 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
1d270 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64  lob|sqlite3_bind
1d280 28 29 5d 2e 20 20 41 20 7a 65 72 6f 0a 2a 2a 20  ()].  A zero.** 
1d290 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 6e  is returned if n
1d2a0 6f 20 6d 61 74 63 68 69 6e 67 20 70 61 72 61 6d  o matching param
1d2b0 65 74 65 72 20 69 73 20 66 6f 75 6e 64 2e 20 20  eter is found.  
1d2c0 54 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a  The parameter.**
1d2d0 20 6e 61 6d 65 20 6d 75 73 74 20 62 65 20 67 69   name must be gi
1d2e0 76 65 6e 20 69 6e 20 55 54 46 2d 38 20 65 76 65  ven in UTF-8 eve
1d2f0 6e 20 69 66 20 74 68 65 20 6f 72 69 67 69 6e 61  n if the origina
1d300 6c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 77  l statement.** w
1d310 61 73 20 70 72 65 70 61 72 65 64 20 66 72 6f 6d  as prepared from
1d320 20 55 54 46 2d 31 36 20 74 65 78 74 20 75 73 69   UTF-16 text usi
1d330 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ng [sqlite3_prep
1d340 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a  are16_v2()]..**.
1d350 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
1d360 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c  lite3_bind_blob|
1d370 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c  sqlite3_bind()],
1d380 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
1d390 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e  d_parameter_coun
1d3a0 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71  t()], and.** [sq
1d3b0 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
1d3c0 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a  eter_index()]..*
1d3d0 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74  *.** Requirement
1d3e0 73 3a 0a 2a 2a 20 5b 48 31 33 36 34 31 5d 0a 2a  s:.** [H13641].*
1d3f0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  /.int sqlite3_bi
1d400 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64  nd_parameter_ind
1d410 65 78 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ex(sqlite3_stmt*
1d420 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
1d430 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ame);../*.** CAP
1d440 49 33 52 45 46 3a 20 52 65 73 65 74 20 41 6c 6c  I3REF: Reset All
1d450 20 42 69 6e 64 69 6e 67 73 20 4f 6e 20 41 20 50   Bindings On A P
1d460 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e  repared Statemen
1d470 74 20 7b 48 31 33 36 36 30 7d 20 3c 53 37 30 33  t {H13660} <S703
1d480 30 30 3e 0a 2a 2a 0a 2a 2a 20 43 6f 6e 74 72 61  00>.**.** Contra
1d490 72 79 20 74 6f 20 74 68 65 20 69 6e 74 75 69 74  ry to the intuit
1d4a0 69 6f 6e 20 6f 66 20 6d 61 6e 79 2c 20 5b 73 71  ion of many, [sq
1d4b0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 64  lite3_reset()] d
1d4c0 6f 65 73 20 6e 6f 74 20 72 65 73 65 74 0a 2a 2a  oes not reset.**
1d4d0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69   the [sqlite3_bi
1d4e0 6e 64 5f 62 6c 6f 62 20 7c 20 62 69 6e 64 69 6e  nd_blob | bindin
1d4f0 67 73 5d 20 6f 6e 20 61 20 5b 70 72 65 70 61 72  gs] on a [prepar
1d500 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a  ed statement]..*
1d510 2a 20 55 73 65 20 74 68 69 73 20 72 6f 75 74 69  * Use this routi
1d520 6e 65 20 74 6f 20 72 65 73 65 74 20 61 6c 6c 20  ne to reset all 
1d530 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 20  host parameters 
1d540 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 52  to NULL..**.** R
1d550 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20  equirements:.** 
1d560 5b 48 31 33 36 36 31 5d 0a 2a 2f 0a 69 6e 74 20  [H13661].*/.int 
1d570 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69  sqlite3_clear_bi
1d580 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73  ndings(sqlite3_s
1d590 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  tmt*);../*.** CA
1d5a0 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f  PI3REF: Number O
1d5b0 66 20 43 6f 6c 75 6d 6e 73 20 49 6e 20 41 20 52  f Columns In A R
1d5c0 65 73 75 6c 74 20 53 65 74 20 7b 48 31 33 37 31  esult Set {H1371
1d5d0 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 2a 0a 2a  0} <S10700>.**.*
1d5e0 2a 20 52 65 74 75 72 6e 20 74 68 65 20 6e 75 6d  * Return the num
1d5f0 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
1d600 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  n the result set
1d610 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65   returned by the
1d620 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
1d630 61 74 65 6d 65 6e 74 5d 2e 20 54 68 69 73 20 72  atement]. This r
1d640 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 30  outine returns 0
1d650 20 69 66 20 70 53 74 6d 74 20 69 73 20 61 6e 20   if pStmt is an 
1d660 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  SQL.** statement
1d670 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 72   that does not r
1d680 65 74 75 72 6e 20 64 61 74 61 20 28 66 6f 72 20  eturn data (for 
1d690 65 78 61 6d 70 6c 65 20 61 6e 20 5b 55 50 44 41  example an [UPDA
1d6a0 54 45 5d 29 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75  TE])..**.** Requ
1d6b0 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31  irements:.** [H1
1d6c0 33 37 31 31 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c  3711].*/.int sql
1d6d0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e  ite3_column_coun
1d6e0 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  t(sqlite3_stmt *
1d6f0 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pStmt);../*.** C
1d700 41 50 49 33 52 45 46 3a 20 43 6f 6c 75 6d 6e 20  API3REF: Column 
1d710 4e 61 6d 65 73 20 49 6e 20 41 20 52 65 73 75 6c  Names In A Resul
1d720 74 20 53 65 74 20 7b 48 31 33 37 32 30 7d 20 3c  t Set {H13720} <
1d730 53 31 30 37 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68  S10700>.**.** Th
1d740 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74  ese routines ret
1d750 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 61 73 73  urn the name ass
1d760 69 67 6e 65 64 20 74 6f 20 61 20 70 61 72 74 69  igned to a parti
1d770 63 75 6c 61 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20  cular column.** 
1d780 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  in the result se
1d790 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20  t of a [SELECT] 
1d7a0 73 74 61 74 65 6d 65 6e 74 2e 20 20 54 68 65 20  statement.  The 
1d7b0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
1d7c0 61 6d 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61  ame().** interfa
1d7d0 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  ce returns a poi
1d7e0 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74  nter to a zero-t
1d7f0 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20  erminated UTF-8 
1d800 73 74 72 69 6e 67 0a 2a 2a 20 61 6e 64 20 73 71  string.** and sq
1d810 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
1d820 65 31 36 28 29 20 72 65 74 75 72 6e 73 20 61 20  e16() returns a 
1d830 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72  pointer to a zer
1d840 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20  o-terminated.** 
1d850 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2e 20 20  UTF-16 string.  
1d860 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
1d870 74 65 72 20 69 73 20 74 68 65 20 5b 70 72 65 70  ter is the [prep
1d880 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a  ared statement].
1d890 2a 2a 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e  ** that implemen
1d8a0 74 73 20 74 68 65 20 5b 53 45 4c 45 43 54 5d 20  ts the [SELECT] 
1d8b0 73 74 61 74 65 6d 65 6e 74 2e 20 54 68 65 20 73  statement. The s
1d8c0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
1d8d0 69 73 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e  is the.** column
1d8e0 20 6e 75 6d 62 65 72 2e 20 20 54 68 65 20 6c 65   number.  The le
1d8f0 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73  ftmost column is
1d900 20 6e 75 6d 62 65 72 20 30 2e 0a 2a 2a 0a 2a 2a   number 0..**.**
1d910 20 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74   The returned st
1d920 72 69 6e 67 20 70 6f 69 6e 74 65 72 20 69 73 20  ring pointer is 
1d930 76 61 6c 69 64 20 75 6e 74 69 6c 20 65 69 74 68  valid until eith
1d940 65 72 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  er the [prepared
1d950 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 69   statement].** i
1d960 73 20 64 65 73 74 72 6f 79 65 64 20 62 79 20 5b  s destroyed by [
1d970 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
1d980 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65  ()] or until the
1d990 20 6e 65 78 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a   next call to.**
1d9a0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
1d9b0 6e 61 6d 65 28 29 20 6f 72 20 73 71 6c 69 74 65  name() or sqlite
1d9c0 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28  3_column_name16(
1d9d0 29 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 63 6f  ) on the same co
1d9e0 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 73  lumn..**.** If s
1d9f0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
1da00 66 61 69 6c 73 20 64 75 72 69 6e 67 20 74 68 65  fails during the
1da10 20 70 72 6f 63 65 73 73 69 6e 67 20 6f 66 20 65   processing of e
1da20 69 74 68 65 72 20 72 6f 75 74 69 6e 65 0a 2a 2a  ither routine.**
1da30 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 64 75   (for example du
1da40 72 69 6e 67 20 61 20 63 6f 6e 76 65 72 73 69 6f  ring a conversio
1da50 6e 20 66 72 6f 6d 20 55 54 46 2d 38 20 74 6f 20  n from UTF-8 to 
1da60 55 54 46 2d 31 36 29 20 74 68 65 6e 20 61 0a 2a  UTF-16) then a.*
1da70 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69  * NULL pointer i
1da80 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  s returned..**.*
1da90 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66 20 61 20  * The name of a 
1daa0 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 73  result column is
1dab0 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68   the value of th
1dac0 65 20 22 41 53 22 20 63 6c 61 75 73 65 20 66 6f  e "AS" clause fo
1dad0 72 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 75 6d 6e  r.** that column
1dae0 2c 20 69 66 20 74 68 65 72 65 20 69 73 20 61 6e  , if there is an
1daf0 20 41 53 20 63 6c 61 75 73 65 2e 20 20 49 66 20   AS clause.  If 
1db00 74 68 65 72 65 20 69 73 20 6e 6f 20 41 53 20 63  there is no AS c
1db10 6c 61 75 73 65 0a 2a 2a 20 74 68 65 6e 20 74 68  lause.** then th
1db20 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 63 6f  e name of the co
1db30 6c 75 6d 6e 20 69 73 20 75 6e 73 70 65 63 69 66  lumn is unspecif
1db40 69 65 64 20 61 6e 64 20 6d 61 79 20 63 68 61 6e  ied and may chan
1db50 67 65 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 72  ge from.** one r
1db60 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65  elease of SQLite
1db70 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 0a 2a 2a   to the next..**
1db80 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73  .** Requirements
1db90 3a 0a 2a 2a 20 5b 48 31 33 37 32 31 5d 20 5b 48  :.** [H13721] [H
1dba0 31 33 37 32 33 5d 20 5b 48 31 33 37 32 34 5d 20  13723] [H13724] 
1dbb0 5b 48 31 33 37 32 35 5d 20 5b 48 31 33 37 32 36  [H13725] [H13726
1dbc0 5d 20 5b 48 31 33 37 32 37 5d 0a 2a 2f 0a 63 6f  ] [H13727].*/.co
1dbd0 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
1dbe0 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73 71  3_column_name(sq
1dbf0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
1dc00 20 4e 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20   N);.const void 
1dc10 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
1dc20 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73  name16(sqlite3_s
1dc30 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 0a 2f  tmt*, int N);../
1dc40 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
1dc50 6f 75 72 63 65 20 4f 66 20 44 61 74 61 20 49 6e  ource Of Data In
1dc60 20 41 20 51 75 65 72 79 20 52 65 73 75 6c 74 20   A Query Result 
1dc70 7b 48 31 33 37 34 30 7d 20 3c 53 31 30 37 30 30  {H13740} <S10700
1dc80 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  >.**.** These ro
1dc90 75 74 69 6e 65 73 20 70 72 6f 76 69 64 65 20 61  utines provide a
1dca0 20 6d 65 61 6e 73 20 74 6f 20 64 65 74 65 72 6d   means to determ
1dcb0 69 6e 65 20 77 68 61 74 20 63 6f 6c 75 6d 6e 20  ine what column 
1dcc0 6f 66 20 77 68 61 74 0a 2a 2a 20 74 61 62 6c 65  of what.** table
1dcd0 20 69 6e 20 77 68 69 63 68 20 64 61 74 61 62 61   in which databa
1dce0 73 65 20 61 20 72 65 73 75 6c 74 20 6f 66 20 61  se a result of a
1dcf0 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d   [SELECT] statem
1dd00 65 6e 74 20 63 6f 6d 65 73 20 66 72 6f 6d 2e 0a  ent comes from..
1dd10 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66 20 74  ** The name of t
1dd20 68 65 20 64 61 74 61 62 61 73 65 20 6f 72 20 74  he database or t
1dd30 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 20 63  able or column c
1dd40 61 6e 20 62 65 20 72 65 74 75 72 6e 65 64 20 61  an be returned a
1dd50 73 0a 2a 2a 20 65 69 74 68 65 72 20 61 20 55 54  s.** either a UT
1dd60 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 73 74  F-8 or UTF-16 st
1dd70 72 69 6e 67 2e 20 20 54 68 65 20 5f 64 61 74 61  ring.  The _data
1dd80 62 61 73 65 5f 20 72 6f 75 74 69 6e 65 73 20 72  base_ routines r
1dd90 65 74 75 72 6e 0a 2a 2a 20 74 68 65 20 64 61 74  eturn.** the dat
1dda0 61 62 61 73 65 20 6e 61 6d 65 2c 20 74 68 65 20  abase name, the 
1ddb0 5f 74 61 62 6c 65 5f 20 72 6f 75 74 69 6e 65 73  _table_ routines
1ddc0 20 72 65 74 75 72 6e 20 74 68 65 20 74 61 62 6c   return the tabl
1ddd0 65 20 6e 61 6d 65 2c 20 61 6e 64 0a 2a 2a 20 74  e name, and.** t
1dde0 68 65 20 6f 72 69 67 69 6e 5f 20 72 6f 75 74 69  he origin_ routi
1ddf0 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 63  nes return the c
1de00 6f 6c 75 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a 20 54  olumn name..** T
1de10 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69  he returned stri
1de20 6e 67 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69  ng is valid unti
1de30 6c 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  l the [prepared 
1de40 73 74 61 74 65 6d 65 6e 74 5d 20 69 73 20 64 65  statement] is de
1de50 73 74 72 6f 79 65 64 0a 2a 2a 20 75 73 69 6e 67  stroyed.** using
1de60 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
1de70 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74  ze()] or until t
1de80 68 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74  he same informat
1de90 69 6f 6e 20 69 73 20 72 65 71 75 65 73 74 65 64  ion is requested
1dea0 0a 2a 2a 20 61 67 61 69 6e 20 69 6e 20 61 20 64  .** again in a d
1deb0 69 66 66 65 72 65 6e 74 20 65 6e 63 6f 64 69 6e  ifferent encodin
1dec0 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6e 61 6d  g..**.** The nam
1ded0 65 73 20 72 65 74 75 72 6e 65 64 20 61 72 65 20  es returned are 
1dee0 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 75 6e 2d  the original un-
1def0 61 6c 69 61 73 65 64 20 6e 61 6d 65 73 20 6f 66  aliased names of
1df00 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65   the.** database
1df10 2c 20 74 61 62 6c 65 2c 20 61 6e 64 20 63 6f 6c  , table, and col
1df20 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  umn..**.** The f
1df30 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
1df40 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63   the following c
1df50 61 6c 6c 73 20 69 73 20 61 20 5b 70 72 65 70 61  alls is a [prepa
1df60 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a  red statement]..
1df70 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f  ** These functio
1df80 6e 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d  ns return inform
1df90 61 74 69 6f 6e 20 61 62 6f 75 74 20 74 68 65 20  ation about the 
1dfa0 4e 74 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72  Nth column retur
1dfb0 6e 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 73 74  ned by.** the st
1dfc0 61 74 65 6d 65 6e 74 2c 20 77 68 65 72 65 20 4e  atement, where N
1dfd0 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20 66   is the second f
1dfe0 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74  unction argument
1dff0 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 4e  ..**.** If the N
1e000 74 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e  th column return
1e010 65 64 20 62 79 20 74 68 65 20 73 74 61 74 65 6d  ed by the statem
1e020 65 6e 74 20 69 73 20 61 6e 20 65 78 70 72 65 73  ent is an expres
1e030 73 69 6f 6e 20 6f 72 0a 2a 2a 20 73 75 62 71 75  sion or.** subqu
1e040 65 72 79 20 61 6e 64 20 69 73 20 6e 6f 74 20 61  ery and is not a
1e050 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 2c 20 74   column value, t
1e060 68 65 6e 20 61 6c 6c 20 6f 66 20 74 68 65 73 65  hen all of these
1e070 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72   functions retur
1e080 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20 20 54 68 65 73  n.** NULL.  Thes
1e090 65 20 72 6f 75 74 69 6e 65 20 6d 69 67 68 74 20  e routine might 
1e0a0 61 6c 73 6f 20 72 65 74 75 72 6e 20 4e 55 4c 4c  also return NULL
1e0b0 20 69 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c   if a memory all
1e0c0 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 0a 2a 2a  ocation error.**
1e0d0 20 6f 63 63 75 72 73 2e 20 20 4f 74 68 65 72 77   occurs.  Otherw
1e0e0 69 73 65 2c 20 74 68 65 79 20 72 65 74 75 72 6e  ise, they return
1e0f0 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
1e100 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61   attached databa
1e110 73 65 2c 20 74 61 62 6c 65 0a 2a 2a 20 61 6e 64  se, table.** and
1e120 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 71 75 65   column that que
1e130 72 79 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  ry result column
1e140 20 77 61 73 20 65 78 74 72 61 63 74 65 64 20 66   was extracted f
1e150 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 41 73 20 77 69  rom..**.** As wi
1e160 74 68 20 61 6c 6c 20 6f 74 68 65 72 20 53 51 4c  th all other SQL
1e170 69 74 65 20 41 50 49 73 2c 20 74 68 6f 73 65 20  ite APIs, those 
1e180 70 6f 73 74 66 69 78 65 64 20 77 69 74 68 20 22  postfixed with "
1e190 31 36 22 20 72 65 74 75 72 6e 0a 2a 2a 20 55 54  16" return.** UT
1e1a0 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 73 74 72  F-16 encoded str
1e1b0 69 6e 67 73 2c 20 74 68 65 20 6f 74 68 65 72 20  ings, the other 
1e1c0 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e  functions return
1e1d0 20 55 54 46 2d 38 2e 20 7b 45 4e 44 7d 0a 2a 2a   UTF-8. {END}.**
1e1e0 0a 2a 2a 20 54 68 65 73 65 20 41 50 49 73 20 61  .** These APIs a
1e1f0 72 65 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c  re only availabl
1e200 65 20 69 66 20 74 68 65 20 6c 69 62 72 61 72 79  e if the library
1e210 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69   was compiled wi
1e220 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  th the.** [SQLIT
1e230 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f  E_ENABLE_COLUMN_
1e240 4d 45 54 41 44 41 54 41 5d 20 43 2d 70 72 65 70  METADATA] C-prep
1e250 72 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c 20  rocessor symbol 
1e260 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b  defined..**.** {
1e270 41 31 33 37 35 31 7d 0a 2a 2a 20 49 66 20 74 77  A13751}.** If tw
1e280 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64  o or more thread
1e290 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f  s call one or mo
1e2a0 72 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  re of these rout
1e2b0 69 6e 65 73 20 61 67 61 69 6e 73 74 20 74 68 65  ines against the
1e2c0 20 73 61 6d 65 0a 2a 2a 20 70 72 65 70 61 72 65   same.** prepare
1e2d0 64 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20  d statement and 
1e2e0 63 6f 6c 75 6d 6e 20 61 74 20 74 68 65 20 73 61  column at the sa
1e2f0 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65  me time then the
1e300 20 72 65 73 75 6c 74 73 20 61 72 65 0a 2a 2a 20   results are.** 
1e310 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
1e320 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a   Requirements:.*
1e330 2a 20 5b 48 31 33 37 34 31 5d 20 5b 48 31 33 37  * [H13741] [H137
1e340 34 32 5d 20 5b 48 31 33 37 34 33 5d 20 5b 48 31  42] [H13743] [H1
1e350 33 37 34 34 5d 20 5b 48 31 33 37 34 35 5d 20 5b  3744] [H13745] [
1e360 48 31 33 37 34 36 5d 20 5b 48 31 33 37 34 38 5d  H13746] [H13748]
1e370 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72  .**.** If two or
1e380 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63 61   more threads ca
1e390 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a  ll one or more.*
1e3a0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  * [sqlite3_colum
1e3b0 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 20  n_database_name 
1e3c0 7c 20 63 6f 6c 75 6d 6e 20 6d 65 74 61 64 61 74  | column metadat
1e3d0 61 20 69 6e 74 65 72 66 61 63 65 73 5d 0a 2a 2a  a interfaces].**
1e3e0 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 5b 70   for the same [p
1e3f0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
1e400 74 5d 20 61 6e 64 20 72 65 73 75 6c 74 20 63 6f  t] and result co
1e410 6c 75 6d 6e 0a 2a 2a 20 61 74 20 74 68 65 20 73  lumn.** at the s
1e420 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68  ame time then th
1e430 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e  e results are un
1e440 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 63 6f 6e 73  defined..*/.cons
1e450 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
1e460 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f  column_database_
1e470 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  name(sqlite3_stm
1e480 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76  t*,int);.const v
1e490 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
1e4a0 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d  umn_database_nam
1e4b0 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  e16(sqlite3_stmt
1e4c0 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68  *,int);.const ch
1e4d0 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ar *sqlite3_colu
1e4e0 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 28 73 71  mn_table_name(sq
1e4f0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
1e500 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
1e510 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62  lite3_column_tab
1e520 6c 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65  le_name16(sqlite
1e530 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f  3_stmt*,int);.co
1e540 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
1e550 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f  3_column_origin_
1e560 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  name(sqlite3_stm
1e570 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76  t*,int);.const v
1e580 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
1e590 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 31  umn_origin_name1
1e5a0 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
1e5b0 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  int);../*.** CAP
1e5c0 49 33 52 45 46 3a 20 44 65 63 6c 61 72 65 64 20  I3REF: Declared 
1e5d0 44 61 74 61 74 79 70 65 20 4f 66 20 41 20 51 75  Datatype Of A Qu
1e5e0 65 72 79 20 52 65 73 75 6c 74 20 7b 48 31 33 37  ery Result {H137
1e5f0 36 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 2a 0a  60} <S10700>.**.
1e600 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 61 72  ** The first par
1e610 61 6d 65 74 65 72 20 69 73 20 61 20 5b 70 72 65  ameter is a [pre
1e620 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
1e630 2e 0a 2a 2a 20 49 66 20 74 68 69 73 20 73 74 61  ..** If this sta
1e640 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 53 45 4c  tement is a [SEL
1e650 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 61  ECT] statement a
1e660 6e 64 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d  nd the Nth colum
1e670 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65 74 75  n of the.** retu
1e680 72 6e 65 64 20 72 65 73 75 6c 74 20 73 65 74 20  rned result set 
1e690 6f 66 20 74 68 61 74 20 5b 53 45 4c 45 43 54 5d  of that [SELECT]
1e6a0 20 69 73 20 61 20 74 61 62 6c 65 20 63 6f 6c 75   is a table colu
1e6b0 6d 6e 20 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78  mn (not an.** ex
1e6c0 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71  pression or subq
1e6d0 75 65 72 79 29 20 74 68 65 6e 20 74 68 65 20 64  uery) then the d
1e6e0 65 63 6c 61 72 65 64 20 74 79 70 65 20 6f 66 20  eclared type of 
1e6f0 74 68 65 20 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c  the table.** col
1e700 75 6d 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e  umn is returned.
1e710 20 20 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c    If the Nth col
1e720 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c  umn of the resul
1e730 74 20 73 65 74 20 69 73 20 61 6e 0a 2a 2a 20 65  t set is an.** e
1e740 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62  xpression or sub
1e750 71 75 65 72 79 2c 20 74 68 65 6e 20 61 20 4e 55  query, then a NU
1e760 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65  LL pointer is re
1e770 74 75 72 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 72  turned..** The r
1e780 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69  eturned string i
1e790 73 20 61 6c 77 61 79 73 20 55 54 46 2d 38 20 65  s always UTF-8 e
1e7a0 6e 63 6f 64 65 64 2e 20 7b 45 4e 44 7d 0a 2a 2a  ncoded. {END}.**
1e7b0 0a 2a 2a 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c  .** For example,
1e7c0 20 67 69 76 65 6e 20 74 68 65 20 64 61 74 61 62   given the datab
1e7d0 61 73 65 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a  ase schema:.**.*
1e7e0 2a 20 43 52 45 41 54 45 20 54 41 42 4c 45 20 74  * CREATE TABLE t
1e7f0 31 28 63 31 20 56 41 52 49 41 4e 54 29 3b 0a 2a  1(c1 VARIANT);.*
1e800 2a 0a 2a 2a 20 61 6e 64 20 74 68 65 20 66 6f 6c  *.** and the fol
1e810 6c 6f 77 69 6e 67 20 73 74 61 74 65 6d 65 6e 74  lowing statement
1e820 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 3a   to be compiled:
1e830 0a 2a 2a 0a 2a 2a 20 53 45 4c 45 43 54 20 63 31  .**.** SELECT c1
1e840 20 2b 20 31 2c 20 63 31 20 46 52 4f 4d 20 74 31   + 1, c1 FROM t1
1e850 3b 0a 2a 2a 0a 2a 2a 20 74 68 69 73 20 72 6f 75  ;.**.** this rou
1e860 74 69 6e 65 20 77 6f 75 6c 64 20 72 65 74 75 72  tine would retur
1e870 6e 20 74 68 65 20 73 74 72 69 6e 67 20 22 56 41  n the string "VA
1e880 52 49 41 4e 54 22 20 66 6f 72 20 74 68 65 20 73  RIANT" for the s
1e890 65 63 6f 6e 64 20 72 65 73 75 6c 74 0a 2a 2a 20  econd result.** 
1e8a0 63 6f 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c 20 61  column (i==1), a
1e8b0 6e 64 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  nd a NULL pointe
1e8c0 72 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20  r for the first 
1e8d0 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 28 69  result column (i
1e8e0 3d 3d 30 29 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  ==0)..**.** SQLi
1e8f0 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20  te uses dynamic 
1e900 72 75 6e 2d 74 69 6d 65 20 74 79 70 69 6e 67 2e  run-time typing.
1e910 20 20 53 6f 20 6a 75 73 74 20 62 65 63 61 75 73    So just becaus
1e920 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73  e a column.** is
1e930 20 64 65 63 6c 61 72 65 64 20 74 6f 20 63 6f 6e   declared to con
1e940 74 61 69 6e 20 61 20 70 61 72 74 69 63 75 6c 61  tain a particula
1e950 72 20 74 79 70 65 20 64 6f 65 73 20 6e 6f 74 20  r type does not 
1e960 6d 65 61 6e 20 74 68 61 74 20 74 68 65 0a 2a 2a  mean that the.**
1e970 20 64 61 74 61 20 73 74 6f 72 65 64 20 69 6e 20   data stored in 
1e980 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6f  that column is o
1e990 66 20 74 68 65 20 64 65 63 6c 61 72 65 64 20 74  f the declared t
1e9a0 79 70 65 2e 20 20 53 51 4c 69 74 65 20 69 73 0a  ype.  SQLite is.
1e9b0 2a 2a 20 73 74 72 6f 6e 67 6c 79 20 74 79 70 65  ** strongly type
1e9c0 64 2c 20 62 75 74 20 74 68 65 20 74 79 70 69 6e  d, but the typin
1e9d0 67 20 69 73 20 64 79 6e 61 6d 69 63 20 6e 6f 74  g is dynamic not
1e9e0 20 73 74 61 74 69 63 2e 20 20 54 79 70 65 0a 2a   static.  Type.*
1e9f0 2a 20 69 73 20 61 73 73 6f 63 69 61 74 65 64 20  * is associated 
1ea00 77 69 74 68 20 69 6e 64 69 76 69 64 75 61 6c 20  with individual 
1ea10 76 61 6c 75 65 73 2c 20 6e 6f 74 20 77 69 74 68  values, not with
1ea20 20 74 68 65 20 63 6f 6e 74 61 69 6e 65 72 73 0a   the containers.
1ea30 2a 2a 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20  ** used to hold 
1ea40 74 68 6f 73 65 20 76 61 6c 75 65 73 2e 0a 2a 2a  those values..**
1ea50 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73  .** Requirements
1ea60 3a 0a 2a 2a 20 5b 48 31 33 37 36 31 5d 20 5b 48  :.** [H13761] [H
1ea70 31 33 37 36 32 5d 20 5b 48 31 33 37 36 33 5d 0a  13762] [H13763].
1ea80 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  */.const char *s
1ea90 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65  qlite3_column_de
1eaa0 63 6c 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73  cltype(sqlite3_s
1eab0 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74  tmt*,int);.const
1eac0 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
1ead0 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31 36  olumn_decltype16
1eae0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
1eaf0 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  nt);../*.** CAPI
1eb00 33 52 45 46 3a 20 45 76 61 6c 75 61 74 65 20 41  3REF: Evaluate A
1eb10 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20  n SQL Statement 
1eb20 7b 48 31 33 32 30 30 7d 20 3c 53 31 30 30 30 30  {H13200} <S10000
1eb30 3e 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 61 20  >.**.** After a 
1eb40 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
1eb50 65 6e 74 5d 20 68 61 73 20 62 65 65 6e 20 70 72  ent] has been pr
1eb60 65 70 61 72 65 64 20 75 73 69 6e 67 20 65 69 74  epared using eit
1eb70 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  her.** [sqlite3_
1eb80 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
1eb90 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1eba0 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65  e16_v2()] or one
1ebb0 20 6f 66 20 74 68 65 20 6c 65 67 61 63 79 0a 2a   of the legacy.*
1ebc0 2a 20 69 6e 74 65 72 66 61 63 65 73 20 5b 73 71  * interfaces [sq
1ebd0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d  lite3_prepare()]
1ebe0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   or [sqlite3_pre
1ebf0 70 61 72 65 31 36 28 29 5d 2c 20 74 68 69 73 20  pare16()], this 
1ec00 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74  function.** must
1ec10 20 62 65 20 63 61 6c 6c 65 64 20 6f 6e 65 20 6f   be called one o
1ec20 72 20 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f 20  r more times to 
1ec30 65 76 61 6c 75 61 74 65 20 74 68 65 20 73 74 61  evaluate the sta
1ec40 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68  tement..**.** Th
1ec50 65 20 64 65 74 61 69 6c 73 20 6f 66 20 74 68 65  e details of the
1ec60 20 62 65 68 61 76 69 6f 72 20 6f 66 20 74 68 65   behavior of the
1ec70 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
1ec80 69 6e 74 65 72 66 61 63 65 20 64 65 70 65 6e 64  interface depend
1ec90 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65 72 20 74  .** on whether t
1eca0 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73  he statement was
1ecb0 20 70 72 65 70 61 72 65 64 20 75 73 69 6e 67 20   prepared using 
1ecc0 74 68 65 20 6e 65 77 65 72 20 22 76 32 22 20 69  the newer "v2" i
1ecd0 6e 74 65 72 66 61 63 65 0a 2a 2a 20 5b 73 71 6c  nterface.** [sql
1ece0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
1ecf0 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
1ed00 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20  prepare16_v2()] 
1ed10 6f 72 20 74 68 65 20 6f 6c 64 65 72 20 6c 65 67  or the older leg
1ed20 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  acy.** interface
1ed30 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1ed40 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  e()] and [sqlite
1ed50 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2e 20  3_prepare16()]. 
1ed60 20 54 68 65 20 75 73 65 20 6f 66 20 74 68 65 0a   The use of the.
1ed70 2a 2a 20 6e 65 77 20 22 76 32 22 20 69 6e 74 65  ** new "v2" inte
1ed80 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65  rface is recomme
1ed90 6e 64 65 64 20 66 6f 72 20 6e 65 77 20 61 70 70  nded for new app
1eda0 6c 69 63 61 74 69 6f 6e 73 20 62 75 74 20 74 68  lications but th
1edb0 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65  e legacy.** inte
1edc0 72 66 61 63 65 20 77 69 6c 6c 20 63 6f 6e 74 69  rface will conti
1edd0 6e 75 65 20 74 6f 20 62 65 20 73 75 70 70 6f 72  nue to be suppor
1ede0 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68  ted..**.** In th
1edf0 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61  e legacy interfa
1ee00 63 65 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76  ce, the return v
1ee10 61 6c 75 65 20 77 69 6c 6c 20 62 65 20 65 69 74  alue will be eit
1ee20 68 65 72 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  her [SQLITE_BUSY
1ee30 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f  ],.** [SQLITE_DO
1ee40 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 52 4f 57  NE], [SQLITE_ROW
1ee50 5d 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  ], [SQLITE_ERROR
1ee60 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4d 49  ], or [SQLITE_MI
1ee70 53 55 53 45 5d 2e 0a 2a 2a 20 57 69 74 68 20 74  SUSE]..** With t
1ee80 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  he "v2" interfac
1ee90 65 2c 20 61 6e 79 20 6f 66 20 74 68 65 20 6f 74  e, any of the ot
1eea0 68 65 72 20 5b 72 65 73 75 6c 74 20 63 6f 64 65  her [result code
1eeb0 73 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64  s] or.** [extend
1eec0 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d  ed result codes]
1eed0 20 6d 69 67 68 74 20 62 65 20 72 65 74 75 72 6e   might be return
1eee0 65 64 20 61 73 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a  ed as well..**.*
1eef0 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20  * [SQLITE_BUSY] 
1ef00 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 64  means that the d
1ef10 61 74 61 62 61 73 65 20 65 6e 67 69 6e 65 20 77  atabase engine w
1ef20 61 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 63 71  as unable to acq
1ef30 75 69 72 65 20 74 68 65 0a 2a 2a 20 64 61 74 61  uire the.** data
1ef40 62 61 73 65 20 6c 6f 63 6b 73 20 69 74 20 6e 65  base locks it ne
1ef50 65 64 73 20 74 6f 20 64 6f 20 69 74 73 20 6a 6f  eds to do its jo
1ef60 62 2e 20 20 49 66 20 74 68 65 20 73 74 61 74 65  b.  If the state
1ef70 6d 65 6e 74 20 69 73 20 61 20 5b 43 4f 4d 4d 49  ment is a [COMMI
1ef80 54 5d 0a 2a 2a 20 6f 72 20 6f 63 63 75 72 73 20  T].** or occurs 
1ef90 6f 75 74 73 69 64 65 20 6f 66 20 61 6e 20 65 78  outside of an ex
1efa0 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69  plicit transacti
1efb0 6f 6e 2c 20 74 68 65 6e 20 79 6f 75 20 63 61 6e  on, then you can
1efc0 20 72 65 74 72 79 20 74 68 65 0a 2a 2a 20 73 74   retry the.** st
1efd0 61 74 65 6d 65 6e 74 2e 20 20 49 66 20 74 68 65  atement.  If the
1efe0 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 6f   statement is no
1eff0 74 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 61 6e 64  t a [COMMIT] and
1f000 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20 61   occurs within a
1f010 0a 2a 2a 20 65 78 70 6c 69 63 69 74 20 74 72 61  .** explicit tra
1f020 6e 73 61 63 74 69 6f 6e 20 74 68 65 6e 20 79 6f  nsaction then yo
1f030 75 20 73 68 6f 75 6c 64 20 72 6f 6c 6c 62 61 63  u should rollbac
1f040 6b 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f  k the transactio
1f050 6e 20 62 65 66 6f 72 65 0a 2a 2a 20 63 6f 6e 74  n before.** cont
1f060 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5b 53  inuing..**.** [S
1f070 51 4c 49 54 45 5f 44 4f 4e 45 5d 20 6d 65 61 6e  QLITE_DONE] mean
1f080 73 20 74 68 61 74 20 74 68 65 20 73 74 61 74 65  s that the state
1f090 6d 65 6e 74 20 68 61 73 20 66 69 6e 69 73 68 65  ment has finishe
1f0a0 64 20 65 78 65 63 75 74 69 6e 67 0a 2a 2a 20 73  d executing.** s
1f0b0 75 63 63 65 73 73 66 75 6c 6c 79 2e 20 20 73 71  uccessfully.  sq
1f0c0 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f  lite3_step() sho
1f0d0 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65  uld not be calle
1f0e0 64 20 61 67 61 69 6e 20 6f 6e 20 74 68 69 73 20  d again on this 
1f0f0 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69  virtual.** machi
1f100 6e 65 20 77 69 74 68 6f 75 74 20 66 69 72 73 74  ne without first
1f110 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   calling [sqlite
1f120 33 5f 72 65 73 65 74 28 29 5d 20 74 6f 20 72 65  3_reset()] to re
1f130 73 65 74 20 74 68 65 20 76 69 72 74 75 61 6c 0a  set the virtual.
1f140 2a 2a 20 6d 61 63 68 69 6e 65 20 62 61 63 6b 20  ** machine back 
1f150 74 6f 20 69 74 73 20 69 6e 69 74 69 61 6c 20 73  to its initial s
1f160 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  tate..**.** If t
1f170 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
1f180 20 62 65 69 6e 67 20 65 78 65 63 75 74 65 64 20   being executed 
1f190 72 65 74 75 72 6e 73 20 61 6e 79 20 64 61 74 61  returns any data
1f1a0 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 52  , then [SQLITE_R
1f1b0 4f 57 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e  OW].** is return
1f1c0 65 64 20 65 61 63 68 20 74 69 6d 65 20 61 20 6e  ed each time a n
1f1d0 65 77 20 72 6f 77 20 6f 66 20 64 61 74 61 20 69  ew row of data i
1f1e0 73 20 72 65 61 64 79 20 66 6f 72 20 70 72 6f 63  s ready for proc
1f1f0 65 73 73 69 6e 67 20 62 79 20 74 68 65 0a 2a 2a  essing by the.**
1f200 20 63 61 6c 6c 65 72 2e 20 54 68 65 20 76 61 6c   caller. The val
1f210 75 65 73 20 6d 61 79 20 62 65 20 61 63 63 65 73  ues may be acces
1f220 73 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b 63  sed using the [c
1f230 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e  olumn access fun
1f240 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 73 71 6c 69  ctions]..** sqli
1f250 74 65 33 5f 73 74 65 70 28 29 20 69 73 20 63 61  te3_step() is ca
1f260 6c 6c 65 64 20 61 67 61 69 6e 20 74 6f 20 72 65  lled again to re
1f270 74 72 69 65 76 65 20 74 68 65 20 6e 65 78 74 20  trieve the next 
1f280 72 6f 77 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a  row of data..**.
1f290 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  ** [SQLITE_ERROR
1f2a0 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 61 20 72  ] means that a r
1f2b0 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72 20 28 73  un-time error (s
1f2c0 75 63 68 20 61 73 20 61 20 63 6f 6e 73 74 72 61  uch as a constra
1f2d0 69 6e 74 0a 2a 2a 20 76 69 6f 6c 61 74 69 6f 6e  int.** violation
1f2e0 29 20 68 61 73 20 6f 63 63 75 72 72 65 64 2e 20  ) has occurred. 
1f2f0 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
1f300 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61  should not be ca
1f310 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 0a 2a 2a  lled again on.**
1f320 20 74 68 65 20 56 4d 2e 20 4d 6f 72 65 20 69 6e   the VM. More in
1f330 66 6f 72 6d 61 74 69 6f 6e 20 6d 61 79 20 62 65  formation may be
1f340 20 66 6f 75 6e 64 20 62 79 20 63 61 6c 6c 69 6e   found by callin
1f350 67 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  g [sqlite3_errms
1f360 67 28 29 5d 2e 0a 2a 2a 20 57 69 74 68 20 74 68  g()]..** With th
1f370 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61  e legacy interfa
1f380 63 65 2c 20 61 20 6d 6f 72 65 20 73 70 65 63 69  ce, a more speci
1f390 66 69 63 20 65 72 72 6f 72 20 63 6f 64 65 20 28  fic error code (
1f3a0 66 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20  for example,.** 
1f3b0 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50  [SQLITE_INTERRUP
1f3c0 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 53 43 48 45  T], [SQLITE_SCHE
1f3d0 4d 41 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 52  MA], [SQLITE_COR
1f3e0 52 55 50 54 5d 2c 20 61 6e 64 20 73 6f 20 66 6f  RUPT], and so fo
1f3f0 72 74 68 29 0a 2a 2a 20 63 61 6e 20 62 65 20 6f  rth).** can be o
1f400 62 74 61 69 6e 65 64 20 62 79 20 63 61 6c 6c 69  btained by calli
1f410 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ng [sqlite3_rese
1f420 74 28 29 5d 20 6f 6e 20 74 68 65 0a 2a 2a 20 5b  t()] on the.** [
1f430 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
1f440 6e 74 5d 2e 20 20 49 6e 20 74 68 65 20 22 76 32  nt].  In the "v2
1f450 22 20 69 6e 74 65 72 66 61 63 65 2c 0a 2a 2a 20  " interface,.** 
1f460 74 68 65 20 6d 6f 72 65 20 73 70 65 63 69 66 69  the more specifi
1f470 63 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20  c error code is 
1f480 72 65 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c  returned directl
1f490 79 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65  y by sqlite3_ste
1f4a0 70 28 29 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49  p()..**.** [SQLI
1f4b0 54 45 5f 4d 49 53 55 53 45 5d 20 6d 65 61 6e 73  TE_MISUSE] means
1f4c0 20 74 68 61 74 20 74 68 65 20 74 68 69 73 20 72   that the this r
1f4d0 6f 75 74 69 6e 65 20 77 61 73 20 63 61 6c 6c 65  outine was calle
1f4e0 64 20 69 6e 61 70 70 72 6f 70 72 69 61 74 65 6c  d inappropriatel
1f4f0 79 2e 0a 2a 2a 20 50 65 72 68 61 70 73 20 69 74  y..** Perhaps it
1f500 20 77 61 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61   was called on a
1f510 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
1f520 6d 65 6e 74 5d 20 74 68 61 74 20 68 61 73 0a 2a  ment] that has.*
1f530 2a 20 61 6c 72 65 61 64 79 20 62 65 65 6e 20 5b  * already been [
1f540 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
1f550 20 7c 20 66 69 6e 61 6c 69 7a 65 64 5d 20 6f 72   | finalized] or
1f560 20 6f 6e 20 6f 6e 65 20 74 68 61 74 20 68 61 64   on one that had
1f570 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 72  .** previously r
1f580 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f  eturned [SQLITE_
1f590 45 52 52 4f 52 5d 20 6f 72 20 5b 53 51 4c 49 54  ERROR] or [SQLIT
1f5a0 45 5f 44 4f 4e 45 5d 2e 20 20 4f 72 20 69 74 20  E_DONE].  Or it 
1f5b0 63 6f 75 6c 64 0a 2a 2a 20 62 65 20 74 68 65 20  could.** be the 
1f5c0 63 61 73 65 20 74 68 61 74 20 74 68 65 20 73 61  case that the sa
1f5d0 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  me database conn
1f5e0 65 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20  ection is being 
1f5f0 75 73 65 64 20 62 79 20 74 77 6f 20 6f 72 0a 2a  used by two or.*
1f600 2a 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 61  * more threads a
1f610 74 20 74 68 65 20 73 61 6d 65 20 6d 6f 6d 65 6e  t the same momen
1f620 74 20 69 6e 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a  t in time..**.**
1f630 20 3c 62 3e 47 6f 6f 66 79 20 49 6e 74 65 72 66   <b>Goofy Interf
1f640 61 63 65 20 41 6c 65 72 74 3a 3c 2f 62 3e 20 49  ace Alert:</b> I
1f650 6e 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74  n the legacy int
1f660 65 72 66 61 63 65 2c 20 74 68 65 20 73 71 6c 69  erface, the sqli
1f670 74 65 33 5f 73 74 65 70 28 29 0a 2a 2a 20 41 50  te3_step().** AP
1f680 49 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73  I always returns
1f690 20 61 20 67 65 6e 65 72 69 63 20 65 72 72 6f 72   a generic error
1f6a0 20 63 6f 64 65 2c 20 5b 53 51 4c 49 54 45 5f 45   code, [SQLITE_E
1f6b0 52 52 4f 52 5d 2c 20 66 6f 6c 6c 6f 77 69 6e 67  RROR], following
1f6c0 20 61 6e 79 0a 2a 2a 20 65 72 72 6f 72 20 6f 74   any.** error ot
1f6d0 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45  her than [SQLITE
1f6e0 5f 42 55 53 59 5d 20 61 6e 64 20 5b 53 51 4c 49  _BUSY] and [SQLI
1f6f0 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 59 6f 75  TE_MISUSE].  You
1f700 20 6d 75 73 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73   must call.** [s
1f710 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
1f720 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  or [sqlite3_fina
1f730 6c 69 7a 65 28 29 5d 20 69 6e 20 6f 72 64 65 72  lize()] in order
1f740 20 74 6f 20 66 69 6e 64 20 6f 6e 65 20 6f 66 20   to find one of 
1f750 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20  the.** specific 
1f760 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 74 68  [error codes] th
1f770 61 74 20 62 65 74 74 65 72 20 64 65 73 63 72 69  at better descri
1f780 62 65 73 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a  bes the error..*
1f790 2a 20 57 65 20 61 64 6d 69 74 20 74 68 61 74 20  * We admit that 
1f7a0 74 68 69 73 20 69 73 20 61 20 67 6f 6f 66 79 20  this is a goofy 
1f7b0 64 65 73 69 67 6e 2e 20 20 54 68 65 20 70 72 6f  design.  The pro
1f7c0 62 6c 65 6d 20 68 61 73 20 62 65 65 6e 20 66 69  blem has been fi
1f7d0 78 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20  xed.** with the 
1f7e0 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2e 20  "v2" interface. 
1f7f0 20 49 66 20 79 6f 75 20 70 72 65 70 61 72 65 20   If you prepare 
1f800 61 6c 6c 20 6f 66 20 79 6f 75 72 20 53 51 4c 20  all of your SQL 
1f810 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 75 73  statements.** us
1f820 69 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69  ing either [sqli
1f830 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
1f840 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72  ] or [sqlite3_pr
1f850 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 69 6e  epare16_v2()] in
1f860 73 74 65 61 64 0a 2a 2a 20 6f 66 20 74 68 65 20  stead.** of the 
1f870 6c 65 67 61 63 79 20 5b 73 71 6c 69 74 65 33 5f  legacy [sqlite3_
1f880 70 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b  prepare()] and [
1f890 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
1f8a0 36 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 2c  6()] interfaces,
1f8b0 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 6d 6f 72  .** then the mor
1f8c0 65 20 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f  e specific [erro
1f8d0 72 20 63 6f 64 65 73 5d 20 61 72 65 20 72 65 74  r codes] are ret
1f8e0 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79 0a 2a  urned directly.*
1f8f0 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65  * by sqlite3_ste
1f900 70 28 29 2e 20 20 54 68 65 20 75 73 65 20 6f 66  p().  The use of
1f910 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66   the "v2" interf
1f920 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64  ace is recommend
1f930 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72  ed..**.** Requir
1f940 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 33 32  ements:.** [H132
1f950 30 32 5d 20 5b 48 31 35 33 30 34 5d 20 5b 48 31  02] [H15304] [H1
1f960 35 33 30 36 5d 20 5b 48 31 35 33 30 38 5d 20 5b  5306] [H15308] [
1f970 48 31 35 33 31 30 5d 0a 2a 2f 0a 69 6e 74 20 73  H15310].*/.int s
1f980 71 6c 69 74 65 33 5f 73 74 65 70 28 73 71 6c 69  qlite3_step(sqli
1f990 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a  te3_stmt*);../*.
1f9a0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d  ** CAPI3REF: Num
1f9b0 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
1f9c0 6e 20 61 20 72 65 73 75 6c 74 20 73 65 74 20 7b  n a result set {
1f9d0 48 31 33 37 37 30 7d 20 3c 53 31 30 37 30 30 3e  H13770} <S10700>
1f9e0 0a 2a 2a 0a 2a 2a 20 52 65 74 75 72 6e 73 20 74  .**.** Returns t
1f9f0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 76 61 6c  he number of val
1fa00 75 65 73 20 69 6e 20 74 68 65 20 63 75 72 72 65  ues in the curre
1fa10 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65  nt row of the re
1fa20 73 75 6c 74 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20  sult set..**.** 
1fa30 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a  Requirements:.**
1fa40 20 5b 48 31 33 37 37 31 5d 20 5b 48 31 33 37 37   [H13771] [H1377
1fa50 32 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  2].*/.int sqlite
1fa60 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 73 71 6c  3_data_count(sql
1fa70 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
1fa80 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1fa90 45 46 3a 20 46 75 6e 64 61 6d 65 6e 74 61 6c 20  EF: Fundamental 
1faa0 44 61 74 61 74 79 70 65 73 20 7b 48 31 30 32 36  Datatypes {H1026
1fab0 35 7d 20 3c 53 31 30 31 31 30 3e 3c 53 31 30 31  5} <S10110><S101
1fac0 32 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  20>.** KEYWORDS:
1fad0 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 2a 2a 0a   SQLITE_TEXT.**.
1fae0 2a 2a 20 7b 48 31 30 32 36 36 7d 20 45 76 65 72  ** {H10266} Ever
1faf0 79 20 76 61 6c 75 65 20 69 6e 20 53 51 4c 69 74  y value in SQLit
1fb00 65 20 68 61 73 20 6f 6e 65 20 6f 66 20 66 69 76  e has one of fiv
1fb10 65 20 66 75 6e 64 61 6d 65 6e 74 61 6c 20 64 61  e fundamental da
1fb20 74 61 74 79 70 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c  tatypes:.**.** <
1fb30 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62  ul>.** <li> 64-b
1fb40 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65  it signed intege
1fb50 72 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74  r.** <li> 64-bit
1fb60 20 49 45 45 45 20 66 6c 6f 61 74 69 6e 67 20 70   IEEE floating p
1fb70 6f 69 6e 74 20 6e 75 6d 62 65 72 0a 2a 2a 20 3c  oint number.** <
1fb80 6c 69 3e 20 73 74 72 69 6e 67 0a 2a 2a 20 3c 6c  li> string.** <l
1fb90 69 3e 20 42 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e 20  i> BLOB.** <li> 
1fba0 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e 20 7b 45  NULL.** </ul> {E
1fbb0 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ND}.**.** These 
1fbc0 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 63 6f  constants are co
1fbd0 64 65 73 20 66 6f 72 20 65 61 63 68 20 6f 66 20  des for each of 
1fbe0 74 68 6f 73 65 20 74 79 70 65 73 2e 0a 2a 2a 0a  those types..**.
1fbf0 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65  ** Note that the
1fc00 20 53 51 4c 49 54 45 5f 54 45 58 54 20 63 6f 6e   SQLITE_TEXT con
1fc10 73 74 61 6e 74 20 77 61 73 20 61 6c 73 6f 20 75  stant was also u
1fc20 73 65 64 20 69 6e 20 53 51 4c 69 74 65 20 76 65  sed in SQLite ve
1fc30 72 73 69 6f 6e 20 32 0a 2a 2a 20 66 6f 72 20 61  rsion 2.** for a
1fc40 20 63 6f 6d 70 6c 65 74 65 6c 79 20 64 69 66 66   completely diff
1fc50 65 72 65 6e 74 20 6d 65 61 6e 69 6e 67 2e 20 20  erent meaning.  
1fc60 53 6f 66 74 77 61 72 65 20 74 68 61 74 20 6c 69  Software that li
1fc70 6e 6b 73 20 61 67 61 69 6e 73 74 20 62 6f 74 68  nks against both
1fc80 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 73 69  .** SQLite versi
1fc90 6f 6e 20 32 20 61 6e 64 20 53 51 4c 69 74 65 20  on 2 and SQLite 
1fca0 76 65 72 73 69 6f 6e 20 33 20 73 68 6f 75 6c 64  version 3 should
1fcb0 20 75 73 65 20 53 51 4c 49 54 45 33 5f 54 45 58   use SQLITE3_TEX
1fcc0 54 2c 20 6e 6f 74 0a 2a 2a 20 53 51 4c 49 54 45  T, not.** SQLITE
1fcd0 5f 54 45 58 54 2e 0a 2a 2f 0a 23 64 65 66 69 6e  _TEXT..*/.#defin
1fce0 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52  e SQLITE_INTEGER
1fcf0 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    1.#define SQLI
1fd00 54 45 5f 46 4c 4f 41 54 20 20 20 20 32 0a 23 64  TE_FLOAT    2.#d
1fd10 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 4c 4f  efine SQLITE_BLO
1fd20 42 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20  B     4.#define 
1fd30 53 51 4c 49 54 45 5f 4e 55 4c 4c 20 20 20 20 20  SQLITE_NULL     
1fd40 35 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f  5.#ifdef SQLITE_
1fd50 54 45 58 54 0a 23 20 75 6e 64 65 66 20 53 51 4c  TEXT.# undef SQL
1fd60 49 54 45 5f 54 45 58 54 0a 23 65 6c 73 65 0a 23  ITE_TEXT.#else.#
1fd70 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54   define SQLITE_T
1fd80 45 58 54 20 20 20 20 20 33 0a 23 65 6e 64 69 66  EXT     3.#endif
1fd90 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 33  .#define SQLITE3
1fda0 5f 54 45 58 54 20 20 20 20 20 33 0a 0a 2f 2a 0a  _TEXT     3../*.
1fdb0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73  ** CAPI3REF: Res
1fdc0 75 6c 74 20 56 61 6c 75 65 73 20 46 72 6f 6d 20  ult Values From 
1fdd0 41 20 51 75 65 72 79 20 7b 48 31 33 38 30 30 7d  A Query {H13800}
1fde0 20 3c 53 31 30 37 30 30 3e 0a 2a 2a 20 4b 45 59   <S10700>.** KEY
1fdf0 57 4f 52 44 53 3a 20 7b 63 6f 6c 75 6d 6e 20 61  WORDS: {column a
1fe00 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 7d  ccess functions}
1fe10 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
1fe20 74 69 6e 65 73 20 66 6f 72 6d 20 74 68 65 20 22  tines form the "
1fe30 72 65 73 75 6c 74 20 73 65 74 20 71 75 65 72 79  result set query
1fe40 22 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a  " interface..**.
1fe50 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
1fe60 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61  s return informa
1fe70 74 69 6f 6e 20 61 62 6f 75 74 20 61 20 73 69 6e  tion about a sin
1fe80 67 6c 65 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68  gle column of th
1fe90 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65 73  e current.** res
1fea0 75 6c 74 20 72 6f 77 20 6f 66 20 61 20 71 75 65  ult row of a que
1feb0 72 79 2e 20 20 49 6e 20 65 76 65 72 79 20 63 61  ry.  In every ca
1fec0 73 65 20 74 68 65 20 66 69 72 73 74 20 61 72 67  se the first arg
1fed0 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74  ument is a point
1fee0 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 70 72  er.** to the [pr
1fef0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
1ff00 5d 20 74 68 61 74 20 69 73 20 62 65 69 6e 67 20  ] that is being 
1ff10 65 76 61 6c 75 61 74 65 64 20 28 74 68 65 20 5b  evaluated (the [
1ff20 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 0a 2a  sqlite3_stmt*].*
1ff30 2a 20 74 68 61 74 20 77 61 73 20 72 65 74 75 72  * that was retur
1ff40 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ned from [sqlite
1ff50 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
1ff60 6f 72 20 6f 6e 65 20 6f 66 20 69 74 73 20 76 61  or one of its va
1ff70 72 69 61 6e 74 73 29 0a 2a 2a 20 61 6e 64 20 74  riants).** and t
1ff80 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
1ff90 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65 78 20  nt is the index 
1ffa0 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 66 6f  of the column fo
1ffb0 72 20 77 68 69 63 68 20 69 6e 66 6f 72 6d 61 74  r which informat
1ffc0 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65  ion.** should be
1ffd0 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20   returned.  The 
1ffe0 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20  leftmost column 
1fff0 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  of the result se
20000 74 20 68 61 73 20 74 68 65 20 69 6e 64 65 78 20  t has the index 
20010 30 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  0..**.** If the 
20020 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 64 6f  SQL statement do
20030 65 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79  es not currently
20040 20 70 6f 69 6e 74 20 74 6f 20 61 20 76 61 6c 69   point to a vali
20050 64 20 72 6f 77 2c 20 6f 72 20 69 66 20 74 68 65  d row, or if the
20060 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 6e 64 65 78  .** column index
20070 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65   is out of range
20080 2c 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  , the result is 
20090 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68  undefined..** Th
200a0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 61 79  ese routines may
200b0 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20   only be called 
200c0 77 68 65 6e 20 74 68 65 20 6d 6f 73 74 20 72 65  when the most re
200d0 63 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20  cent call to.** 
200e0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
200f0 20 68 61 73 20 72 65 74 75 72 6e 65 64 20 5b 53   has returned [S
20100 51 4c 49 54 45 5f 52 4f 57 5d 20 61 6e 64 20 6e  QLITE_ROW] and n
20110 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74  either.** [sqlit
20120 65 33 5f 72 65 73 65 74 28 29 5d 20 6e 6f 72 20  e3_reset()] nor 
20130 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
20140 65 28 29 5d 20 68 61 76 65 20 62 65 65 6e 20 63  e()] have been c
20150 61 6c 6c 65 64 20 73 75 62 73 65 71 75 65 6e 74  alled subsequent
20160 6c 79 2e 0a 2a 2a 20 49 66 20 61 6e 79 20 6f 66  ly..** If any of
20170 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
20180 61 72 65 20 63 61 6c 6c 65 64 20 61 66 74 65 72  are called after
20190 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
201a0 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  )] or.** [sqlite
201b0 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72  3_finalize()] or
201c0 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f   after [sqlite3_
201d0 73 74 65 70 28 29 5d 20 68 61 73 20 72 65 74 75  step()] has retu
201e0 72 6e 65 64 0a 2a 2a 20 73 6f 6d 65 74 68 69 6e  rned.** somethin
201f0 67 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51  g other than [SQ
20200 4c 49 54 45 5f 52 4f 57 5d 2c 20 74 68 65 20 72  LITE_ROW], the r
20210 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66  esults are undef
20220 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 5b 73 71 6c  ined..** If [sql
20230 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20  ite3_step()] or 
20240 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
20250 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69  ] or [sqlite3_fi
20260 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20 61 72 65  nalize()].** are
20270 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61 20 64   called from a d
20280 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 20  ifferent thread 
20290 77 68 69 6c 65 20 61 6e 79 20 6f 66 20 74 68 65  while any of the
202a0 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 61  se routines.** a
202b0 72 65 20 70 65 6e 64 69 6e 67 2c 20 74 68 65 6e  re pending, then
202c0 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65   the results are
202d0 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
202e0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f  * The sqlite3_co
202f0 6c 75 6d 6e 5f 74 79 70 65 28 29 20 72 6f 75 74  lumn_type() rout
20300 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 0a  ine returns the.
20310 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47  ** [SQLITE_INTEG
20320 45 52 20 7c 20 64 61 74 61 74 79 70 65 20 63 6f  ER | datatype co
20330 64 65 5d 20 66 6f 72 20 74 68 65 20 69 6e 69 74  de] for the init
20340 69 61 6c 20 64 61 74 61 20 74 79 70 65 0a 2a 2a  ial data type.**
20350 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 63   of the result c
20360 6f 6c 75 6d 6e 2e 20 20 54 68 65 20 72 65 74 75  olumn.  The retu
20370 72 6e 65 64 20 76 61 6c 75 65 20 69 73 20 6f 6e  rned value is on
20380 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e 54  e of [SQLITE_INT
20390 45 47 45 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54  EGER],.** [SQLIT
203a0 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49 54  E_FLOAT], [SQLIT
203b0 45 5f 54 45 58 54 5d 2c 20 5b 53 51 4c 49 54 45  E_TEXT], [SQLITE
203c0 5f 42 4c 4f 42 5d 2c 20 6f 72 20 5b 53 51 4c 49  _BLOB], or [SQLI
203d0 54 45 5f 4e 55 4c 4c 5d 2e 20 20 54 68 65 20 76  TE_NULL].  The v
203e0 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64  alue.** returned
203f0 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   by sqlite3_colu
20400 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 6f 6e 6c  mn_type() is onl
20410 79 20 6d 65 61 6e 69 6e 67 66 75 6c 20 69 66 20  y meaningful if 
20420 6e 6f 20 74 79 70 65 0a 2a 2a 20 63 6f 6e 76 65  no type.** conve
20430 72 73 69 6f 6e 73 20 68 61 76 65 20 6f 63 63 75  rsions have occu
20440 72 72 65 64 20 61 73 20 64 65 73 63 72 69 62 65  rred as describe
20450 64 20 62 65 6c 6f 77 2e 20 20 41 66 74 65 72 20  d below.  After 
20460 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f  a type conversio
20470 6e 2c 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20  n,.** the value 
20480 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
20490 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28  te3_column_type(
204a0 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 20  ) is undefined. 
204b0 20 46 75 74 75 72 65 0a 2a 2a 20 76 65 72 73 69   Future.** versi
204c0 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 61  ons of SQLite ma
204d0 79 20 63 68 61 6e 67 65 20 74 68 65 20 62 65 68  y change the beh
204e0 61 76 69 6f 72 20 6f 66 20 73 71 6c 69 74 65 33  avior of sqlite3
204f0 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 0a 2a  _column_type().*
20500 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 74 79  * following a ty
20510 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a  pe conversion..*
20520 2a 0a 2a 2a 20 49 66 20 74 68 65 20 72 65 73 75  *.** If the resu
20530 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20  lt is a BLOB or 
20540 55 54 46 2d 38 20 73 74 72 69 6e 67 20 74 68 65  UTF-8 string the
20550 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f  n the sqlite3_co
20560 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a 2a 20  lumn_bytes().** 
20570 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
20580 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
20590 74 65 73 20 69 6e 20 74 68 61 74 20 42 4c 4f 42  tes in that BLOB
205a0 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 49   or string..** I
205b0 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
205c0 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2c  a UTF-16 string,
205d0 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f   then sqlite3_co
205e0 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 63 6f 6e  lumn_bytes() con
205f0 76 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 74 72  verts.** the str
20600 69 6e 67 20 74 6f 20 55 54 46 2d 38 20 61 6e 64  ing to UTF-8 and
20610 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20 74 68   then returns th
20620 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
20630 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20 72 65 73  s..** If the res
20640 75 6c 74 20 69 73 20 61 20 6e 75 6d 65 72 69 63  ult is a numeric
20650 20 76 61 6c 75 65 20 74 68 65 6e 20 73 71 6c 69   value then sqli
20660 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
20670 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69  () uses.** [sqli
20680 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20  te3_snprintf()] 
20690 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 61 74 20  to convert that 
206a0 76 61 6c 75 65 20 74 6f 20 61 20 55 54 46 2d 38  value to a UTF-8
206b0 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75   string and retu
206c0 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65  rns.** the numbe
206d0 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
206e0 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 54 68  at string..** Th
206f0 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
20700 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64   does not includ
20710 65 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69  e the zero termi
20720 6e 61 74 6f 72 20 61 74 20 74 68 65 20 65 6e 64  nator at the end
20730 0a 2a 2a 20 6f 66 20 74 68 65 20 73 74 72 69 6e  .** of the strin
20740 67 2e 20 20 46 6f 72 20 63 6c 61 72 69 74 79 3a  g.  For clarity:
20750 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
20760 6e 65 64 20 69 73 20 74 68 65 20 6e 75 6d 62 65  ned is the numbe
20770 72 20 6f 66 0a 2a 2a 20 62 79 74 65 73 20 69 6e  r of.** bytes in
20780 20 74 68 65 20 73 74 72 69 6e 67 2c 20 6e 6f 74   the string, not
20790 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
207a0 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a  haracters..**.**
207b0 20 53 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65   Strings returne
207c0 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c  d by sqlite3_col
207d0 75 6d 6e 5f 74 65 78 74 28 29 20 61 6e 64 20 73  umn_text() and s
207e0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
207f0 78 74 31 36 28 29 2c 0a 2a 2a 20 65 76 65 6e 20  xt16(),.** even 
20800 65 6d 70 74 79 20 73 74 72 69 6e 67 73 2c 20 61  empty strings, a
20810 72 65 20 61 6c 77 61 79 73 20 7a 65 72 6f 20 74  re always zero t
20820 65 72 6d 69 6e 61 74 65 64 2e 20 20 54 68 65 20  erminated.  The 
20830 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20  return.** value 
20840 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6c  from sqlite3_col
20850 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 72 20 61  umn_blob() for a
20860 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f   zero-length BLO
20870 42 20 69 73 20 61 6e 20 61 72 62 69 74 72 61 72  B is an arbitrar
20880 79 0a 2a 2a 20 70 6f 69 6e 74 65 72 2c 20 70 6f  y.** pointer, po
20890 73 73 69 62 6c 79 20 65 76 65 6e 20 61 20 4e 55  ssibly even a NU
208a0 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a  LL pointer..**.*
208b0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f  * The sqlite3_co
208c0 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 72  lumn_bytes16() r
208d0 6f 75 74 69 6e 65 20 69 73 20 73 69 6d 69 6c 61  outine is simila
208e0 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c  r to sqlite3_col
208f0 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a 2a 20 62  umn_bytes().** b
20900 75 74 20 6c 65 61 76 65 73 20 74 68 65 20 72 65  ut leaves the re
20910 73 75 6c 74 20 69 6e 20 55 54 46 2d 31 36 20 69  sult in UTF-16 i
20920 6e 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  n native byte or
20930 64 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20 55  der instead of U
20940 54 46 2d 38 2e 0a 2a 2a 20 54 68 65 20 7a 65 72  TF-8..** The zer
20950 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 69 73 20  o terminator is 
20960 6e 6f 74 20 69 6e 63 6c 75 64 65 64 20 69 6e 20  not included in 
20970 74 68 69 73 20 63 6f 75 6e 74 2e 0a 2a 2a 0a 2a  this count..**.*
20980 2a 20 54 68 65 20 6f 62 6a 65 63 74 20 72 65 74  * The object ret
20990 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65  urned by [sqlite
209a0 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29  3_column_value()
209b0 5d 20 69 73 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72  ] is an.** [unpr
209c0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
209d0 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 2e 20 20  value] object.  
209e0 41 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73  An unprotected s
209f0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
20a00 65 63 74 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20  ect.** may only 
20a10 62 65 20 75 73 65 64 20 77 69 74 68 20 5b 73 71  be used with [sq
20a20 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65  lite3_bind_value
20a30 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
20a40 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d  _result_value()]
20a50 2e 0a 2a 2a 20 49 66 20 74 68 65 20 5b 75 6e 70  ..** If the [unp
20a60 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
20a70 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 72  _value] object r
20a80 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73  eturned by.** [s
20a90 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61  qlite3_column_va
20aa0 6c 75 65 28 29 5d 20 69 73 20 75 73 65 64 20 69  lue()] is used i
20ab0 6e 20 61 6e 79 20 6f 74 68 65 72 20 77 61 79 2c  n any other way,
20ac0 20 69 6e 63 6c 75 64 69 6e 67 20 63 61 6c 6c 73   including calls
20ad0 0a 2a 2a 20 74 6f 20 72 6f 75 74 69 6e 65 73 20  .** to routines 
20ae0 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 76 61  like [sqlite3_va
20af0 6c 75 65 5f 69 6e 74 28 29 5d 2c 20 5b 73 71 6c  lue_int()], [sql
20b00 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28  ite3_value_text(
20b10 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74  )],.** or [sqlit
20b20 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 29  e3_value_bytes()
20b30 5d 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61  ], then the beha
20b40 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65  vior is undefine
20b50 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  d..**.** These r
20b60 6f 75 74 69 6e 65 73 20 61 74 74 65 6d 70 74 20  outines attempt 
20b70 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20 76  to convert the v
20b80 61 6c 75 65 20 77 68 65 72 65 20 61 70 70 72 6f  alue where appro
20b90 70 72 69 61 74 65 2e 20 20 46 6f 72 0a 2a 2a 20  priate.  For.** 
20ba0 65 78 61 6d 70 6c 65 2c 20 69 66 20 74 68 65 20  example, if the 
20bb0 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65  internal represe
20bc0 6e 74 61 74 69 6f 6e 20 69 73 20 46 4c 4f 41 54  ntation is FLOAT
20bd0 20 61 6e 64 20 61 20 74 65 78 74 20 72 65 73 75   and a text resu
20be0 6c 74 0a 2a 2a 20 69 73 20 72 65 71 75 65 73 74  lt.** is request
20bf0 65 64 2c 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70  ed, [sqlite3_snp
20c00 72 69 6e 74 66 28 29 5d 20 69 73 20 75 73 65 64  rintf()] is used
20c10 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20 70   internally to p
20c20 65 72 66 6f 72 6d 20 74 68 65 0a 2a 2a 20 63 6f  erform the.** co
20c30 6e 76 65 72 73 69 6f 6e 20 61 75 74 6f 6d 61 74  nversion automat
20c40 69 63 61 6c 6c 79 2e 20 20 54 68 65 20 66 6f 6c  ically.  The fol
20c50 6c 6f 77 69 6e 67 20 74 61 62 6c 65 20 64 65 74  lowing table det
20c60 61 69 6c 73 20 74 68 65 20 63 6f 6e 76 65 72 73  ails the convers
20c70 69 6f 6e 73 0a 2a 2a 20 74 68 61 74 20 61 72 65  ions.** that are
20c80 20 61 70 70 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a 20   applied:.**.** 
20c90 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20  <blockquote>.** 
20ca0 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 31  <table border="1
20cb0 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 49  ">.** <tr><th> I
20cc0 6e 74 65 72 6e 61 6c 3c 62 72 3e 54 79 70 65 20  nternal<br>Type 
20cd0 3c 74 68 3e 20 52 65 71 75 65 73 74 65 64 3c 62  <th> Requested<b
20ce0 72 3e 54 79 70 65 20 3c 74 68 3e 20 20 43 6f 6e  r>Type <th>  Con
20cf0 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74  version.**.** <t
20d00 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20  r><td>  NULL    
20d10 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c  <td> INTEGER   <
20d20 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30 0a  td> Result is 0.
20d30 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c  ** <tr><td>  NUL
20d40 4c 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54  L    <td>  FLOAT
20d50 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20      <td> Result 
20d60 69 73 20 30 2e 30 0a 2a 2a 20 3c 74 72 3e 3c 74  is 0.0.** <tr><t
20d70 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e  d>  NULL    <td>
20d80 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20     TEXT    <td> 
20d90 52 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 20 70  Result is NULL p
20da0 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74  ointer.** <tr><t
20db0 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e  d>  NULL    <td>
20dc0 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20     BLOB    <td> 
20dd0 52 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 20 70  Result is NULL p
20de0 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74  ointer.** <tr><t
20df0 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e  d> INTEGER  <td>
20e00 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20    FLOAT    <td> 
20e10 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 69 6e 74  Convert from int
20e20 65 67 65 72 20 74 6f 20 66 6c 6f 61 74 0a 2a 2a  eger to float.**
20e30 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45   <tr><td> INTEGE
20e40 52 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20  R  <td>   TEXT  
20e50 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e    <td> ASCII ren
20e60 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 69 6e  dering of the in
20e70 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64  teger.** <tr><td
20e80 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20  > INTEGER  <td> 
20e90 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53    BLOB    <td> S
20ea0 61 6d 65 20 61 73 20 49 4e 54 45 47 45 52 2d 3e  ame as INTEGER->
20eb0 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  TEXT.** <tr><td>
20ec0 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 49    FLOAT   <td> I
20ed0 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 43 6f  NTEGER   <td> Co
20ee0 6e 76 65 72 74 20 66 72 6f 6d 20 66 6c 6f 61 74  nvert from float
20ef0 20 74 6f 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c   to integer.** <
20f00 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20  tr><td>  FLOAT  
20f10 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20   <td>   TEXT    
20f20 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65  <td> ASCII rende
20f30 72 69 6e 67 20 6f 66 20 74 68 65 20 66 6c 6f 61  ring of the floa
20f40 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46  t.** <tr><td>  F
20f50 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 42 4c  LOAT   <td>   BL
20f60 4f 42 20 20 20 20 3c 74 64 3e 20 53 61 6d 65 20  OB    <td> Same 
20f70 61 73 20 46 4c 4f 41 54 2d 3e 54 45 58 54 0a 2a  as FLOAT->TEXT.*
20f80 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54  * <tr><td>  TEXT
20f90 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52      <td> INTEGER
20fa0 20 20 20 3c 74 64 3e 20 55 73 65 20 61 74 6f 69     <td> Use atoi
20fb0 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  ().** <tr><td>  
20fc0 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20 46 4c  TEXT    <td>  FL
20fd0 4f 41 54 20 20 20 20 3c 74 64 3e 20 55 73 65 20  OAT    <td> Use 
20fe0 61 74 6f 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74  atof().** <tr><t
20ff0 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  d>  TEXT    <td>
21000 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20     BLOB    <td> 
21010 4e 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 3c 74 72  No change.** <tr
21020 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c  ><td>  BLOB    <
21030 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74  td> INTEGER   <t
21040 64 3e 20 43 6f 6e 76 65 72 74 20 74 6f 20 54 45  d> Convert to TE
21050 58 54 20 74 68 65 6e 20 75 73 65 20 61 74 6f 69  XT then use atoi
21060 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  ().** <tr><td>  
21070 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 46 4c  BLOB    <td>  FL
21080 4f 41 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76  OAT    <td> Conv
21090 65 72 74 20 74 6f 20 54 45 58 54 20 74 68 65 6e  ert to TEXT then
210a0 20 75 73 65 20 61 74 6f 66 28 29 0a 2a 2a 20 3c   use atof().** <
210b0 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20  tr><td>  BLOB   
210c0 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20   <td>   TEXT    
210d0 3c 74 64 3e 20 41 64 64 20 61 20 7a 65 72 6f 20  <td> Add a zero 
210e0 74 65 72 6d 69 6e 61 74 6f 72 20 69 66 20 6e 65  terminator if ne
210f0 65 64 65 64 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e  eded.** </table>
21100 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  .** </blockquote
21110 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c  >.**.** The tabl
21120 65 20 61 62 6f 76 65 20 6d 61 6b 65 73 20 72 65  e above makes re
21130 66 65 72 65 6e 63 65 20 74 6f 20 73 74 61 6e 64  ference to stand
21140 61 72 64 20 43 20 6c 69 62 72 61 72 79 20 66 75  ard C library fu
21150 6e 63 74 69 6f 6e 73 20 61 74 6f 69 28 29 0a 2a  nctions atoi().*
21160 2a 20 61 6e 64 20 61 74 6f 66 28 29 2e 20 20 53  * and atof().  S
21170 51 4c 69 74 65 20 64 6f 65 73 20 6e 6f 74 20 72  QLite does not r
21180 65 61 6c 6c 79 20 75 73 65 20 74 68 65 73 65 20  eally use these 
21190 66 75 6e 63 74 69 6f 6e 73 2e 20 20 49 74 20 68  functions.  It h
211a0 61 73 20 69 74 73 0a 2a 2a 20 6f 77 6e 20 65 71  as its.** own eq
211b0 75 69 76 61 6c 65 6e 74 20 69 6e 74 65 72 6e 61  uivalent interna
211c0 6c 20 72 6f 75 74 69 6e 65 73 2e 20 20 54 68 65  l routines.  The
211d0 20 61 74 6f 69 28 29 20 61 6e 64 20 61 74 6f 66   atoi() and atof
211e0 28 29 20 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20  () names are.** 
211f0 75 73 65 64 20 69 6e 20 74 68 65 20 74 61 62 6c  used in the tabl
21200 65 20 66 6f 72 20 62 72 65 76 69 74 79 20 61 6e  e for brevity an
21210 64 20 62 65 63 61 75 73 65 20 74 68 65 79 20 61  d because they a
21220 72 65 20 66 61 6d 69 6c 69 61 72 20 74 6f 20 6d  re familiar to m
21230 6f 73 74 0a 2a 2a 20 43 20 70 72 6f 67 72 61 6d  ost.** C program
21240 6d 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65  mers..**.** Note
21250 20 74 68 61 74 20 77 68 65 6e 20 74 79 70 65 20   that when type 
21260 63 6f 6e 76 65 72 73 69 6f 6e 73 20 6f 63 63 75  conversions occu
21270 72 2c 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75  r, pointers retu
21280 72 6e 65 64 20 62 79 20 70 72 69 6f 72 0a 2a 2a  rned by prior.**
21290 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65   calls to sqlite
212a0 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c  3_column_blob(),
212b0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
212c0 74 65 78 74 28 29 2c 20 61 6e 64 2f 6f 72 0a 2a  text(), and/or.*
212d0 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  * sqlite3_column
212e0 5f 74 65 78 74 31 36 28 29 20 6d 61 79 20 62 65  _text16() may be
212f0 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a   invalidated..**
21300 20 54 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e   Type conversion
21310 73 20 61 6e 64 20 70 6f 69 6e 74 65 72 20 69 6e  s and pointer in
21320 76 61 6c 69 64 61 74 69 6f 6e 73 20 6d 69 67 68  validations migh
21330 74 20 6f 63 63 75 72 0a 2a 2a 20 69 6e 20 74 68  t occur.** in th
21340 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 61 73 65  e following case
21350 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  s:.**.** <ul>.**
21360 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61   <li> The initia
21370 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 61 20 42  l content is a B
21380 4c 4f 42 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  LOB and sqlite3_
21390 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72  column_text() or
213a0 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33  .**      sqlite3
213b0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
213c0 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 41 20 7a   is called.  A z
213d0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 20 6d  ero-terminator m
213e0 69 67 68 74 0a 2a 2a 20 20 20 20 20 20 6e 65 65  ight.**      nee
213f0 64 20 74 6f 20 62 65 20 61 64 64 65 64 20 74 6f  d to be added to
21400 20 74 68 65 20 73 74 72 69 6e 67 2e 3c 2f 6c 69   the string.</li
21410 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e  >.** <li> The in
21420 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73  itial content is
21430 20 55 54 46 2d 38 20 74 65 78 74 20 61 6e 64 20   UTF-8 text and 
21440 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
21450 79 74 65 73 31 36 28 29 20 6f 72 0a 2a 2a 20 20  ytes16() or.**  
21460 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75      sqlite3_colu
21470 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73 20 63  mn_text16() is c
21480 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74  alled.  The cont
21490 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76  ent must be conv
214a0 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f  erted.**      to
214b0 20 55 54 46 2d 31 36 2e 3c 2f 6c 69 3e 0a 2a 2a   UTF-16.</li>.**
214c0 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61   <li> The initia
214d0 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 46  l content is UTF
214e0 2d 31 36 20 74 65 78 74 20 61 6e 64 20 73 71 6c  -16 text and sql
214f0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
21500 73 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73  s() or.**      s
21510 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
21520 78 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20  xt() is called. 
21530 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73   The content mus
21540 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a  t be converted.*
21550 2a 20 20 20 20 20 20 74 6f 20 55 54 46 2d 38 2e  *      to UTF-8.
21560 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  </li>.** </ul>.*
21570 2a 0a 2a 2a 20 43 6f 6e 76 65 72 73 69 6f 6e 73  *.** Conversions
21580 20 62 65 74 77 65 65 6e 20 55 54 46 2d 31 36 62   between UTF-16b
21590 65 20 61 6e 64 20 55 54 46 2d 31 36 6c 65 20 61  e and UTF-16le a
215a0 72 65 20 61 6c 77 61 79 73 20 64 6f 6e 65 20 69  re always done i
215b0 6e 20 70 6c 61 63 65 20 61 6e 64 20 64 6f 0a 2a  n place and do.*
215c0 2a 20 6e 6f 74 20 69 6e 76 61 6c 69 64 61 74 65  * not invalidate
215d0 20 61 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72   a prior pointer
215e0 2c 20 74 68 6f 75 67 68 20 6f 66 20 63 6f 75 72  , though of cour
215f0 73 65 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f  se the content o
21600 66 20 74 68 65 20 62 75 66 66 65 72 0a 2a 2a 20  f the buffer.** 
21610 74 68 61 74 20 74 68 65 20 70 72 69 6f 72 20 70  that the prior p
21620 6f 69 6e 74 65 72 20 70 6f 69 6e 74 73 20 74 6f  ointer points to
21630 20 77 69 6c 6c 20 68 61 76 65 20 62 65 65 6e 20   will have been 
21640 6d 6f 64 69 66 69 65 64 2e 20 20 4f 74 68 65 72  modified.  Other
21650 20 6b 69 6e 64 73 0a 2a 2a 20 6f 66 20 63 6f 6e   kinds.** of con
21660 76 65 72 73 69 6f 6e 20 61 72 65 20 64 6f 6e 65  version are done
21670 20 69 6e 20 70 6c 61 63 65 20 77 68 65 6e 20 69   in place when i
21680 74 20 69 73 20 70 6f 73 73 69 62 6c 65 2c 20 62  t is possible, b
21690 75 74 20 73 6f 6d 65 74 69 6d 65 73 20 74 68 65  ut sometimes the
216a0 79 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 70 6f 73  y.** are not pos
216b0 73 69 62 6c 65 20 61 6e 64 20 69 6e 20 74 68 6f  sible and in tho
216c0 73 65 20 63 61 73 65 73 20 70 72 69 6f 72 20 70  se cases prior p
216d0 6f 69 6e 74 65 72 73 20 61 72 65 20 69 6e 76 61  ointers are inva
216e0 6c 69 64 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  lidated..**.** T
216f0 68 65 20 73 61 66 65 73 74 20 61 6e 64 20 65 61  he safest and ea
21700 73 69 65 73 74 20 74 6f 20 72 65 6d 65 6d 62 65  siest to remembe
21710 72 20 70 6f 6c 69 63 79 20 69 73 20 74 6f 20 69  r policy is to i
21720 6e 76 6f 6b 65 20 74 68 65 73 65 20 72 6f 75 74  nvoke these rout
21730 69 6e 65 73 0a 2a 2a 20 69 6e 20 6f 6e 65 20 6f  ines.** in one o
21740 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  f the following 
21750 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  ways:.**.** <ul>
21760 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33  .**  <li>sqlite3
21770 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 66  _column_text() f
21780 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74  ollowed by sqlit
21790 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
217a0 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73  )</li>.**  <li>s
217b0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
217c0 6f 62 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79  ob() followed by
217d0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
217e0 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20  bytes()</li>.** 
217f0 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c   <li>sqlite3_col
21800 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 6f 6c  umn_text16() fol
21810 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33  lowed by sqlite3
21820 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
21830 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a  )</li>.** </ul>.
21840 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77  **.** In other w
21850 6f 72 64 73 2c 20 79 6f 75 20 73 68 6f 75 6c 64  ords, you should
21860 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 63 6f   call sqlite3_co
21870 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 0a 2a 2a 20  lumn_text(),.** 
21880 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
21890 6c 6f 62 28 29 2c 20 6f 72 20 73 71 6c 69 74 65  lob(), or sqlite
218a0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
218b0 29 20 66 69 72 73 74 20 74 6f 20 66 6f 72 63 65  ) first to force
218c0 20 74 68 65 20 72 65 73 75 6c 74 0a 2a 2a 20 69   the result.** i
218d0 6e 74 6f 20 74 68 65 20 64 65 73 69 72 65 64 20  nto the desired 
218e0 66 6f 72 6d 61 74 2c 20 74 68 65 6e 20 69 6e 76  format, then inv
218f0 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  oke sqlite3_colu
21900 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a  mn_bytes() or.**
21910 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
21920 62 79 74 65 73 31 36 28 29 20 74 6f 20 66 69 6e  bytes16() to fin
21930 64 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68  d the size of th
21940 65 20 72 65 73 75 6c 74 2e 20 20 44 6f 20 6e 6f  e result.  Do no
21950 74 20 6d 69 78 20 63 61 6c 6c 73 0a 2a 2a 20 74  t mix calls.** t
21960 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  o sqlite3_column
21970 5f 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74  _text() or sqlit
21980 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29  e3_column_blob()
21990 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 0a 2a   with calls to.*
219a0 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  * sqlite3_column
219b0 5f 62 79 74 65 73 31 36 28 29 2c 20 61 6e 64 20  _bytes16(), and 
219c0 64 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73  do not mix calls
219d0 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   to sqlite3_colu
219e0 6d 6e 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 77  mn_text16().** w
219f0 69 74 68 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c  ith calls to sql
21a00 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
21a10 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70  s()..**.** The p
21a20 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64  ointers returned
21a30 20 61 72 65 20 76 61 6c 69 64 20 75 6e 74 69 6c   are valid until
21a40 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69   a type conversi
21a50 6f 6e 20 6f 63 63 75 72 73 20 61 73 0a 2a 2a 20  on occurs as.** 
21a60 64 65 73 63 72 69 62 65 64 20 61 62 6f 76 65 2c  described above,
21a70 20 6f 72 20 75 6e 74 69 6c 20 5b 73 71 6c 69 74   or until [sqlit
21a80 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b 73  e3_step()] or [s
21a90 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
21aa0 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  or.** [sqlite3_f
21ab0 69 6e 61 6c 69 7a 65 28 29 5d 20 69 73 20 63 61  inalize()] is ca
21ac0 6c 6c 65 64 2e 20 20 54 68 65 20 6d 65 6d 6f 72  lled.  The memor
21ad0 79 20 73 70 61 63 65 20 75 73 65 64 20 74 6f 20  y space used to 
21ae0 68 6f 6c 64 20 73 74 72 69 6e 67 73 0a 2a 2a 20  hold strings.** 
21af0 61 6e 64 20 42 4c 4f 42 73 20 69 73 20 66 72 65  and BLOBs is fre
21b00 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ed automatically
21b10 2e 20 20 44 6f 20 3c 62 3e 6e 6f 74 3c 2f 62 3e  .  Do <b>not</b>
21b20 20 70 61 73 73 20 74 68 65 20 70 6f 69 6e 74 65   pass the pointe
21b30 72 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b  rs returned.** [
21b40 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
21b50 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  lob()], [sqlite3
21b60 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c  _column_text()],
21b70 20 65 74 63 2e 20 69 6e 74 6f 0a 2a 2a 20 5b 73   etc. into.** [s
21b80 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a  qlite3_free()]..
21b90 2a 2a 0a 2a 2a 20 49 66 20 61 20 6d 65 6d 6f 72  **.** If a memor
21ba0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72  y allocation err
21bb0 6f 72 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67  or occurs during
21bc0 20 74 68 65 20 65 76 61 6c 75 61 74 69 6f 6e 20   the evaluation 
21bd0 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65  of any.** of the
21be0 73 65 20 72 6f 75 74 69 6e 65 73 2c 20 61 20 64  se routines, a d
21bf0 65 66 61 75 6c 74 20 76 61 6c 75 65 20 69 73 20  efault value is 
21c00 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 64  returned.  The d
21c10 65 66 61 75 6c 74 20 76 61 6c 75 65 0a 2a 2a 20  efault value.** 
21c20 69 73 20 65 69 74 68 65 72 20 74 68 65 20 69 6e  is either the in
21c30 74 65 67 65 72 20 30 2c 20 74 68 65 20 66 6c 6f  teger 0, the flo
21c40 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62  ating point numb
21c50 65 72 20 30 2e 30 2c 20 6f 72 20 61 20 4e 55 4c  er 0.0, or a NUL
21c60 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 2e 20 20 53  L.** pointer.  S
21c70 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20  ubsequent calls 
21c80 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63  to [sqlite3_errc
21c90 6f 64 65 28 29 5d 20 77 69 6c 6c 20 72 65 74 75  ode()] will retu
21ca0 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f  rn.** [SQLITE_NO
21cb0 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75  MEM]..**.** Requ
21cc0 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31  irements:.** [H1
21cd0 33 38 30 33 5d 20 5b 48 31 33 38 30 36 5d 20 5b  3803] [H13806] [
21ce0 48 31 33 38 30 39 5d 20 5b 48 31 33 38 31 32 5d  H13809] [H13812]
21cf0 20 5b 48 31 33 38 31 35 5d 20 5b 48 31 33 38 31   [H13815] [H1381
21d00 38 5d 20 5b 48 31 33 38 32 31 5d 20 5b 48 31 33  8] [H13821] [H13
21d10 38 32 34 5d 0a 2a 2a 20 5b 48 31 33 38 32 37 5d  824].** [H13827]
21d20 20 5b 48 31 33 38 33 30 5d 0a 2a 2f 0a 63 6f 6e   [H13830].*/.con
21d30 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
21d40 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 73 71 6c  _column_blob(sql
21d50 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
21d60 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74  iCol);.int sqlit
21d70 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
21d80 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
21d90 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71  nt iCol);.int sq
21da0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
21db0 65 73 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  es16(sqlite3_stm
21dc0 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 64  t*, int iCol);.d
21dd0 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f  ouble sqlite3_co
21de0 6c 75 6d 6e 5f 64 6f 75 62 6c 65 28 73 71 6c 69  lumn_double(sqli
21df0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
21e00 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  Col);.int sqlite
21e10 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 28 73 71 6c  3_column_int(sql
21e20 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
21e30 69 43 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 69  iCol);.sqlite3_i
21e40 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 63 6f 6c  nt64 sqlite3_col
21e50 75 6d 6e 5f 69 6e 74 36 34 28 73 71 6c 69 74 65  umn_int64(sqlite
21e60 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
21e70 6c 29 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e  l);.const unsign
21e80 65 64 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  ed char *sqlite3
21e90 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 73 71 6c  _column_text(sql
21ea0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
21eb0 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  iCol);.const voi
21ec0 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
21ed0 6e 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33  n_text16(sqlite3
21ee0 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
21ef0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
21f00 6f 6c 75 6d 6e 5f 74 79 70 65 28 73 71 6c 69 74  olumn_type(sqlit
21f10 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
21f20 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 76 61 6c  ol);.sqlite3_val
21f30 75 65 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ue *sqlite3_colu
21f40 6d 6e 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33  mn_value(sqlite3
21f50 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
21f60 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
21f70 45 46 3a 20 44 65 73 74 72 6f 79 20 41 20 50 72  EF: Destroy A Pr
21f80 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74  epared Statement
21f90 20 4f 62 6a 65 63 74 20 7b 48 31 33 33 30 30 7d   Object {H13300}
21fa0 20 3c 53 37 30 33 30 30 3e 3c 53 33 30 31 30 30   <S70300><S30100
21fb0 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  >.**.** The sqli
21fc0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 66  te3_finalize() f
21fd0 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65  unction is calle
21fe0 64 20 74 6f 20 64 65 6c 65 74 65 20 61 20 5b 70  d to delete a [p
21ff0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
22000 74 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20 73 74  t]..** If the st
22010 61 74 65 6d 65 6e 74 20 77 61 73 20 65 78 65 63  atement was exec
22020 75 74 65 64 20 73 75 63 63 65 73 73 66 75 6c 6c  uted successfull
22030 79 20 6f 72 20 6e 6f 74 20 65 78 65 63 75 74 65  y or not execute
22040 64 20 61 74 20 61 6c 6c 2c 20 74 68 65 6e 0a 2a  d at all, then.*
22050 2a 20 53 51 4c 49 54 45 5f 4f 4b 20 69 73 20 72  * SQLITE_OK is r
22060 65 74 75 72 6e 65 64 2e 20 49 66 20 65 78 65 63  eturned. If exec
22070 75 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 74 61  ution of the sta
22080 74 65 6d 65 6e 74 20 66 61 69 6c 65 64 20 74 68  tement failed th
22090 65 6e 20 61 6e 0a 2a 2a 20 5b 65 72 72 6f 72 20  en an.** [error 
220a0 63 6f 64 65 5d 20 6f 72 20 5b 65 78 74 65 6e 64  code] or [extend
220b0 65 64 20 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  ed error code] i
220c0 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  s returned..**.*
220d0 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 63  * This routine c
220e0 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 74 20  an be called at 
220f0 61 6e 79 20 70 6f 69 6e 74 20 64 75 72 69 6e 67  any point during
22100 20 74 68 65 20 65 78 65 63 75 74 69 6f 6e 20 6f   the execution o
22110 66 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72  f the.** [prepar
22120 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20  ed statement].  
22130 49 66 20 74 68 65 20 76 69 72 74 75 61 6c 20 6d  If the virtual m
22140 61 63 68 69 6e 65 20 68 61 73 20 6e 6f 74 0a 2a  achine has not.*
22150 2a 20 63 6f 6d 70 6c 65 74 65 64 20 65 78 65 63  * completed exec
22160 75 74 69 6f 6e 20 77 68 65 6e 20 74 68 69 73 20  ution when this 
22170 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65  routine is calle
22180 64 2c 20 74 68 61 74 20 69 73 20 6c 69 6b 65 0a  d, that is like.
22190 2a 2a 20 65 6e 63 6f 75 6e 74 65 72 69 6e 67 20  ** encountering 
221a0 61 6e 20 65 72 72 6f 72 20 6f 72 20 61 6e 20 5b  an error or an [
221b0 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
221c0 74 20 7c 20 69 6e 74 65 72 72 75 70 74 5d 2e 0a  t | interrupt]..
221d0 2a 2a 20 49 6e 63 6f 6d 70 6c 65 74 65 20 75 70  ** Incomplete up
221e0 64 61 74 65 73 20 6d 61 79 20 62 65 20 72 6f 6c  dates may be rol
221f0 6c 65 64 20 62 61 63 6b 20 61 6e 64 20 74 72 61  led back and tra
22200 6e 73 61 63 74 69 6f 6e 73 20 63 61 6e 63 65 6c  nsactions cancel
22210 65 64 2c 0a 2a 2a 20 64 65 70 65 6e 64 69 6e 67  ed,.** depending
22220 20 6f 6e 20 74 68 65 20 63 69 72 63 75 6d 73 74   on the circumst
22230 61 6e 63 65 73 2c 20 61 6e 64 20 74 68 65 0a 2a  ances, and the.*
22240 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 72  * [error code] r
22250 65 74 75 72 6e 65 64 20 77 69 6c 6c 20 62 65 20  eturned will be 
22260 5b 53 51 4c 49 54 45 5f 41 42 4f 52 54 5d 2e 0a  [SQLITE_ABORT]..
22270 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e  **.** Requiremen
22280 74 73 3a 0a 2a 2a 20 5b 48 31 31 33 30 32 5d 20  ts:.** [H11302] 
22290 5b 48 31 31 33 30 34 5d 0a 2a 2f 0a 69 6e 74 20  [H11304].*/.int 
222a0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
222b0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70  (sqlite3_stmt *p
222c0 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Stmt);../*.** CA
222d0 50 49 33 52 45 46 3a 20 52 65 73 65 74 20 41 20  PI3REF: Reset A 
222e0 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65  Prepared Stateme
222f0 6e 74 20 4f 62 6a 65 63 74 20 7b 48 31 33 33 33  nt Object {H1333
22300 30 7d 20 3c 53 37 30 33 30 30 3e 0a 2a 2a 0a 2a  0} <S70300>.**.*
22310 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65  * The sqlite3_re
22320 73 65 74 28 29 20 66 75 6e 63 74 69 6f 6e 20 69  set() function i
22330 73 20 63 61 6c 6c 65 64 20 74 6f 20 72 65 73 65  s called to rese
22340 74 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  t a [prepared st
22350 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65  atement].** obje
22360 63 74 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69  ct back to its i
22370 6e 69 74 69 61 6c 20 73 74 61 74 65 2c 20 72 65  nitial state, re
22380 61 64 79 20 74 6f 20 62 65 20 72 65 2d 65 78 65  ady to be re-exe
22390 63 75 74 65 64 2e 0a 2a 2a 20 41 6e 79 20 53 51  cuted..** Any SQ
223a0 4c 20 73 74 61 74 65 6d 65 6e 74 20 76 61 72 69  L statement vari
223b0 61 62 6c 65 73 20 74 68 61 74 20 68 61 64 20 76  ables that had v
223c0 61 6c 75 65 73 20 62 6f 75 6e 64 20 74 6f 20 74  alues bound to t
223d0 68 65 6d 20 75 73 69 6e 67 0a 2a 2a 20 74 68 65  hem using.** the
223e0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
223f0 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 62 69  lob | sqlite3_bi
22400 6e 64 5f 2a 28 29 20 41 50 49 5d 20 72 65 74 61  nd_*() API] reta
22410 69 6e 20 74 68 65 69 72 20 76 61 6c 75 65 73 2e  in their values.
22420 0a 2a 2a 20 55 73 65 20 5b 73 71 6c 69 74 65 33  .** Use [sqlite3
22430 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28  _clear_bindings(
22440 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65 20  )] to reset the 
22450 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20  bindings..**.** 
22460 7b 48 31 31 33 33 32 7d 20 54 68 65 20 5b 73 71  {H11332} The [sq
22470 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20  lite3_reset(S)] 
22480 69 6e 74 65 72 66 61 63 65 20 72 65 73 65 74 73  interface resets
22490 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
224a0 74 61 74 65 6d 65 6e 74 5d 20 53 0a 2a 2a 20 20  tatement] S.**  
224b0 20 20 20 20 20 20 20 20 62 61 63 6b 20 74 6f 20          back to 
224c0 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66  the beginning of
224d0 20 69 74 73 20 70 72 6f 67 72 61 6d 2e 0a 2a 2a   its program..**
224e0 0a 2a 2a 20 7b 48 31 31 33 33 34 7d 20 49 66 20  .** {H11334} If 
224f0 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
22500 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
22510 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68  _step(S)] for th
22520 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70  e.**          [p
22530 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
22540 74 5d 20 53 20 72 65 74 75 72 6e 65 64 20 5b 53  t] S returned [S
22550 51 4c 49 54 45 5f 52 4f 57 5d 20 6f 72 20 5b 53  QLITE_ROW] or [S
22560 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20  QLITE_DONE],.** 
22570 20 20 20 20 20 20 20 20 20 6f 72 20 69 66 20 5b           or if [
22580 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d  sqlite3_step(S)]
22590 20 68 61 73 20 6e 65 76 65 72 20 62 65 66 6f 72   has never befor
225a0 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 6f 6e  e been called on
225b0 20 53 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   S,.**          
225c0 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65  then [sqlite3_re
225d0 73 65 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20  set(S)] returns 
225e0 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a  [SQLITE_OK]..**.
225f0 2a 2a 20 7b 48 31 31 33 33 36 7d 20 49 66 20 74  ** {H11336} If t
22600 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63  he most recent c
22610 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
22620 73 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68 65  step(S)] for the
22630 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72  .**          [pr
22640 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
22650 5d 20 53 20 69 6e 64 69 63 61 74 65 64 20 61 6e  ] S indicated an
22660 20 65 72 72 6f 72 2c 20 74 68 65 6e 0a 2a 2a 20   error, then.** 
22670 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
22680 33 5f 72 65 73 65 74 28 53 29 5d 20 72 65 74 75  3_reset(S)] retu
22690 72 6e 73 20 61 6e 20 61 70 70 72 6f 70 72 69 61  rns an appropria
226a0 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e  te [error code].
226b0 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 33 33 38 7d 20  .**.** {H11338} 
226c0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  The [sqlite3_res
226d0 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65  et(S)] interface
226e0 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65   does not change
226f0 20 74 68 65 20 76 61 6c 75 65 73 0a 2a 2a 20 20   the values.**  
22700 20 20 20 20 20 20 20 20 6f 66 20 61 6e 79 20 5b          of any [
22710 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
22720 62 7c 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 74  b|bindings] on t
22730 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
22740 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 69 6e  tement] S..*/.in
22750 74 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28  t sqlite3_reset(
22760 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
22770 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
22780 49 33 52 45 46 3a 20 43 72 65 61 74 65 20 4f 72  I3REF: Create Or
22790 20 52 65 64 65 66 69 6e 65 20 53 51 4c 20 46 75   Redefine SQL Fu
227a0 6e 63 74 69 6f 6e 73 20 7b 48 31 36 31 30 30 7d  nctions {H16100}
227b0 20 3c 53 32 30 32 30 30 3e 0a 2a 2a 20 4b 45 59   <S20200>.** KEY
227c0 57 4f 52 44 53 3a 20 7b 66 75 6e 63 74 69 6f 6e  WORDS: {function
227d0 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e   creation routin
227e0 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  es}.** KEYWORDS:
227f0 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65   {application-de
22800 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
22810 6f 6e 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  on}.** KEYWORDS:
22820 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65   {application-de
22830 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
22840 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ons}.**.** These
22850 20 74 77 6f 20 66 75 6e 63 74 69 6f 6e 73 20 28   two functions (
22860 63 6f 6c 6c 65 63 74 69 76 65 6c 79 20 6b 6e 6f  collectively kno
22870 77 6e 20 61 73 20 22 66 75 6e 63 74 69 6f 6e 20  wn as "function 
22880 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65  creation routine
22890 73 22 29 0a 2a 2a 20 61 72 65 20 75 73 65 64 20  s").** are used 
228a0 74 6f 20 61 64 64 20 53 51 4c 20 66 75 6e 63 74  to add SQL funct
228b0 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74  ions or aggregat
228c0 65 73 20 6f 72 20 74 6f 20 72 65 64 65 66 69 6e  es or to redefin
228d0 65 20 74 68 65 20 62 65 68 61 76 69 6f 72 0a 2a  e the behavior.*
228e0 2a 20 6f 66 20 65 78 69 73 74 69 6e 67 20 53 51  * of existing SQ
228f0 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61  L functions or a
22900 67 67 72 65 67 61 74 65 73 2e 20 20 54 68 65 20  ggregates.  The 
22910 6f 6e 6c 79 20 64 69 66 66 65 72 65 6e 63 65 20  only difference 
22920 62 65 74 77 65 65 6e 20 74 68 65 0a 2a 2a 20 74  between the.** t
22930 77 6f 20 69 73 20 74 68 61 74 20 74 68 65 20 73  wo is that the s
22940 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2c  econd parameter,
22950 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
22960 20 28 73 63 61 6c 61 72 29 20 66 75 6e 63 74 69   (scalar) functi
22970 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61  on or.** aggrega
22980 74 65 2c 20 69 73 20 65 6e 63 6f 64 65 64 20 69  te, is encoded i
22990 6e 20 55 54 46 2d 38 20 66 6f 72 20 73 71 6c 69  n UTF-8 for sqli
229a0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
229b0 69 6f 6e 28 29 20 61 6e 64 20 55 54 46 2d 31 36  ion() and UTF-16
229c0 0a 2a 2a 20 66 6f 72 20 73 71 6c 69 74 65 33 5f  .** for sqlite3_
229d0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31  create_function1
229e0 36 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  6()..**.** The f
229f0 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69  irst parameter i
22a00 73 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  s the [database 
22a10 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 77  connection] to w
22a20 68 69 63 68 20 74 68 65 20 53 51 4c 0a 2a 2a 20  hich the SQL.** 
22a30 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 6f 20 62  function is to b
22a40 65 20 61 64 64 65 64 2e 20 20 49 66 20 61 20 73  e added.  If a s
22a50 69 6e 67 6c 65 20 70 72 6f 67 72 61 6d 20 75 73  ingle program us
22a60 65 73 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65  es more than one
22a70 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e   database.** con
22a80 6e 65 63 74 69 6f 6e 20 69 6e 74 65 72 6e 61 6c  nection internal
22a90 6c 79 2c 20 74 68 65 6e 20 53 51 4c 20 66 75 6e  ly, then SQL fun
22aa0 63 74 69 6f 6e 73 20 6d 75 73 74 20 62 65 20 61  ctions must be a
22ab0 64 64 65 64 20 69 6e 64 69 76 69 64 75 61 6c 6c  dded individuall
22ac0 79 20 74 6f 0a 2a 2a 20 65 61 63 68 20 64 61 74  y to.** each dat
22ad0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
22ae0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f  ..**.** The seco
22af0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  nd parameter is 
22b00 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
22b10 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  SQL function to 
22b20 62 65 20 63 72 65 61 74 65 64 20 6f 72 0a 2a 2a  be created or.**
22b30 20 72 65 64 65 66 69 6e 65 64 2e 20 20 54 68 65   redefined.  The
22b40 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 6e   length of the n
22b50 61 6d 65 20 69 73 20 6c 69 6d 69 74 65 64 20 74  ame is limited t
22b60 6f 20 32 35 35 20 62 79 74 65 73 2c 20 65 78 63  o 255 bytes, exc
22b70 6c 75 73 69 76 65 20 6f 66 0a 2a 2a 20 74 68 65  lusive of.** the
22b80 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72   zero-terminator
22b90 2e 20 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65  .  Note that the
22ba0 20 6e 61 6d 65 20 6c 65 6e 67 74 68 20 6c 69 6d   name length lim
22bb0 69 74 20 69 73 20 69 6e 20 62 79 74 65 73 2c 20  it is in bytes, 
22bc0 6e 6f 74 0a 2a 2a 20 63 68 61 72 61 63 74 65 72  not.** character
22bd0 73 2e 20 20 41 6e 79 20 61 74 74 65 6d 70 74 20  s.  Any attempt 
22be0 74 6f 20 63 72 65 61 74 65 20 61 20 66 75 6e 63  to create a func
22bf0 74 69 6f 6e 20 77 69 74 68 20 61 20 6c 6f 6e 67  tion with a long
22c00 65 72 20 6e 61 6d 65 0a 2a 2a 20 77 69 6c 6c 20  er name.** will 
22c10 72 65 73 75 6c 74 20 69 6e 20 5b 53 51 4c 49 54  result in [SQLIT
22c20 45 5f 45 52 52 4f 52 5d 20 62 65 69 6e 67 20 72  E_ERROR] being r
22c30 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  eturned..**.** T
22c40 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
22c50 65 72 20 28 6e 41 72 67 29 0a 2a 2a 20 69 73 20  er (nArg).** is 
22c60 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 61 72  the number of ar
22c70 67 75 6d 65 6e 74 73 20 74 68 61 74 20 74 68 65  guments that the
22c80 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72   SQL function or
22c90 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20 74 61  .** aggregate ta
22ca0 6b 65 73 2e 20 49 66 20 74 68 69 73 20 70 61 72  kes. If this par
22cb0 61 6d 65 74 65 72 20 69 73 20 2d 31 2c 20 74 68  ameter is -1, th
22cc0 65 6e 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  en the SQL funct
22cd0 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67  ion or.** aggreg
22ce0 61 74 65 20 6d 61 79 20 74 61 6b 65 20 61 6e 79  ate may take any
22cf0 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d   number of argum
22d00 65 6e 74 73 20 62 65 74 77 65 65 6e 20 30 20 61  ents between 0 a
22d10 6e 64 20 74 68 65 20 6c 69 6d 69 74 0a 2a 2a 20  nd the limit.** 
22d20 73 65 74 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  set by [sqlite3_
22d30 6c 69 6d 69 74 5d 28 5b 53 51 4c 49 54 45 5f 4c  limit]([SQLITE_L
22d40 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52  IMIT_FUNCTION_AR
22d50 47 5d 29 2e 20 20 49 66 20 74 68 65 20 74 68 69  G]).  If the thi
22d60 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  rd.** parameter 
22d70 69 73 20 6c 65 73 73 20 74 68 61 6e 20 2d 31 20  is less than -1 
22d80 6f 72 20 67 72 65 61 74 65 72 20 74 68 61 6e 20  or greater than 
22d90 31 32 37 20 74 68 65 6e 20 74 68 65 20 62 65 68  127 then the beh
22da0 61 76 69 6f 72 20 69 73 0a 2a 2a 20 75 6e 64 65  avior is.** unde
22db0 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  fined..**.** The
22dc0 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
22dd0 72 2c 20 65 54 65 78 74 52 65 70 2c 20 73 70 65  r, eTextRep, spe
22de0 63 69 66 69 65 73 20 77 68 61 74 0a 2a 2a 20 5b  cifies what.** [
22df0 53 51 4c 49 54 45 5f 55 54 46 38 20 7c 20 74 65  SQLITE_UTF8 | te
22e00 78 74 20 65 6e 63 6f 64 69 6e 67 5d 20 74 68 69  xt encoding] thi
22e10 73 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 70  s SQL function p
22e20 72 65 66 65 72 73 20 66 6f 72 0a 2a 2a 20 69 74  refers for.** it
22e30 73 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20 41  s parameters.  A
22e40 6e 79 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  ny SQL function 
22e50 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73  implementation s
22e60 68 6f 75 6c 64 20 62 65 20 61 62 6c 65 20 74 6f  hould be able to
22e70 20 77 6f 72 6b 0a 2a 2a 20 77 6f 72 6b 20 77 69   work.** work wi
22e80 74 68 20 55 54 46 2d 38 2c 20 55 54 46 2d 31 36  th UTF-8, UTF-16
22e90 6c 65 2c 20 6f 72 20 55 54 46 2d 31 36 62 65 2e  le, or UTF-16be.
22ea0 20 20 42 75 74 20 73 6f 6d 65 20 69 6d 70 6c 65    But some imple
22eb0 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 61 79 20 62  mentations may b
22ec0 65 0a 2a 2a 20 6d 6f 72 65 20 65 66 66 69 63 69  e.** more effici
22ed0 65 6e 74 20 77 69 74 68 20 6f 6e 65 20 65 6e 63  ent with one enc
22ee0 6f 64 69 6e 67 20 74 68 61 6e 20 61 6e 6f 74 68  oding than anoth
22ef0 65 72 2e 20 20 49 74 20 69 73 20 61 6c 6c 6f 77  er.  It is allow
22f00 65 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20  ed to.** invoke 
22f10 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
22f20 75 6e 63 74 69 6f 6e 28 29 20 6f 72 20 73 71 6c  unction() or sql
22f30 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
22f40 74 69 6f 6e 31 36 28 29 20 6d 75 6c 74 69 70 6c  tion16() multipl
22f50 65 0a 2a 2a 20 74 69 6d 65 73 20 77 69 74 68 20  e.** times with 
22f60 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f  the same functio
22f70 6e 20 62 75 74 20 77 69 74 68 20 64 69 66 66 65  n but with diffe
22f80 72 65 6e 74 20 76 61 6c 75 65 73 20 6f 66 20 65  rent values of e
22f90 54 65 78 74 52 65 70 2e 0a 2a 2a 20 57 68 65 6e  TextRep..** When
22fa0 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d   multiple implem
22fb0 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65  entations of the
22fc0 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 61   same function a
22fd0 72 65 20 61 76 61 69 6c 61 62 6c 65 2c 20 53 51  re available, SQ
22fe0 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 70 69 63  Lite.** will pic
22ff0 6b 20 74 68 65 20 6f 6e 65 20 74 68 61 74 20 69  k the one that i
23000 6e 76 6f 6c 76 65 73 20 74 68 65 20 6c 65 61 73  nvolves the leas
23010 74 20 61 6d 6f 75 6e 74 20 6f 66 20 64 61 74 61  t amount of data
23020 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 20   conversion..** 
23030 49 66 20 74 68 65 72 65 20 69 73 20 6f 6e 6c 79  If there is only
23040 20 61 20 73 69 6e 67 6c 65 20 69 6d 70 6c 65 6d   a single implem
23050 65 6e 74 61 74 69 6f 6e 20 77 68 69 63 68 20 64  entation which d
23060 6f 65 73 20 6e 6f 74 20 63 61 72 65 20 77 68 61  oes not care wha
23070 74 20 74 65 78 74 0a 2a 2a 20 65 6e 63 6f 64 69  t text.** encodi
23080 6e 67 20 69 73 20 75 73 65 64 2c 20 74 68 65 6e  ng is used, then
23090 20 74 68 65 20 66 6f 75 72 74 68 20 61 72 67 75   the fourth argu
230a0 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 5b  ment should be [
230b0 53 51 4c 49 54 45 5f 41 4e 59 5d 2e 0a 2a 2a 0a  SQLITE_ANY]..**.
230c0 2a 2a 20 54 68 65 20 66 69 66 74 68 20 70 61 72  ** The fifth par
230d0 61 6d 65 74 65 72 20 69 73 20 61 6e 20 61 72 62  ameter is an arb
230e0 69 74 72 61 72 79 20 70 6f 69 6e 74 65 72 2e 20  itrary pointer. 
230f0 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   The implementat
23100 69 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 66 75  ion of the.** fu
23110 6e 63 74 69 6f 6e 20 63 61 6e 20 67 61 69 6e 20  nction can gain 
23120 61 63 63 65 73 73 20 74 6f 20 74 68 69 73 20 70  access to this p
23130 6f 69 6e 74 65 72 20 75 73 69 6e 67 20 5b 73 71  ointer using [sq
23140 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28  lite3_user_data(
23150 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65  )]..**.** The se
23160 76 65 6e 74 68 2c 20 65 69 67 68 74 68 20 61 6e  venth, eighth an
23170 64 20 6e 69 6e 74 68 20 70 61 72 61 6d 65 74 65  d ninth paramete
23180 72 73 2c 20 78 46 75 6e 63 2c 20 78 53 74 65 70  rs, xFunc, xStep
23190 20 61 6e 64 20 78 46 69 6e 61 6c 2c 20 61 72 65   and xFinal, are
231a0 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f 20  .** pointers to 
231b0 43 2d 6c 61 6e 67 75 61 67 65 20 66 75 6e 63 74  C-language funct
231c0 69 6f 6e 73 20 74 68 61 74 20 69 6d 70 6c 65 6d  ions that implem
231d0 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63  ent the SQL func
231e0 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65  tion or.** aggre
231f0 67 61 74 65 2e 20 41 20 73 63 61 6c 61 72 20 53  gate. A scalar S
23200 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75  QL function requ
23210 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e  ires an implemen
23220 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 78 46  tation of the xF
23230 75 6e 63 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20  unc.** callback 
23240 6f 6e 6c 79 2c 20 4e 55 4c 4c 20 70 6f 69 6e 74  only, NULL point
23250 65 72 73 20 73 68 6f 75 6c 64 20 62 65 20 70 61  ers should be pa
23260 73 73 65 64 20 61 73 20 74 68 65 20 78 53 74 65  ssed as the xSte
23270 70 20 61 6e 64 20 78 46 69 6e 61 6c 0a 2a 2a 20  p and xFinal.** 
23280 70 61 72 61 6d 65 74 65 72 73 2e 20 41 6e 20 61  parameters. An a
23290 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e  ggregate SQL fun
232a0 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61  ction requires a
232b0 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  n implementation
232c0 20 6f 66 20 78 53 74 65 70 0a 2a 2a 20 61 6e 64   of xStep.** and
232d0 20 78 46 69 6e 61 6c 20 61 6e 64 20 4e 55 4c 4c   xFinal and NULL
232e0 20 73 68 6f 75 6c 64 20 62 65 20 70 61 73 73 65   should be passe
232f0 64 20 66 6f 72 20 78 46 75 6e 63 2e 20 54 6f 20  d for xFunc. To 
23300 64 65 6c 65 74 65 20 61 6e 20 65 78 69 73 74 69  delete an existi
23310 6e 67 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69  ng.** SQL functi
23320 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65 2c  on or aggregate,
23330 20 70 61 73 73 20 4e 55 4c 4c 20 66 6f 72 20 61   pass NULL for a
23340 6c 6c 20 74 68 72 65 65 20 66 75 6e 63 74 69 6f  ll three functio
23350 6e 20 63 61 6c 6c 62 61 63 6b 73 2e 0a 2a 2a 0a  n callbacks..**.
23360 2a 2a 20 49 74 20 69 73 20 70 65 72 6d 69 74 74  ** It is permitt
23370 65 64 20 74 6f 20 72 65 67 69 73 74 65 72 20 6d  ed to register m
23380 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e  ultiple implemen
23390 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73  tations of the s
233a0 61 6d 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73  ame.** functions
233b0 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 6e   with the same n
233c0 61 6d 65 20 62 75 74 20 77 69 74 68 20 65 69 74  ame but with eit
233d0 68 65 72 20 64 69 66 66 65 72 69 6e 67 20 6e 75  her differing nu
233e0 6d 62 65 72 73 20 6f 66 0a 2a 2a 20 61 72 67 75  mbers of.** argu
233f0 6d 65 6e 74 73 20 6f 72 20 64 69 66 66 65 72 69  ments or differi
23400 6e 67 20 70 72 65 66 65 72 72 65 64 20 74 65 78  ng preferred tex
23410 74 20 65 6e 63 6f 64 69 6e 67 73 2e 20 20 53 51  t encodings.  SQ
23420 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a  Lite will use.**
23430 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   the implementat
23440 69 6f 6e 20 6d 6f 73 74 20 63 6c 6f 73 65 6c 79  ion most closely
23450 20 6d 61 74 63 68 65 73 20 74 68 65 20 77 61 79   matches the way
23460 20 69 6e 20 77 68 69 63 68 20 74 68 65 0a 2a 2a   in which the.**
23470 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73   SQL function is
23480 20 75 73 65 64 2e 20 20 41 20 66 75 6e 63 74 69   used.  A functi
23490 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  on implementatio
234a0 6e 20 77 69 74 68 20 61 20 6e 6f 6e 2d 6e 65 67  n with a non-neg
234b0 61 74 69 76 65 0a 2a 2a 20 6e 41 72 67 20 70 61  ative.** nArg pa
234c0 72 61 6d 65 74 65 72 20 69 73 20 61 20 62 65 74  rameter is a bet
234d0 74 65 72 20 6d 61 74 63 68 20 74 68 61 6e 20 61  ter match than a
234e0 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d   function implem
234f0 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 0a 2a 2a  entation with.**
23500 20 61 20 6e 65 67 61 74 69 76 65 20 6e 41 72 67   a negative nArg
23510 2e 20 20 41 20 66 75 6e 63 74 69 6f 6e 20 77 68  .  A function wh
23520 65 72 65 20 74 68 65 20 70 72 65 66 65 72 72 65  ere the preferre
23530 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 0a  d text encoding.
23540 2a 2a 20 6d 61 74 63 68 65 73 20 74 68 65 20 64  ** matches the d
23550 61 74 61 62 61 73 65 20 65 6e 63 6f 64 69 6e 67  atabase encoding
23560 20 69 73 20 61 20 62 65 74 74 65 72 0a 2a 2a 20   is a better.** 
23570 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e  match than a fun
23580 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20  ction where the 
23590 65 6e 63 6f 64 69 6e 67 20 69 73 20 64 69 66 66  encoding is diff
235a0 65 72 65 6e 74 2e 20 20 0a 2a 2a 20 41 20 66 75  erent.  .** A fu
235b0 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65  nction where the
235c0 20 65 6e 63 6f 64 69 6e 67 20 64 69 66 66 65 72   encoding differ
235d0 65 6e 63 65 20 69 73 20 62 65 74 77 65 65 6e 20  ence is between 
235e0 55 54 46 31 36 6c 65 20 61 6e 64 20 55 54 46 31  UTF16le and UTF1
235f0 36 62 65 0a 2a 2a 20 69 73 20 61 20 63 6c 6f 73  6be.** is a clos
23600 65 72 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20  er match than a 
23610 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74  function where t
23620 68 65 20 65 6e 63 6f 64 69 6e 67 20 64 69 66 66  he encoding diff
23630 65 72 65 6e 63 65 20 69 73 0a 2a 2a 20 62 65 74  erence is.** bet
23640 77 65 65 6e 20 55 54 46 38 20 61 6e 64 20 55 54  ween UTF8 and UT
23650 46 31 36 2e 0a 2a 2a 0a 2a 2a 20 42 75 69 6c 74  F16..**.** Built
23660 2d 69 6e 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61  -in functions ma
23670 79 20 62 65 20 6f 76 65 72 6c 6f 61 64 65 64 20  y be overloaded 
23680 62 79 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69  by new applicati
23690 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
236a0 69 6f 6e 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72  ions..** The fir
236b0 73 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  st application-d
236c0 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
236d0 77 69 74 68 20 61 20 67 69 76 65 6e 20 6e 61 6d  with a given nam
236e0 65 20 6f 76 65 72 72 69 64 65 73 20 61 6c 6c 0a  e overrides all.
236f0 2a 2a 20 62 75 69 6c 74 2d 69 6e 20 66 75 6e 63  ** built-in func
23700 74 69 6f 6e 73 20 69 6e 20 74 68 65 20 73 61 6d  tions in the sam
23710 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
23720 65 63 74 69 6f 6e 5d 20 77 69 74 68 20 74 68 65  ection] with the
23730 20 73 61 6d 65 20 6e 61 6d 65 2e 0a 2a 2a 20 53   same name..** S
23740 75 62 73 65 71 75 65 6e 74 20 61 70 70 6c 69 63  ubsequent applic
23750 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
23760 6e 63 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73  nctions of the s
23770 61 6d 65 20 6e 61 6d 65 20 6f 6e 6c 79 20 6f 76  ame name only ov
23780 65 72 72 69 64 65 20 0a 2a 2a 20 70 72 69 6f 72  erride .** prior
23790 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
237a0 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 73 20 74  ined functions t
237b0 68 61 74 20 61 72 65 20 61 6e 20 65 78 61 63 74  hat are an exact
237c0 20 6d 61 74 63 68 20 66 6f 72 20 74 68 65 0a 2a   match for the.*
237d0 2a 20 6e 75 6d 62 65 72 20 6f 66 20 70 61 72 61  * number of para
237e0 6d 65 74 65 72 73 20 61 6e 64 20 70 72 65 66 65  meters and prefe
237f0 72 72 65 64 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a  rred encoding..*
23800 2a 0a 2a 2a 20 41 6e 20 61 70 70 6c 69 63 61 74  *.** An applicat
23810 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
23820 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65  tion is permitte
23830 64 20 74 6f 20 63 61 6c 6c 20 6f 74 68 65 72 0a  d to call other.
23840 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  ** SQLite interf
23850 61 63 65 73 2e 20 20 48 6f 77 65 76 65 72 2c 20  aces.  However, 
23860 73 75 63 68 20 63 61 6c 6c 73 20 6d 75 73 74 20  such calls must 
23870 6e 6f 74 0a 2a 2a 20 63 6c 6f 73 65 20 74 68 65  not.** close the
23880 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
23890 74 69 6f 6e 20 6e 6f 72 20 66 69 6e 61 6c 69 7a  tion nor finaliz
238a0 65 20 6f 72 20 72 65 73 65 74 20 74 68 65 20 70  e or reset the p
238b0 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65  repared.** state
238c0 6d 65 6e 74 20 69 6e 20 77 68 69 63 68 20 74 68  ment in which th
238d0 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75  e function is ru
238e0 6e 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 52 65 71  nning..**.** Req
238f0 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48  uirements:.** [H
23900 31 36 31 30 33 5d 20 5b 48 31 36 31 30 36 5d 20  16103] [H16106] 
23910 5b 48 31 36 31 30 39 5d 20 5b 48 31 36 31 31 32  [H16109] [H16112
23920 5d 20 5b 48 31 36 31 31 38 5d 20 5b 48 31 36 31  ] [H16118] [H161
23930 32 31 5d 20 5b 48 31 36 31 32 37 5d 0a 2a 2a 20  21] [H16127].** 
23940 5b 48 31 36 31 33 30 5d 20 5b 48 31 36 31 33 33  [H16130] [H16133
23950 5d 20 5b 48 31 36 31 33 36 5d 20 5b 48 31 36 31  ] [H16136] [H161
23960 33 39 5d 20 5b 48 31 36 31 34 32 5d 0a 2a 2f 0a  39] [H16142].*/.
23970 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61  int sqlite3_crea
23980 74 65 5f 66 75 6e 63 74 69 6f 6e 28 0a 20 20 73  te_function(.  s
23990 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f  qlite3 *db,.  co
239a0 6e 73 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 74  nst char *zFunct
239b0 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e  ionName,.  int n
239c0 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74  Arg,.  int eText
239d0 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70  Rep,.  void *pAp
239e0 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e  p,.  void (*xFun
239f0 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  c)(sqlite3_conte
23a00 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f  xt*,int,sqlite3_
23a10 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64  value**),.  void
23a20 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65   (*xStep)(sqlite
23a30 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73  3_context*,int,s
23a40 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c  qlite3_value**),
23a50 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c  .  void (*xFinal
23a60 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
23a70 74 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  t*).);.int sqlit
23a80 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
23a90 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74 65 33 20  on16(.  sqlite3 
23aa0 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 76 6f 69  *db,.  const voi
23ab0 64 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65  d *zFunctionName
23ac0 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20  ,.  int nArg,.  
23ad0 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20  int eTextRep,.  
23ae0 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f  void *pApp,.  vo
23af0 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69  id (*xFunc)(sqli
23b00 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74  te3_context*,int
23b10 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a  ,sqlite3_value**
23b20 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65  ),.  void (*xSte
23b30 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  p)(sqlite3_conte
23b40 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f  xt*,int,sqlite3_
23b50 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64  value**),.  void
23b60 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74   (*xFinal)(sqlit
23b70 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a  e3_context*).);.
23b80 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
23b90 20 54 65 78 74 20 45 6e 63 6f 64 69 6e 67 73 20   Text Encodings 
23ba0 7b 48 31 30 32 36 37 7d 20 3c 53 35 30 32 30 30  {H10267} <S50200
23bb0 3e 20 3c 48 31 36 31 30 30 3e 0a 2a 2a 0a 2a 2a  > <H16100>.**.**
23bc0 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 20   These constant 
23bd0 64 65 66 69 6e 65 20 69 6e 74 65 67 65 72 20 63  define integer c
23be0 6f 64 65 73 20 74 68 61 74 20 72 65 70 72 65 73  odes that repres
23bf0 65 6e 74 20 74 68 65 20 76 61 72 69 6f 75 73 0a  ent the various.
23c00 2a 2a 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67  ** text encoding
23c10 73 20 73 75 70 70 6f 72 74 65 64 20 62 79 20 53  s supported by S
23c20 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e  QLite..*/.#defin
23c30 65 20 53 51 4c 49 54 45 5f 55 54 46 38 20 20 20  e SQLITE_UTF8   
23c40 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e          1.#defin
23c50 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45  e SQLITE_UTF16LE
23c60 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e          2.#defin
23c70 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45  e SQLITE_UTF16BE
23c80 20 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e          3.#defin
23c90 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 20 20  e SQLITE_UTF16  
23ca0 20 20 20 20 20 20 20 20 34 20 20 20 20 2f 2a 20          4    /* 
23cb0 55 73 65 20 6e 61 74 69 76 65 20 62 79 74 65 20  Use native byte 
23cc0 6f 72 64 65 72 20 2a 2f 0a 23 64 65 66 69 6e 65  order */.#define
23cd0 20 53 51 4c 49 54 45 5f 41 4e 59 20 20 20 20 20   SQLITE_ANY     
23ce0 20 20 20 20 20 20 20 35 20 20 20 20 2f 2a 20 73         5    /* s
23cf0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
23d00 6e 63 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 23  nction only */.#
23d10 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54  define SQLITE_UT
23d20 46 31 36 5f 41 4c 49 47 4e 45 44 20 20 38 20 20  F16_ALIGNED  8  
23d30 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72 65    /* sqlite3_cre
23d40 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 20 6f 6e  ate_collation on
23d50 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ly */../*.** CAP
23d60 49 33 52 45 46 3a 20 44 65 70 72 65 63 61 74 65  I3REF: Deprecate
23d70 64 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 44  d Functions.** D
23d80 45 50 52 45 43 41 54 45 44 0a 2a 2a 0a 2a 2a 20  EPRECATED.**.** 
23d90 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20  These functions 
23da0 61 72 65 20 5b 64 65 70 72 65 63 61 74 65 64 5d  are [deprecated]
23db0 2e 20 20 49 6e 20 6f 72 64 65 72 20 74 6f 20 6d  .  In order to m
23dc0 61 69 6e 74 61 69 6e 0a 2a 2a 20 62 61 63 6b 77  aintain.** backw
23dd0 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69  ards compatibili
23de0 74 79 20 77 69 74 68 20 6f 6c 64 65 72 20 63 6f  ty with older co
23df0 64 65 2c 20 74 68 65 73 65 20 66 75 6e 63 74 69  de, these functi
23e00 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20 0a 2a 2a  ons continue .**
23e10 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64   to be supported
23e20 2e 20 20 48 6f 77 65 76 65 72 2c 20 6e 65 77 20  .  However, new 
23e30 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f  applications sho
23e40 75 6c 64 20 61 76 6f 69 64 0a 2a 2a 20 74 68 65  uld avoid.** the
23e50 20 75 73 65 20 6f 66 20 74 68 65 73 65 20 66 75   use of these fu
23e60 6e 63 74 69 6f 6e 73 2e 20 20 54 6f 20 68 65 6c  nctions.  To hel
23e70 70 20 65 6e 63 6f 75 72 61 67 65 20 70 65 6f 70  p encourage peop
23e80 6c 65 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 75  le to avoid.** u
23e90 73 69 6e 67 20 74 68 65 73 65 20 66 75 6e 63 74  sing these funct
23ea0 69 6f 6e 73 2c 20 77 65 20 61 72 65 20 6e 6f 74  ions, we are not
23eb0 20 67 6f 69 6e 67 20 74 6f 20 74 65 6c 6c 20 79   going to tell y
23ec0 6f 75 20 77 68 61 74 20 74 68 65 79 20 64 6f 2e  ou what they do.
23ed0 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49  .*/.#ifndef SQLI
23ee0 54 45 5f 4f 4d 49 54 5f 44 45 50 52 45 43 41 54  TE_OMIT_DEPRECAT
23ef0 45 44 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43  ED.SQLITE_DEPREC
23f00 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33  ATED int sqlite3
23f10 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 75 6e 74  _aggregate_count
23f20 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
23f30 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45  *);.SQLITE_DEPRE
23f40 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65  CATED int sqlite
23f50 33 5f 65 78 70 69 72 65 64 28 73 71 6c 69 74 65  3_expired(sqlite
23f60 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45  3_stmt*);.SQLITE
23f70 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20  _DEPRECATED int 
23f80 73 71 6c 69 74 65 33 5f 74 72 61 6e 73 66 65 72  sqlite3_transfer
23f90 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65  _bindings(sqlite
23fa0 33 5f 73 74 6d 74 2a 2c 20 73 71 6c 69 74 65 33  3_stmt*, sqlite3
23fb0 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f  _stmt*);.SQLITE_
23fc0 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73  DEPRECATED int s
23fd0 71 6c 69 74 65 33 5f 67 6c 6f 62 61 6c 5f 72 65  qlite3_global_re
23fe0 63 6f 76 65 72 28 76 6f 69 64 29 3b 0a 53 51 4c  cover(void);.SQL
23ff0 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 76  ITE_DEPRECATED v
24000 6f 69 64 20 73 71 6c 69 74 65 33 5f 74 68 72 65  oid sqlite3_thre
24010 61 64 5f 63 6c 65 61 6e 75 70 28 76 6f 69 64 29  ad_cleanup(void)
24020 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41  ;.SQLITE_DEPRECA
24030 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  TED int sqlite3_
24040 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d 28 76 6f 69  memory_alarm(voi
24050 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74  d(*)(void*,sqlit
24060 65 33 5f 69 6e 74 36 34 2c 69 6e 74 29 2c 76 6f  e3_int64,int),vo
24070 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36  id*,sqlite3_int6
24080 34 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a  4);.#endif../*.*
24090 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61  * CAPI3REF: Obta
240a0 69 6e 69 6e 67 20 53 51 4c 20 46 75 6e 63 74 69  ining SQL Functi
240b0 6f 6e 20 50 61 72 61 6d 65 74 65 72 20 56 61 6c  on Parameter Val
240c0 75 65 73 20 7b 48 31 35 31 30 30 7d 20 3c 53 32  ues {H15100} <S2
240d0 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  0200>.**.** The 
240e0 43 2d 6c 61 6e 67 75 61 67 65 20 69 6d 70 6c 65  C-language imple
240f0 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 53 51 4c  mentation of SQL
24100 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61   functions and a
24110 67 67 72 65 67 61 74 65 73 20 75 73 65 73 0a 2a  ggregates uses.*
24120 2a 20 74 68 69 73 20 73 65 74 20 6f 66 20 69 6e  * this set of in
24130 74 65 72 66 61 63 65 20 72 6f 75 74 69 6e 65 73  terface routines
24140 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 70   to access the p
24150 61 72 61 6d 65 74 65 72 20 76 61 6c 75 65 73 20  arameter values 
24160 6f 6e 0a 2a 2a 20 74 68 65 20 66 75 6e 63 74 69  on.** the functi
24170 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65 2e  on or aggregate.
24180 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 75 6e 63  .**.** The xFunc
24190 20 28 66 6f 72 20 73 63 61 6c 61 72 20 66 75 6e   (for scalar fun
241a0 63 74 69 6f 6e 73 29 20 6f 72 20 78 53 74 65 70  ctions) or xStep
241b0 20 28 66 6f 72 20 61 67 67 72 65 67 61 74 65 73   (for aggregates
241c0 29 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20  ) parameters.** 
241d0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  to [sqlite3_crea
241e0 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61  te_function()] a
241f0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  nd [sqlite3_crea
24200 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d  te_function16()]
24210 0a 2a 2a 20 64 65 66 69 6e 65 20 63 61 6c 6c 62  .** define callb
24220 61 63 6b 73 20 74 68 61 74 20 69 6d 70 6c 65 6d  acks that implem
24230 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63  ent the SQL func
24240 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67  tions and aggreg
24250 61 74 65 73 2e 0a 2a 2a 20 54 68 65 20 34 74 68  ates..** The 4th
24260 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
24270 65 73 65 20 63 61 6c 6c 62 61 63 6b 73 20 69 73  ese callbacks is
24280 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69   an array of poi
24290 6e 74 65 72 73 20 74 6f 0a 2a 2a 20 5b 70 72 6f  nters to.** [pro
242a0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
242b0 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 20 20  alue] objects.  
242c0 54 68 65 72 65 20 69 73 20 6f 6e 65 20 5b 73 71  There is one [sq
242d0 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
242e0 65 63 74 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20  ect for.** each 
242f0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
24300 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 20 20   SQL function.  
24310 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
24320 72 65 20 75 73 65 64 20 74 6f 0a 2a 2a 20 65 78  re used to.** ex
24330 74 72 61 63 74 20 76 61 6c 75 65 73 20 66 72 6f  tract values fro
24340 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  m the [sqlite3_v
24350 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a  alue] objects..*
24360 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
24370 6e 65 73 20 77 6f 72 6b 20 6f 6e 6c 79 20 77 69  nes work only wi
24380 74 68 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71  th [protected sq
24390 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
243a0 65 63 74 73 2e 0a 2a 2a 20 41 6e 79 20 61 74 74  ects..** Any att
243b0 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68 65 73  empt to use thes
243c0 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e 20 61 6e  e routines on an
243d0 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71   [unprotected sq
243e0 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20  lite3_value].** 
243f0 6f 62 6a 65 63 74 20 72 65 73 75 6c 74 73 20 69  object results i
24400 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61  n undefined beha
24410 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  vior..**.** Thes
24420 65 20 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20  e routines work 
24430 6a 75 73 74 20 6c 69 6b 65 20 74 68 65 20 63 6f  just like the co
24440 72 72 65 73 70 6f 6e 64 69 6e 67 20 5b 63 6f 6c  rresponding [col
24450 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74  umn access funct
24460 69 6f 6e 73 5d 0a 2a 2a 20 65 78 63 65 70 74 20  ions].** except 
24470 74 68 61 74 20 20 74 68 65 73 65 20 72 6f 75 74  that  these rout
24480 69 6e 65 73 20 74 61 6b 65 20 61 20 73 69 6e 67  ines take a sing
24490 6c 65 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71  le [protected sq
244a0 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
244b0 65 63 74 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69  ect.** pointer i
244c0 6e 73 74 65 61 64 20 6f 66 20 61 20 5b 73 71 6c  nstead of a [sql
244d0 69 74 65 33 5f 73 74 6d 74 2a 5d 20 70 6f 69 6e  ite3_stmt*] poin
244e0 74 65 72 20 61 6e 64 20 61 6e 20 69 6e 74 65 67  ter and an integ
244f0 65 72 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72  er column number
24500 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
24510 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
24520 28 29 20 69 6e 74 65 72 66 61 63 65 20 65 78 74  () interface ext
24530 72 61 63 74 73 20 61 20 55 54 46 2d 31 36 20 73  racts a UTF-16 s
24540 74 72 69 6e 67 0a 2a 2a 20 69 6e 20 74 68 65 20  tring.** in the 
24550 6e 61 74 69 76 65 20 62 79 74 65 2d 6f 72 64 65  native byte-orde
24560 72 20 6f 66 20 74 68 65 20 68 6f 73 74 20 6d 61  r of the host ma
24570 63 68 69 6e 65 2e 20 20 54 68 65 0a 2a 2a 20 73  chine.  The.** s
24580 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
24590 74 31 36 62 65 28 29 20 61 6e 64 20 73 71 6c 69  t16be() and sqli
245a0 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
245b0 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a  le() interfaces.
245c0 2a 2a 20 65 78 74 72 61 63 74 20 55 54 46 2d 31  ** extract UTF-1
245d0 36 20 73 74 72 69 6e 67 73 20 61 73 20 62 69 67  6 strings as big
245e0 2d 65 6e 64 69 61 6e 20 61 6e 64 20 6c 69 74 74  -endian and litt
245f0 6c 65 2d 65 6e 64 69 61 6e 20 72 65 73 70 65 63  le-endian respec
24600 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68  tively..**.** Th
24610 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  e sqlite3_value_
24620 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 29 20 69  numeric_type() i
24630 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74  nterface attempt
24640 73 20 74 6f 20 61 70 70 6c 79 0a 2a 2a 20 6e 75  s to apply.** nu
24650 6d 65 72 69 63 20 61 66 66 69 6e 69 74 79 20 74  meric affinity t
24660 6f 20 74 68 65 20 76 61 6c 75 65 2e 20 20 54 68  o the value.  Th
24670 69 73 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6e  is means that an
24680 20 61 74 74 65 6d 70 74 20 69 73 0a 2a 2a 20 6d   attempt is.** m
24690 61 64 65 20 74 6f 20 63 6f 6e 76 65 72 74 20 74  ade to convert t
246a0 68 65 20 76 61 6c 75 65 20 74 6f 20 61 6e 20 69  he value to an i
246b0 6e 74 65 67 65 72 20 6f 72 20 66 6c 6f 61 74 69  nteger or floati
246c0 6e 67 20 70 6f 69 6e 74 2e 20 20 49 66 0a 2a 2a  ng point.  If.**
246d0 20 73 75 63 68 20 61 20 63 6f 6e 76 65 72 73 69   such a conversi
246e0 6f 6e 20 69 73 20 70 6f 73 73 69 62 6c 65 20 77  on is possible w
246f0 69 74 68 6f 75 74 20 6c 6f 73 73 20 6f 66 20 69  ithout loss of i
24700 6e 66 6f 72 6d 61 74 69 6f 6e 20 28 69 6e 20 6f  nformation (in o
24710 74 68 65 72 0a 2a 2a 20 77 6f 72 64 73 2c 20 69  ther.** words, i
24720 66 20 74 68 65 20 76 61 6c 75 65 20 69 73 20 61  f the value is a
24730 20 73 74 72 69 6e 67 20 74 68 61 74 20 6c 6f 6f   string that loo
24740 6b 73 20 6c 69 6b 65 20 61 20 6e 75 6d 62 65 72  ks like a number
24750 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 6f  ).** then the co
24760 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 65 72 66  nversion is perf
24770 6f 72 6d 65 64 2e 20 20 4f 74 68 65 72 77 69 73  ormed.  Otherwis
24780 65 20 6e 6f 20 63 6f 6e 76 65 72 73 69 6f 6e 20  e no conversion 
24790 6f 63 63 75 72 73 2e 0a 2a 2a 20 54 68 65 20 5b  occurs..** The [
247a0 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c  SQLITE_INTEGER |
247b0 20 64 61 74 61 74 79 70 65 5d 20 61 66 74 65 72   datatype] after
247c0 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 72   conversion is r
247d0 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 50  eturned..**.** P
247e0 6c 65 61 73 65 20 70 61 79 20 70 61 72 74 69 63  lease pay partic
247f0 75 6c 61 72 20 61 74 74 65 6e 74 69 6f 6e 20 74  ular attention t
24800 6f 20 74 68 65 20 66 61 63 74 20 74 68 61 74 20  o the fact that 
24810 74 68 65 20 70 6f 69 6e 74 65 72 20 72 65 74 75  the pointer retu
24820 72 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71  rned.** from [sq
24830 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62  lite3_value_blob
24840 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61  ()], [sqlite3_va
24850 6c 75 65 5f 74 65 78 74 28 29 5d 2c 20 6f 72 0a  lue_text()], or.
24860 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ** [sqlite3_valu
24870 65 5f 74 65 78 74 31 36 28 29 5d 20 63 61 6e 20  e_text16()] can 
24880 62 65 20 69 6e 76 61 6c 69 64 61 74 65 64 20 62  be invalidated b
24890 79 20 61 20 73 75 62 73 65 71 75 65 6e 74 20 63  y a subsequent c
248a0 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  all to.** [sqlit
248b0 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 29  e3_value_bytes()
248c0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ], [sqlite3_valu
248d0 65 5f 62 79 74 65 73 31 36 28 29 5d 2c 20 5b 73  e_bytes16()], [s
248e0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
248f0 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c  t()],.** or [sql
24900 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
24910 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  6()]..**.** Thes
24920 65 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20  e routines must 
24930 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74  be called from t
24940 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 61  he same thread a
24950 73 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66 75 6e  s.** the SQL fun
24960 63 74 69 6f 6e 20 74 68 61 74 20 73 75 70 70 6c  ction that suppl
24970 69 65 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33  ied the [sqlite3
24980 5f 76 61 6c 75 65 2a 5d 20 70 61 72 61 6d 65 74  _value*] paramet
24990 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69  ers..**.** Requi
249a0 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 35  rements:.** [H15
249b0 31 30 33 5d 20 5b 48 31 35 31 30 36 5d 20 5b 48  103] [H15106] [H
249c0 31 35 31 30 39 5d 20 5b 48 31 35 31 31 32 5d 20  15109] [H15112] 
249d0 5b 48 31 35 31 31 35 5d 20 5b 48 31 35 31 31 38  [H15115] [H15118
249e0 5d 20 5b 48 31 35 31 32 31 5d 20 5b 48 31 35 31  ] [H15121] [H151
249f0 32 34 5d 0a 2a 2a 20 5b 48 31 35 31 32 37 5d 20  24].** [H15127] 
24a00 5b 48 31 35 31 33 30 5d 20 5b 48 31 35 31 33 33  [H15130] [H15133
24a10 5d 20 5b 48 31 35 31 33 36 5d 0a 2a 2f 0a 63 6f  ] [H15136].*/.co
24a20 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
24a30 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 73 71 6c  3_value_blob(sql
24a40 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e  ite3_value*);.in
24a50 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  t sqlite3_value_
24a60 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f 76 61  bytes(sqlite3_va
24a70 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  lue*);.int sqlit
24a80 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36  e3_value_bytes16
24a90 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
24aa0 3b 0a 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33  ;.double sqlite3
24ab0 5f 76 61 6c 75 65 5f 64 6f 75 62 6c 65 28 73 71  _value_double(sq
24ac0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69  lite3_value*);.i
24ad0 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt sqlite3_value
24ae0 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 76 61 6c  _int(sqlite3_val
24af0 75 65 2a 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e  ue*);.sqlite3_in
24b00 74 36 34 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  t64 sqlite3_valu
24b10 65 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f  e_int64(sqlite3_
24b20 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 75  value*);.const u
24b30 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a 73 71  nsigned char *sq
24b40 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
24b50 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
24b60 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
24b70 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
24b80 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  16(sqlite3_value
24b90 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  *);.const void *
24ba0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
24bb0 78 74 31 36 6c 65 28 73 71 6c 69 74 65 33 5f 76  xt16le(sqlite3_v
24bc0 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f  alue*);.const vo
24bd0 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75  id *sqlite3_valu
24be0 65 5f 74 65 78 74 31 36 62 65 28 73 71 6c 69 74  e_text16be(sqlit
24bf0 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20  e3_value*);.int 
24c00 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79  sqlite3_value_ty
24c10 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  pe(sqlite3_value
24c20 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  *);.int sqlite3_
24c30 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79  value_numeric_ty
24c40 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  pe(sqlite3_value
24c50 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
24c60 52 45 46 3a 20 4f 62 74 61 69 6e 20 41 67 67 72  REF: Obtain Aggr
24c70 65 67 61 74 65 20 46 75 6e 63 74 69 6f 6e 20 43  egate Function C
24c80 6f 6e 74 65 78 74 20 7b 48 31 36 32 31 30 7d 20  ontext {H16210} 
24c90 3c 53 32 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54  <S20200>.**.** T
24ca0 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
24cb0 6e 20 6f 66 20 61 67 67 72 65 67 61 74 65 20 53  n of aggregate S
24cc0 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 75 73 65  QL functions use
24cd0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 74 6f   this routine to
24ce0 20 61 6c 6c 6f 63 61 74 65 0a 2a 2a 20 61 20 73   allocate.** a s
24cf0 74 72 75 63 74 75 72 65 20 66 6f 72 20 73 74 6f  tructure for sto
24d00 72 69 6e 67 20 74 68 65 69 72 20 73 74 61 74 65  ring their state
24d10 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73  ..**.** The firs
24d20 74 20 74 69 6d 65 20 74 68 65 20 73 71 6c 69 74  t time the sqlit
24d30 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
24d40 74 65 78 74 28 29 20 72 6f 75 74 69 6e 65 20 69  text() routine i
24d50 73 20 63 61 6c 6c 65 64 20 66 6f 72 20 61 0a 2a  s called for a.*
24d60 2a 20 70 61 72 74 69 63 75 6c 61 72 20 61 67 67  * particular agg
24d70 72 65 67 61 74 65 2c 20 53 51 4c 69 74 65 20 61  regate, SQLite a
24d80 6c 6c 6f 63 61 74 65 73 20 6e 42 79 74 65 73 20  llocates nBytes 
24d90 6f 66 20 6d 65 6d 6f 72 79 2c 20 7a 65 72 6f 65  of memory, zeroe
24da0 73 20 6f 75 74 20 74 68 61 74 0a 2a 2a 20 6d 65  s out that.** me
24db0 6d 6f 72 79 2c 20 61 6e 64 20 72 65 74 75 72 6e  mory, and return
24dc0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 69  s a pointer to i
24dd0 74 2e 20 4f 6e 20 73 65 63 6f 6e 64 20 61 6e 64  t. On second and
24de0 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c   subsequent call
24df0 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  s to.** sqlite3_
24e00 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
24e10 74 28 29 20 66 6f 72 20 74 68 65 20 73 61 6d 65  t() for the same
24e20 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74   aggregate funct
24e30 69 6f 6e 20 69 6e 64 65 78 2c 0a 2a 2a 20 74 68  ion index,.** th
24e40 65 20 73 61 6d 65 20 62 75 66 66 65 72 20 69 73  e same buffer is
24e50 20 72 65 74 75 72 6e 65 64 2e 20 54 68 65 20 69   returned. The i
24e60 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
24e70 20 74 68 65 20 61 67 67 72 65 67 61 74 65 20 63   the aggregate c
24e80 61 6e 20 75 73 65 0a 2a 2a 20 74 68 65 20 72 65  an use.** the re
24e90 74 75 72 6e 65 64 20 62 75 66 66 65 72 20 74 6f  turned buffer to
24ea0 20 61 63 63 75 6d 75 6c 61 74 65 20 64 61 74 61   accumulate data
24eb0 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 61  ..**.** SQLite a
24ec0 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 66 72 65  utomatically fre
24ed0 65 73 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64  es the allocated
24ee0 20 62 75 66 66 65 72 20 77 68 65 6e 20 74 68 65   buffer when the
24ef0 20 61 67 67 72 65 67 61 74 65 0a 2a 2a 20 71 75   aggregate.** qu
24f00 65 72 79 20 63 6f 6e 63 6c 75 64 65 73 2e 0a 2a  ery concludes..*
24f10 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70  *.** The first p
24f20 61 72 61 6d 65 74 65 72 20 73 68 6f 75 6c 64 20  arameter should 
24f30 62 65 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  be a copy of the
24f40 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
24f50 74 65 78 74 20 7c 20 53 51 4c 20 66 75 6e 63 74  text | SQL funct
24f60 69 6f 6e 20 63 6f 6e 74 65 78 74 5d 20 74 68 61  ion context] tha
24f70 74 20 69 73 20 74 68 65 20 66 69 72 73 74 20 70  t is the first p
24f80 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74  arameter.** to t
24f90 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 6f 75 74  he callback rout
24fa0 69 6e 65 20 74 68 61 74 20 69 6d 70 6c 65 6d 65  ine that impleme
24fb0 6e 74 73 20 74 68 65 20 61 67 67 72 65 67 61 74  nts the aggregat
24fc0 65 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a  e function..**.*
24fd0 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6d  * This routine m
24fe0 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72  ust be called fr
24ff0 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65  om the same thre
25000 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74  ad in which.** t
25010 68 65 20 61 67 67 72 65 67 61 74 65 20 53 51 4c  he aggregate SQL
25020 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e   function is run
25030 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75  ning..**.** Requ
25040 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31  irements:.** [H1
25050 36 32 31 31 5d 20 5b 48 31 36 32 31 33 5d 20 5b  6211] [H16213] [
25060 48 31 36 32 31 35 5d 20 5b 48 31 36 32 31 37 5d  H16215] [H16217]
25070 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65  .*/.void *sqlite
25080 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
25090 65 78 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ext(sqlite3_cont
250a0 65 78 74 2a 2c 20 69 6e 74 20 6e 42 79 74 65 73  ext*, int nBytes
250b0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
250c0 45 46 3a 20 55 73 65 72 20 44 61 74 61 20 46 6f  EF: User Data Fo
250d0 72 20 46 75 6e 63 74 69 6f 6e 73 20 7b 48 31 36  r Functions {H16
250e0 32 34 30 7d 20 3c 53 32 30 32 30 30 3e 0a 2a 2a  240} <S20200>.**
250f0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
25100 75 73 65 72 5f 64 61 74 61 28 29 20 69 6e 74 65  user_data() inte
25110 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20  rface returns a 
25120 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70  copy of.** the p
25130 6f 69 6e 74 65 72 20 74 68 61 74 20 77 61 73 20  ointer that was 
25140 74 68 65 20 70 55 73 65 72 44 61 74 61 20 70 61  the pUserData pa
25150 72 61 6d 65 74 65 72 20 28 74 68 65 20 35 74 68  rameter (the 5th
25160 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f   parameter).** o
25170 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  f the [sqlite3_c
25180 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29  reate_function()
25190 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65  ].** and [sqlite
251a0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
251b0 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20  n16()] routines 
251c0 74 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a  that originally.
251d0 2a 2a 20 72 65 67 69 73 74 65 72 65 64 20 74 68  ** registered th
251e0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65  e application de
251f0 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20  fined function. 
25200 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73  {END}.**.** This
25210 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65   routine must be
25220 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65   called from the
25230 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20   same thread in 
25240 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 70 70  which.** the app
25250 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
25260 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e   function is run
25270 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75  ning..**.** Requ
25280 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31  irements:.** [H1
25290 36 32 34 33 5d 0a 2a 2f 0a 76 6f 69 64 20 2a 73  6243].*/.void *s
252a0 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61  qlite3_user_data
252b0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
252c0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
252d0 52 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f  REF: Database Co
252e0 6e 6e 65 63 74 69 6f 6e 20 46 6f 72 20 46 75 6e  nnection For Fun
252f0 63 74 69 6f 6e 73 20 7b 48 31 36 32 35 30 7d 20  ctions {H16250} 
25300 3c 53 36 30 36 30 30 3e 3c 53 32 30 32 30 30 3e  <S60600><S20200>
25310 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
25320 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61  e3_context_db_ha
25330 6e 64 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65  ndle() interface
25340 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20   returns a copy 
25350 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65  of.** the pointe
25360 72 20 74 6f 20 74 68 65 20 5b 64 61 74 61 62 61  r to the [databa
25370 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28  se connection] (
25380 74 68 65 20 31 73 74 20 70 61 72 61 6d 65 74 65  the 1st paramete
25390 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71  r).** of the [sq
253a0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
253b0 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20  ction()].** and 
253c0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
253d0 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f  function16()] ro
253e0 75 74 69 6e 65 73 20 74 68 61 74 20 6f 72 69 67  utines that orig
253f0 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74  inally.** regist
25400 65 72 65 64 20 74 68 65 20 61 70 70 6c 69 63 61  ered the applica
25410 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 6e  tion defined fun
25420 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 52 65 71  ction..**.** Req
25430 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48  uirements:.** [H
25440 31 36 32 35 33 5d 0a 2a 2f 0a 73 71 6c 69 74 65  16253].*/.sqlite
25450 33 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  3 *sqlite3_conte
25460 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 73 71 6c  xt_db_handle(sql
25470 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a  ite3_context*);.
25480 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
25490 20 46 75 6e 63 74 69 6f 6e 20 41 75 78 69 6c 69   Function Auxili
254a0 61 72 79 20 44 61 74 61 20 7b 48 31 36 32 37 30  ary Data {H16270
254b0 7d 20 3c 53 32 30 32 30 30 3e 0a 2a 2a 0a 2a 2a  } <S20200>.**.**
254c0 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74   The following t
254d0 77 6f 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79  wo functions may
254e0 20 62 65 20 75 73 65 64 20 62 79 20 73 63 61 6c   be used by scal
254f0 61 72 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  ar SQL functions
25500 20 74 6f 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65   to.** associate
25510 20 6d 65 74 61 64 61 74 61 20 77 69 74 68 20 61   metadata with a
25520 72 67 75 6d 65 6e 74 20 76 61 6c 75 65 73 2e 20  rgument values. 
25530 49 66 20 74 68 65 20 73 61 6d 65 20 76 61 6c 75  If the same valu
25540 65 20 69 73 20 70 61 73 73 65 64 20 74 6f 0a 2a  e is passed to.*
25550 2a 20 6d 75 6c 74 69 70 6c 65 20 69 6e 76 6f 63  * multiple invoc
25560 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61  ations of the sa
25570 6d 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  me SQL function 
25580 64 75 72 69 6e 67 20 71 75 65 72 79 20 65 78 65  during query exe
25590 63 75 74 69 6f 6e 2c 20 75 6e 64 65 72 0a 2a 2a  cution, under.**
255a0 20 73 6f 6d 65 20 63 69 72 63 75 6d 73 74 61 6e   some circumstan
255b0 63 65 73 20 74 68 65 20 61 73 73 6f 63 69 61 74  ces the associat
255c0 65 64 20 6d 65 74 61 64 61 74 61 20 6d 61 79 20  ed metadata may 
255d0 62 65 20 70 72 65 73 65 72 76 65 64 2e 20 54 68  be preserved. Th
255e0 69 73 20 6d 61 79 0a 2a 2a 20 62 65 20 75 73 65  is may.** be use
255f0 64 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20  d, for example, 
25600 74 6f 20 61 64 64 20 61 20 72 65 67 75 6c 61 72  to add a regular
25610 2d 65 78 70 72 65 73 73 69 6f 6e 20 6d 61 74 63  -expression matc
25620 68 69 6e 67 20 73 63 61 6c 61 72 0a 2a 2a 20 66  hing scalar.** f
25630 75 6e 63 74 69 6f 6e 2e 20 54 68 65 20 63 6f 6d  unction. The com
25640 70 69 6c 65 64 20 76 65 72 73 69 6f 6e 20 6f 66  piled version of
25650 20 74 68 65 20 72 65 67 75 6c 61 72 20 65 78 70   the regular exp
25660 72 65 73 73 69 6f 6e 20 69 73 20 73 74 6f 72 65  ression is store
25670 64 20 61 73 0a 2a 2a 20 6d 65 74 61 64 61 74 61  d as.** metadata
25680 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
25690 20 74 68 65 20 53 51 4c 20 76 61 6c 75 65 20 70   the SQL value p
256a0 61 73 73 65 64 20 61 73 20 74 68 65 20 72 65 67  assed as the reg
256b0 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e 0a  ular expression.
256c0 2a 2a 20 70 61 74 74 65 72 6e 2e 20 20 54 68 65  ** pattern.  The
256d0 20 63 6f 6d 70 69 6c 65 64 20 72 65 67 75 6c 61   compiled regula
256e0 72 20 65 78 70 72 65 73 73 69 6f 6e 20 63 61 6e  r expression can
256f0 20 62 65 20 72 65 75 73 65 64 20 6f 6e 20 6d 75   be reused on mu
25700 6c 74 69 70 6c 65 0a 2a 2a 20 69 6e 76 6f 63 61  ltiple.** invoca
25710 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d  tions of the sam
25720 65 20 66 75 6e 63 74 69 6f 6e 20 73 6f 20 74 68  e function so th
25730 61 74 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20  at the original 
25740 70 61 74 74 65 72 6e 20 73 74 72 69 6e 67 0a 2a  pattern string.*
25750 2a 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20  * does not need 
25760 74 6f 20 62 65 20 72 65 63 6f 6d 70 69 6c 65 64  to be recompiled
25770 20 6f 6e 20 65 61 63 68 20 69 6e 76 6f 63 61 74   on each invocat
25780 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ion..**.** The s
25790 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61  qlite3_get_auxda
257a0 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  ta() interface r
257b0 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
257c0 20 74 6f 20 74 68 65 20 6d 65 74 61 64 61 74 61   to the metadata
257d0 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 62  .** associated b
257e0 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 65  y the sqlite3_se
257f0 74 5f 61 75 78 64 61 74 61 28 29 20 66 75 6e 63  t_auxdata() func
25800 74 69 6f 6e 20 77 69 74 68 20 74 68 65 20 4e 74  tion with the Nt
25810 68 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 76 61  h argument.** va
25820 6c 75 65 20 74 6f 20 74 68 65 20 61 70 70 6c 69  lue to the appli
25830 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
25840 75 6e 63 74 69 6f 6e 2e 20 49 66 20 6e 6f 20 6d  unction. If no m
25850 65 74 61 64 61 74 61 20 68 61 73 20 62 65 65 6e  etadata has been
25860 20 65 76 65 72 0a 2a 2a 20 62 65 65 6e 20 73 65   ever.** been se
25870 74 20 66 6f 72 20 74 68 65 20 4e 74 68 20 61 72  t for the Nth ar
25880 67 75 6d 65 6e 74 20 6f 66 20 74 68 65 20 66 75  gument of the fu
25890 6e 63 74 69 6f 6e 2c 20 6f 72 20 69 66 20 74 68  nction, or if th
258a0 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a  e corresponding.
258b0 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70 61 72 61  ** function para
258c0 6d 65 74 65 72 20 68 61 73 20 63 68 61 6e 67 65  meter has change
258d0 64 20 73 69 6e 63 65 20 74 68 65 20 6d 65 74 61  d since the meta
258e0 2d 64 61 74 61 20 77 61 73 20 73 65 74 2c 0a 2a  -data was set,.*
258f0 2a 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 67  * then sqlite3_g
25900 65 74 5f 61 75 78 64 61 74 61 28 29 20 72 65 74  et_auxdata() ret
25910 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  urns a NULL poin
25920 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ter..**.** The s
25930 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61  qlite3_set_auxda
25940 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 20 73  ta() interface s
25950 61 76 65 73 20 74 68 65 20 6d 65 74 61 64 61 74  aves the metadat
25960 61 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20  a.** pointed to 
25970 62 79 20 69 74 73 20 33 72 64 20 70 61 72 61 6d  by its 3rd param
25980 65 74 65 72 20 61 73 20 74 68 65 20 6d 65 74 61  eter as the meta
25990 64 61 74 61 20 66 6f 72 20 74 68 65 20 4e 2d 74  data for the N-t
259a0 68 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6f 66  h.** argument of
259b0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
259c0 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
259d0 6e 2e 20 20 53 75 62 73 65 71 75 65 6e 74 0a 2a  n.  Subsequent.*
259e0 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74  * calls to sqlit
259f0 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29  e3_get_auxdata()
25a00 20 6d 69 67 68 74 20 72 65 74 75 72 6e 20 74 68   might return th
25a10 69 73 20 64 61 74 61 2c 20 69 66 20 69 74 20 68  is data, if it h
25a20 61 73 0a 2a 2a 20 6e 6f 74 20 62 65 65 6e 20 64  as.** not been d
25a30 65 73 74 72 6f 79 65 64 2e 0a 2a 2a 20 49 66 20  estroyed..** If 
25a40 69 74 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20  it is not NULL, 
25a50 53 51 4c 69 74 65 20 77 69 6c 6c 20 69 6e 76 6f  SQLite will invo
25a60 6b 65 20 74 68 65 20 64 65 73 74 72 75 63 74 6f  ke the destructo
25a70 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 67 69  r.** function gi
25a80 76 65 6e 20 62 79 20 74 68 65 20 34 74 68 20 70  ven by the 4th p
25a90 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
25aa0 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28  te3_set_auxdata(
25ab0 29 20 6f 6e 0a 2a 2a 20 74 68 65 20 6d 65 74 61  ) on.** the meta
25ac0 64 61 74 61 20 77 68 65 6e 20 74 68 65 20 63 6f  data when the co
25ad0 72 72 65 73 70 6f 6e 64 69 6e 67 20 66 75 6e 63  rresponding func
25ae0 74 69 6f 6e 20 70 61 72 61 6d 65 74 65 72 20 63  tion parameter c
25af0 68 61 6e 67 65 73 0a 2a 2a 20 6f 72 20 77 68 65  hanges.** or whe
25b00 6e 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  n the SQL statem
25b10 65 6e 74 20 63 6f 6d 70 6c 65 74 65 73 2c 20 77  ent completes, w
25b20 68 69 63 68 65 76 65 72 20 63 6f 6d 65 73 20 66  hichever comes f
25b30 69 72 73 74 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  irst..**.** SQLi
25b40 74 65 20 69 73 20 66 72 65 65 20 74 6f 20 63 61  te is free to ca
25b50 6c 6c 20 74 68 65 20 64 65 73 74 72 75 63 74 6f  ll the destructo
25b60 72 20 61 6e 64 20 64 72 6f 70 20 6d 65 74 61 64  r and drop metad
25b70 61 74 61 20 6f 6e 20 61 6e 79 0a 2a 2a 20 70 61  ata on any.** pa
25b80 72 61 6d 65 74 65 72 20 6f 66 20 61 6e 79 20 66  rameter of any f
25b90 75 6e 63 74 69 6f 6e 20 61 74 20 61 6e 79 20 74  unction at any t
25ba0 69 6d 65 2e 20 20 54 68 65 20 6f 6e 6c 79 20 67  ime.  The only g
25bb0 75 61 72 61 6e 74 65 65 20 69 73 20 74 68 61 74  uarantee is that
25bc0 0a 2a 2a 20 74 68 65 20 64 65 73 74 72 75 63 74  .** the destruct
25bd0 6f 72 20 77 69 6c 6c 20 62 65 20 63 61 6c 6c 65  or will be calle
25be0 64 20 62 65 66 6f 72 65 20 74 68 65 20 6d 65 74  d before the met
25bf0 61 64 61 74 61 20 69 73 20 64 72 6f 70 70 65 64  adata is dropped
25c00 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 70 72 61 63 74  ..**.** In pract
25c10 69 63 65 2c 20 6d 65 74 61 64 61 74 61 20 69 73  ice, metadata is
25c20 20 70 72 65 73 65 72 76 65 64 20 62 65 74 77 65   preserved betwe
25c30 65 6e 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c  en function call
25c40 73 20 66 6f 72 0a 2a 2a 20 65 78 70 72 65 73 73  s for.** express
25c50 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 63 6f  ions that are co
25c60 6e 73 74 61 6e 74 20 61 74 20 63 6f 6d 70 69 6c  nstant at compil
25c70 65 20 74 69 6d 65 2e 20 54 68 69 73 20 69 6e 63  e time. This inc
25c80 6c 75 64 65 73 20 6c 69 74 65 72 61 6c 0a 2a 2a  ludes literal.**
25c90 20 76 61 6c 75 65 73 20 61 6e 64 20 53 51 4c 20   values and SQL 
25ca0 76 61 72 69 61 62 6c 65 73 2e 0a 2a 2a 0a 2a 2a  variables..**.**
25cb0 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
25cc0 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66  must be called f
25cd0 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72  rom the same thr
25ce0 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20  ead in which.** 
25cf0 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
25d00 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 0a   is running..**.
25d10 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a  ** Requirements:
25d20 0a 2a 2a 20 5b 48 31 36 32 37 32 5d 20 5b 48 31  .** [H16272] [H1
25d30 36 32 37 34 5d 20 5b 48 31 36 32 37 36 5d 20 5b  6274] [H16276] [
25d40 48 31 36 32 37 37 5d 20 5b 48 31 36 32 37 38 5d  H16277] [H16278]
25d50 20 5b 48 31 36 32 37 39 5d 0a 2a 2f 0a 76 6f 69   [H16279].*/.voi
25d60 64 20 2a 73 71 6c 69 74 65 33 5f 67 65 74 5f 61  d *sqlite3_get_a
25d70 75 78 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63  uxdata(sqlite3_c
25d80 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e 29 3b  ontext*, int N);
25d90 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 73 65  .void sqlite3_se
25da0 74 5f 61 75 78 64 61 74 61 28 73 71 6c 69 74 65  t_auxdata(sqlite
25db0 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20  3_context*, int 
25dc0 4e 2c 20 76 6f 69 64 2a 2c 20 76 6f 69 64 20 28  N, void*, void (
25dd0 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 0a 0a 2f 2a  *)(void*));.../*
25de0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
25df0 6e 73 74 61 6e 74 73 20 44 65 66 69 6e 69 6e 67  nstants Defining
25e00 20 53 70 65 63 69 61 6c 20 44 65 73 74 72 75 63   Special Destruc
25e10 74 6f 72 20 42 65 68 61 76 69 6f 72 20 7b 48 31  tor Behavior {H1
25e20 30 32 38 30 7d 20 3c 53 33 30 31 30 30 3e 0a 2a  0280} <S30100>.*
25e30 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72 65 20 73  *.** These are s
25e40 70 65 63 69 61 6c 20 76 61 6c 75 65 73 20 66 6f  pecial values fo
25e50 72 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72  r the destructor
25e60 20 74 68 61 74 20 69 73 20 70 61 73 73 65 64 20   that is passed 
25e70 69 6e 20 61 73 20 74 68 65 0a 2a 2a 20 66 69 6e  in as the.** fin
25e80 61 6c 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 72  al argument to r
25e90 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71  outines like [sq
25ea0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f  lite3_result_blo
25eb0 62 28 29 5d 2e 20 20 49 66 20 74 68 65 20 64 65  b()].  If the de
25ec0 73 74 72 75 63 74 6f 72 0a 2a 2a 20 61 72 67 75  structor.** argu
25ed0 6d 65 6e 74 20 69 73 20 53 51 4c 49 54 45 5f 53  ment is SQLITE_S
25ee0 54 41 54 49 43 2c 20 69 74 20 6d 65 61 6e 73 20  TATIC, it means 
25ef0 74 68 61 74 20 74 68 65 20 63 6f 6e 74 65 6e 74  that the content
25f00 20 70 6f 69 6e 74 65 72 20 69 73 20 63 6f 6e 73   pointer is cons
25f10 74 61 6e 74 0a 2a 2a 20 61 6e 64 20 77 69 6c 6c  tant.** and will
25f20 20 6e 65 76 65 72 20 63 68 61 6e 67 65 2e 20 20   never change.  
25f30 49 74 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64  It does not need
25f40 20 74 6f 20 62 65 20 64 65 73 74 72 6f 79 65 64   to be destroyed
25f50 2e 20 20 54 68 65 0a 2a 2a 20 53 51 4c 49 54 45  .  The.** SQLITE
25f60 5f 54 52 41 4e 53 49 45 4e 54 20 76 61 6c 75 65  _TRANSIENT value
25f70 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20   means that the 
25f80 63 6f 6e 74 65 6e 74 20 77 69 6c 6c 20 6c 69 6b  content will lik
25f90 65 6c 79 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a  ely change in.**
25fa0 20 74 68 65 20 6e 65 61 72 20 66 75 74 75 72 65   the near future
25fb0 20 61 6e 64 20 74 68 61 74 20 53 51 4c 69 74 65   and that SQLite
25fc0 20 73 68 6f 75 6c 64 20 6d 61 6b 65 20 69 74 73   should make its
25fd0 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70   own private cop
25fe0 79 20 6f 66 0a 2a 2a 20 74 68 65 20 63 6f 6e 74  y of.** the cont
25ff0 65 6e 74 20 62 65 66 6f 72 65 20 72 65 74 75 72  ent before retur
26000 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ning..**.** The 
26010 74 79 70 65 64 65 66 20 69 73 20 6e 65 63 65 73  typedef is neces
26020 73 61 72 79 20 74 6f 20 77 6f 72 6b 20 61 72 6f  sary to work aro
26030 75 6e 64 20 70 72 6f 62 6c 65 6d 73 20 69 6e 20  und problems in 
26040 63 65 72 74 61 69 6e 0a 2a 2a 20 43 2b 2b 20 63  certain.** C++ c
26050 6f 6d 70 69 6c 65 72 73 2e 20 20 53 65 65 20 74  ompilers.  See t
26060 69 63 6b 65 74 20 23 32 31 39 31 2e 0a 2a 2f 0a  icket #2191..*/.
26070 74 79 70 65 64 65 66 20 76 6f 69 64 20 28 2a 73  typedef void (*s
26080 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f  qlite3_destructo
26090 72 5f 74 79 70 65 29 28 76 6f 69 64 2a 29 3b 0a  r_type)(void*);.
260a0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
260b0 54 41 54 49 43 20 20 20 20 20 20 28 28 73 71 6c  TATIC      ((sql
260c0 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f  ite3_destructor_
260d0 74 79 70 65 29 30 29 0a 23 64 65 66 69 6e 65 20  type)0).#define 
260e0 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54  SQLITE_TRANSIENT
260f0 20 20 20 28 28 73 71 6c 69 74 65 33 5f 64 65 73     ((sqlite3_des
26100 74 72 75 63 74 6f 72 5f 74 79 70 65 29 2d 31 29  tructor_type)-1)
26110 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
26120 3a 20 53 65 74 74 69 6e 67 20 54 68 65 20 52 65  : Setting The Re
26130 73 75 6c 74 20 4f 66 20 41 6e 20 53 51 4c 20 46  sult Of An SQL F
26140 75 6e 63 74 69 6f 6e 20 7b 48 31 36 34 30 30 7d  unction {H16400}
26150 20 3c 53 32 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20   <S20200>.**.** 
26160 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
26170 72 65 20 75 73 65 64 20 62 79 20 74 68 65 20 78  re used by the x
26180 46 75 6e 63 20 6f 72 20 78 46 69 6e 61 6c 20 63  Func or xFinal c
26190 61 6c 6c 62 61 63 6b 73 20 74 68 61 74 0a 2a 2a  allbacks that.**
261a0 20 69 6d 70 6c 65 6d 65 6e 74 20 53 51 4c 20 66   implement SQL f
261b0 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67  unctions and agg
261c0 72 65 67 61 74 65 73 2e 20 20 53 65 65 0a 2a 2a  regates.  See.**
261d0 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
261e0 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64  _function()] and
261f0 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
26200 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a  _function16()].*
26210 2a 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  * for additional
26220 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a   information..**
26230 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69  .** These functi
26240 6f 6e 73 20 77 6f 72 6b 20 76 65 72 79 20 6d 75  ons work very mu
26250 63 68 20 6c 69 6b 65 20 74 68 65 20 5b 70 61 72  ch like the [par
26260 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 5d 20  ameter binding] 
26270 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 66 75 6e  family of.** fun
26280 63 74 69 6f 6e 73 20 75 73 65 64 20 74 6f 20 62  ctions used to b
26290 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 68 6f  ind values to ho
262a0 73 74 20 70 61 72 61 6d 65 74 65 72 73 20 69 6e  st parameters in
262b0 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
262c0 65 6e 74 73 2e 0a 2a 2a 20 52 65 66 65 72 20 74  ents..** Refer t
262d0 6f 20 74 68 65 20 5b 53 51 4c 20 70 61 72 61 6d  o the [SQL param
262e0 65 74 65 72 5d 20 64 6f 63 75 6d 65 6e 74 61 74  eter] documentat
262f0 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69 6f 6e  ion for addition
26300 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a  al information..
26310 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
26320 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29 20  3_result_blob() 
26330 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74  interface sets t
26340 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a  he result from.*
26350 2a 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  * an application
26360 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
26370 6e 20 74 6f 20 62 65 20 74 68 65 20 42 4c 4f 42  n to be the BLOB
26380 20 77 68 6f 73 65 20 63 6f 6e 74 65 6e 74 20 69   whose content i
26390 73 20 70 6f 69 6e 74 65 64 0a 2a 2a 20 74 6f 20  s pointed.** to 
263a0 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61  by the second pa
263b0 72 61 6d 65 74 65 72 20 61 6e 64 20 77 68 69 63  rameter and whic
263c0 68 20 69 73 20 4e 20 62 79 74 65 73 20 6c 6f 6e  h is N bytes lon
263d0 67 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65  g where N is the
263e0 0a 2a 2a 20 74 68 69 72 64 20 70 61 72 61 6d 65  .** third parame
263f0 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ter..**.** The s
26400 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65  qlite3_result_ze
26410 72 6f 62 6c 6f 62 28 29 20 69 6e 74 65 72 66 61  roblob() interfa
26420 63 65 73 20 73 65 74 20 74 68 65 20 72 65 73 75  ces set the resu
26430 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70  lt of.** the app
26440 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
26450 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
26460 61 20 42 4c 4f 42 20 63 6f 6e 74 61 69 6e 69 6e  a BLOB containin
26470 67 20 61 6c 6c 20 7a 65 72 6f 0a 2a 2a 20 62 79  g all zero.** by
26480 74 65 73 20 61 6e 64 20 4e 20 62 79 74 65 73 20  tes and N bytes 
26490 69 6e 20 73 69 7a 65 2c 20 77 68 65 72 65 20 4e  in size, where N
264a0 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66   is the value of
264b0 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
264c0 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  er..**.** The sq
264d0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75  lite3_result_dou
264e0 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 20  ble() interface 
264f0 73 65 74 73 20 74 68 65 20 72 65 73 75 6c 74 20  sets the result 
26500 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69  from.** an appli
26510 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
26520 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20  unction to be a 
26530 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76  floating point v
26540 61 6c 75 65 20 73 70 65 63 69 66 69 65 64 0a 2a  alue specified.*
26550 2a 20 62 79 20 69 74 73 20 32 6e 64 20 61 72 67  * by its 2nd arg
26560 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ument..**.** The
26570 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
26580 65 72 72 6f 72 28 29 20 61 6e 64 20 73 71 6c 69  error() and sqli
26590 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
265a0 31 36 28 29 20 66 75 6e 63 74 69 6f 6e 73 0a 2a  16() functions.*
265b0 2a 20 63 61 75 73 65 20 74 68 65 20 69 6d 70 6c  * cause the impl
265c0 65 6d 65 6e 74 65 64 20 53 51 4c 20 66 75 6e 63  emented SQL func
265d0 74 69 6f 6e 20 74 6f 20 74 68 72 6f 77 20 61 6e  tion to throw an
265e0 20 65 78 63 65 70 74 69 6f 6e 2e 0a 2a 2a 20 53   exception..** S
265f0 51 4c 69 74 65 20 75 73 65 73 20 74 68 65 20 73  QLite uses the s
26600 74 72 69 6e 67 20 70 6f 69 6e 74 65 64 20 74 6f  tring pointed to
26610 20 62 79 20 74 68 65 0a 2a 2a 20 32 6e 64 20 70   by the.** 2nd p
26620 61 72 61 6d 65 74 65 72 20 6f 66 20 73 71 6c 69  arameter of sqli
26630 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
26640 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65  () or sqlite3_re
26650 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a  sult_error16().*
26660 2a 20 61 73 20 74 68 65 20 74 65 78 74 20 6f 66  * as the text of
26670 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67   an error messag
26680 65 2e 20 20 53 51 4c 69 74 65 20 69 6e 74 65 72  e.  SQLite inter
26690 70 72 65 74 73 20 74 68 65 20 65 72 72 6f 72 0a  prets the error.
266a0 2a 2a 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e  ** message strin
266b0 67 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72  g from sqlite3_r
266c0 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 73  esult_error() as
266d0 20 55 54 46 2d 38 2e 20 53 51 4c 69 74 65 0a 2a   UTF-8. SQLite.*
266e0 2a 20 69 6e 74 65 72 70 72 65 74 73 20 74 68 65  * interprets the
266f0 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c   string from sql
26700 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
26710 72 31 36 28 29 20 61 73 20 55 54 46 2d 31 36 20  r16() as UTF-16 
26720 69 6e 20 6e 61 74 69 76 65 0a 2a 2a 20 62 79 74  in native.** byt
26730 65 20 6f 72 64 65 72 2e 20 20 49 66 20 74 68 65  e order.  If the
26740 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
26750 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75   to sqlite3_resu
26760 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72  lt_error().** or
26770 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
26780 65 72 72 6f 72 31 36 28 29 20 69 73 20 6e 65 67  error16() is neg
26790 61 74 69 76 65 20 74 68 65 6e 20 53 51 4c 69 74  ative then SQLit
267a0 65 20 74 61 6b 65 73 20 61 73 20 74 68 65 20 65  e takes as the e
267b0 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20  rror.** message 
267c0 61 6c 6c 20 74 65 78 74 20 75 70 20 74 68 72 6f  all text up thro
267d0 75 67 68 20 74 68 65 20 66 69 72 73 74 20 7a 65  ugh the first ze
267e0 72 6f 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a  ro character..**
267f0 20 49 66 20 74 68 65 20 74 68 69 72 64 20 70 61   If the third pa
26800 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
26810 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28  e3_result_error(
26820 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ) or.** sqlite3_
26830 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29  result_error16()
26840 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65   is non-negative
26850 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b   then SQLite tak
26860 65 73 20 74 68 61 74 20 6d 61 6e 79 0a 2a 2a 20  es that many.** 
26870 62 79 74 65 73 20 28 6e 6f 74 20 63 68 61 72 61  bytes (not chara
26880 63 74 65 72 73 29 20 66 72 6f 6d 20 74 68 65 20  cters) from the 
26890 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 73  2nd parameter as
268a0 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61   the error messa
268b0 67 65 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  ge..** The sqlit
268c0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28  e3_result_error(
268d0 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65  ) and sqlite3_re
268e0 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a  sult_error16().*
268f0 2a 20 72 6f 75 74 69 6e 65 73 20 6d 61 6b 65 20  * routines make 
26900 61 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f  a private copy o
26910 66 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73  f the error mess
26920 61 67 65 20 74 65 78 74 20 62 65 66 6f 72 65 0a  age text before.
26930 2a 2a 20 74 68 65 79 20 72 65 74 75 72 6e 2e 20  ** they return. 
26940 20 48 65 6e 63 65 2c 20 74 68 65 20 63 61 6c 6c   Hence, the call
26950 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e  ing function can
26960 20 64 65 61 6c 6c 6f 63 61 74 65 20 6f 72 0a 2a   deallocate or.*
26970 2a 20 6d 6f 64 69 66 79 20 74 68 65 20 74 65 78  * modify the tex
26980 74 20 61 66 74 65 72 20 74 68 65 79 20 72 65 74  t after they ret
26990 75 72 6e 20 77 69 74 68 6f 75 74 20 68 61 72 6d  urn without harm
269a0 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  ..** The sqlite3
269b0 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63 6f  _result_error_co
269c0 64 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 63 68  de() function ch
269d0 61 6e 67 65 73 20 74 68 65 20 65 72 72 6f 72 20  anges the error 
269e0 63 6f 64 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64  code.** returned
269f0 20 62 79 20 53 51 4c 69 74 65 20 61 73 20 61 20   by SQLite as a 
26a00 72 65 73 75 6c 74 20 6f 66 20 61 6e 20 65 72 72  result of an err
26a10 6f 72 20 69 6e 20 61 20 66 75 6e 63 74 69 6f 6e  or in a function
26a20 2e 20 20 42 79 20 64 65 66 61 75 6c 74 2c 0a 2a  .  By default,.*
26a30 2a 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65  * the error code
26a40 20 69 73 20 53 51 4c 49 54 45 5f 45 52 52 4f 52   is SQLITE_ERROR
26a50 2e 20 20 41 20 73 75 62 73 65 71 75 65 6e 74 20  .  A subsequent 
26a60 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
26a70 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a  result_error().*
26a80 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73  * or sqlite3_res
26a90 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 72 65  ult_error16() re
26aa0 73 65 74 73 20 74 68 65 20 65 72 72 6f 72 20 63  sets the error c
26ab0 6f 64 65 20 74 6f 20 53 51 4c 49 54 45 5f 45 52  ode to SQLITE_ER
26ac0 52 4f 52 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ROR..**.** The s
26ad0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 6f  qlite3_result_to
26ae0 6f 62 69 67 28 29 20 69 6e 74 65 72 66 61 63 65  obig() interface
26af0 20 63 61 75 73 65 73 20 53 51 4c 69 74 65 20 74   causes SQLite t
26b00 6f 20 74 68 72 6f 77 20 61 6e 20 65 72 72 6f 72  o throw an error
26b10 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67 20 74  .** indicating t
26b20 68 61 74 20 61 20 73 74 72 69 6e 67 20 6f 72 20  hat a string or 
26b30 42 4c 4f 42 20 69 73 20 74 6f 20 6c 6f 6e 67 20  BLOB is to long 
26b40 74 6f 20 72 65 70 72 65 73 65 6e 74 2e 0a 2a 2a  to represent..**
26b50 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
26b60 72 65 73 75 6c 74 5f 6e 6f 6d 65 6d 28 29 20 69  result_nomem() i
26b70 6e 74 65 72 66 61 63 65 20 63 61 75 73 65 73 20  nterface causes 
26b80 53 51 4c 69 74 65 20 74 6f 20 74 68 72 6f 77 20  SQLite to throw 
26b90 61 6e 20 65 72 72 6f 72 0a 2a 2a 20 69 6e 64 69  an error.** indi
26ba0 63 61 74 69 6e 67 20 74 68 61 74 20 61 20 6d 65  cating that a me
26bb0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
26bc0 66 61 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  failed..**.** Th
26bd0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
26be0 5f 69 6e 74 28 29 20 69 6e 74 65 72 66 61 63 65  _int() interface
26bf0 20 73 65 74 73 20 74 68 65 20 72 65 74 75 72 6e   sets the return
26c00 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65   value.** of the
26c10 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
26c20 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f  ined function to
26c30 20 62 65 20 74 68 65 20 33 32 2d 62 69 74 20 73   be the 32-bit s
26c40 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a  igned integer.**
26c50 20 76 61 6c 75 65 20 67 69 76 65 6e 20 69 6e 20   value given in 
26c60 74 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74  the 2nd argument
26c70 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  ..** The sqlite3
26c80 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 28 29 20  _result_int64() 
26c90 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74  interface sets t
26ca0 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a  he return value.
26cb0 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63  ** of the applic
26cc0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
26cd0 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65  nction to be the
26ce0 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69   64-bit signed i
26cf0 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20  nteger.** value 
26d00 67 69 76 65 6e 20 69 6e 20 74 68 65 20 32 6e 64  given in the 2nd
26d10 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a   argument..**.**
26d20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   The sqlite3_res
26d30 75 6c 74 5f 6e 75 6c 6c 28 29 20 69 6e 74 65 72  ult_null() inter
26d40 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65  face sets the re
26d50 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66  turn value.** of
26d60 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
26d70 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
26d80 6e 20 74 6f 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a  n to be NULL..**
26d90 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
26da0 72 65 73 75 6c 74 5f 74 65 78 74 28 29 2c 20 73  result_text(), s
26db0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
26dc0 78 74 31 36 28 29 2c 0a 2a 2a 20 73 71 6c 69 74  xt16(),.** sqlit
26dd0 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
26de0 6c 65 28 29 2c 20 61 6e 64 20 73 71 6c 69 74 65  le(), and sqlite
26df0 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62  3_result_text16b
26e00 65 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  e() interfaces.*
26e10 2a 20 73 65 74 20 74 68 65 20 72 65 74 75 72 6e  * set the return
26e20 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 61 70   value of the ap
26e30 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
26e40 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  d function to be
26e50 0a 2a 2a 20 61 20 74 65 78 74 20 73 74 72 69 6e  .** a text strin
26e60 67 20 77 68 69 63 68 20 69 73 20 72 65 70 72 65  g which is repre
26e70 73 65 6e 74 65 64 20 61 73 20 55 54 46 2d 38 2c  sented as UTF-8,
26e80 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62   UTF-16 native b
26e90 79 74 65 20 6f 72 64 65 72 2c 0a 2a 2a 20 55 54  yte order,.** UT
26ea0 46 2d 31 36 20 6c 69 74 74 6c 65 20 65 6e 64 69  F-16 little endi
26eb0 61 6e 2c 20 6f 72 20 55 54 46 2d 31 36 20 62 69  an, or UTF-16 bi
26ec0 67 20 65 6e 64 69 61 6e 2c 20 72 65 73 70 65 63  g endian, respec
26ed0 74 69 76 65 6c 79 2e 0a 2a 2a 20 53 51 4c 69 74  tively..** SQLit
26ee0 65 20 74 61 6b 65 73 20 74 68 65 20 74 65 78 74  e takes the text
26ef0 20 72 65 73 75 6c 74 20 66 72 6f 6d 20 74 68 65   result from the
26f00 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 66 72 6f   application fro
26f10 6d 0a 2a 2a 20 74 68 65 20 32 6e 64 20 70 61 72  m.** the 2nd par
26f20 61 6d 65 74 65 72 20 6f 66 20 74 68 65 20 73 71  ameter of the sq
26f30 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
26f40 74 2a 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a  t* interfaces..*
26f50 2a 20 49 66 20 74 68 65 20 33 72 64 20 70 61 72  * If the 3rd par
26f60 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71  ameter to the sq
26f70 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
26f80 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  t* interfaces.**
26f90 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68   is negative, th
26fa0 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20  en SQLite takes 
26fb0 72 65 73 75 6c 74 20 74 65 78 74 20 66 72 6f 6d  result text from
26fc0 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
26fd0 65 72 0a 2a 2a 20 74 68 72 6f 75 67 68 20 74 68  er.** through th
26fe0 65 20 66 69 72 73 74 20 7a 65 72 6f 20 63 68 61  e first zero cha
26ff0 72 61 63 74 65 72 2e 0a 2a 2a 20 49 66 20 74 68  racter..** If th
27000 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20  e 3rd parameter 
27010 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72  to the sqlite3_r
27020 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65  esult_text* inte
27030 72 66 61 63 65 73 0a 2a 2a 20 69 73 20 6e 6f 6e  rfaces.** is non
27040 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20  -negative, then 
27050 61 73 20 6d 61 6e 79 20 62 79 74 65 73 20 28 6e  as many bytes (n
27060 6f 74 20 63 68 61 72 61 63 74 65 72 73 29 20 6f  ot characters) o
27070 66 20 74 68 65 20 74 65 78 74 0a 2a 2a 20 70 6f  f the text.** po
27080 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65 20  inted to by the 
27090 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 72  2nd parameter ar
270a0 65 20 74 61 6b 65 6e 20 61 73 20 74 68 65 20 61  e taken as the a
270b0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
270c0 65 64 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 72  ed.** function r
270d0 65 73 75 6c 74 2e 0a 2a 2a 20 49 66 20 74 68 65  esult..** If the
270e0 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   4th parameter t
270f0 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65  o the sqlite3_re
27100 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72  sult_text* inter
27110 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69  faces.** or sqli
27120 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20  te3_result_blob 
27130 69 73 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f  is a non-NULL po
27140 69 6e 74 65 72 2c 20 74 68 65 6e 20 53 51 4c 69  inter, then SQLi
27150 74 65 20 63 61 6c 6c 73 20 74 68 61 74 0a 2a 2a  te calls that.**
27160 20 66 75 6e 63 74 69 6f 6e 20 61 73 20 74 68 65   function as the
27170 20 64 65 73 74 72 75 63 74 6f 72 20 6f 6e 20 74   destructor on t
27180 68 65 20 74 65 78 74 20 6f 72 20 42 4c 4f 42 20  he text or BLOB 
27190 72 65 73 75 6c 74 20 77 68 65 6e 20 69 74 20 68  result when it h
271a0 61 73 0a 2a 2a 20 66 69 6e 69 73 68 65 64 20 75  as.** finished u
271b0 73 69 6e 67 20 74 68 61 74 20 72 65 73 75 6c 74  sing that result
271c0 2e 0a 2a 2a 20 49 66 20 74 68 65 20 34 74 68 20  ..** If the 4th 
271d0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
271e0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
271f0 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73  text* interfaces
27200 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72   or.** sqlite3_r
27210 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68  esult_blob is th
27220 65 20 73 70 65 63 69 61 6c 20 63 6f 6e 73 74 61  e special consta
27230 6e 74 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43  nt SQLITE_STATIC
27240 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 0a 2a 2a  , then SQLite.**
27250 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 68   assumes that th
27260 65 20 74 65 78 74 20 6f 72 20 42 4c 4f 42 20 72  e text or BLOB r
27270 65 73 75 6c 74 20 69 73 20 69 6e 20 63 6f 6e 73  esult is in cons
27280 74 61 6e 74 20 73 70 61 63 65 20 61 6e 64 20 64  tant space and d
27290 6f 65 73 20 6e 6f 74 0a 2a 2a 20 63 6f 70 79 20  oes not.** copy 
272a0 74 68 65 20 69 74 20 6f 72 20 63 61 6c 6c 20 61  the it or call a
272b0 20 64 65 73 74 72 75 63 74 6f 72 20 77 68 65 6e   destructor when
272c0 20 69 74 20 68 61 73 20 66 69 6e 69 73 68 65 64   it has finished
272d0 20 75 73 69 6e 67 20 74 68 61 74 20 72 65 73 75   using that resu
272e0 6c 74 2e 0a 2a 2a 20 49 66 20 74 68 65 20 34 74  lt..** If the 4t
272f0 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
27300 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
27310 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63  t_text* interfac
27320 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33  es.** or sqlite3
27330 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20  _result_blob is 
27340 74 68 65 20 73 70 65 63 69 61 6c 20 63 6f 6e 73  the special cons
27350 74 61 6e 74 20 53 51 4c 49 54 45 5f 54 52 41 4e  tant SQLITE_TRAN
27360 53 49 45 4e 54 0a 2a 2a 20 74 68 65 6e 20 53 51  SIENT.** then SQ
27370 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70  Lite makes a cop
27380 79 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  y of the result 
27390 69 6e 74 6f 20 73 70 61 63 65 20 6f 62 74 61 69  into space obtai
273a0 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 66 72 6f 6d  ned from.** from
273b0 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
273c0 28 29 5d 20 62 65 66 6f 72 65 20 69 74 20 72 65  ()] before it re
273d0 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  turns..**.** The
273e0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
273f0 76 61 6c 75 65 28 29 20 69 6e 74 65 72 66 61 63  value() interfac
27400 65 20 73 65 74 73 20 74 68 65 20 72 65 73 75 6c  e sets the resul
27410 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c  t of.** the appl
27420 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
27430 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61  function to be a
27440 20 63 6f 70 79 20 74 68 65 0a 2a 2a 20 5b 75 6e   copy the.** [un
27450 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
27460 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
27470 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65  specified by the
27480 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20   2nd parameter. 
27490 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   The.** sqlite3_
274a0 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 69  result_value() i
274b0 6e 74 65 72 66 61 63 65 20 6d 61 6b 65 73 20 61  nterface makes a
274c0 20 63 6f 70 79 20 6f 66 20 74 68 65 20 5b 73 71   copy of the [sq
274d0 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20  lite3_value].** 
274e0 73 6f 20 74 68 61 74 20 74 68 65 20 5b 73 71 6c  so that the [sql
274f0 69 74 65 33 5f 76 61 6c 75 65 5d 20 73 70 65 63  ite3_value] spec
27500 69 66 69 65 64 20 69 6e 20 74 68 65 20 70 61 72  ified in the par
27510 61 6d 65 74 65 72 20 6d 61 79 20 63 68 61 6e 67  ameter may chang
27520 65 20 6f 72 0a 2a 2a 20 62 65 20 64 65 61 6c 6c  e or.** be deall
27530 6f 63 61 74 65 64 20 61 66 74 65 72 20 73 71 6c  ocated after sql
27540 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75  ite3_result_valu
27550 65 28 29 20 72 65 74 75 72 6e 73 20 77 69 74 68  e() returns with
27560 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 41 20 5b  out harm..** A [
27570 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
27580 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
27590 6d 61 79 20 61 6c 77 61 79 73 20 62 65 20 75 73  may always be us
275a0 65 64 20 77 68 65 72 65 20 61 6e 0a 2a 2a 20 5b  ed where an.** [
275b0 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
275c0 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
275d0 74 20 69 73 20 72 65 71 75 69 72 65 64 2c 20 73  t is required, s
275e0 6f 20 65 69 74 68 65 72 0a 2a 2a 20 6b 69 6e 64  o either.** kind
275f0 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c   of [sqlite3_val
27600 75 65 5d 20 6f 62 6a 65 63 74 20 63 61 6e 20 62  ue] object can b
27610 65 20 75 73 65 64 20 77 69 74 68 20 74 68 69 73  e used with this
27620 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a   interface..**.*
27630 2a 20 49 66 20 74 68 65 73 65 20 72 6f 75 74 69  * If these routi
27640 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 66  nes are called f
27650 72 6f 6d 20 77 69 74 68 69 6e 20 74 68 65 20 64  rom within the d
27660 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 0a  ifferent thread.
27670 2a 2a 20 74 68 61 6e 20 74 68 65 20 6f 6e 65 20  ** than the one 
27680 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 61  containing the a
27690 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
276a0 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74  ed function that
276b0 20 72 65 63 65 69 76 65 64 0a 2a 2a 20 74 68 65   received.** the
276c0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78   [sqlite3_contex
276d0 74 5d 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 20  t] pointer, the 
276e0 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65  results are unde
276f0 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 71  fined..**.** Req
27700 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48  uirements:.** [H
27710 31 36 34 30 33 5d 20 5b 48 31 36 34 30 36 5d 20  16403] [H16406] 
27720 5b 48 31 36 34 30 39 5d 20 5b 48 31 36 34 31 32  [H16409] [H16412
27730 5d 20 5b 48 31 36 34 31 35 5d 20 5b 48 31 36 34  ] [H16415] [H164
27740 31 38 5d 20 5b 48 31 36 34 32 31 5d 20 5b 48 31  18] [H16421] [H1
27750 36 34 32 34 5d 0a 2a 2a 20 5b 48 31 36 34 32 37  6424].** [H16427
27760 5d 20 5b 48 31 36 34 33 30 5d 20 5b 48 31 36 34  ] [H16430] [H164
27770 33 33 5d 20 5b 48 31 36 34 33 36 5d 20 5b 48 31  33] [H16436] [H1
27780 36 34 33 39 5d 20 5b 48 31 36 34 34 32 5d 20 5b  6439] [H16442] [
27790 48 31 36 34 34 35 5d 20 5b 48 31 36 34 34 38 5d  H16445] [H16448]
277a0 0a 2a 2a 20 5b 48 31 36 34 35 31 5d 20 5b 48 31  .** [H16451] [H1
277b0 36 34 35 34 5d 20 5b 48 31 36 34 35 37 5d 20 5b  6454] [H16457] [
277c0 48 31 36 34 36 30 5d 20 5b 48 31 36 34 36 33 5d  H16460] [H16463]
277d0 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  .*/.void sqlite3
277e0 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 73 71 6c  _result_blob(sql
277f0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63  ite3_context*, c
27800 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c  onst void*, int,
27810 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29   void(*)(void*))
27820 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
27830 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28 73 71 6c  esult_double(sql
27840 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 64  ite3_context*, d
27850 6f 75 62 6c 65 29 3b 0a 76 6f 69 64 20 73 71 6c  ouble);.void sql
27860 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
27870 72 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  r(sqlite3_contex
27880 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c  t*, const char*,
27890 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69   int);.void sqli
278a0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
278b0 31 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  16(sqlite3_conte
278c0 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  xt*, const void*
278d0 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c  , int);.void sql
278e0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
278f0 72 5f 74 6f 6f 62 69 67 28 73 71 6c 69 74 65 33  r_toobig(sqlite3
27900 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64  _context*);.void
27910 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
27920 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28 73 71 6c 69  error_nomem(sqli
27930 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76  te3_context*);.v
27940 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
27950 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28 73 71  lt_error_code(sq
27960 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
27970 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  int);.void sqlit
27980 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 73 71  e3_result_int(sq
27990 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
279a0 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  int);.void sqlit
279b0 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 28  e3_result_int64(
279c0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
279d0 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29  , sqlite3_int64)
279e0 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
279f0 65 73 75 6c 74 5f 6e 75 6c 6c 28 73 71 6c 69 74  esult_null(sqlit
27a00 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f  e3_context*);.vo
27a10 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
27a20 74 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 63  t_text(sqlite3_c
27a30 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63  ontext*, const c
27a40 68 61 72 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28  har*, int, void(
27a50 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64  *)(void*));.void
27a60 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
27a70 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 63  text16(sqlite3_c
27a80 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76  ontext*, const v
27a90 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28  oid*, int, void(
27aa0 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64  *)(void*));.void
27ab0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
27ac0 74 65 78 74 31 36 6c 65 28 73 71 6c 69 74 65 33  text16le(sqlite3
27ad0 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74  _context*, const
27ae0 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64   void*, int,void
27af0 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69  (*)(void*));.voi
27b00 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
27b10 5f 74 65 78 74 31 36 62 65 28 73 71 6c 69 74 65  _text16be(sqlite
27b20 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73  3_context*, cons
27b30 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69  t void*, int,voi
27b40 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f  d(*)(void*));.vo
27b50 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
27b60 74 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f  t_value(sqlite3_
27b70 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74 65  context*, sqlite
27b80 33 5f 76 61 6c 75 65 2a 29 3b 0a 76 6f 69 64 20  3_value*);.void 
27b90 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a  sqlite3_result_z
27ba0 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f  eroblob(sqlite3_
27bb0 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e 29  context*, int n)
27bc0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
27bd0 46 3a 20 44 65 66 69 6e 65 20 4e 65 77 20 43 6f  F: Define New Co
27be0 6c 6c 61 74 69 6e 67 20 53 65 71 75 65 6e 63 65  llating Sequence
27bf0 73 20 7b 48 31 36 36 30 30 7d 20 3c 53 32 30 33  s {H16600} <S203
27c00 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  00>.**.** These 
27c10 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 75 73  functions are us
27c20 65 64 20 74 6f 20 61 64 64 20 6e 65 77 20 63 6f  ed to add new co
27c30 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65  llation sequence
27c40 73 20 74 6f 20 74 68 65 0a 2a 2a 20 5b 64 61 74  s to the.** [dat
27c50 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
27c60 5d 20 73 70 65 63 69 66 69 65 64 20 61 73 20 74  ] specified as t
27c70 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
27c80 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6e 61 6d  t..**.** The nam
27c90 65 20 6f 66 20 74 68 65 20 6e 65 77 20 63 6f 6c  e of the new col
27ca0 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 20  lation sequence 
27cb0 69 73 20 73 70 65 63 69 66 69 65 64 20 61 73 20  is specified as 
27cc0 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a  a UTF-8 string.*
27cd0 2a 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72  * for sqlite3_cr
27ce0 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29  eate_collation()
27cf0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 72 65   and sqlite3_cre
27d00 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32  ate_collation_v2
27d10 28 29 0a 2a 2a 20 61 6e 64 20 61 20 55 54 46 2d  ().** and a UTF-
27d20 31 36 20 73 74 72 69 6e 67 20 66 6f 72 20 73 71  16 string for sq
27d30 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
27d40 6c 61 74 69 6f 6e 31 36 28 29 2e 20 49 6e 20 61  lation16(). In a
27d50 6c 6c 20 63 61 73 65 73 0a 2a 2a 20 74 68 65 20  ll cases.** the 
27d60 6e 61 6d 65 20 69 73 20 70 61 73 73 65 64 20 61  name is passed a
27d70 73 20 74 68 65 20 73 65 63 6f 6e 64 20 66 75 6e  s the second fun
27d80 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a  ction argument..
27d90 2a 2a 0a 2a 2a 20 54 68 65 20 74 68 69 72 64 20  **.** The third 
27da0 61 72 67 75 6d 65 6e 74 20 6d 61 79 20 62 65 20  argument may be 
27db0 6f 6e 65 20 6f 66 20 74 68 65 20 63 6f 6e 73 74  one of the const
27dc0 61 6e 74 73 20 5b 53 51 4c 49 54 45 5f 55 54 46  ants [SQLITE_UTF
27dd0 38 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55  8],.** [SQLITE_U
27de0 54 46 31 36 4c 45 5d 2c 20 6f 72 20 5b 53 51 4c  TF16LE], or [SQL
27df0 49 54 45 5f 55 54 46 31 36 42 45 5d 2c 20 69 6e  ITE_UTF16BE], in
27e00 64 69 63 61 74 69 6e 67 20 74 68 61 74 20 74 68  dicating that th
27e10 65 20 75 73 65 72 2d 73 75 70 70 6c 69 65 64 0a  e user-supplied.
27e20 2a 2a 20 72 6f 75 74 69 6e 65 20 65 78 70 65 63  ** routine expec
27e30 74 73 20 74 6f 20 62 65 20 70 61 73 73 65 64 20  ts to be passed 
27e40 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69  pointers to stri
27e50 6e 67 73 20 65 6e 63 6f 64 65 64 20 75 73 69 6e  ngs encoded usin
27e60 67 20 55 54 46 2d 38 2c 0a 2a 2a 20 55 54 46 2d  g UTF-8,.** UTF-
27e70 31 36 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e  16 little-endian
27e80 2c 20 6f 72 20 55 54 46 2d 31 36 20 62 69 67 2d  , or UTF-16 big-
27e90 65 6e 64 69 61 6e 2c 20 72 65 73 70 65 63 74 69  endian, respecti
27ea0 76 65 6c 79 2e 20 54 68 65 0a 2a 2a 20 74 68 69  vely. The.** thi
27eb0 72 64 20 61 72 67 75 6d 65 6e 74 20 6d 69 67 68  rd argument migh
27ec0 74 20 61 6c 73 6f 20 62 65 20 5b 53 51 4c 49 54  t also be [SQLIT
27ed0 45 5f 55 54 46 31 36 5d 20 74 6f 20 69 6e 64 69  E_UTF16] to indi
27ee0 63 61 74 65 20 74 68 61 74 20 74 68 65 20 72 6f  cate that the ro
27ef0 75 74 69 6e 65 0a 2a 2a 20 65 78 70 65 63 74 73  utine.** expects
27f00 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 62 65 20   pointers to be 
27f10 55 54 46 2d 31 36 20 73 74 72 69 6e 67 73 20 69  UTF-16 strings i
27f20 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74  n the native byt
27f30 65 20 6f 72 64 65 72 2c 20 6f 72 20 74 68 65 0a  e order, or the.
27f40 2a 2a 20 61 72 67 75 6d 65 6e 74 20 63 61 6e 20  ** argument can 
27f50 62 65 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  be [SQLITE_UTF16
27f60 5f 41 4c 49 47 4e 45 44 5d 20 69 66 20 74 68 65  _ALIGNED] if the
27f70 0a 2a 2a 20 74 68 65 20 72 6f 75 74 69 6e 65 20  .** the routine 
27f80 65 78 70 65 63 74 73 20 70 6f 69 6e 74 65 72 73  expects pointers
27f90 20 74 6f 20 31 36 2d 62 69 74 20 77 6f 72 64 20   to 16-bit word 
27fa0 61 6c 69 67 6e 65 64 20 73 74 72 69 6e 67 73 0a  aligned strings.
27fb0 2a 2a 20 6f 66 20 55 54 46 2d 31 36 20 69 6e 20  ** of UTF-16 in 
27fc0 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 20  the native byte 
27fd0 6f 72 64 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 20 70  order..**.** A p
27fe0 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 75 73  ointer to the us
27ff0 65 72 20 73 75 70 70 6c 69 65 64 20 72 6f 75 74  er supplied rout
28000 69 6e 65 20 6d 75 73 74 20 62 65 20 70 61 73 73  ine must be pass
28010 65 64 20 61 73 20 74 68 65 20 66 69 66 74 68 0a  ed as the fifth.
28020 2a 2a 20 61 72 67 75 6d 65 6e 74 2e 20 20 49 66  ** argument.  If
28030 20 69 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 69   it is NULL, thi
28040 73 20 69 73 20 74 68 65 20 73 61 6d 65 20 61 73  s is the same as
28050 20 64 65 6c 65 74 69 6e 67 20 74 68 65 20 63 6f   deleting the co
28060 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65  llation.** seque
28070 6e 63 65 20 28 73 6f 20 74 68 61 74 20 53 51 4c  nce (so that SQL
28080 69 74 65 20 63 61 6e 6e 6f 74 20 63 61 6c 6c 20  ite cannot call 
28090 69 74 20 61 6e 79 6d 6f 72 65 29 2e 0a 2a 2a 20  it anymore)..** 
280a0 45 61 63 68 20 74 69 6d 65 20 74 68 65 20 61 70  Each time the ap
280b0 70 6c 69 63 61 74 69 6f 6e 20 73 75 70 70 6c 69  plication suppli
280c0 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 69  ed function is i
280d0 6e 76 6f 6b 65 64 2c 20 69 74 20 69 73 20 70 61  nvoked, it is pa
280e0 73 73 65 64 0a 2a 2a 20 61 73 20 69 74 73 20 66  ssed.** as its f
280f0 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 61  irst parameter a
28100 20 63 6f 70 79 20 6f 66 20 74 68 65 20 76 6f 69   copy of the voi
28110 64 2a 20 70 61 73 73 65 64 20 61 73 20 74 68 65  d* passed as the
28120 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74   fourth argument
28130 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  .** to sqlite3_c
28140 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28  reate_collation(
28150 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65  ) or sqlite3_cre
28160 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28  ate_collation16(
28170 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 72 65 6d  )..**.** The rem
28180 61 69 6e 69 6e 67 20 61 72 67 75 6d 65 6e 74 73  aining arguments
28190 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74   to the applicat
281a0 69 6f 6e 2d 73 75 70 70 6c 69 65 64 20 72 6f 75  ion-supplied rou
281b0 74 69 6e 65 20 61 72 65 20 74 77 6f 20 73 74 72  tine are two str
281c0 69 6e 67 73 2c 0a 2a 2a 20 65 61 63 68 20 72 65  ings,.** each re
281d0 70 72 65 73 65 6e 74 65 64 20 62 79 20 61 20 28  presented by a (
281e0 6c 65 6e 67 74 68 2c 20 64 61 74 61 29 20 70 61  length, data) pa
281f0 69 72 20 61 6e 64 20 65 6e 63 6f 64 65 64 20 69  ir and encoded i
28200 6e 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 0a 2a  n the encoding.*
28210 2a 20 74 68 61 74 20 77 61 73 20 70 61 73 73 65  * that was passe
28220 64 20 61 73 20 74 68 65 20 74 68 69 72 64 20 61  d as the third a
28230 72 67 75 6d 65 6e 74 20 77 68 65 6e 20 74 68 65  rgument when the
28240 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65   collation seque
28250 6e 63 65 20 77 61 73 0a 2a 2a 20 72 65 67 69 73  nce was.** regis
28260 74 65 72 65 64 2e 20 7b 45 4e 44 7d 20 20 54 68  tered. {END}  Th
28270 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65  e application de
28280 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20  fined collation 
28290 72 6f 75 74 69 6e 65 20 73 68 6f 75 6c 64 0a 2a  routine should.*
282a0 2a 20 72 65 74 75 72 6e 20 6e 65 67 61 74 69 76  * return negativ
282b0 65 2c 20 7a 65 72 6f 20 6f 72 20 70 6f 73 69 74  e, zero or posit
282c0 69 76 65 20 69 66 20 74 68 65 20 66 69 72 73 74  ive if the first
282d0 20 73 74 72 69 6e 67 20 69 73 20 6c 65 73 73 20   string is less 
282e0 74 68 61 6e 2c 0a 2a 2a 20 65 71 75 61 6c 20 74  than,.** equal t
282f0 6f 2c 20 6f 72 20 67 72 65 61 74 65 72 20 74 68  o, or greater th
28300 61 6e 20 74 68 65 20 73 65 63 6f 6e 64 20 73 74  an the second st
28310 72 69 6e 67 2e 20 69 2e 65 2e 20 28 53 54 52 49  ring. i.e. (STRI
28320 4e 47 31 20 2d 20 53 54 52 49 4e 47 32 29 2e 0a  NG1 - STRING2)..
28330 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
28340 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
28350 6f 6e 5f 76 32 28 29 20 77 6f 72 6b 73 20 6c 69  on_v2() works li
28360 6b 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  ke sqlite3_creat
28370 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 0a 2a 2a  e_collation().**
28380 20 65 78 63 65 70 74 20 74 68 61 74 20 69 74 20   except that it 
28390 74 61 6b 65 73 20 61 6e 20 65 78 74 72 61 20 61  takes an extra a
283a0 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73  rgument which is
283b0 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 66 6f   a destructor fo
283c0 72 0a 2a 2a 20 74 68 65 20 63 6f 6c 6c 61 74 69  r.** the collati
283d0 6f 6e 2e 20 20 54 68 65 20 64 65 73 74 72 75 63  on.  The destruc
283e0 74 6f 72 20 69 73 20 63 61 6c 6c 65 64 20 77 68  tor is called wh
283f0 65 6e 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e  en the collation
28400 20 69 73 0a 2a 2a 20 64 65 73 74 72 6f 79 65 64   is.** destroyed
28410 20 61 6e 64 20 69 73 20 70 61 73 73 65 64 20 61   and is passed a
28420 20 63 6f 70 79 20 6f 66 20 74 68 65 20 66 6f 75   copy of the fou
28430 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 76 6f  rth parameter vo
28440 69 64 2a 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 6f  id* pointer.** o
28450 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 72  f the sqlite3_cr
28460 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76  eate_collation_v
28470 32 28 29 2e 0a 2a 2a 20 43 6f 6c 6c 61 74 69 6f  2()..** Collatio
28480 6e 73 20 61 72 65 20 64 65 73 74 72 6f 79 65 64  ns are destroyed
28490 20 77 68 65 6e 20 74 68 65 79 20 61 72 65 20 6f   when they are o
284a0 76 65 72 72 69 64 64 65 6e 20 62 79 20 6c 61 74  verridden by lat
284b0 65 72 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 0a  er calls to the.
284c0 2a 2a 20 63 6f 6c 6c 61 74 69 6f 6e 20 63 72 65  ** collation cre
284d0 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 73 20  ation functions 
284e0 6f 72 20 77 68 65 6e 20 74 68 65 20 5b 64 61 74  or when the [dat
284f0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
28500 5d 20 69 73 20 63 6c 6f 73 65 64 0a 2a 2a 20 75  ] is closed.** u
28510 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6c  sing [sqlite3_cl
28520 6f 73 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65  ose()]..**.** Se
28530 65 20 61 6c 73 6f 3a 20 20 5b 73 71 6c 69 74 65  e also:  [sqlite
28540 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64  3_collation_need
28550 65 64 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  ed()] and [sqlit
28560 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65  e3_collation_nee
28570 64 65 64 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  ded16()]..**.** 
28580 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a  Requirements:.**
28590 20 5b 48 31 36 36 30 33 5d 20 5b 48 31 36 36 30   [H16603] [H1660
285a0 34 5d 20 5b 48 31 36 36 30 36 5d 20 5b 48 31 36  4] [H16606] [H16
285b0 36 30 39 5d 20 5b 48 31 36 36 31 32 5d 20 5b 48  609] [H16612] [H
285c0 31 36 36 31 35 5d 20 5b 48 31 36 36 31 38 5d 20  16615] [H16618] 
285d0 5b 48 31 36 36 32 31 5d 0a 2a 2a 20 5b 48 31 36  [H16621].** [H16
285e0 36 32 34 5d 20 5b 48 31 36 36 32 37 5d 20 5b 48  624] [H16627] [H
285f0 31 36 36 33 30 5d 0a 2a 2f 0a 69 6e 74 20 73 71  16630].*/.int sq
28600 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
28610 6c 61 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65  lation(.  sqlite
28620 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68 61  3*, .  const cha
28630 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74  r *zName, .  int
28640 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f   eTextRep, .  vo
28650 69 64 2a 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d  id*,.  int(*xCom
28660 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c  pare)(void*,int,
28670 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c  const void*,int,
28680 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a  const void*).);.
28690 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61  int sqlite3_crea
286a0 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28  te_collation_v2(
286b0 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20  .  sqlite3*, .  
286c0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
286d0 65 2c 20 0a 20 20 69 6e 74 20 65 54 65 78 74 52  e, .  int eTextR
286e0 65 70 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20  ep, .  void*,.  
286f0 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76  int(*xCompare)(v
28700 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76  oid*,int,const v
28710 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76  oid*,int,const v
28720 6f 69 64 2a 29 2c 0a 20 20 76 6f 69 64 28 2a 78  oid*),.  void(*x
28730 44 65 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 0a  Destroy)(void*).
28740 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
28750 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31  reate_collation1
28760 36 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a  6(.  sqlite3*, .
28770 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 4e    const void *zN
28780 61 6d 65 2c 0a 20 20 69 6e 74 20 65 54 65 78 74  ame,.  int eText
28790 52 65 70 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20  Rep, .  void*,. 
287a0 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28   int(*xCompare)(
287b0 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20  void*,int,const 
287c0 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20  void*,int,const 
287d0 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  void*).);../*.**
287e0 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6c 6c 61   CAPI3REF: Colla
287f0 74 69 6f 6e 20 4e 65 65 64 65 64 20 43 61 6c 6c  tion Needed Call
28800 62 61 63 6b 73 20 7b 48 31 36 37 30 30 7d 20 3c  backs {H16700} <
28810 53 32 30 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 6f  S20300>.**.** To
28820 20 61 76 6f 69 64 20 68 61 76 69 6e 67 20 74 6f   avoid having to
28830 20 72 65 67 69 73 74 65 72 20 61 6c 6c 20 63 6f   register all co
28840 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65  llation sequence
28850 73 20 62 65 66 6f 72 65 20 61 20 64 61 74 61 62  s before a datab
28860 61 73 65 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73  ase.** can be us
28870 65 64 2c 20 61 20 73 69 6e 67 6c 65 20 63 61 6c  ed, a single cal
28880 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 6d  lback function m
28890 61 79 20 62 65 20 72 65 67 69 73 74 65 72 65 64  ay be registered
288a0 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 64 61   with the.** [da
288b0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
288c0 6e 5d 20 74 6f 20 62 65 20 63 61 6c 6c 65 64 20  n] to be called 
288d0 77 68 65 6e 65 76 65 72 20 61 6e 20 75 6e 64 65  whenever an unde
288e0 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 0a  fined collation.
288f0 2a 2a 20 73 65 71 75 65 6e 63 65 20 69 73 20 72  ** sequence is r
28900 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 49  equired..**.** I
28910 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69  f the function i
28920 73 20 72 65 67 69 73 74 65 72 65 64 20 75 73 69  s registered usi
28930 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63  ng the sqlite3_c
28940 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28  ollation_needed(
28950 29 20 41 50 49 2c 0a 2a 2a 20 74 68 65 6e 20 69  ) API,.** then i
28960 74 20 69 73 20 70 61 73 73 65 64 20 74 68 65 20  t is passed the 
28970 6e 61 6d 65 73 20 6f 66 20 75 6e 64 65 66 69 6e  names of undefin
28980 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71  ed collation seq
28990 75 65 6e 63 65 73 20 61 73 20 73 74 72 69 6e 67  uences as string
289a0 73 0a 2a 2a 20 65 6e 63 6f 64 65 64 20 69 6e 20  s.** encoded in 
289b0 55 54 46 2d 38 2e 20 7b 48 31 36 37 30 33 7d 20  UTF-8. {H16703} 
289c0 49 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61  If sqlite3_colla
289d0 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 20  tion_needed16() 
289e0 69 73 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65 20  is used,.** the 
289f0 6e 61 6d 65 73 20 61 72 65 20 70 61 73 73 65 64  names are passed
28a00 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 6d 61   as UTF-16 in ma
28a10 63 68 69 6e 65 20 6e 61 74 69 76 65 20 62 79 74  chine native byt
28a20 65 20 6f 72 64 65 72 2e 0a 2a 2a 20 41 20 63 61  e order..** A ca
28a30 6c 6c 20 74 6f 20 65 69 74 68 65 72 20 66 75 6e  ll to either fun
28a40 63 74 69 6f 6e 20 72 65 70 6c 61 63 65 73 20 61  ction replaces a
28a50 6e 79 20 65 78 69 73 74 69 6e 67 20 63 61 6c 6c  ny existing call
28a60 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e  back..**.** When
28a70 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73   the callback is
28a80 20 69 6e 76 6f 6b 65 64 2c 20 74 68 65 20 66 69   invoked, the fi
28a90 72 73 74 20 61 72 67 75 6d 65 6e 74 20 70 61 73  rst argument pas
28aa0 73 65 64 20 69 73 20 61 20 63 6f 70 79 0a 2a 2a  sed is a copy.**
28ab0 20 6f 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61   of the second a
28ac0 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
28ad0 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65  e3_collation_nee
28ae0 64 65 64 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69  ded() or.** sqli
28af0 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65  te3_collation_ne
28b00 65 64 65 64 31 36 28 29 2e 20 20 54 68 65 20 73  eded16().  The s
28b10 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69  econd argument i
28b20 73 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a  s the database.*
28b30 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 54  * connection.  T
28b40 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  he third argumen
28b50 74 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c  t is one of [SQL
28b60 49 54 45 5f 55 54 46 38 5d 2c 20 5b 53 51 4c 49  ITE_UTF8], [SQLI
28b70 54 45 5f 55 54 46 31 36 42 45 5d 2c 0a 2a 2a 20  TE_UTF16BE],.** 
28b80 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  or [SQLITE_UTF16
28b90 4c 45 5d 2c 20 69 6e 64 69 63 61 74 69 6e 67 20  LE], indicating 
28ba0 74 68 65 20 6d 6f 73 74 20 64 65 73 69 72 61 62  the most desirab
28bb0 6c 65 20 66 6f 72 6d 20 6f 66 20 74 68 65 20 63  le form of the c
28bc0 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75  ollation.** sequ
28bd0 65 6e 63 65 20 66 75 6e 63 74 69 6f 6e 20 72 65  ence function re
28be0 71 75 69 72 65 64 2e 20 20 54 68 65 20 66 6f 75  quired.  The fou
28bf0 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73  rth parameter is
28c00 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
28c10 0a 2a 2a 20 72 65 71 75 69 72 65 64 20 63 6f 6c  .** required col
28c20 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 2e  lation sequence.
28c30 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62  .**.** The callb
28c40 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f  ack function sho
28c50 75 6c 64 20 72 65 67 69 73 74 65 72 20 74 68 65  uld register the
28c60 20 64 65 73 69 72 65 64 20 63 6f 6c 6c 61 74 69   desired collati
28c70 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c  on using.** [sql
28c80 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
28c90 61 74 69 6f 6e 28 29 5d 2c 20 5b 73 71 6c 69 74  ation()], [sqlit
28ca0 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
28cb0 69 6f 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20  ion16()], or.** 
28cc0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
28cd0 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 5d 2e  collation_v2()].
28ce0 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65  .**.** Requireme
28cf0 6e 74 73 3a 0a 2a 2a 20 5b 48 31 36 37 30 32 5d  nts:.** [H16702]
28d00 20 5b 48 31 36 37 30 34 5d 20 5b 48 31 36 37 30   [H16704] [H1670
28d10 36 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  6].*/.int sqlite
28d20 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64  3_collation_need
28d30 65 64 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20  ed(.  sqlite3*, 
28d40 0a 20 20 76 6f 69 64 2a 2c 20 0a 20 20 76 6f 69  .  void*, .  voi
28d50 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74  d(*)(void*,sqlit
28d60 65 33 2a 2c 69 6e 74 20 65 54 65 78 74 52 65 70  e3*,int eTextRep
28d70 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 0a 29 3b  ,const char*).);
28d80 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c  .int sqlite3_col
28d90 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28  lation_needed16(
28da0 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20  .  sqlite3*, .  
28db0 76 6f 69 64 2a 2c 0a 20 20 76 6f 69 64 28 2a 29  void*,.  void(*)
28dc0 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c  (void*,sqlite3*,
28dd0 69 6e 74 20 65 54 65 78 74 52 65 70 2c 63 6f 6e  int eTextRep,con
28de0 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a  st void*).);../*
28df0 0a 2a 2a 20 53 70 65 63 69 66 79 20 74 68 65 20  .** Specify the 
28e00 6b 65 79 20 66 6f 72 20 61 6e 20 65 6e 63 72 79  key for an encry
28e10 70 74 65 64 20 64 61 74 61 62 61 73 65 2e 20 20  pted database.  
28e20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73 68 6f  This routine sho
28e30 75 6c 64 20 62 65 0a 2a 2a 20 63 61 6c 6c 65 64  uld be.** called
28e40 20 72 69 67 68 74 20 61 66 74 65 72 20 73 71 6c   right after sql
28e50 69 74 65 33 5f 6f 70 65 6e 28 29 2e 0a 2a 2a 0a  ite3_open()..**.
28e60 2a 2a 20 54 68 65 20 63 6f 64 65 20 74 6f 20 69  ** The code to i
28e70 6d 70 6c 65 6d 65 6e 74 20 74 68 69 73 20 41 50  mplement this AP
28e80 49 20 69 73 20 6e 6f 74 20 61 76 61 69 6c 61 62  I is not availab
28e90 6c 65 20 69 6e 20 74 68 65 20 70 75 62 6c 69 63  le in the public
28ea0 20 72 65 6c 65 61 73 65 0a 2a 2a 20 6f 66 20 53   release.** of S
28eb0 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71  QLite..*/.int sq
28ec0 6c 69 74 65 33 5f 6b 65 79 28 0a 20 20 73 71 6c  lite3_key(.  sql
28ed0 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
28ee0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44              /* D
28ef0 61 74 61 62 61 73 65 20 74 6f 20 62 65 20 72 65  atabase to be re
28f00 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74  keyed */.  const
28f10 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74   void *pKey, int
28f20 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54 68 65   nKey     /* The
28f30 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a   key */.);../*.*
28f40 2a 20 43 68 61 6e 67 65 20 74 68 65 20 6b 65 79  * Change the key
28f50 20 6f 6e 20 61 6e 20 6f 70 65 6e 20 64 61 74 61   on an open data
28f60 62 61 73 65 2e 20 20 49 66 20 74 68 65 20 63 75  base.  If the cu
28f70 72 72 65 6e 74 20 64 61 74 61 62 61 73 65 20 69  rrent database i
28f80 73 20 6e 6f 74 0a 2a 2a 20 65 6e 63 72 79 70 74  s not.** encrypt
28f90 65 64 2c 20 74 68 69 73 20 72 6f 75 74 69 6e 65  ed, this routine
28fa0 20 77 69 6c 6c 20 65 6e 63 72 79 70 74 20 69 74   will encrypt it
28fb0 2e 20 20 49 66 20 70 4e 65 77 3d 3d 30 20 6f 72  .  If pNew==0 or
28fc0 20 6e 4e 65 77 3d 3d 30 2c 20 74 68 65 0a 2a 2a   nNew==0, the.**
28fd0 20 64 61 74 61 62 61 73 65 20 69 73 20 64 65 63   database is dec
28fe0 72 79 70 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  rypted..**.** Th
28ff0 65 20 63 6f 64 65 20 74 6f 20 69 6d 70 6c 65 6d  e code to implem
29000 65 6e 74 20 74 68 69 73 20 41 50 49 20 69 73 20  ent this API is 
29010 6e 6f 74 20 61 76 61 69 6c 61 62 6c 65 20 69 6e  not available in
29020 20 74 68 65 20 70 75 62 6c 69 63 20 72 65 6c 65   the public rele
29030 61 73 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65  ase.** of SQLite
29040 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
29050 5f 72 65 6b 65 79 28 0a 20 20 73 71 6c 69 74 65  _rekey(.  sqlite
29060 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
29070 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61           /* Data
29080 62 61 73 65 20 74 6f 20 62 65 20 72 65 6b 65 79  base to be rekey
29090 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f  ed */.  const vo
290a0 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b  id *pKey, int nK
290b0 65 79 20 20 20 20 20 2f 2a 20 54 68 65 20 6e 65  ey     /* The ne
290c0 77 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a  w key */.);../*.
290d0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 75 73  ** CAPI3REF: Sus
290e0 70 65 6e 64 20 45 78 65 63 75 74 69 6f 6e 20 46  pend Execution F
290f0 6f 72 20 41 20 53 68 6f 72 74 20 54 69 6d 65 20  or A Short Time 
29100 7b 48 31 30 35 33 30 7d 20 3c 53 34 30 34 31 30  {H10530} <S40410
29110 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  >.**.** The sqli
29120 74 65 33 5f 73 6c 65 65 70 28 29 20 66 75 6e 63  te3_sleep() func
29130 74 69 6f 6e 20 63 61 75 73 65 73 20 74 68 65 20  tion causes the 
29140 63 75 72 72 65 6e 74 20 74 68 72 65 61 64 20 74  current thread t
29150 6f 20 73 75 73 70 65 6e 64 20 65 78 65 63 75 74  o suspend execut
29160 69 6f 6e 0a 2a 2a 20 66 6f 72 20 61 74 20 6c 65  ion.** for at le
29170 61 73 74 20 61 20 6e 75 6d 62 65 72 20 6f 66 20  ast a number of 
29180 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 73 70 65  milliseconds spe
29190 63 69 66 69 65 64 20 69 6e 20 69 74 73 20 70 61  cified in its pa
291a0 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49  rameter..**.** I
291b0 66 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20  f the operating 
291c0 73 79 73 74 65 6d 20 64 6f 65 73 20 6e 6f 74 20  system does not 
291d0 73 75 70 70 6f 72 74 20 73 6c 65 65 70 20 72 65  support sleep re
291e0 71 75 65 73 74 73 20 77 69 74 68 0a 2a 2a 20 6d  quests with.** m
291f0 69 6c 6c 69 73 65 63 6f 6e 64 20 74 69 6d 65 20  illisecond time 
29200 72 65 73 6f 6c 75 74 69 6f 6e 2c 20 74 68 65 6e  resolution, then
29210 20 74 68 65 20 74 69 6d 65 20 77 69 6c 6c 20 62   the time will b
29220 65 20 72 6f 75 6e 64 65 64 20 75 70 20 74 6f 0a  e rounded up to.
29230 2a 2a 20 74 68 65 20 6e 65 61 72 65 73 74 20 73  ** the nearest s
29240 65 63 6f 6e 64 2e 20 54 68 65 20 6e 75 6d 62 65  econd. The numbe
29250 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  r of millisecond
29260 73 20 6f 66 20 73 6c 65 65 70 20 61 63 74 75 61  s of sleep actua
29270 6c 6c 79 0a 2a 2a 20 72 65 71 75 65 73 74 65 64  lly.** requested
29280 20 66 72 6f 6d 20 74 68 65 20 6f 70 65 72 61 74   from the operat
29290 69 6e 67 20 73 79 73 74 65 6d 20 69 73 20 72 65  ing system is re
292a0 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 53 51  turned..**.** SQ
292b0 4c 69 74 65 20 69 6d 70 6c 65 6d 65 6e 74 73 20  Lite implements 
292c0 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 62  this interface b
292d0 79 20 63 61 6c 6c 69 6e 67 20 74 68 65 20 78 53  y calling the xS
292e0 6c 65 65 70 28 29 0a 2a 2a 20 6d 65 74 68 6f 64  leep().** method
292f0 20 6f 66 20 74 68 65 20 64 65 66 61 75 6c 74 20   of the default 
29300 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62  [sqlite3_vfs] ob
29310 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75  ject..**.** Requ
29320 69 72 65 6d 65 6e 74 73 3a 20 5b 48 31 30 35 33  irements: [H1053
29330 33 5d 20 5b 48 31 30 35 33 36 5d 0a 2a 2f 0a 69  3] [H10536].*/.i
29340 6e 74 20 73 71 6c 69 74 65 33 5f 73 6c 65 65 70  nt sqlite3_sleep
29350 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  (int);../*.** CA
29360 50 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20  PI3REF: Name Of 
29370 54 68 65 20 46 6f 6c 64 65 72 20 48 6f 6c 64 69  The Folder Holdi
29380 6e 67 20 54 65 6d 70 6f 72 61 72 79 20 46 69 6c  ng Temporary Fil
29390 65 73 20 7b 48 31 30 33 31 30 7d 20 3c 53 32 30  es {H10310} <S20
293a0 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  000>.**.** If th
293b0 69 73 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62  is global variab
293c0 6c 65 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f  le is made to po
293d0 69 6e 74 20 74 6f 20 61 20 73 74 72 69 6e 67 20  int to a string 
293e0 77 68 69 63 68 20 69 73 0a 2a 2a 20 74 68 65 20  which is.** the 
293f0 6e 61 6d 65 20 6f 66 20 61 20 66 6f 6c 64 65 72  name of a folder
29400 20 28 61 2e 6b 2e 61 2e 20 64 69 72 65 63 74 6f   (a.k.a. directo
29410 72 79 29 2c 20 74 68 65 6e 20 61 6c 6c 20 74 65  ry), then all te
29420 6d 70 6f 72 61 72 79 20 66 69 6c 65 73 0a 2a 2a  mporary files.**
29430 20 63 72 65 61 74 65 64 20 62 79 20 53 51 4c 69   created by SQLi
29440 74 65 20 77 69 6c 6c 20 62 65 20 70 6c 61 63 65  te will be place
29450 64 20 69 6e 20 74 68 61 74 20 64 69 72 65 63 74  d in that direct
29460 6f 72 79 2e 20 20 49 66 20 74 68 69 73 20 76 61  ory.  If this va
29470 72 69 61 62 6c 65 0a 2a 2a 20 69 73 20 61 20 4e  riable.** is a N
29480 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65  ULL pointer, the
29490 6e 20 53 51 4c 69 74 65 20 70 65 72 66 6f 72 6d  n SQLite perform
294a0 73 20 61 20 73 65 61 72 63 68 20 66 6f 72 20 61  s a search for a
294b0 6e 20 61 70 70 72 6f 70 72 69 61 74 65 0a 2a 2a  n appropriate.**
294c0 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 20   temporary file 
294d0 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a  directory..**.**
294e0 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20   It is not safe 
294f0 74 6f 20 72 65 61 64 20 6f 72 20 6d 6f 64 69 66  to read or modif
29500 79 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20  y this variable 
29510 69 6e 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65  in more than one
29520 0a 2a 2a 20 74 68 72 65 61 64 20 61 74 20 61 20  .** thread at a 
29530 74 69 6d 65 2e 20 20 49 74 20 69 73 20 6e 6f 74  time.  It is not
29540 20 73 61 66 65 20 74 6f 20 72 65 61 64 20 6f 72   safe to read or
29550 20 6d 6f 64 69 66 79 20 74 68 69 73 20 76 61 72   modify this var
29560 69 61 62 6c 65 0a 2a 2a 20 69 66 20 61 20 5b 64  iable.** if a [d
29570 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
29580 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20 75 73 65  on] is being use
29590 64 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69  d at the same ti
295a0 6d 65 20 69 6e 20 61 20 73 65 70 61 72 61 74 65  me in a separate
295b0 0a 2a 2a 20 74 68 72 65 61 64 2e 0a 2a 2a 20 49  .** thread..** I
295c0 74 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74 68  t is intended th
295d0 61 74 20 74 68 69 73 20 76 61 72 69 61 62 6c 65  at this variable
295e0 20 62 65 20 73 65 74 20 6f 6e 63 65 0a 2a 2a 20   be set once.** 
295f0 61 73 20 70 61 72 74 20 6f 66 20 70 72 6f 63 65  as part of proce
29600 73 73 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f  ss initializatio
29610 6e 20 61 6e 64 20 62 65 66 6f 72 65 20 61 6e 79  n and before any
29620 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
29630 65 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 68 61  e.** routines ha
29640 76 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 61  ve been called a
29650 6e 64 20 74 68 61 74 20 74 68 69 73 20 76 61 72  nd that this var
29660 69 61 62 6c 65 20 72 65 6d 61 69 6e 20 75 6e 63  iable remain unc
29670 68 61 6e 67 65 64 0a 2a 2a 20 74 68 65 72 65 61  hanged.** therea
29680 66 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  fter..**.** The 
29690 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65  [temp_store_dire
296a0 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 20 6d 61  ctory pragma] ma
296b0 79 20 6d 6f 64 69 66 79 20 74 68 69 73 20 76 61  y modify this va
296c0 72 69 61 62 6c 65 20 61 6e 64 20 63 61 75 73 65  riable and cause
296d0 0a 2a 2a 20 69 74 20 74 6f 20 70 6f 69 6e 74 20  .** it to point 
296e0 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e  to memory obtain
296f0 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
29700 5f 6d 61 6c 6c 6f 63 5d 2e 20 20 46 75 72 74 68  _malloc].  Furth
29710 65 72 6d 6f 72 65 2c 0a 2a 2a 20 74 68 65 20 5b  ermore,.** the [
29720 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63  temp_store_direc
29730 74 6f 72 79 20 70 72 61 67 6d 61 5d 20 61 6c 77  tory pragma] alw
29740 61 79 73 20 61 73 73 75 6d 65 73 20 74 68 61 74  ays assumes that
29750 20 61 6e 79 20 73 74 72 69 6e 67 0a 2a 2a 20 74   any string.** t
29760 68 61 74 20 74 68 69 73 20 76 61 72 69 61 62 6c  hat this variabl
29770 65 20 70 6f 69 6e 74 73 20 74 6f 20 69 73 20 68  e points to is h
29780 65 6c 64 20 69 6e 20 6d 65 6d 6f 72 79 20 6f 62  eld in memory ob
29790 74 61 69 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a 20  tained from .** 
297a0 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d  [sqlite3_malloc]
297b0 20 61 6e 64 20 74 68 65 20 70 72 61 67 6d 61 20   and the pragma 
297c0 6d 61 79 20 61 74 74 65 6d 70 74 20 74 6f 20 66  may attempt to f
297d0 72 65 65 20 74 68 61 74 20 6d 65 6d 6f 72 79 0a  ree that memory.
297e0 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ** using [sqlite
297f0 33 5f 66 72 65 65 5d 2e 0a 2a 2a 20 48 65 6e 63  3_free]..** Henc
29800 65 2c 20 69 66 20 74 68 69 73 20 76 61 72 69 61  e, if this varia
29810 62 6c 65 20 69 73 20 6d 6f 64 69 66 69 65 64 20  ble is modified 
29820 64 69 72 65 63 74 6c 79 2c 20 65 69 74 68 65 72  directly, either
29830 20 69 74 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a   it should be.**
29840 20 6d 61 64 65 20 4e 55 4c 4c 20 6f 72 20 6d 61   made NULL or ma
29850 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 6d  de to point to m
29860 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66  emory obtained f
29870 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  rom [sqlite3_mal
29880 6c 6f 63 5d 0a 2a 2a 20 6f 72 20 65 6c 73 65 20  loc].** or else 
29890 74 68 65 20 75 73 65 20 6f 66 20 74 68 65 20 5b  the use of the [
298a0 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63  temp_store_direc
298b0 74 6f 72 79 20 70 72 61 67 6d 61 5d 20 73 68 6f  tory pragma] sho
298c0 75 6c 64 20 62 65 20 61 76 6f 69 64 65 64 2e 0a  uld be avoided..
298d0 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 54 45 52 4e  */.SQLITE_EXTERN
298e0 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 74   char *sqlite3_t
298f0 65 6d 70 5f 64 69 72 65 63 74 6f 72 79 3b 0a 0a  emp_directory;..
29900 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
29910 54 65 73 74 20 46 6f 72 20 41 75 74 6f 2d 43 6f  Test For Auto-Co
29920 6d 6d 69 74 20 4d 6f 64 65 20 7b 48 31 32 39 33  mmit Mode {H1293
29930 30 7d 20 3c 53 36 30 32 30 30 3e 0a 2a 2a 20 4b  0} <S60200>.** K
29940 45 59 57 4f 52 44 53 3a 20 7b 61 75 74 6f 63 6f  EYWORDS: {autoco
29950 6d 6d 69 74 20 6d 6f 64 65 7d 0a 2a 2a 0a 2a 2a  mmit mode}.**.**
29960 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74   The sqlite3_get
29970 5f 61 75 74 6f 63 6f 6d 6d 69 74 28 29 20 69 6e  _autocommit() in
29980 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
29990 6e 6f 6e 2d 7a 65 72 6f 20 6f 72 0a 2a 2a 20 7a  non-zero or.** z
299a0 65 72 6f 20 69 66 20 74 68 65 20 67 69 76 65 6e  ero if the given
299b0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
299c0 74 69 6f 6e 20 69 73 20 6f 72 20 69 73 20 6e 6f  tion is or is no
299d0 74 20 69 6e 20 61 75 74 6f 63 6f 6d 6d 69 74 20  t in autocommit 
299e0 6d 6f 64 65 2c 0a 2a 2a 20 72 65 73 70 65 63 74  mode,.** respect
299f0 69 76 65 6c 79 2e 20 20 41 75 74 6f 63 6f 6d 6d  ively.  Autocomm
29a00 69 74 20 6d 6f 64 65 20 69 73 20 6f 6e 20 62 79  it mode is on by
29a10 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 20 41 75 74   default..** Aut
29a20 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20  ocommit mode is 
29a30 64 69 73 61 62 6c 65 64 20 62 79 20 61 20 5b 42  disabled by a [B
29a40 45 47 49 4e 5d 20 73 74 61 74 65 6d 65 6e 74 2e  EGIN] statement.
29a50 0a 2a 2a 20 41 75 74 6f 63 6f 6d 6d 69 74 20 6d  .** Autocommit m
29a60 6f 64 65 20 69 73 20 72 65 2d 65 6e 61 62 6c 65  ode is re-enable
29a70 64 20 62 79 20 61 20 5b 43 4f 4d 4d 49 54 5d 20  d by a [COMMIT] 
29a80 6f 72 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2e 0a 2a  or [ROLLBACK]..*
29a90 2a 0a 2a 2a 20 49 66 20 63 65 72 74 61 69 6e 20  *.** If certain 
29aa0 6b 69 6e 64 73 20 6f 66 20 65 72 72 6f 72 73 20  kinds of errors 
29ab0 6f 63 63 75 72 20 6f 6e 20 61 20 73 74 61 74 65  occur on a state
29ac0 6d 65 6e 74 20 77 69 74 68 69 6e 20 61 20 6d 75  ment within a mu
29ad0 6c 74 69 2d 73 74 61 74 65 6d 65 6e 74 0a 2a 2a  lti-statement.**
29ae0 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 28 65 72   transaction (er
29af0 72 6f 72 73 20 69 6e 63 6c 75 64 69 6e 67 20 5b  rors including [
29b00 53 51 4c 49 54 45 5f 46 55 4c 4c 5d 2c 20 5b 53  SQLITE_FULL], [S
29b10 51 4c 49 54 45 5f 49 4f 45 52 52 5d 2c 0a 2a 2a  QLITE_IOERR],.**
29b20 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2c   [SQLITE_NOMEM],
29b30 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c 20   [SQLITE_BUSY], 
29b40 61 6e 64 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45  and [SQLITE_INTE
29b50 52 52 55 50 54 5d 29 20 74 68 65 6e 20 74 68 65  RRUPT]) then the
29b60 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  .** transaction 
29b70 6d 69 67 68 74 20 62 65 20 72 6f 6c 6c 65 64 20  might be rolled 
29b80 62 61 63 6b 20 61 75 74 6f 6d 61 74 69 63 61 6c  back automatical
29b90 6c 79 2e 20 20 54 68 65 20 6f 6e 6c 79 20 77 61  ly.  The only wa
29ba0 79 20 74 6f 0a 2a 2a 20 66 69 6e 64 20 6f 75 74  y to.** find out
29bb0 20 77 68 65 74 68 65 72 20 53 51 4c 69 74 65 20   whether SQLite 
29bc0 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f  automatically ro
29bd0 6c 6c 65 64 20 62 61 63 6b 20 74 68 65 20 74 72  lled back the tr
29be0 61 6e 73 61 63 74 69 6f 6e 20 61 66 74 65 72 0a  ansaction after.
29bf0 2a 2a 20 61 6e 20 65 72 72 6f 72 20 69 73 20 74  ** an error is t
29c00 6f 20 75 73 65 20 74 68 69 73 20 66 75 6e 63 74  o use this funct
29c10 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e  ion..**.** If an
29c20 6f 74 68 65 72 20 74 68 72 65 61 64 20 63 68 61  other thread cha
29c30 6e 67 65 73 20 74 68 65 20 61 75 74 6f 63 6f 6d  nges the autocom
29c40 6d 69 74 20 73 74 61 74 75 73 20 6f 66 20 74 68  mit status of th
29c50 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f  e database.** co
29c60 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65 20 74  nnection while t
29c70 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 72  his routine is r
29c80 75 6e 6e 69 6e 67 2c 20 74 68 65 6e 20 74 68 65  unning, then the
29c90 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a   return value.**
29ca0 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a   is undefined..*
29cb0 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74  *.** Requirement
29cc0 73 3a 20 5b 48 31 32 39 33 31 5d 20 5b 48 31 32  s: [H12931] [H12
29cd0 39 33 32 5d 20 5b 48 31 32 39 33 33 5d 20 5b 48  932] [H12933] [H
29ce0 31 32 39 33 34 5d 0a 2a 2f 0a 69 6e 74 20 73 71  12934].*/.int sq
29cf0 6c 69 74 65 33 5f 67 65 74 5f 61 75 74 6f 63 6f  lite3_get_autoco
29d00 6d 6d 69 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a  mmit(sqlite3*);.
29d10 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
29d20 20 46 69 6e 64 20 54 68 65 20 44 61 74 61 62 61   Find The Databa
29d30 73 65 20 48 61 6e 64 6c 65 20 4f 66 20 41 20 50  se Handle Of A P
29d40 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e  repared Statemen
29d50 74 20 7b 48 31 33 31 32 30 7d 20 3c 53 36 30 36  t {H13120} <S606
29d60 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  00>.**.** The sq
29d70 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65 20  lite3_db_handle 
29d80 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
29d90 73 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  s the [database 
29da0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64  connection] hand
29db0 6c 65 0a 2a 2a 20 74 6f 20 77 68 69 63 68 20 61  le.** to which a
29dc0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
29dd0 6d 65 6e 74 5d 20 62 65 6c 6f 6e 67 73 2e 20 20  ment] belongs.  
29de0 54 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  The [database co
29df0 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 72 65 74  nnection].** ret
29e00 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
29e10 5f 64 62 5f 68 61 6e 64 6c 65 20 69 73 20 74 68  _db_handle is th
29e20 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65  e same [database
29e30 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61   connection] tha
29e40 74 20 77 61 73 20 74 68 65 20 66 69 72 73 74 20  t was the first 
29e50 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 74  argument.** to t
29e60 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  he [sqlite3_prep
29e70 61 72 65 5f 76 32 28 29 5d 20 63 61 6c 6c 20 28  are_v2()] call (
29e80 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 29  or its variants)
29e90 20 74 68 61 74 20 77 61 73 20 75 73 65 64 20 74   that was used t
29ea0 6f 0a 2a 2a 20 63 72 65 61 74 65 20 74 68 65 20  o.** create the 
29eb0 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 74 68 65  statement in the
29ec0 20 66 69 72 73 74 20 70 6c 61 63 65 2e 0a 2a 2a   first place..**
29ed0 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73  .** Requirements
29ee0 3a 20 5b 48 31 33 31 32 33 5d 0a 2a 2f 0a 73 71  : [H13123].*/.sq
29ef0 6c 69 74 65 33 20 2a 73 71 6c 69 74 65 33 5f 64  lite3 *sqlite3_d
29f00 62 5f 68 61 6e 64 6c 65 28 73 71 6c 69 74 65 33  b_handle(sqlite3
29f10 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  _stmt*);../*.** 
29f20 43 41 50 49 33 52 45 46 3a 20 46 69 6e 64 20 74  CAPI3REF: Find t
29f30 68 65 20 6e 65 78 74 20 70 72 65 70 61 72 65 64  he next prepared
29f40 20 73 74 61 74 65 6d 65 6e 74 20 7b 48 31 33 31   statement {H131
29f50 34 30 7d 20 3c 53 36 30 36 30 30 3e 0a 2a 2a 0a  40} <S60600>.**.
29f60 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63  ** This interfac
29f70 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  e returns a poin
29f80 74 65 72 20 74 6f 20 74 68 65 20 6e 65 78 74 20  ter to the next 
29f90 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
29fa0 65 6e 74 5d 20 61 66 74 65 72 0a 2a 2a 20 70 53  ent] after.** pS
29fb0 74 6d 74 20 61 73 73 6f 63 69 61 74 65 64 20 77  tmt associated w
29fc0 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 73  ith the [databas
29fd0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 44  e connection] pD
29fe0 62 2e 20 20 49 66 20 70 53 74 6d 74 20 69 73 20  b.  If pStmt is 
29ff0 4e 55 4c 4c 0a 2a 2a 20 74 68 65 6e 20 74 68 69  NULL.** then thi
2a000 73 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  s interface retu
2a010 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
2a020 20 74 68 65 20 66 69 72 73 74 20 70 72 65 70 61   the first prepa
2a030 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a  red statement.**
2a040 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
2a050 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
2a060 6e 6e 65 63 74 69 6f 6e 20 70 44 62 2e 20 20 49  nnection pDb.  I
2a070 66 20 6e 6f 20 70 72 65 70 61 72 65 64 20 73 74  f no prepared st
2a080 61 74 65 6d 65 6e 74 0a 2a 2a 20 73 61 74 69 73  atement.** satis
2a090 66 69 65 73 20 74 68 65 20 63 6f 6e 64 69 74 69  fies the conditi
2a0a0 6f 6e 73 20 6f 66 20 74 68 69 73 20 72 6f 75 74  ons of this rout
2a0b0 69 6e 65 2c 20 69 74 20 72 65 74 75 72 6e 73 20  ine, it returns 
2a0c0 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  NULL..**.** The 
2a0d0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
2a0e0 74 69 6f 6e 5d 20 70 6f 69 6e 74 65 72 20 44 20  tion] pointer D 
2a0f0 69 6e 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20  in a call to.** 
2a100 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74  [sqlite3_next_st
2a110 6d 74 28 44 2c 53 29 5d 20 6d 75 73 74 20 72 65  mt(D,S)] must re
2a120 66 65 72 20 74 6f 20 61 6e 20 6f 70 65 6e 20 64  fer to an open d
2a130 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65  atabase.** conne
2a140 63 74 69 6f 6e 20 61 6e 64 20 69 6e 20 70 61 72  ction and in par
2a150 74 69 63 75 6c 61 72 20 6d 75 73 74 20 6e 6f 74  ticular must not
2a160 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   be a NULL point
2a170 65 72 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72  er..**.** Requir
2a180 65 6d 65 6e 74 73 3a 20 5b 48 31 33 31 34 33 5d  ements: [H13143]
2a190 20 5b 48 31 33 31 34 36 5d 20 5b 48 31 33 31 34   [H13146] [H1314
2a1a0 39 5d 20 5b 48 31 33 31 35 32 5d 0a 2a 2f 0a 73  9] [H13152].*/.s
2a1b0 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 73 71 6c  qlite3_stmt *sql
2a1c0 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 73  ite3_next_stmt(s
2a1d0 71 6c 69 74 65 33 20 2a 70 44 62 2c 20 73 71 6c  qlite3 *pDb, sql
2a1e0 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
2a1f0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2a200 45 46 3a 20 43 6f 6d 6d 69 74 20 41 6e 64 20 52  EF: Commit And R
2a210 6f 6c 6c 62 61 63 6b 20 4e 6f 74 69 66 69 63 61  ollback Notifica
2a220 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 20 7b  tion Callbacks {
2a230 48 31 32 39 35 30 7d 20 3c 53 36 30 34 30 30 3e  H12950} <S60400>
2a240 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
2a250 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29  e3_commit_hook()
2a260 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73   interface regis
2a270 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 0a  ters a callback.
2a280 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ** function to b
2a290 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76  e invoked whenev
2a2a0 65 72 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e  er a transaction
2a2b0 20 69 73 20 5b 43 4f 4d 4d 49 54 20 7c 20 63 6f   is [COMMIT | co
2a2c0 6d 6d 69 74 74 65 64 5d 2e 0a 2a 2a 20 41 6e 79  mmitted]..** Any
2a2d0 20 63 61 6c 6c 62 61 63 6b 20 73 65 74 20 62 79   callback set by
2a2e0 20 61 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c   a previous call
2a2f0 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d   to sqlite3_comm
2a300 69 74 5f 68 6f 6f 6b 28 29 0a 2a 2a 20 66 6f 72  it_hook().** for
2a310 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61   the same databa
2a320 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
2a330 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 20   overridden..** 
2a340 54 68 65 20 73 71 6c 69 74 65 33 5f 72 6f 6c 6c  The sqlite3_roll
2a350 62 61 63 6b 5f 68 6f 6f 6b 28 29 20 69 6e 74 65  back_hook() inte
2a360 72 66 61 63 65 20 72 65 67 69 73 74 65 72 73 20  rface registers 
2a370 61 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75  a callback.** fu
2a380 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 69 6e 76  nction to be inv
2a390 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61 20  oked whenever a 
2a3a0 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 5b  transaction is [
2a3b0 52 4f 4c 4c 42 41 43 4b 20 7c 20 72 6f 6c 6c 65  ROLLBACK | rolle
2a3c0 64 20 62 61 63 6b 5d 2e 0a 2a 2a 20 41 6e 79 20  d back]..** Any 
2a3d0 63 61 6c 6c 62 61 63 6b 20 73 65 74 20 62 79 20  callback set by 
2a3e0 61 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20  a previous call 
2a3f0 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69  to sqlite3_commi
2a400 74 5f 68 6f 6f 6b 28 29 0a 2a 2a 20 66 6f 72 20  t_hook().** for 
2a410 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73  the same databas
2a420 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
2a430 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 20 54  overridden..** T
2a440 68 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e 74  he pArg argument
2a450 20 69 73 20 70 61 73 73 65 64 20 74 68 72 6f 75   is passed throu
2a460 67 68 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61  gh to the callba
2a470 63 6b 2e 0a 2a 2a 20 49 66 20 74 68 65 20 63 61  ck..** If the ca
2a480 6c 6c 62 61 63 6b 20 6f 6e 20 61 20 63 6f 6d 6d  llback on a comm
2a490 69 74 20 68 6f 6f 6b 20 66 75 6e 63 74 69 6f 6e  it hook function
2a4a0 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72   returns non-zer
2a4b0 6f 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63  o,.** then the c
2a4c0 6f 6d 6d 69 74 20 69 73 20 63 6f 6e 76 65 72 74  ommit is convert
2a4d0 65 64 20 69 6e 74 6f 20 61 20 72 6f 6c 6c 62 61  ed into a rollba
2a4e0 63 6b 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 6f  ck..**.** If ano
2a4f0 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 20 77 61  ther function wa
2a500 73 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 67  s previously reg
2a510 69 73 74 65 72 65 64 2c 20 69 74 73 0a 2a 2a 20  istered, its.** 
2a520 70 41 72 67 20 76 61 6c 75 65 20 69 73 20 72 65  pArg value is re
2a530 74 75 72 6e 65 64 2e 20 20 4f 74 68 65 72 77 69  turned.  Otherwi
2a540 73 65 20 4e 55 4c 4c 20 69 73 20 72 65 74 75 72  se NULL is retur
2a550 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63  ned..**.** The c
2a560 61 6c 6c 62 61 63 6b 20 69 6d 70 6c 65 6d 65 6e  allback implemen
2a570 74 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20  tation must not 
2a580 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74  do anything that
2a590 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20   will modify.** 
2a5a0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
2a5b0 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76  nection that inv
2a5c0 6f 6b 65 64 20 74 68 65 20 63 61 6c 6c 62 61 63  oked the callbac
2a5d0 6b 2e 20 20 41 6e 79 20 61 63 74 69 6f 6e 73 0a  k.  Any actions.
2a5e0 2a 2a 20 74 6f 20 6d 6f 64 69 66 79 20 74 68 65  ** to modify the
2a5f0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
2a600 74 69 6f 6e 20 6d 75 73 74 20 62 65 20 64 65 66  tion must be def
2a610 65 72 72 65 64 20 75 6e 74 69 6c 20 61 66 74 65  erred until afte
2a620 72 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74  r the.** complet
2a630 69 6f 6e 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  ion of the [sqli
2a640 74 65 33 5f 73 74 65 70 28 29 5d 20 63 61 6c 6c  te3_step()] call
2a650 20 74 68 61 74 20 74 72 69 67 67 65 72 65 64 20   that triggered 
2a660 74 68 65 20 63 6f 6d 6d 69 74 0a 2a 2a 20 6f 72  the commit.** or
2a670 20 72 6f 6c 6c 62 61 63 6b 20 68 6f 6f 6b 20 69   rollback hook i
2a680 6e 20 74 68 65 20 66 69 72 73 74 20 70 6c 61 63  n the first plac
2a690 65 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  e..** Note that 
2a6a0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2a6b0 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  _v2()] and [sqli
2a6c0 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68  te3_step()] both
2a6d0 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a   modify their.**
2a6e0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
2a6f0 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65  tions for the me
2a700 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79  aning of "modify
2a710 22 20 69 6e 20 74 68 69 73 20 70 61 72 61 67 72  " in this paragr
2a720 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73  aph..**.** Regis
2a730 74 65 72 69 6e 67 20 61 20 4e 55 4c 4c 20 66 75  tering a NULL fu
2a740 6e 63 74 69 6f 6e 20 64 69 73 61 62 6c 65 73 20  nction disables 
2a750 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a  the callback..**
2a760 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 63 6f 6d  .** When the com
2a770 6d 69 74 20 68 6f 6f 6b 20 63 61 6c 6c 62 61 63  mit hook callbac
2a780 6b 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  k routine return
2a790 73 20 7a 65 72 6f 2c 20 74 68 65 20 5b 43 4f 4d  s zero, the [COM
2a7a0 4d 49 54 5d 0a 2a 2a 20 6f 70 65 72 61 74 69 6f  MIT].** operatio
2a7b0 6e 20 69 73 20 61 6c 6c 6f 77 65 64 20 74 6f 20  n is allowed to 
2a7c0 63 6f 6e 74 69 6e 75 65 20 6e 6f 72 6d 61 6c 6c  continue normall
2a7d0 79 2e 20 20 49 66 20 74 68 65 20 63 6f 6d 6d 69  y.  If the commi
2a7e0 74 20 68 6f 6f 6b 0a 2a 2a 20 72 65 74 75 72 6e  t hook.** return
2a7f0 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e  s non-zero, then
2a800 20 74 68 65 20 5b 43 4f 4d 4d 49 54 5d 20 69 73   the [COMMIT] is
2a810 20 63 6f 6e 76 65 72 74 65 64 20 69 6e 74 6f 20   converted into 
2a820 61 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2e 0a 2a 2a  a [ROLLBACK]..**
2a830 20 54 68 65 20 72 6f 6c 6c 62 61 63 6b 20 68 6f   The rollback ho
2a840 6f 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e  ok is invoked on
2a850 20 61 20 72 6f 6c 6c 62 61 63 6b 20 74 68 61 74   a rollback that
2a860 20 72 65 73 75 6c 74 73 20 66 72 6f 6d 20 61 20   results from a 
2a870 63 6f 6d 6d 69 74 0a 2a 2a 20 68 6f 6f 6b 20 72  commit.** hook r
2a880 65 74 75 72 6e 69 6e 67 20 6e 6f 6e 2d 7a 65 72  eturning non-zer
2a890 6f 2c 20 6a 75 73 74 20 61 73 20 69 74 20 77 6f  o, just as it wo
2a8a0 75 6c 64 20 62 65 20 77 69 74 68 20 61 6e 79 20  uld be with any 
2a8b0 6f 74 68 65 72 20 72 6f 6c 6c 62 61 63 6b 2e 0a  other rollback..
2a8c0 2a 2a 0a 2a 2a 20 46 6f 72 20 74 68 65 20 70 75  **.** For the pu
2a8d0 72 70 6f 73 65 73 20 6f 66 20 74 68 69 73 20 41  rposes of this A
2a8e0 50 49 2c 20 61 20 74 72 61 6e 73 61 63 74 69 6f  PI, a transactio
2a8f0 6e 20 69 73 20 73 61 69 64 20 74 6f 20 68 61 76  n is said to hav
2a900 65 20 62 65 65 6e 0a 2a 2a 20 72 6f 6c 6c 65 64  e been.** rolled
2a910 20 62 61 63 6b 20 69 66 20 61 6e 20 65 78 70 6c   back if an expl
2a920 69 63 69 74 20 22 52 4f 4c 4c 42 41 43 4b 22 20  icit "ROLLBACK" 
2a930 73 74 61 74 65 6d 65 6e 74 20 69 73 20 65 78 65  statement is exe
2a940 63 75 74 65 64 2c 20 6f 72 0a 2a 2a 20 61 6e 20  cuted, or.** an 
2a950 65 72 72 6f 72 20 6f 72 20 63 6f 6e 73 74 72 61  error or constra
2a960 69 6e 74 20 63 61 75 73 65 73 20 61 6e 20 69 6d  int causes an im
2a970 70 6c 69 63 69 74 20 72 6f 6c 6c 62 61 63 6b 20  plicit rollback 
2a980 74 6f 20 6f 63 63 75 72 2e 0a 2a 2a 20 54 68 65  to occur..** The
2a990 20 72 6f 6c 6c 62 61 63 6b 20 63 61 6c 6c 62 61   rollback callba
2a9a0 63 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65  ck is not invoke
2a9b0 64 20 69 66 20 61 20 74 72 61 6e 73 61 63 74 69  d if a transacti
2a9c0 6f 6e 20 69 73 0a 2a 2a 20 61 75 74 6f 6d 61 74  on is.** automat
2a9d0 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61  ically rolled ba
2a9e0 63 6b 20 62 65 63 61 75 73 65 20 74 68 65 20 64  ck because the d
2a9f0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2aa00 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a  on is closed..**
2aa10 20 54 68 65 20 72 6f 6c 6c 62 61 63 6b 20 63 61   The rollback ca
2aa20 6c 6c 62 61 63 6b 20 69 73 20 6e 6f 74 20 69 6e  llback is not in
2aa30 76 6f 6b 65 64 20 69 66 20 61 20 74 72 61 6e 73  voked if a trans
2aa40 61 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 72 6f 6c  action is.** rol
2aa50 6c 65 64 20 62 61 63 6b 20 62 65 63 61 75 73 65  led back because
2aa60 20 61 20 63 6f 6d 6d 69 74 20 63 61 6c 6c 62 61   a commit callba
2aa70 63 6b 20 72 65 74 75 72 6e 65 64 20 6e 6f 6e 2d  ck returned non-
2aa80 7a 65 72 6f 2e 0a 2a 2a 20 3c 74 6f 64 6f 3e 20  zero..** <todo> 
2aa90 43 68 65 63 6b 20 6f 6e 20 74 68 69 73 20 3c 2f  Check on this </
2aaa0 74 6f 64 6f 3e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  todo>.**.** See 
2aab0 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  also the [sqlite
2aac0 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 29 5d  3_update_hook()]
2aad0 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a   interface..**.*
2aae0 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a  * Requirements:.
2aaf0 2a 2a 20 5b 48 31 32 39 35 31 5d 20 5b 48 31 32  ** [H12951] [H12
2ab00 39 35 32 5d 20 5b 48 31 32 39 35 33 5d 20 5b 48  952] [H12953] [H
2ab10 31 32 39 35 34 5d 20 5b 48 31 32 39 35 35 5d 0a  12954] [H12955].
2ab20 2a 2a 20 5b 48 31 32 39 36 31 5d 20 5b 48 31 32  ** [H12961] [H12
2ab30 39 36 32 5d 20 5b 48 31 32 39 36 33 5d 20 5b 48  962] [H12963] [H
2ab40 31 32 39 36 34 5d 0a 2a 2f 0a 76 6f 69 64 20 2a  12964].*/.void *
2ab50 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68  sqlite3_commit_h
2ab60 6f 6f 6b 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e  ook(sqlite3*, in
2ab70 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69  t(*)(void*), voi
2ab80 64 2a 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74  d*);.void *sqlit
2ab90 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b  e3_rollback_hook
2aba0 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 28  (sqlite3*, void(
2abb0 2a 29 28 76 6f 69 64 20 2a 29 2c 20 76 6f 69 64  *)(void *), void
2abc0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
2abd0 52 45 46 3a 20 44 61 74 61 20 43 68 61 6e 67 65  REF: Data Change
2abe0 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e 20 43 61   Notification Ca
2abf0 6c 6c 62 61 63 6b 73 20 7b 48 31 32 39 37 30 7d  llbacks {H12970}
2ac00 20 3c 53 36 30 34 30 30 3e 0a 2a 2a 0a 2a 2a 20   <S60400>.**.** 
2ac10 54 68 65 20 73 71 6c 69 74 65 33 5f 75 70 64 61  The sqlite3_upda
2ac20 74 65 5f 68 6f 6f 6b 28 29 20 69 6e 74 65 72 66  te_hook() interf
2ac30 61 63 65 20 72 65 67 69 73 74 65 72 73 20 61 20  ace registers a 
2ac40 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
2ac50 6e 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 64  n.** with the [d
2ac60 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2ac70 6f 6e 5d 20 69 64 65 6e 74 69 66 69 65 64 20 62  on] identified b
2ac80 79 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  y the first argu
2ac90 6d 65 6e 74 0a 2a 2a 20 74 6f 20 62 65 20 69 6e  ment.** to be in
2aca0 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61  voked whenever a
2acb0 20 72 6f 77 20 69 73 20 75 70 64 61 74 65 64 2c   row is updated,
2acc0 20 69 6e 73 65 72 74 65 64 20 6f 72 20 64 65 6c   inserted or del
2acd0 65 74 65 64 2e 0a 2a 2a 20 41 6e 79 20 63 61 6c  eted..** Any cal
2ace0 6c 62 61 63 6b 20 73 65 74 20 62 79 20 61 20 70  lback set by a p
2acf0 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20  revious call to 
2ad00 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  this function.**
2ad10 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 64 61   for the same da
2ad20 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2ad30 6e 20 69 73 20 6f 76 65 72 72 69 64 64 65 6e 2e  n is overridden.
2ad40 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e  .**.** The secon
2ad50 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20  d argument is a 
2ad60 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 66  pointer to the f
2ad70 75 6e 63 74 69 6f 6e 20 74 6f 20 69 6e 76 6f 6b  unction to invok
2ad80 65 20 77 68 65 6e 20 61 0a 2a 2a 20 72 6f 77 20  e when a.** row 
2ad90 69 73 20 75 70 64 61 74 65 64 2c 20 69 6e 73 65  is updated, inse
2ada0 72 74 65 64 20 6f 72 20 64 65 6c 65 74 65 64 2e  rted or deleted.
2adb0 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72  .** The first ar
2adc0 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 63 61  gument to the ca
2add0 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79  llback is a copy
2ade0 20 6f 66 20 74 68 65 20 74 68 69 72 64 20 61 72   of the third ar
2adf0 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 73 71 6c  gument.** to sql
2ae00 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b  ite3_update_hook
2ae10 28 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e  ()..** The secon
2ae20 64 20 63 61 6c 6c 62 61 63 6b 20 61 72 67 75 6d  d callback argum
2ae30 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53  ent is one of [S
2ae40 51 4c 49 54 45 5f 49 4e 53 45 52 54 5d 2c 20 5b  QLITE_INSERT], [
2ae50 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d 2c 0a  SQLITE_DELETE],.
2ae60 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 50  ** or [SQLITE_UP
2ae70 44 41 54 45 5d 2c 20 64 65 70 65 6e 64 69 6e 67  DATE], depending
2ae80 20 6f 6e 20 74 68 65 20 6f 70 65 72 61 74 69 6f   on the operatio
2ae90 6e 20 74 68 61 74 20 63 61 75 73 65 64 20 74 68  n that caused th
2aea0 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74 6f  e callback.** to
2aeb0 20 62 65 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 20   be invoked..** 
2aec0 54 68 65 20 74 68 69 72 64 20 61 6e 64 20 66 6f  The third and fo
2aed0 75 72 74 68 20 61 72 67 75 6d 65 6e 74 73 20 74  urth arguments t
2aee0 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 63  o the callback c
2aef0 6f 6e 74 61 69 6e 20 70 6f 69 6e 74 65 72 73 20  ontain pointers 
2af00 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61  to the.** databa
2af10 73 65 20 61 6e 64 20 74 61 62 6c 65 20 6e 61 6d  se and table nam
2af20 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65  e containing the
2af30 20 61 66 66 65 63 74 65 64 20 72 6f 77 2e 0a 2a   affected row..*
2af40 2a 20 54 68 65 20 66 69 6e 61 6c 20 63 61 6c 6c  * The final call
2af50 62 61 63 6b 20 70 61 72 61 6d 65 74 65 72 20 69  back parameter i
2af60 73 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66  s the [rowid] of
2af70 20 74 68 65 20 72 6f 77 2e 0a 2a 2a 20 49 6e 20   the row..** In 
2af80 74 68 65 20 63 61 73 65 20 6f 66 20 61 6e 20 75  the case of an u
2af90 70 64 61 74 65 2c 20 74 68 69 73 20 69 73 20 74  pdate, this is t
2afa0 68 65 20 5b 72 6f 77 69 64 5d 20 61 66 74 65 72  he [rowid] after
2afb0 20 74 68 65 20 75 70 64 61 74 65 20 74 61 6b 65   the update take
2afc0 73 20 70 6c 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54  s place..**.** T
2afd0 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 20 69  he update hook i
2afe0 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 77 68  s not invoked wh
2aff0 65 6e 20 69 6e 74 65 72 6e 61 6c 20 73 79 73 74  en internal syst
2b000 65 6d 20 74 61 62 6c 65 73 20 61 72 65 0a 2a 2a  em tables are.**
2b010 20 6d 6f 64 69 66 69 65 64 20 28 69 2e 65 2e 20   modified (i.e. 
2b020 73 71 6c 69 74 65 5f 6d 61 73 74 65 72 20 61 6e  sqlite_master an
2b030 64 20 73 71 6c 69 74 65 5f 73 65 71 75 65 6e 63  d sqlite_sequenc
2b040 65 29 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65  e)..**.** In the
2b050 20 63 75 72 72 65 6e 74 20 69 6d 70 6c 65 6d 65   current impleme
2b060 6e 74 61 74 69 6f 6e 2c 20 74 68 65 20 75 70 64  ntation, the upd
2b070 61 74 65 20 68 6f 6f 6b 0a 2a 2a 20 69 73 20 6e  ate hook.** is n
2b080 6f 74 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20  ot invoked when 
2b090 64 75 70 6c 69 63 61 74 69 6f 6e 20 72 6f 77 73  duplication rows
2b0a0 20 61 72 65 20 64 65 6c 65 74 65 64 20 62 65 63   are deleted bec
2b0b0 61 75 73 65 20 6f 66 20 61 6e 0a 2a 2a 20 5b 4f  ause of an.** [O
2b0c0 4e 20 43 4f 4e 46 4c 49 43 54 20 7c 20 4f 4e 20  N CONFLICT | ON 
2b0d0 43 4f 4e 46 4c 49 43 54 20 52 45 50 4c 41 43 45  CONFLICT REPLACE
2b0e0 5d 20 63 6c 61 75 73 65 2e 20 20 4e 6f 72 20 69  ] clause.  Nor i
2b0f0 73 20 74 68 65 20 75 70 64 61 74 65 20 68 6f 6f  s the update hoo
2b100 6b 0a 2a 2a 20 69 6e 76 6f 6b 65 64 20 77 68 65  k.** invoked whe
2b110 6e 20 72 6f 77 73 20 61 72 65 20 64 65 6c 65 74  n rows are delet
2b120 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b 74 72  ed using the [tr
2b130 75 6e 63 61 74 65 20 6f 70 74 69 6d 69 7a 61 74  uncate optimizat
2b140 69 6f 6e 5d 2e 0a 2a 2a 20 54 68 65 20 65 78 63  ion]..** The exc
2b150 65 70 74 69 6f 6e 73 20 64 65 66 69 6e 65 64 20  eptions defined 
2b160 69 6e 20 74 68 69 73 20 70 61 72 61 67 72 61 70  in this paragrap
2b170 68 20 6d 69 67 68 74 20 63 68 61 6e 67 65 20 69  h might change i
2b180 6e 20 61 20 66 75 74 75 72 65 0a 2a 2a 20 72 65  n a future.** re
2b190 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 2e  lease of SQLite.
2b1a0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 75 70 64 61 74  .**.** The updat
2b1b0 65 20 68 6f 6f 6b 20 69 6d 70 6c 65 6d 65 6e 74  e hook implement
2b1c0 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 64  ation must not d
2b1d0 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20  o anything that 
2b1e0 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74  will modify.** t
2b1f0 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
2b200 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f  ection that invo
2b210 6b 65 64 20 74 68 65 20 75 70 64 61 74 65 20 68  ked the update h
2b220 6f 6f 6b 2e 20 20 41 6e 79 20 61 63 74 69 6f 6e  ook.  Any action
2b230 73 0a 2a 2a 20 74 6f 20 6d 6f 64 69 66 79 20 74  s.** to modify t
2b240 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
2b250 65 63 74 69 6f 6e 20 6d 75 73 74 20 62 65 20 64  ection must be d
2b260 65 66 65 72 72 65 64 20 75 6e 74 69 6c 20 61 66  eferred until af
2b270 74 65 72 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c  ter the.** compl
2b280 65 74 69 6f 6e 20 6f 66 20 74 68 65 20 5b 73 71  etion of the [sq
2b290 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 63 61  lite3_step()] ca
2b2a0 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65 72 65  ll that triggere
2b2b0 64 20 74 68 65 20 75 70 64 61 74 65 20 68 6f 6f  d the update hoo
2b2c0 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  k..** Note that 
2b2d0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2b2e0 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  _v2()] and [sqli
2b2f0 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68  te3_step()] both
2b300 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a   modify their.**
2b310 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
2b320 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65  tions for the me
2b330 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79  aning of "modify
2b340 22 20 69 6e 20 74 68 69 73 20 70 61 72 61 67 72  " in this paragr
2b350 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e  aph..**.** If an
2b360 6f 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 20 77  other function w
2b370 61 73 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65  as previously re
2b380 67 69 73 74 65 72 65 64 2c 20 69 74 73 20 70 41  gistered, its pA
2b390 72 67 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20 72  rg value.** is r
2b3a0 65 74 75 72 6e 65 64 2e 20 20 4f 74 68 65 72 77  eturned.  Otherw
2b3b0 69 73 65 20 4e 55 4c 4c 20 69 73 20 72 65 74 75  ise NULL is retu
2b3c0 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  rned..**.** See 
2b3d0 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  also the [sqlite
2b3e0 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 5d  3_commit_hook()]
2b3f0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 6f   and [sqlite3_ro
2b400 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29 5d 0a 2a  llback_hook()].*
2b410 2a 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a  * interfaces..**
2b420 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73  .** Requirements
2b430 3a 0a 2a 2a 20 5b 48 31 32 39 37 31 5d 20 5b 48  :.** [H12971] [H
2b440 31 32 39 37 33 5d 20 5b 48 31 32 39 37 35 5d 20  12973] [H12975] 
2b450 5b 48 31 32 39 37 37 5d 20 5b 48 31 32 39 37 39  [H12977] [H12979
2b460 5d 20 5b 48 31 32 39 38 31 5d 20 5b 48 31 32 39  ] [H12981] [H129
2b470 38 33 5d 20 5b 48 31 32 39 38 36 5d 0a 2a 2f 0a  83] [H12986].*/.
2b480 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 75 70  void *sqlite3_up
2b490 64 61 74 65 5f 68 6f 6f 6b 28 0a 20 20 73 71 6c  date_hook(.  sql
2b4a0 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 28 2a  ite3*, .  void(*
2b4b0 29 28 76 6f 69 64 20 2a 2c 69 6e 74 20 2c 63 68  )(void *,int ,ch
2b4c0 61 72 20 63 6f 6e 73 74 20 2a 2c 63 68 61 72 20  ar const *,char 
2b4d0 63 6f 6e 73 74 20 2a 2c 73 71 6c 69 74 65 33 5f  const *,sqlite3_
2b4e0 69 6e 74 36 34 29 2c 0a 20 20 76 6f 69 64 2a 0a  int64),.  void*.
2b4f0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2b500 45 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44 69  EF: Enable Or Di
2b510 73 61 62 6c 65 20 53 68 61 72 65 64 20 50 61 67  sable Shared Pag
2b520 65 72 20 43 61 63 68 65 20 7b 48 31 30 33 33 30  er Cache {H10330
2b530 7d 20 3c 53 33 30 39 30 30 3e 0a 2a 2a 20 4b 45  } <S30900>.** KE
2b540 59 57 4f 52 44 53 3a 20 7b 73 68 61 72 65 64 20  YWORDS: {shared 
2b550 63 61 63 68 65 7d 20 7b 73 68 61 72 65 64 20 63  cache} {shared c
2b560 61 63 68 65 20 6d 6f 64 65 7d 0a 2a 2a 0a 2a 2a  ache mode}.**.**
2b570 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 65 6e   This routine en
2b580 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65  ables or disable
2b590 73 20 74 68 65 20 73 68 61 72 69 6e 67 20 6f 66  s the sharing of
2b5a0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 61   the database ca
2b5b0 63 68 65 0a 2a 2a 20 61 6e 64 20 73 63 68 65 6d  che.** and schem
2b5c0 61 20 64 61 74 61 20 73 74 72 75 63 74 75 72 65  a data structure
2b5d0 73 20 62 65 74 77 65 65 6e 20 5b 64 61 74 61 62  s between [datab
2b5e0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 7c  ase connection |
2b5f0 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 0a 2a 2a   connections].**
2b600 20 74 6f 20 74 68 65 20 73 61 6d 65 20 64 61 74   to the same dat
2b610 61 62 61 73 65 2e 20 53 68 61 72 69 6e 67 20 69  abase. Sharing i
2b620 73 20 65 6e 61 62 6c 65 64 20 69 66 20 74 68 65  s enabled if the
2b630 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 72 75   argument is tru
2b640 65 0a 2a 2a 20 61 6e 64 20 64 69 73 61 62 6c 65  e.** and disable
2b650 64 20 69 66 20 74 68 65 20 61 72 67 75 6d 65 6e  d if the argumen
2b660 74 20 69 73 20 66 61 6c 73 65 2e 0a 2a 2a 0a 2a  t is false..**.*
2b670 2a 20 43 61 63 68 65 20 73 68 61 72 69 6e 67 20  * Cache sharing 
2b680 69 73 20 65 6e 61 62 6c 65 64 20 61 6e 64 20 64  is enabled and d
2b690 69 73 61 62 6c 65 64 20 66 6f 72 20 61 6e 20 65  isabled for an e
2b6a0 6e 74 69 72 65 20 70 72 6f 63 65 73 73 2e 0a 2a  ntire process..*
2b6b0 2a 20 54 68 69 73 20 69 73 20 61 20 63 68 61 6e  * This is a chan
2b6c0 67 65 20 61 73 20 6f 66 20 53 51 4c 69 74 65 20  ge as of SQLite 
2b6d0 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 2e 20 49  version 3.5.0. I
2b6e0 6e 20 70 72 69 6f 72 20 76 65 72 73 69 6f 6e 73  n prior versions
2b6f0 20 6f 66 20 53 51 4c 69 74 65 2c 0a 2a 2a 20 73   of SQLite,.** s
2b700 68 61 72 69 6e 67 20 77 61 73 20 65 6e 61 62 6c  haring was enabl
2b710 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64 20 66  ed or disabled f
2b720 6f 72 20 65 61 63 68 20 74 68 72 65 61 64 20 73  or each thread s
2b730 65 70 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a  eparately..**.**
2b740 20 54 68 65 20 63 61 63 68 65 20 73 68 61 72 69   The cache shari
2b750 6e 67 20 6d 6f 64 65 20 73 65 74 20 62 79 20 74  ng mode set by t
2b760 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 65 66  his interface ef
2b770 66 65 63 74 73 20 61 6c 6c 20 73 75 62 73 65 71  fects all subseq
2b780 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f  uent.** calls to
2b790 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
2b7a0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ], [sqlite3_open
2b7b0 5f 76 32 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c  _v2()], and [sql
2b7c0 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 0a  ite3_open16()]..
2b7d0 2a 2a 20 45 78 69 73 74 69 6e 67 20 64 61 74 61  ** Existing data
2b7e0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
2b7f0 20 63 6f 6e 74 69 6e 75 65 20 75 73 65 20 74 68   continue use th
2b800 65 20 73 68 61 72 69 6e 67 20 6d 6f 64 65 0a 2a  e sharing mode.*
2b810 2a 20 74 68 61 74 20 77 61 73 20 69 6e 20 65 66  * that was in ef
2b820 66 65 63 74 20 61 74 20 74 68 65 20 74 69 6d 65  fect at the time
2b830 20 74 68 65 79 20 77 65 72 65 20 6f 70 65 6e 65   they were opene
2b840 64 2e 0a 2a 2a 0a 2a 2a 20 56 69 72 74 75 61 6c  d..**.** Virtual
2b850 20 74 61 62 6c 65 73 20 63 61 6e 6e 6f 74 20 62   tables cannot b
2b860 65 20 75 73 65 64 20 77 69 74 68 20 61 20 73 68  e used with a sh
2b870 61 72 65 64 20 63 61 63 68 65 2e 20 20 57 68 65  ared cache.  Whe
2b880 6e 20 73 68 61 72 65 64 0a 2a 2a 20 63 61 63 68  n shared.** cach
2b890 65 20 69 73 20 65 6e 61 62 6c 65 64 2c 20 74 68  e is enabled, th
2b8a0 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  e [sqlite3_creat
2b8b0 65 5f 6d 6f 64 75 6c 65 28 29 5d 20 41 50 49 20  e_module()] API 
2b8c0 75 73 65 64 20 74 6f 20 72 65 67 69 73 74 65 72  used to register
2b8d0 0a 2a 2a 20 76 69 72 74 75 61 6c 20 74 61 62 6c  .** virtual tabl
2b8e0 65 73 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 72  es will always r
2b8f0 65 74 75 72 6e 20 61 6e 20 65 72 72 6f 72 2e 0a  eturn an error..
2b900 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69  **.** This routi
2b910 6e 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  ne returns [SQLI
2b920 54 45 5f 4f 4b 5d 20 69 66 20 73 68 61 72 65 64  TE_OK] if shared
2b930 20 63 61 63 68 65 20 77 61 73 20 65 6e 61 62 6c   cache was enabl
2b940 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64 0a 2a  ed or disabled.*
2b950 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2e 20  * successfully. 
2b960 20 41 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d   An [error code]
2b970 20 69 73 20 72 65 74 75 72 6e 65 64 20 6f 74 68   is returned oth
2b980 65 72 77 69 73 65 2e 0a 2a 2a 0a 2a 2a 20 53 68  erwise..**.** Sh
2b990 61 72 65 64 20 63 61 63 68 65 20 69 73 20 64 69  ared cache is di
2b9a0 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c  sabled by defaul
2b9b0 74 2e 20 42 75 74 20 74 68 69 73 20 6d 69 67 68  t. But this migh
2b9c0 74 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a 20 66  t change in.** f
2b9d0 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f  uture releases o
2b9e0 66 20 53 51 4c 69 74 65 2e 20 20 41 70 70 6c 69  f SQLite.  Appli
2b9f0 63 61 74 69 6f 6e 73 20 74 68 61 74 20 63 61 72  cations that car
2ba00 65 20 61 62 6f 75 74 20 73 68 61 72 65 64 0a 2a  e about shared.*
2ba10 2a 20 63 61 63 68 65 20 73 65 74 74 69 6e 67 20  * cache setting 
2ba20 73 68 6f 75 6c 64 20 73 65 74 20 69 74 20 65 78  should set it ex
2ba30 70 6c 69 63 69 74 6c 79 2e 0a 2a 2a 0a 2a 2a 20  plicitly..**.** 
2ba40 53 65 65 20 41 6c 73 6f 3a 20 20 5b 53 51 4c 69  See Also:  [SQLi
2ba50 74 65 20 53 68 61 72 65 64 2d 43 61 63 68 65 20  te Shared-Cache 
2ba60 4d 6f 64 65 5d 0a 2a 2a 0a 2a 2a 20 52 65 71 75  Mode].**.** Requ
2ba70 69 72 65 6d 65 6e 74 73 3a 20 5b 48 31 30 33 33  irements: [H1033
2ba80 31 5d 20 5b 48 31 30 33 33 36 5d 20 5b 48 31 30  1] [H10336] [H10
2ba90 33 33 37 5d 20 5b 48 31 30 33 33 39 5d 0a 2a 2f  337] [H10339].*/
2baa0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 6e 61  .int sqlite3_ena
2bab0 62 6c 65 5f 73 68 61 72 65 64 5f 63 61 63 68 65  ble_shared_cache
2bac0 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  (int);../*.** CA
2bad0 50 49 33 52 45 46 3a 20 41 74 74 65 6d 70 74 20  PI3REF: Attempt 
2bae0 54 6f 20 46 72 65 65 20 48 65 61 70 20 4d 65 6d  To Free Heap Mem
2baf0 6f 72 79 20 7b 48 31 37 33 34 30 7d 20 3c 53 33  ory {H17340} <S3
2bb00 30 32 32 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  0220>.**.** The 
2bb10 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f  sqlite3_release_
2bb20 6d 65 6d 6f 72 79 28 29 20 69 6e 74 65 72 66 61  memory() interfa
2bb30 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20 66  ce attempts to f
2bb40 72 65 65 20 4e 20 62 79 74 65 73 0a 2a 2a 20 6f  ree N bytes.** o
2bb50 66 20 68 65 61 70 20 6d 65 6d 6f 72 79 20 62 79  f heap memory by
2bb60 20 64 65 61 6c 6c 6f 63 61 74 69 6e 67 20 6e 6f   deallocating no
2bb70 6e 2d 65 73 73 65 6e 74 69 61 6c 20 6d 65 6d 6f  n-essential memo
2bb80 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 0a 2a  ry allocations.*
2bb90 2a 20 68 65 6c 64 20 62 79 20 74 68 65 20 64 61  * held by the da
2bba0 74 61 62 61 73 65 20 6c 69 62 72 61 72 79 2e 20  tabase library. 
2bbb0 7b 45 4e 44 7d 20 20 4d 65 6d 6f 72 79 20 75 73  {END}  Memory us
2bbc0 65 64 20 74 6f 20 63 61 63 68 65 20 64 61 74 61  ed to cache data
2bbd0 62 61 73 65 0a 2a 2a 20 70 61 67 65 73 20 74 6f  base.** pages to
2bbe0 20 69 6d 70 72 6f 76 65 20 70 65 72 66 6f 72 6d   improve perform
2bbf0 61 6e 63 65 20 69 73 20 61 6e 20 65 78 61 6d 70  ance is an examp
2bc00 6c 65 20 6f 66 20 6e 6f 6e 2d 65 73 73 65 6e 74  le of non-essent
2bc10 69 61 6c 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 73  ial memory..** s
2bc20 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d  qlite3_release_m
2bc30 65 6d 6f 72 79 28 29 20 72 65 74 75 72 6e 73 20  emory() returns 
2bc40 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
2bc50 74 65 73 20 61 63 74 75 61 6c 6c 79 20 66 72 65  tes actually fre
2bc60 65 64 2c 0a 2a 2a 20 77 68 69 63 68 20 6d 69 67  ed,.** which mig
2bc70 68 74 20 62 65 20 6d 6f 72 65 20 6f 72 20 6c 65  ht be more or le
2bc80 73 73 20 74 68 61 6e 20 74 68 65 20 61 6d 6f 75  ss than the amou
2bc90 6e 74 20 72 65 71 75 65 73 74 65 64 2e 0a 2a 2a  nt requested..**
2bca0 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73  .** Requirements
2bcb0 3a 20 5b 48 31 37 33 34 31 5d 20 5b 48 31 37 33  : [H17341] [H173
2bcc0 34 32 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  42].*/.int sqlit
2bcd0 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72  e3_release_memor
2bce0 79 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  y(int);../*.** C
2bcf0 41 50 49 33 52 45 46 3a 20 49 6d 70 6f 73 65 20  API3REF: Impose 
2bd00 41 20 4c 69 6d 69 74 20 4f 6e 20 48 65 61 70 20  A Limit On Heap 
2bd10 53 69 7a 65 20 7b 48 31 37 33 35 30 7d 20 3c 53  Size {H17350} <S
2bd20 33 30 32 32 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  30220>.**.** The
2bd30 20 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65   sqlite3_soft_he
2bd40 61 70 5f 6c 69 6d 69 74 28 29 20 69 6e 74 65 72  ap_limit() inter
2bd50 66 61 63 65 20 70 6c 61 63 65 73 20 61 20 22 73  face places a "s
2bd60 6f 66 74 22 20 6c 69 6d 69 74 0a 2a 2a 20 6f 6e  oft" limit.** on
2bd70 20 74 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 68   the amount of h
2bd80 65 61 70 20 6d 65 6d 6f 72 79 20 74 68 61 74 20  eap memory that 
2bd90 6d 61 79 20 62 65 20 61 6c 6c 6f 63 61 74 65 64  may be allocated
2bda0 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 49   by SQLite..** I
2bdb0 66 20 61 6e 20 69 6e 74 65 72 6e 61 6c 20 61 6c  f an internal al
2bdc0 6c 6f 63 61 74 69 6f 6e 20 69 73 20 72 65 71 75  location is requ
2bdd0 65 73 74 65 64 20 74 68 61 74 20 77 6f 75 6c 64  ested that would
2bde0 20 65 78 63 65 65 64 20 74 68 65 0a 2a 2a 20 73   exceed the.** s
2bdf0 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 2c 20  oft heap limit, 
2be00 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65  [sqlite3_release
2be10 5f 6d 65 6d 6f 72 79 28 29 5d 20 69 73 20 69 6e  _memory()] is in
2be20 76 6f 6b 65 64 20 6f 6e 65 20 6f 72 0a 2a 2a 20  voked one or.** 
2be30 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f 20 66 72  more times to fr
2be40 65 65 20 75 70 20 73 6f 6d 65 20 73 70 61 63 65  ee up some space
2be50 20 62 65 66 6f 72 65 20 74 68 65 20 61 6c 6c 6f   before the allo
2be60 63 61 74 69 6f 6e 20 69 73 20 70 65 72 66 6f 72  cation is perfor
2be70 6d 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6c  med..**.** The l
2be80 69 6d 69 74 20 69 73 20 63 61 6c 6c 65 64 20 22  imit is called "
2be90 73 6f 66 74 22 2c 20 62 65 63 61 75 73 65 20 69  soft", because i
2bea0 66 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65 61  f [sqlite3_relea
2beb0 73 65 5f 6d 65 6d 6f 72 79 28 29 5d 0a 2a 2a 20  se_memory()].** 
2bec0 63 61 6e 6e 6f 74 20 66 72 65 65 20 73 75 66 66  cannot free suff
2bed0 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79 20 74 6f  icient memory to
2bee0 20 70 72 65 76 65 6e 74 20 74 68 65 20 6c 69 6d   prevent the lim
2bef0 69 74 20 66 72 6f 6d 20 62 65 69 6e 67 20 65 78  it from being ex
2bf00 63 65 65 64 65 64 2c 0a 2a 2a 20 74 68 65 20 6d  ceeded,.** the m
2bf10 65 6d 6f 72 79 20 69 73 20 61 6c 6c 6f 63 61 74  emory is allocat
2bf20 65 64 20 61 6e 79 77 61 79 20 61 6e 64 20 74 68  ed anyway and th
2bf30 65 20 63 75 72 72 65 6e 74 20 6f 70 65 72 61 74  e current operat
2bf40 69 6f 6e 20 70 72 6f 63 65 65 64 73 2e 0a 2a 2a  ion proceeds..**
2bf50 0a 2a 2a 20 41 20 6e 65 67 61 74 69 76 65 20 6f  .** A negative o
2bf60 72 20 7a 65 72 6f 20 76 61 6c 75 65 20 66 6f 72  r zero value for
2bf70 20 4e 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68   N means that th
2bf80 65 72 65 20 69 73 20 6e 6f 20 73 6f 66 74 20 68  ere is no soft h
2bf90 65 61 70 20 6c 69 6d 69 74 20 61 6e 64 0a 2a 2a  eap limit and.**
2bfa0 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73   [sqlite3_releas
2bfb0 65 5f 6d 65 6d 6f 72 79 28 29 5d 20 77 69 6c 6c  e_memory()] will
2bfc0 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20   only be called 
2bfd0 77 68 65 6e 20 6d 65 6d 6f 72 79 20 69 73 20 65  when memory is e
2bfe0 78 68 61 75 73 74 65 64 2e 0a 2a 2a 20 54 68 65  xhausted..** The
2bff0 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20 66   default value f
2c000 6f 72 20 74 68 65 20 73 6f 66 74 20 68 65 61 70  or the soft heap
2c010 20 6c 69 6d 69 74 20 69 73 20 7a 65 72 6f 2e 0a   limit is zero..
2c020 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 61 6b  **.** SQLite mak
2c030 65 73 20 61 20 62 65 73 74 20 65 66 66 6f 72 74  es a best effort
2c040 20 74 6f 20 68 6f 6e 6f 72 20 74 68 65 20 73 6f   to honor the so
2c050 66 74 20 68 65 61 70 20 6c 69 6d 69 74 2e 0a 2a  ft heap limit..*
2c060 2a 20 42 75 74 20 69 66 20 74 68 65 20 73 6f 66  * But if the sof
2c070 74 20 68 65 61 70 20 6c 69 6d 69 74 20 63 61 6e  t heap limit can
2c080 6e 6f 74 20 62 65 20 68 6f 6e 6f 72 65 64 2c 20  not be honored, 
2c090 65 78 65 63 75 74 69 6f 6e 20 77 69 6c 6c 0a 2a  execution will.*
2c0a0 2a 20 63 6f 6e 74 69 6e 75 65 20 77 69 74 68 6f  * continue witho
2c0b0 75 74 20 65 72 72 6f 72 20 6f 72 20 6e 6f 74 69  ut error or noti
2c0c0 66 69 63 61 74 69 6f 6e 2e 20 20 54 68 69 73 20  fication.  This 
2c0d0 69 73 20 77 68 79 20 74 68 65 20 6c 69 6d 69 74  is why the limit
2c0e0 20 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 20 61 20   is.** called a 
2c0f0 22 73 6f 66 74 22 20 6c 69 6d 69 74 2e 20 20 49  "soft" limit.  I
2c100 74 20 69 73 20 61 64 76 69 73 6f 72 79 20 6f 6e  t is advisory on
2c110 6c 79 2e 0a 2a 2a 0a 2a 2a 20 50 72 69 6f 72 20  ly..**.** Prior 
2c120 74 6f 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  to SQLite versio
2c130 6e 20 33 2e 35 2e 30 2c 20 74 68 69 73 20 72 6f  n 3.5.0, this ro
2c140 75 74 69 6e 65 20 6f 6e 6c 79 20 63 6f 6e 73 74  utine only const
2c150 72 61 69 6e 65 64 20 74 68 65 20 6d 65 6d 6f 72  rained the memor
2c160 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 64 20 62  y.** allocated b
2c170 79 20 61 20 73 69 6e 67 6c 65 20 74 68 72 65 61  y a single threa
2c180 64 20 2d 20 74 68 65 20 73 61 6d 65 20 74 68 72  d - the same thr
2c190 65 61 64 20 69 6e 20 77 68 69 63 68 20 74 68 69  ead in which thi
2c1a0 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 72 75 6e  s routine.** run
2c1b0 73 2e 20 20 42 65 67 69 6e 6e 69 6e 67 20 77 69  s.  Beginning wi
2c1c0 74 68 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  th SQLite versio
2c1d0 6e 20 33 2e 35 2e 30 2c 20 74 68 65 20 73 6f 66  n 3.5.0, the sof
2c1e0 74 20 68 65 61 70 20 6c 69 6d 69 74 20 69 73 0a  t heap limit is.
2c1f0 2a 2a 20 61 70 70 6c 69 65 64 20 74 6f 20 61 6c  ** applied to al
2c200 6c 20 74 68 72 65 61 64 73 2e 20 54 68 65 20 76  l threads. The v
2c210 61 6c 75 65 20 73 70 65 63 69 66 69 65 64 20 66  alue specified f
2c220 6f 72 20 74 68 65 20 73 6f 66 74 20 68 65 61 70  or the soft heap
2c230 20 6c 69 6d 69 74 0a 2a 2a 20 69 73 20 61 6e 20   limit.** is an 
2c240 75 70 70 65 72 20 62 6f 75 6e 64 20 6f 6e 20 74  upper bound on t
2c250 68 65 20 74 6f 74 61 6c 20 6d 65 6d 6f 72 79 20  he total memory 
2c260 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 6f 72 20 61  allocation for a
2c270 6c 6c 20 74 68 72 65 61 64 73 2e 20 49 6e 0a 2a  ll threads. In.*
2c280 2a 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 20  * version 3.5.0 
2c290 74 68 65 72 65 20 69 73 20 6e 6f 20 6d 65 63 68  there is no mech
2c2a0 61 6e 69 73 6d 20 66 6f 72 20 6c 69 6d 69 74 69  anism for limiti
2c2b0 6e 67 20 74 68 65 20 68 65 61 70 20 75 73 61 67  ng the heap usag
2c2c0 65 20 66 6f 72 0a 2a 2a 20 69 6e 64 69 76 69 64  e for.** individ
2c2d0 75 61 6c 20 74 68 72 65 61 64 73 2e 0a 2a 2a 0a  ual threads..**.
2c2e0 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a  ** Requirements:
2c2f0 0a 2a 2a 20 5b 48 31 36 33 35 31 5d 20 5b 48 31  .** [H16351] [H1
2c300 36 33 35 32 5d 20 5b 48 31 36 33 35 33 5d 20 5b  6352] [H16353] [
2c310 48 31 36 33 35 34 5d 20 5b 48 31 36 33 35 35 5d  H16354] [H16355]
2c320 20 5b 48 31 36 33 35 38 5d 0a 2a 2f 0a 76 6f 69   [H16358].*/.voi
2c330 64 20 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68  d sqlite3_soft_h
2c340 65 61 70 5f 6c 69 6d 69 74 28 69 6e 74 29 3b 0a  eap_limit(int);.
2c350 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2c360 20 45 78 74 72 61 63 74 20 4d 65 74 61 64 61 74   Extract Metadat
2c370 61 20 41 62 6f 75 74 20 41 20 43 6f 6c 75 6d 6e  a About A Column
2c380 20 4f 66 20 41 20 54 61 62 6c 65 20 7b 48 31 32   Of A Table {H12
2c390 38 35 30 7d 20 3c 53 36 30 33 30 30 3e 0a 2a 2a  850} <S60300>.**
2c3a0 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65  .** This routine
2c3b0 20 72 65 74 75 72 6e 73 20 6d 65 74 61 64 61 74   returns metadat
2c3c0 61 20 61 62 6f 75 74 20 61 20 73 70 65 63 69 66  a about a specif
2c3d0 69 63 20 63 6f 6c 75 6d 6e 20 6f 66 20 61 20 73  ic column of a s
2c3e0 70 65 63 69 66 69 63 0a 2a 2a 20 64 61 74 61 62  pecific.** datab
2c3f0 61 73 65 20 74 61 62 6c 65 20 61 63 63 65 73 73  ase table access
2c400 69 62 6c 65 20 75 73 69 6e 67 20 74 68 65 20 5b  ible using the [
2c410 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2c420 69 6f 6e 5d 20 68 61 6e 64 6c 65 0a 2a 2a 20 70  ion] handle.** p
2c430 61 73 73 65 64 20 61 73 20 74 68 65 20 66 69 72  assed as the fir
2c440 73 74 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75  st function argu
2c450 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ment..**.** The 
2c460 63 6f 6c 75 6d 6e 20 69 73 20 69 64 65 6e 74 69  column is identi
2c470 66 69 65 64 20 62 79 20 74 68 65 20 73 65 63 6f  fied by the seco
2c480 6e 64 2c 20 74 68 69 72 64 20 61 6e 64 20 66 6f  nd, third and fo
2c490 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 73 20  urth parameters 
2c4a0 74 6f 0a 2a 2a 20 74 68 69 73 20 66 75 6e 63 74  to.** this funct
2c4b0 69 6f 6e 2e 20 54 68 65 20 73 65 63 6f 6e 64 20  ion. The second 
2c4c0 70 61 72 61 6d 65 74 65 72 20 69 73 20 65 69 74  parameter is eit
2c4d0 68 65 72 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  her the name of 
2c4e0 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  the database.** 
2c4f0 28 69 2e 65 2e 20 22 6d 61 69 6e 22 2c 20 22 74  (i.e. "main", "t
2c500 65 6d 70 22 20 6f 72 20 61 6e 20 61 74 74 61 63  emp" or an attac
2c510 68 65 64 20 64 61 74 61 62 61 73 65 29 20 63 6f  hed database) co
2c520 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 73 70 65  ntaining the spe
2c530 63 69 66 69 65 64 0a 2a 2a 20 74 61 62 6c 65 20  cified.** table 
2c540 6f 72 20 4e 55 4c 4c 2e 20 49 66 20 69 74 20 69  or NULL. If it i
2c550 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 61 6c 6c  s NULL, then all
2c560 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61   attached databa
2c570 73 65 73 20 61 72 65 20 73 65 61 72 63 68 65 64  ses are searched
2c580 0a 2a 2a 20 66 6f 72 20 74 68 65 20 74 61 62 6c  .** for the tabl
2c590 65 20 75 73 69 6e 67 20 74 68 65 20 73 61 6d 65  e using the same
2c5a0 20 61 6c 67 6f 72 69 74 68 6d 20 75 73 65 64 20   algorithm used 
2c5b0 62 79 20 74 68 65 20 64 61 74 61 62 61 73 65 20  by the database 
2c5c0 65 6e 67 69 6e 65 20 74 6f 0a 2a 2a 20 72 65 73  engine to.** res
2c5d0 6f 6c 76 65 20 75 6e 71 75 61 6c 69 66 69 65 64  olve unqualified
2c5e0 20 74 61 62 6c 65 20 72 65 66 65 72 65 6e 63 65   table reference
2c5f0 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 68 69  s..**.** The thi
2c600 72 64 20 61 6e 64 20 66 6f 75 72 74 68 20 70 61  rd and fourth pa
2c610 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68 69 73  rameters to this
2c620 20 66 75 6e 63 74 69 6f 6e 20 61 72 65 20 74 68   function are th
2c630 65 20 74 61 62 6c 65 20 61 6e 64 20 63 6f 6c 75  e table and colu
2c640 6d 6e 0a 2a 2a 20 6e 61 6d 65 20 6f 66 20 74 68  mn.** name of th
2c650 65 20 64 65 73 69 72 65 64 20 63 6f 6c 75 6d 6e  e desired column
2c660 2c 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 20  , respectively. 
2c670 4e 65 69 74 68 65 72 20 6f 66 20 74 68 65 73 65  Neither of these
2c680 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 6d   parameters.** m
2c690 61 79 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  ay be NULL..**.*
2c6a0 2a 20 4d 65 74 61 64 61 74 61 20 69 73 20 72 65  * Metadata is re
2c6b0 74 75 72 6e 65 64 20 62 79 20 77 72 69 74 69 6e  turned by writin
2c6c0 67 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79 20  g to the memory 
2c6d0 6c 6f 63 61 74 69 6f 6e 73 20 70 61 73 73 65 64  locations passed
2c6e0 20 61 73 20 74 68 65 20 35 74 68 0a 2a 2a 20 61   as the 5th.** a
2c6f0 6e 64 20 73 75 62 73 65 71 75 65 6e 74 20 70 61  nd subsequent pa
2c700 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68 69 73  rameters to this
2c710 20 66 75 6e 63 74 69 6f 6e 2e 20 41 6e 79 20 6f   function. Any o
2c720 66 20 74 68 65 73 65 20 61 72 67 75 6d 65 6e 74  f these argument
2c730 73 20 6d 61 79 20 62 65 0a 2a 2a 20 4e 55 4c 4c  s may be.** NULL
2c740 2c 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20  , in which case 
2c750 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  the correspondin
2c760 67 20 65 6c 65 6d 65 6e 74 20 6f 66 20 6d 65 74  g element of met
2c770 61 64 61 74 61 20 69 73 20 6f 6d 69 74 74 65 64  adata is omitted
2c780 2e 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  ..**.** <blockqu
2c790 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20 62  ote>.** <table b
2c7a0 6f 72 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74  order="1">.** <t
2c7b0 72 3e 3c 74 68 3e 20 50 61 72 61 6d 65 74 65 72  r><th> Parameter
2c7c0 20 3c 74 68 3e 20 4f 75 74 70 75 74 3c 62 72 3e   <th> Output<br>
2c7d0 54 79 70 65 20 3c 74 68 3e 20 20 44 65 73 63 72  Type <th>  Descr
2c7e0 69 70 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72  iption.**.** <tr
2c7f0 3e 3c 74 64 3e 20 35 74 68 20 3c 74 64 3e 20 63  ><td> 5th <td> c
2c800 6f 6e 73 74 20 63 68 61 72 2a 20 3c 74 64 3e 20  onst char* <td> 
2c810 44 61 74 61 20 74 79 70 65 0a 2a 2a 20 3c 74 72  Data type.** <tr
2c820 3e 3c 74 64 3e 20 36 74 68 20 3c 74 64 3e 20 63  ><td> 6th <td> c
2c830 6f 6e 73 74 20 63 68 61 72 2a 20 3c 74 64 3e 20  onst char* <td> 
2c840 4e 61 6d 65 20 6f 66 20 64 65 66 61 75 6c 74 20  Name of default 
2c850 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e  collation sequen
2c860 63 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 37  ce.** <tr><td> 7
2c870 74 68 20 3c 74 64 3e 20 69 6e 74 20 20 20 20 20  th <td> int     
2c880 20 20 20 20 3c 74 64 3e 20 54 72 75 65 20 69 66      <td> True if
2c890 20 63 6f 6c 75 6d 6e 20 68 61 73 20 61 20 4e 4f   column has a NO
2c8a0 54 20 4e 55 4c 4c 20 63 6f 6e 73 74 72 61 69 6e  T NULL constrain
2c8b0 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 38 74  t.** <tr><td> 8t
2c8c0 68 20 3c 74 64 3e 20 69 6e 74 20 20 20 20 20 20  h <td> int      
2c8d0 20 20 20 3c 74 64 3e 20 54 72 75 65 20 69 66 20     <td> True if 
2c8e0 63 6f 6c 75 6d 6e 20 69 73 20 70 61 72 74 20 6f  column is part o
2c8f0 66 20 74 68 65 20 50 52 49 4d 41 52 59 20 4b 45  f the PRIMARY KE
2c900 59 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 39 74  Y.** <tr><td> 9t
2c910 68 20 3c 74 64 3e 20 69 6e 74 20 20 20 20 20 20  h <td> int      
2c920 20 20 20 3c 74 64 3e 20 54 72 75 65 20 69 66 20     <td> True if 
2c930 63 6f 6c 75 6d 6e 20 69 73 20 5b 41 55 54 4f 49  column is [AUTOI
2c940 4e 43 52 45 4d 45 4e 54 5d 0a 2a 2a 20 3c 2f 74  NCREMENT].** </t
2c950 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b  able>.** </block
2c960 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  quote>.**.** The
2c970 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 64 20   memory pointed 
2c980 74 6f 20 62 79 20 74 68 65 20 63 68 61 72 61 63  to by the charac
2c990 74 65 72 20 70 6f 69 6e 74 65 72 73 20 72 65 74  ter pointers ret
2c9a0 75 72 6e 65 64 20 66 6f 72 20 74 68 65 0a 2a 2a  urned for the.**
2c9b0 20 64 65 63 6c 61 72 61 74 69 6f 6e 20 74 79 70   declaration typ
2c9c0 65 20 61 6e 64 20 63 6f 6c 6c 61 74 69 6f 6e 20  e and collation 
2c9d0 73 65 71 75 65 6e 63 65 20 69 73 20 76 61 6c 69  sequence is vali
2c9e0 64 20 6f 6e 6c 79 20 75 6e 74 69 6c 20 74 68 65  d only until the
2c9f0 20 6e 65 78 74 0a 2a 2a 20 63 61 6c 6c 20 74 6f   next.** call to
2ca00 20 61 6e 79 20 53 51 4c 69 74 65 20 41 50 49 20   any SQLite API 
2ca10 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  function..**.** 
2ca20 49 66 20 74 68 65 20 73 70 65 63 69 66 69 65 64  If the specified
2ca30 20 74 61 62 6c 65 20 69 73 20 61 63 74 75 61 6c   table is actual
2ca40 6c 79 20 61 20 76 69 65 77 2c 20 61 6e 20 5b 65  ly a view, an [e
2ca50 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65  rror code] is re
2ca60 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66  turned..**.** If
2ca70 20 74 68 65 20 73 70 65 63 69 66 69 65 64 20 63   the specified c
2ca80 6f 6c 75 6d 6e 20 69 73 20 22 72 6f 77 69 64 22  olumn is "rowid"
2ca90 2c 20 22 6f 69 64 22 20 6f 72 20 22 5f 72 6f 77  , "oid" or "_row
2caa0 69 64 5f 22 20 61 6e 64 20 61 6e 0a 2a 2a 20 5b  id_" and an.** [
2cab0 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59 20  INTEGER PRIMARY 
2cac0 4b 45 59 5d 20 63 6f 6c 75 6d 6e 20 68 61 73 20  KEY] column has 
2cad0 62 65 65 6e 20 65 78 70 6c 69 63 69 74 6c 79 20  been explicitly 
2cae0 64 65 63 6c 61 72 65 64 2c 20 74 68 65 6e 20 74  declared, then t
2caf0 68 65 20 6f 75 74 70 75 74 0a 2a 2a 20 70 61 72  he output.** par
2cb00 61 6d 65 74 65 72 73 20 61 72 65 20 73 65 74 20  ameters are set 
2cb10 66 6f 72 20 74 68 65 20 65 78 70 6c 69 63 69 74  for the explicit
2cb20 6c 79 20 64 65 63 6c 61 72 65 64 20 63 6f 6c 75  ly declared colu
2cb30 6d 6e 2e 20 49 66 20 74 68 65 72 65 20 69 73 20  mn. If there is 
2cb40 6e 6f 0a 2a 2a 20 65 78 70 6c 69 63 69 74 6c 79  no.** explicitly
2cb50 20 64 65 63 6c 61 72 65 64 20 5b 49 4e 54 45 47   declared [INTEG
2cb60 45 52 20 50 52 49 4d 41 52 59 20 4b 45 59 5d 20  ER PRIMARY KEY] 
2cb70 63 6f 6c 75 6d 6e 2c 20 74 68 65 6e 20 74 68 65  column, then the
2cb80 20 6f 75 74 70 75 74 0a 2a 2a 20 70 61 72 61 6d   output.** param
2cb90 65 74 65 72 73 20 61 72 65 20 73 65 74 20 61 73  eters are set as
2cba0 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20   follows:.**.** 
2cbb0 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 64 61 74  <pre>.**     dat
2cbc0 61 20 74 79 70 65 3a 20 22 49 4e 54 45 47 45 52  a type: "INTEGER
2cbd0 22 0a 2a 2a 20 20 20 20 20 63 6f 6c 6c 61 74 69  ".**     collati
2cbe0 6f 6e 20 73 65 71 75 65 6e 63 65 3a 20 22 42 49  on sequence: "BI
2cbf0 4e 41 52 59 22 0a 2a 2a 20 20 20 20 20 6e 6f 74  NARY".**     not
2cc00 20 6e 75 6c 6c 3a 20 30 0a 2a 2a 20 20 20 20 20   null: 0.**     
2cc10 70 72 69 6d 61 72 79 20 6b 65 79 3a 20 31 0a 2a  primary key: 1.*
2cc20 2a 20 20 20 20 20 61 75 74 6f 20 69 6e 63 72 65  *     auto incre
2cc30 6d 65 6e 74 3a 20 30 0a 2a 2a 20 3c 2f 70 72 65  ment: 0.** </pre
2cc40 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e  >.**.** This fun
2cc50 63 74 69 6f 6e 20 6d 61 79 20 6c 6f 61 64 20 6f  ction may load o
2cc60 6e 65 20 6f 72 20 6d 6f 72 65 20 73 63 68 65 6d  ne or more schem
2cc70 61 73 20 66 72 6f 6d 20 64 61 74 61 62 61 73 65  as from database
2cc80 20 66 69 6c 65 73 2e 20 49 66 20 61 6e 0a 2a 2a   files. If an.**
2cc90 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 64 75   error occurs du
2cca0 72 69 6e 67 20 74 68 69 73 20 70 72 6f 63 65 73  ring this proces
2ccb0 73 2c 20 6f 72 20 69 66 20 74 68 65 20 72 65 71  s, or if the req
2ccc0 75 65 73 74 65 64 20 74 61 62 6c 65 20 6f 72 20  uested table or 
2ccd0 63 6f 6c 75 6d 6e 0a 2a 2a 20 63 61 6e 6e 6f 74  column.** cannot
2cce0 20 62 65 20 66 6f 75 6e 64 2c 20 61 6e 20 5b 65   be found, an [e
2ccf0 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65  rror code] is re
2cd00 74 75 72 6e 65 64 20 61 6e 64 20 61 6e 20 65 72  turned and an er
2cd10 72 6f 72 20 6d 65 73 73 61 67 65 20 6c 65 66 74  ror message left
2cd20 0a 2a 2a 20 69 6e 20 74 68 65 20 5b 64 61 74 61  .** in the [data
2cd30 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
2cd40 20 28 74 6f 20 62 65 20 72 65 74 72 69 65 76 65   (to be retrieve
2cd50 64 20 75 73 69 6e 67 20 73 71 6c 69 74 65 33 5f  d using sqlite3_
2cd60 65 72 72 6d 73 67 28 29 29 2e 0a 2a 2a 0a 2a 2a  errmsg())..**.**
2cd70 20 54 68 69 73 20 41 50 49 20 69 73 20 6f 6e 6c   This API is onl
2cd80 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20 74  y available if t
2cd90 68 65 20 6c 69 62 72 61 72 79 20 77 61 73 20 63  he library was c
2cda0 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65  ompiled with the
2cdb0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42  .** [SQLITE_ENAB
2cdc0 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41  LE_COLUMN_METADA
2cdd0 54 41 5d 20 43 2d 70 72 65 70 72 6f 63 65 73 73  TA] C-preprocess
2cde0 6f 72 20 73 79 6d 62 6f 6c 20 64 65 66 69 6e 65  or symbol define
2cdf0 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  d..*/.int sqlite
2ce00 33 5f 74 61 62 6c 65 5f 63 6f 6c 75 6d 6e 5f 6d  3_table_column_m
2ce10 65 74 61 64 61 74 61 28 0a 20 20 73 71 6c 69 74  etadata(.  sqlit
2ce20 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
2ce30 20 20 20 20 20 20 20 2f 2a 20 43 6f 6e 6e 65 63         /* Connec
2ce40 74 69 6f 6e 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  tion handle */. 
2ce50 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44 62   const char *zDb
2ce60 4e 61 6d 65 2c 20 20 20 20 20 20 20 20 2f 2a 20  Name,        /* 
2ce70 44 61 74 61 62 61 73 65 20 6e 61 6d 65 20 6f 72  Database name or
2ce80 20 4e 55 4c 4c 20 2a 2f 0a 20 20 63 6f 6e 73 74   NULL */.  const
2ce90 20 63 68 61 72 20 2a 7a 54 61 62 6c 65 4e 61 6d   char *zTableNam
2cea0 65 2c 20 20 20 20 20 2f 2a 20 54 61 62 6c 65 20  e,     /* Table 
2ceb0 6e 61 6d 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  name */.  const 
2cec0 63 68 61 72 20 2a 7a 43 6f 6c 75 6d 6e 4e 61 6d  char *zColumnNam
2ced0 65 2c 20 20 20 20 2f 2a 20 43 6f 6c 75 6d 6e 20  e,    /* Column 
2cee0 6e 61 6d 65 20 2a 2f 0a 20 20 63 68 61 72 20 63  name */.  char c
2cef0 6f 6e 73 74 20 2a 2a 70 7a 44 61 74 61 54 79 70  onst **pzDataTyp
2cf00 65 2c 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a  e,    /* OUTPUT:
2cf10 20 44 65 63 6c 61 72 65 64 20 64 61 74 61 20 74   Declared data t
2cf20 79 70 65 20 2a 2f 0a 20 20 63 68 61 72 20 63 6f  ype */.  char co
2cf30 6e 73 74 20 2a 2a 70 7a 43 6f 6c 6c 53 65 71 2c  nst **pzCollSeq,
2cf40 20 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20       /* OUTPUT: 
2cf50 43 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e  Collation sequen
2cf60 63 65 20 6e 61 6d 65 20 2a 2f 0a 20 20 69 6e 74  ce name */.  int
2cf70 20 2a 70 4e 6f 74 4e 75 6c 6c 2c 20 20 20 20 20   *pNotNull,     
2cf80 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 50           /* OUTP
2cf90 55 54 3a 20 54 72 75 65 20 69 66 20 4e 4f 54 20  UT: True if NOT 
2cfa0 4e 55 4c 4c 20 63 6f 6e 73 74 72 61 69 6e 74 20  NULL constraint 
2cfb0 65 78 69 73 74 73 20 2a 2f 0a 20 20 69 6e 74 20  exists */.  int 
2cfc0 2a 70 50 72 69 6d 61 72 79 4b 65 79 2c 20 20 20  *pPrimaryKey,   
2cfd0 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 50 55          /* OUTPU
2cfe0 54 3a 20 54 72 75 65 20 69 66 20 63 6f 6c 75 6d  T: True if colum
2cff0 6e 20 70 61 72 74 20 6f 66 20 50 4b 20 2a 2f 0a  n part of PK */.
2d000 20 20 69 6e 74 20 2a 70 41 75 74 6f 69 6e 63 20    int *pAutoinc 
2d010 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
2d020 20 4f 55 54 50 55 54 3a 20 54 72 75 65 20 69 66   OUTPUT: True if
2d030 20 63 6f 6c 75 6d 6e 20 69 73 20 61 75 74 6f 2d   column is auto-
2d040 69 6e 63 72 65 6d 65 6e 74 20 2a 2f 0a 29 3b 0a  increment */.);.
2d050 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2d060 20 4c 6f 61 64 20 41 6e 20 45 78 74 65 6e 73 69   Load An Extensi
2d070 6f 6e 20 7b 48 31 32 36 30 30 7d 20 3c 53 32 30  on {H12600} <S20
2d080 35 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  500>.**.** This 
2d090 69 6e 74 65 72 66 61 63 65 20 6c 6f 61 64 73 20  interface loads 
2d0a0 61 6e 20 53 51 4c 69 74 65 20 65 78 74 65 6e 73  an SQLite extens
2d0b0 69 6f 6e 20 6c 69 62 72 61 72 79 20 66 72 6f 6d  ion library from
2d0c0 20 74 68 65 20 6e 61 6d 65 64 20 66 69 6c 65 2e   the named file.
2d0d0 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36 30 31 7d 20  .**.** {H12601} 
2d0e0 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 6f 61 64  The sqlite3_load
2d0f0 5f 65 78 74 65 6e 73 69 6f 6e 28 29 20 69 6e 74  _extension() int
2d100 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20  erface attempts 
2d110 74 6f 20 6c 6f 61 64 20 61 6e 0a 2a 2a 20 20 20  to load an.**   
2d120 20 20 20 20 20 20 20 53 51 4c 69 74 65 20 65 78         SQLite ex
2d130 74 65 6e 73 69 6f 6e 20 6c 69 62 72 61 72 79 20  tension library 
2d140 63 6f 6e 74 61 69 6e 65 64 20 69 6e 20 74 68 65  contained in the
2d150 20 66 69 6c 65 20 7a 46 69 6c 65 2e 0a 2a 2a 0a   file zFile..**.
2d160 2a 2a 20 7b 48 31 32 36 30 32 7d 20 54 68 65 20  ** {H12602} The 
2d170 65 6e 74 72 79 20 70 6f 69 6e 74 20 69 73 20 7a  entry point is z
2d180 50 72 6f 63 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  Proc..**.** {H12
2d190 36 30 33 7d 20 7a 50 72 6f 63 20 6d 61 79 20 62  603} zProc may b
2d1a0 65 20 30 2c 20 69 6e 20 77 68 69 63 68 20 63 61  e 0, in which ca
2d1b0 73 65 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  se the name of t
2d1c0 68 65 20 65 6e 74 72 79 20 70 6f 69 6e 74 0a 2a  he entry point.*
2d1d0 2a 20 20 20 20 20 20 20 20 20 20 64 65 66 61 75  *          defau
2d1e0 6c 74 73 20 74 6f 20 22 73 71 6c 69 74 65 33 5f  lts to "sqlite3_
2d1f0 65 78 74 65 6e 73 69 6f 6e 5f 69 6e 69 74 22 2e  extension_init".
2d200 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36 30 34 7d 20  .**.** {H12604} 
2d210 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 6f 61 64  The sqlite3_load
2d220 5f 65 78 74 65 6e 73 69 6f 6e 28 29 20 69 6e 74  _extension() int
2d230 65 72 66 61 63 65 20 73 68 61 6c 6c 20 72 65 74  erface shall ret
2d240 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  urn.**          
2d250 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73  [SQLITE_OK] on s
2d260 75 63 63 65 73 73 20 61 6e 64 20 5b 53 51 4c 49  uccess and [SQLI
2d270 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 73 6f 6d  TE_ERROR] if som
2d280 65 74 68 69 6e 67 20 67 6f 65 73 20 77 72 6f 6e  ething goes wron
2d290 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36 30 35  g..**.** {H12605
2d2a0 7d 20 49 66 20 61 6e 20 65 72 72 6f 72 20 6f 63  } If an error oc
2d2b0 63 75 72 73 20 61 6e 64 20 70 7a 45 72 72 4d 73  curs and pzErrMs
2d2c0 67 20 69 73 20 6e 6f 74 20 30 2c 20 74 68 65 6e  g is not 0, then
2d2d0 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
2d2e0 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65   [sqlite3_load_e
2d2f0 78 74 65 6e 73 69 6f 6e 28 29 5d 20 69 6e 74 65  xtension()] inte
2d300 72 66 61 63 65 20 73 68 61 6c 6c 20 61 74 74 65  rface shall atte
2d310 6d 70 74 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20  mpt to.**       
2d320 20 20 20 66 69 6c 6c 20 2a 70 7a 45 72 72 4d 73     fill *pzErrMs
2d330 67 20 77 69 74 68 20 65 72 72 6f 72 20 6d 65 73  g with error mes
2d340 73 61 67 65 20 74 65 78 74 20 73 74 6f 72 65 64  sage text stored
2d350 20 69 6e 20 6d 65 6d 6f 72 79 0a 2a 2a 20 20 20   in memory.**   
2d360 20 20 20 20 20 20 20 6f 62 74 61 69 6e 65 64 20         obtained 
2d370 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61  from [sqlite3_ma
2d380 6c 6c 6f 63 28 29 5d 2e 20 7b 45 4e 44 7d 20 20  lloc()]. {END}  
2d390 54 68 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63  The calling func
2d3a0 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  tion.**         
2d3b0 20 73 68 6f 75 6c 64 20 66 72 65 65 20 74 68 69   should free thi
2d3c0 73 20 6d 65 6d 6f 72 79 20 62 79 20 63 61 6c 6c  s memory by call
2d3d0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  ing [sqlite3_fre
2d3e0 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  e()]..**.** {H12
2d3f0 36 30 36 7d 20 45 78 74 65 6e 73 69 6f 6e 20 6c  606} Extension l
2d400 6f 61 64 69 6e 67 20 6d 75 73 74 20 62 65 20 65  oading must be e
2d410 6e 61 62 6c 65 64 20 75 73 69 6e 67 0a 2a 2a 20  nabled using.** 
2d420 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
2d430 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65 78  3_enable_load_ex
2d440 74 65 6e 73 69 6f 6e 28 29 5d 20 70 72 69 6f 72  tension()] prior
2d450 20 74 6f 20 63 61 6c 6c 69 6e 67 20 74 68 69 73   to calling this
2d460 20 41 50 49 2c 0a 2a 2a 20 20 20 20 20 20 20 20   API,.**        
2d470 20 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20 65    otherwise an e
2d480 72 72 6f 72 20 77 69 6c 6c 20 62 65 20 72 65 74  rror will be ret
2d490 75 72 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71  urned..*/.int sq
2d4a0 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e  lite3_load_exten
2d4b0 73 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 20  sion(.  sqlite3 
2d4c0 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 2f 2a  *db,          /*
2d4d0 20 4c 6f 61 64 20 74 68 65 20 65 78 74 65 6e 73   Load the extens
2d4e0 69 6f 6e 20 69 6e 74 6f 20 74 68 69 73 20 64 61  ion into this da
2d4f0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2d500 6e 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  n */.  const cha
2d510 72 20 2a 7a 46 69 6c 65 2c 20 20 20 20 2f 2a 20  r *zFile,    /* 
2d520 4e 61 6d 65 20 6f 66 20 74 68 65 20 73 68 61 72  Name of the shar
2d530 65 64 20 6c 69 62 72 61 72 79 20 63 6f 6e 74 61  ed library conta
2d540 69 6e 69 6e 67 20 65 78 74 65 6e 73 69 6f 6e 20  ining extension 
2d550 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
2d560 2a 7a 50 72 6f 63 2c 20 20 20 20 2f 2a 20 45 6e  *zProc,    /* En
2d570 74 72 79 20 70 6f 69 6e 74 2e 20 20 44 65 72 69  try point.  Deri
2d580 76 65 64 20 66 72 6f 6d 20 7a 46 69 6c 65 20 69  ved from zFile i
2d590 66 20 30 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a  f 0 */.  char **
2d5a0 70 7a 45 72 72 4d 73 67 20 20 20 20 20 20 20 2f  pzErrMsg       /
2d5b0 2a 20 50 75 74 20 65 72 72 6f 72 20 6d 65 73 73  * Put error mess
2d5c0 61 67 65 20 68 65 72 65 20 69 66 20 6e 6f 74 20  age here if not 
2d5d0 30 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  0 */.);../*.** C
2d5e0 41 50 49 33 52 45 46 3a 20 45 6e 61 62 6c 65 20  API3REF: Enable 
2d5f0 4f 72 20 44 69 73 61 62 6c 65 20 45 78 74 65 6e  Or Disable Exten
2d600 73 69 6f 6e 20 4c 6f 61 64 69 6e 67 20 7b 48 31  sion Loading {H1
2d610 32 36 32 30 7d 20 3c 53 32 30 35 30 30 3e 0a 2a  2620} <S20500>.*
2d620 2a 0a 2a 2a 20 53 6f 20 61 73 20 6e 6f 74 20 74  *.** So as not t
2d630 6f 20 6f 70 65 6e 20 73 65 63 75 72 69 74 79 20  o open security 
2d640 68 6f 6c 65 73 20 69 6e 20 6f 6c 64 65 72 20 61  holes in older a
2d650 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74  pplications that
2d660 20 61 72 65 0a 2a 2a 20 75 6e 70 72 65 70 61 72   are.** unprepar
2d670 65 64 20 74 6f 20 64 65 61 6c 20 77 69 74 68 20  ed to deal with 
2d680 65 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e  extension loadin
2d690 67 2c 20 61 6e 64 20 61 73 20 61 20 6d 65 61 6e  g, and as a mean
2d6a0 73 20 6f 66 20 64 69 73 61 62 6c 69 6e 67 0a 2a  s of disabling.*
2d6b0 2a 20 65 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64  * extension load
2d6c0 69 6e 67 20 77 68 69 6c 65 20 65 76 61 6c 75 61  ing while evalua
2d6d0 74 69 6e 67 20 75 73 65 72 2d 65 6e 74 65 72 65  ting user-entere
2d6e0 64 20 53 51 4c 2c 20 74 68 65 20 66 6f 6c 6c 6f  d SQL, the follo
2d6f0 77 69 6e 67 20 41 50 49 0a 2a 2a 20 69 73 20 70  wing API.** is p
2d700 72 6f 76 69 64 65 64 20 74 6f 20 74 75 72 6e 20  rovided to turn 
2d710 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 61  the [sqlite3_loa
2d720 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 6d  d_extension()] m
2d730 65 63 68 61 6e 69 73 6d 20 6f 6e 20 61 6e 64 20  echanism on and 
2d740 6f 66 66 2e 0a 2a 2a 0a 2a 2a 20 45 78 74 65 6e  off..**.** Exten
2d750 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 69 73 20  sion loading is 
2d760 6f 66 66 20 62 79 20 64 65 66 61 75 6c 74 2e 20  off by default. 
2d770 53 65 65 20 74 69 63 6b 65 74 20 23 31 38 36 33  See ticket #1863
2d780 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36 32 31 7d  ..**.** {H12621}
2d790 20 43 61 6c 6c 20 74 68 65 20 73 71 6c 69 74 65   Call the sqlite
2d7a0 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65 78  3_enable_load_ex
2d7b0 74 65 6e 73 69 6f 6e 28 29 20 72 6f 75 74 69 6e  tension() routin
2d7c0 65 20 77 69 74 68 20 6f 6e 6f 66 66 3d 3d 31 0a  e with onoff==1.
2d7d0 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20 74  **          to t
2d7e0 75 72 6e 20 65 78 74 65 6e 73 69 6f 6e 20 6c 6f  urn extension lo
2d7f0 61 64 69 6e 67 20 6f 6e 20 61 6e 64 20 63 61 6c  ading on and cal
2d800 6c 20 69 74 20 77 69 74 68 20 6f 6e 6f 66 66 3d  l it with onoff=
2d810 3d 30 20 74 6f 20 74 75 72 6e 0a 2a 2a 20 20 20  =0 to turn.**   
2d820 20 20 20 20 20 20 20 69 74 20 62 61 63 6b 20 6f         it back o
2d830 66 66 20 61 67 61 69 6e 2e 0a 2a 2a 0a 2a 2a 20  ff again..**.** 
2d840 7b 48 31 32 36 32 32 7d 20 45 78 74 65 6e 73 69  {H12622} Extensi
2d850 6f 6e 20 6c 6f 61 64 69 6e 67 20 69 73 20 6f 66  on loading is of
2d860 66 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2f  f by default..*/
2d870 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 6e 61  .int sqlite3_ena
2d880 62 6c 65 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69  ble_load_extensi
2d890 6f 6e 28 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  on(sqlite3 *db, 
2d8a0 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a  int onoff);../*.
2d8b0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75 74  ** CAPI3REF: Aut
2d8c0 6f 6d 61 74 69 63 61 6c 6c 79 20 4c 6f 61 64 20  omatically Load 
2d8d0 41 6e 20 45 78 74 65 6e 73 69 6f 6e 73 20 7b 48  An Extensions {H
2d8e0 31 32 36 34 30 7d 20 3c 53 32 30 35 30 30 3e 0a  12640} <S20500>.
2d8f0 2a 2a 0a 2a 2a 20 54 68 69 73 20 41 50 49 20 63  **.** This API c
2d900 61 6e 20 62 65 20 69 6e 76 6f 6b 65 64 20 61 74  an be invoked at
2d910 20 70 72 6f 67 72 61 6d 20 73 74 61 72 74 75 70   program startup
2d920 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 72 65 67   in order to reg
2d930 69 73 74 65 72 0a 2a 2a 20 6f 6e 65 20 6f 72 20  ister.** one or 
2d940 6d 6f 72 65 20 73 74 61 74 69 63 61 6c 6c 79 20  more statically 
2d950 6c 69 6e 6b 65 64 20 65 78 74 65 6e 73 69 6f 6e  linked extension
2d960 73 20 74 68 61 74 20 77 69 6c 6c 20 62 65 20 61  s that will be a
2d970 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 74 6f 20 61  vailable.** to a
2d980 6c 6c 20 6e 65 77 20 5b 64 61 74 61 62 61 73 65  ll new [database
2d990 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 2e 20 7b   connections]. {
2d9a0 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  END}.**.** This 
2d9b0 72 6f 75 74 69 6e 65 20 73 74 6f 72 65 73 20 61  routine stores a
2d9c0 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
2d9d0 65 78 74 65 6e 73 69 6f 6e 20 69 6e 20 61 6e 20  extension in an 
2d9e0 61 72 72 61 79 20 74 68 61 74 20 69 73 0a 2a 2a  array that is.**
2d9f0 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b   obtained from [
2da00 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
2da10 5d 2e 20 20 49 66 20 79 6f 75 20 72 75 6e 20 61  ].  If you run a
2da20 20 6d 65 6d 6f 72 79 20 6c 65 61 6b 20 63 68 65   memory leak che
2da30 63 6b 65 72 0a 2a 2a 20 6f 6e 20 79 6f 75 72 20  cker.** on your 
2da40 70 72 6f 67 72 61 6d 20 61 6e 64 20 69 74 20 72  program and it r
2da50 65 70 6f 72 74 73 20 61 20 6c 65 61 6b 20 62 65  eports a leak be
2da60 63 61 75 73 65 20 6f 66 20 74 68 69 73 20 61 72  cause of this ar
2da70 72 61 79 2c 20 69 6e 76 6f 6b 65 0a 2a 2a 20 5b  ray, invoke.** [
2da80 73 71 6c 69 74 65 33 5f 72 65 73 65 74 5f 61 75  sqlite3_reset_au
2da90 74 6f 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20  to_extension()] 
2daa0 70 72 69 6f 72 20 74 6f 20 73 68 75 74 64 6f 77  prior to shutdow
2dab0 6e 20 74 6f 20 66 72 65 65 20 74 68 65 20 6d 65  n to free the me
2dac0 6d 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  mory..**.** {H12
2dad0 36 34 31 7d 20 54 68 69 73 20 66 75 6e 63 74 69  641} This functi
2dae0 6f 6e 20 72 65 67 69 73 74 65 72 73 20 61 6e 20  on registers an 
2daf0 65 78 74 65 6e 73 69 6f 6e 20 65 6e 74 72 79 20  extension entry 
2db00 70 6f 69 6e 74 20 74 68 61 74 20 69 73 0a 2a 2a  point that is.**
2db10 20 20 20 20 20 20 20 20 20 20 61 75 74 6f 6d 61            automa
2db20 74 69 63 61 6c 6c 79 20 69 6e 76 6f 6b 65 64 20  tically invoked 
2db30 77 68 65 6e 65 76 65 72 20 61 20 6e 65 77 20 5b  whenever a new [
2db40 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2db50 69 6f 6e 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  ion].**         
2db60 20 69 73 20 6f 70 65 6e 65 64 20 75 73 69 6e 67   is opened using
2db70 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
2db80 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ], [sqlite3_open
2db90 31 36 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20  16()],.**       
2dba0 20 20 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f     or [sqlite3_o
2dbb0 70 65 6e 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a  pen_v2()]..**.**
2dbc0 20 7b 48 31 32 36 34 32 7d 20 44 75 70 6c 69 63   {H12642} Duplic
2dbd0 61 74 65 20 65 78 74 65 6e 73 69 6f 6e 73 20 61  ate extensions a
2dbe0 72 65 20 64 65 74 65 63 74 65 64 20 73 6f 20 63  re detected so c
2dbf0 61 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f 75 74  alling this rout
2dc00 69 6e 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ine.**          
2dc10 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 77  multiple times w
2dc20 69 74 68 20 74 68 65 20 73 61 6d 65 20 65 78 74  ith the same ext
2dc30 65 6e 73 69 6f 6e 20 69 73 20 68 61 72 6d 6c 65  ension is harmle
2dc40 73 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36 34  ss..**.** {H1264
2dc50 33 7d 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  3} This routine 
2dc60 73 74 6f 72 65 73 20 61 20 70 6f 69 6e 74 65 72  stores a pointer
2dc70 20 74 6f 20 74 68 65 20 65 78 74 65 6e 73 69 6f   to the extensio
2dc80 6e 20 69 6e 20 61 6e 20 61 72 72 61 79 0a 2a 2a  n in an array.**
2dc90 20 20 20 20 20 20 20 20 20 20 74 68 61 74 20 69            that i
2dca0 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  s obtained from 
2dcb0 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
2dcc0 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36 34  )]..**.** {H1264
2dcd0 34 7d 20 41 75 74 6f 6d 61 74 69 63 20 65 78 74  4} Automatic ext
2dce0 65 6e 73 69 6f 6e 73 20 61 70 70 6c 79 20 61 63  ensions apply ac
2dcf0 72 6f 73 73 20 61 6c 6c 20 74 68 72 65 61 64 73  ross all threads
2dd00 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
2dd10 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e 28  _auto_extension(
2dd20 76 6f 69 64 20 28 2a 78 45 6e 74 72 79 50 6f 69  void (*xEntryPoi
2dd30 6e 74 29 28 76 6f 69 64 29 29 3b 0a 0a 2f 2a 0a  nt)(void));../*.
2dd40 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73  ** CAPI3REF: Res
2dd50 65 74 20 41 75 74 6f 6d 61 74 69 63 20 45 78 74  et Automatic Ext
2dd60 65 6e 73 69 6f 6e 20 4c 6f 61 64 69 6e 67 20 7b  ension Loading {
2dd70 48 31 32 36 36 30 7d 20 3c 53 32 30 35 30 30 3e  H12660} <S20500>
2dd80 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63  .**.** This func
2dd90 74 69 6f 6e 20 64 69 73 61 62 6c 65 73 20 61 6c  tion disables al
2dda0 6c 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 67  l previously reg
2ddb0 69 73 74 65 72 65 64 20 61 75 74 6f 6d 61 74 69  istered automati
2ddc0 63 0a 2a 2a 20 65 78 74 65 6e 73 69 6f 6e 73 2e  c.** extensions.
2ddd0 20 7b 45 4e 44 7d 20 20 49 74 20 75 6e 64 6f 65   {END}  It undoe
2dde0 73 20 74 68 65 20 65 66 66 65 63 74 20 6f 66 20  s the effect of 
2ddf0 61 6c 6c 20 70 72 69 6f 72 0a 2a 2a 20 5b 73 71  all prior.** [sq
2de00 6c 69 74 65 33 5f 61 75 74 6f 5f 65 78 74 65 6e  lite3_auto_exten
2de10 73 69 6f 6e 28 29 5d 20 63 61 6c 6c 73 2e 0a 2a  sion()] calls..*
2de20 2a 0a 2a 2a 20 7b 48 31 32 36 36 31 7d 20 54 68  *.** {H12661} Th
2de30 69 73 20 66 75 6e 63 74 69 6f 6e 20 64 69 73 61  is function disa
2de40 62 6c 65 73 20 61 6c 6c 20 70 72 65 76 69 6f 75  bles all previou
2de50 73 6c 79 20 72 65 67 69 73 74 65 72 65 64 0a 2a  sly registered.*
2de60 2a 20 20 20 20 20 20 20 20 20 20 61 75 74 6f 6d  *          autom
2de70 61 74 69 63 20 65 78 74 65 6e 73 69 6f 6e 73 2e  atic extensions.
2de80 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36 36 32 7d 20  .**.** {H12662} 
2de90 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 64 69  This function di
2dea0 73 61 62 6c 65 73 20 61 75 74 6f 6d 61 74 69 63  sables automatic
2deb0 20 65 78 74 65 6e 73 69 6f 6e 73 20 69 6e 20 61   extensions in a
2dec0 6c 6c 20 74 68 72 65 61 64 73 2e 0a 2a 2f 0a 76  ll threads..*/.v
2ded0 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 65  oid sqlite3_rese
2dee0 74 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e  t_auto_extension
2def0 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 2a 2a  (void);../*.****
2df00 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 20  ** EXPERIMENTAL 
2df10 2d 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61  - subject to cha
2df20 6e 67 65 20 77 69 74 68 6f 75 74 20 6e 6f 74 69  nge without noti
2df30 63 65 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ce *************
2df40 2a 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 74 65  *.**.** The inte
2df50 72 66 61 63 65 20 74 6f 20 74 68 65 20 76 69 72  rface to the vir
2df60 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65 63 68 61  tual-table mecha
2df70 6e 69 73 6d 20 69 73 20 63 75 72 72 65 6e 74 6c  nism is currentl
2df80 79 20 63 6f 6e 73 69 64 65 72 65 64 0a 2a 2a 20  y considered.** 
2df90 74 6f 20 62 65 20 65 78 70 65 72 69 6d 65 6e 74  to be experiment
2dfa0 61 6c 2e 20 20 54 68 65 20 69 6e 74 65 72 66 61  al.  The interfa
2dfb0 63 65 20 6d 69 67 68 74 20 63 68 61 6e 67 65 20  ce might change 
2dfc0 69 6e 20 69 6e 63 6f 6d 70 61 74 69 62 6c 65 20  in incompatible 
2dfd0 77 61 79 73 2e 0a 2a 2a 20 49 66 20 74 68 69 73  ways..** If this
2dfe0 20 69 73 20 61 20 70 72 6f 62 6c 65 6d 20 66 6f   is a problem fo
2dff0 72 20 79 6f 75 2c 20 64 6f 20 6e 6f 74 20 75 73  r you, do not us
2e000 65 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 20  e the interface 
2e010 61 74 20 74 68 69 73 20 74 69 6d 65 2e 0a 2a 2a  at this time..**
2e020 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 76 69 72  .** When the vir
2e030 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65 63 68 61  tual-table mecha
2e040 6e 69 73 6d 20 73 74 61 62 69 6c 69 7a 65 73 2c  nism stabilizes,
2e050 20 77 65 20 77 69 6c 6c 20 64 65 63 6c 61 72 65   we will declare
2e060 20 74 68 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63   the.** interfac
2e070 65 20 66 69 78 65 64 2c 20 73 75 70 70 6f 72 74  e fixed, support
2e080 20 69 74 20 69 6e 64 65 66 69 6e 69 74 65 6c 79   it indefinitely
2e090 2c 20 61 6e 64 20 72 65 6d 6f 76 65 20 74 68 69  , and remove thi
2e0a0 73 20 63 6f 6d 6d 65 6e 74 2e 0a 2a 2f 0a 0a 2f  s comment..*/../
2e0b0 2a 0a 2a 2a 20 53 74 72 75 63 74 75 72 65 73 20  *.** Structures 
2e0c0 75 73 65 64 20 62 79 20 74 68 65 20 76 69 72 74  used by the virt
2e0d0 75 61 6c 20 74 61 62 6c 65 20 69 6e 74 65 72 66  ual table interf
2e0e0 61 63 65 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  ace.*/.typedef s
2e0f0 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 74  truct sqlite3_vt
2e100 61 62 20 73 71 6c 69 74 65 33 5f 76 74 61 62 3b  ab sqlite3_vtab;
2e110 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
2e120 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e  sqlite3_index_in
2e130 66 6f 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78  fo sqlite3_index
2e140 5f 69 6e 66 6f 3b 0a 74 79 70 65 64 65 66 20 73  _info;.typedef s
2e150 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 74  truct sqlite3_vt
2e160 61 62 5f 63 75 72 73 6f 72 20 73 71 6c 69 74 65  ab_cursor sqlite
2e170 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 3b 0a 74  3_vtab_cursor;.t
2e180 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
2e190 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20 73 71 6c  lite3_module sql
2e1a0 69 74 65 33 5f 6d 6f 64 75 6c 65 3b 0a 0a 2f 2a  ite3_module;../*
2e1b0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 56 69  .** CAPI3REF: Vi
2e1c0 72 74 75 61 6c 20 54 61 62 6c 65 20 4f 62 6a 65  rtual Table Obje
2e1d0 63 74 20 7b 48 31 38 30 30 30 7d 20 3c 53 32 30  ct {H18000} <S20
2e1e0 34 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  400>.** KEYWORDS
2e1f0 3a 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65  : sqlite3_module
2e200 20 7b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20   {virtual table 
2e210 6d 6f 64 75 6c 65 7d 0a 2a 2a 20 45 58 50 45 52  module}.** EXPER
2e220 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68  IMENTAL.**.** Th
2e230 69 73 20 73 74 72 75 63 74 75 72 65 2c 20 73 6f  is structure, so
2e240 6d 65 74 69 6d 65 73 20 63 61 6c 6c 65 64 20 61  metimes called a
2e250 20 61 20 22 76 69 72 74 75 61 6c 20 74 61 62 6c   a "virtual tabl
2e260 65 20 6d 6f 64 75 6c 65 22 2c 20 0a 2a 2a 20 64  e module", .** d
2e270 65 66 69 6e 65 73 20 74 68 65 20 69 6d 70 6c 65  efines the imple
2e280 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 20 5b  mentation of a [
2e290 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 5d 2e  virtual tables].
2e2a0 20 20 0a 2a 2a 20 54 68 69 73 20 73 74 72 75 63    .** This struc
2e2b0 74 75 72 65 20 63 6f 6e 73 69 73 74 73 20 6d 6f  ture consists mo
2e2c0 73 74 6c 79 20 6f 66 20 6d 65 74 68 6f 64 73 20  stly of methods 
2e2d0 66 6f 72 20 74 68 65 20 6d 6f 64 75 6c 65 2e 0a  for the module..
2e2e0 2a 2a 0a 2a 2a 20 41 20 76 69 72 74 75 61 6c 20  **.** A virtual 
2e2f0 74 61 62 6c 65 20 6d 6f 64 75 6c 65 20 69 73 20  table module is 
2e300 63 72 65 61 74 65 64 20 62 79 20 66 69 6c 6c 69  created by filli
2e310 6e 67 20 69 6e 20 61 20 70 65 72 73 69 73 74 65  ng in a persiste
2e320 6e 74 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f  nt.** instance o
2e330 66 20 74 68 69 73 20 73 74 72 75 63 74 75 72 65  f this structure
2e340 20 61 6e 64 20 70 61 73 73 69 6e 67 20 61 20 70   and passing a p
2e350 6f 69 6e 74 65 72 20 74 6f 20 74 68 61 74 20 69  ointer to that i
2e360 6e 73 74 61 6e 63 65 0a 2a 2a 20 74 6f 20 5b 73  nstance.** to [s
2e370 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f  qlite3_create_mo
2e380 64 75 6c 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69  dule()] or [sqli
2e390 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c  te3_create_modul
2e3a0 65 5f 76 32 28 29 5d 2e 0a 2a 2a 20 54 68 65 20  e_v2()]..** The 
2e3b0 72 65 67 69 73 74 72 61 74 69 6f 6e 20 72 65 6d  registration rem
2e3c0 61 69 6e 73 20 76 61 6c 69 64 20 75 6e 74 69 6c  ains valid until
2e3d0 20 69 74 20 69 73 20 72 65 70 6c 61 63 65 64 20   it is replaced 
2e3e0 62 79 20 61 20 64 69 66 66 65 72 65 6e 74 0a 2a  by a different.*
2e3f0 2a 20 6d 6f 64 75 6c 65 20 6f 72 20 75 6e 74 69  * module or unti
2e400 6c 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  l the [database 
2e410 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 63 6c 6f 73  connection] clos
2e420 65 73 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74  es.  The content
2e430 0a 2a 2a 20 6f 66 20 74 68 69 73 20 73 74 72 75  .** of this stru
2e440 63 74 75 72 65 20 6d 75 73 74 20 6e 6f 74 20 63  cture must not c
2e450 68 61 6e 67 65 20 77 68 69 6c 65 20 69 74 20 69  hange while it i
2e460 73 20 72 65 67 69 73 74 65 72 65 64 20 77 69 74  s registered wit
2e470 68 0a 2a 2a 20 61 6e 79 20 64 61 74 61 62 61 73  h.** any databas
2e480 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 0a 2a 2f  e connection..*/
2e490 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f  .struct sqlite3_
2e4a0 6d 6f 64 75 6c 65 20 7b 0a 20 20 69 6e 74 20 69  module {.  int i
2e4b0 56 65 72 73 69 6f 6e 3b 0a 20 20 69 6e 74 20 28  Version;.  int (
2e4c0 2a 78 43 72 65 61 74 65 29 28 73 71 6c 69 74 65  *xCreate)(sqlite
2e4d0 33 2a 2c 20 76 6f 69 64 20 2a 70 41 75 78 2c 0a  3*, void *pAux,.
2e4e0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 69                 i
2e4f0 6e 74 20 61 72 67 63 2c 20 63 6f 6e 73 74 20 63  nt argc, const c
2e500 68 61 72 20 2a 63 6f 6e 73 74 2a 61 72 67 76 2c  har *const*argv,
2e510 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  .               
2e520 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 2a 70  sqlite3_vtab **p
2e530 70 56 54 61 62 2c 20 63 68 61 72 2a 2a 29 3b 0a  pVTab, char**);.
2e540 20 20 69 6e 74 20 28 2a 78 43 6f 6e 6e 65 63 74    int (*xConnect
2e550 29 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64  )(sqlite3*, void
2e560 20 2a 70 41 75 78 2c 0a 20 20 20 20 20 20 20 20   *pAux,.        
2e570 20 20 20 20 20 20 20 69 6e 74 20 61 72 67 63 2c         int argc,
2e580 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 63 6f 6e   const char *con
2e590 73 74 2a 61 72 67 76 2c 0a 20 20 20 20 20 20 20  st*argv,.       
2e5a0 20 20 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f          sqlite3_
2e5b0 76 74 61 62 20 2a 2a 70 70 56 54 61 62 2c 20 63  vtab **ppVTab, c
2e5c0 68 61 72 2a 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  har**);.  int (*
2e5d0 78 42 65 73 74 49 6e 64 65 78 29 28 73 71 6c 69  xBestIndex)(sqli
2e5e0 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 2c  te3_vtab *pVTab,
2e5f0 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69   sqlite3_index_i
2e600 6e 66 6f 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  nfo*);.  int (*x
2e610 44 69 73 63 6f 6e 6e 65 63 74 29 28 73 71 6c 69  Disconnect)(sqli
2e620 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 29  te3_vtab *pVTab)
2e630 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 73 74 72  ;.  int (*xDestr
2e640 6f 79 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62  oy)(sqlite3_vtab
2e650 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74 20   *pVTab);.  int 
2e660 28 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74 65 33  (*xOpen)(sqlite3
2e670 5f 76 74 61 62 20 2a 70 56 54 61 62 2c 20 73 71  _vtab *pVTab, sq
2e680 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f  lite3_vtab_curso
2e690 72 20 2a 2a 70 70 43 75 72 73 6f 72 29 3b 0a 20  r **ppCursor);. 
2e6a0 20 69 6e 74 20 28 2a 78 43 6c 6f 73 65 29 28 73   int (*xClose)(s
2e6b0 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73  qlite3_vtab_curs
2e6c0 6f 72 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46  or*);.  int (*xF
2e6d0 69 6c 74 65 72 29 28 73 71 6c 69 74 65 33 5f 76  ilter)(sqlite3_v
2e6e0 74 61 62 5f 63 75 72 73 6f 72 2a 2c 20 69 6e 74  tab_cursor*, int
2e6f0 20 69 64 78 4e 75 6d 2c 20 63 6f 6e 73 74 20 63   idxNum, const c
2e700 68 61 72 20 2a 69 64 78 53 74 72 2c 0a 20 20 20  har *idxStr,.   
2e710 20 20 20 20 20 20 20 20 20 20 20 20 20 69 6e 74               int
2e720 20 61 72 67 63 2c 20 73 71 6c 69 74 65 33 5f 76   argc, sqlite3_v
2e730 61 6c 75 65 20 2a 2a 61 72 67 76 29 3b 0a 20 20  alue **argv);.  
2e740 69 6e 74 20 28 2a 78 4e 65 78 74 29 28 73 71 6c  int (*xNext)(sql
2e750 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72  ite3_vtab_cursor
2e760 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 45 6f 66  *);.  int (*xEof
2e770 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63  )(sqlite3_vtab_c
2e780 75 72 73 6f 72 2a 29 3b 0a 20 20 69 6e 74 20 28  ursor*);.  int (
2e790 2a 78 43 6f 6c 75 6d 6e 29 28 73 71 6c 69 74 65  *xColumn)(sqlite
2e7a0 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 2c 20  3_vtab_cursor*, 
2e7b0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
2e7c0 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a  , int);.  int (*
2e7d0 78 52 6f 77 69 64 29 28 73 71 6c 69 74 65 33 5f  xRowid)(sqlite3_
2e7e0 76 74 61 62 5f 63 75 72 73 6f 72 2a 2c 20 73 71  vtab_cursor*, sq
2e7f0 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 70 52 6f  lite3_int64 *pRo
2e800 77 69 64 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55  wid);.  int (*xU
2e810 70 64 61 74 65 29 28 73 71 6c 69 74 65 33 5f 76  pdate)(sqlite3_v
2e820 74 61 62 20 2a 2c 20 69 6e 74 2c 20 73 71 6c 69  tab *, int, sqli
2e830 74 65 33 5f 76 61 6c 75 65 20 2a 2a 2c 20 73 71  te3_value **, sq
2e840 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 29 3b 0a  lite3_int64 *);.
2e850 20 20 69 6e 74 20 28 2a 78 42 65 67 69 6e 29 28    int (*xBegin)(
2e860 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56  sqlite3_vtab *pV
2e870 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53  Tab);.  int (*xS
2e880 79 6e 63 29 28 73 71 6c 69 74 65 33 5f 76 74 61  ync)(sqlite3_vta
2e890 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74  b *pVTab);.  int
2e8a0 20 28 2a 78 43 6f 6d 6d 69 74 29 28 73 71 6c 69   (*xCommit)(sqli
2e8b0 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 29  te3_vtab *pVTab)
2e8c0 3b 0a 20 20 69 6e 74 20 28 2a 78 52 6f 6c 6c 62  ;.  int (*xRollb
2e8d0 61 63 6b 29 28 73 71 6c 69 74 65 33 5f 76 74 61  ack)(sqlite3_vta
2e8e0 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74  b *pVTab);.  int
2e8f0 20 28 2a 78 46 69 6e 64 46 75 6e 63 74 69 6f 6e   (*xFindFunction
2e900 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a  )(sqlite3_vtab *
2e910 70 56 74 61 62 2c 20 69 6e 74 20 6e 41 72 67 2c  pVtab, int nArg,
2e920 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
2e930 6d 65 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20  me,.            
2e940 20 20 20 20 20 20 20 20 20 20 20 76 6f 69 64 20             void 
2e950 28 2a 2a 70 78 46 75 6e 63 29 28 73 71 6c 69 74  (**pxFunc)(sqlit
2e960 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c  e3_context*,int,
2e970 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29  sqlite3_value**)
2e980 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,.              
2e990 20 20 20 20 20 20 20 20 20 76 6f 69 64 20 2a 2a           void **
2e9a0 70 70 41 72 67 29 3b 0a 20 20 69 6e 74 20 28 2a  ppArg);.  int (*
2e9b0 78 52 65 6e 61 6d 65 29 28 73 71 6c 69 74 65 33  xRename)(sqlite3
2e9c0 5f 76 74 61 62 20 2a 70 56 74 61 62 2c 20 63 6f  _vtab *pVtab, co
2e9d0 6e 73 74 20 63 68 61 72 20 2a 7a 4e 65 77 29 3b  nst char *zNew);
2e9e0 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .};../*.** CAPI3
2e9f0 52 45 46 3a 20 56 69 72 74 75 61 6c 20 54 61 62  REF: Virtual Tab
2ea00 6c 65 20 49 6e 64 65 78 69 6e 67 20 49 6e 66 6f  le Indexing Info
2ea10 72 6d 61 74 69 6f 6e 20 7b 48 31 38 31 30 30 7d  rmation {H18100}
2ea20 20 3c 53 32 30 34 30 30 3e 0a 2a 2a 20 4b 45 59   <S20400>.** KEY
2ea30 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 69  WORDS: sqlite3_i
2ea40 6e 64 65 78 5f 69 6e 66 6f 0a 2a 2a 20 45 58 50  ndex_info.** EXP
2ea50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20  ERIMENTAL.**.** 
2ea60 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 64 65  The sqlite3_inde
2ea70 78 5f 69 6e 66 6f 20 73 74 72 75 63 74 75 72 65  x_info structure
2ea80 20 61 6e 64 20 69 74 73 20 73 75 62 73 74 72 75   and its substru
2ea90 63 74 75 72 65 73 20 69 73 20 75 73 65 64 20 74  ctures is used t
2eaa0 6f 0a 2a 2a 20 70 61 73 73 20 69 6e 66 6f 72 6d  o.** pass inform
2eab0 61 74 69 6f 6e 20 69 6e 74 6f 20 61 6e 64 20 72  ation into and r
2eac0 65 63 65 69 76 65 20 74 68 65 20 72 65 70 6c 79  eceive the reply
2ead0 20 66 72 6f 6d 20 74 68 65 20 5b 78 42 65 73 74   from the [xBest
2eae0 49 6e 64 65 78 5d 0a 2a 2a 20 6d 65 74 68 6f 64  Index].** method
2eaf0 20 6f 66 20 61 20 5b 76 69 72 74 75 61 6c 20 74   of a [virtual t
2eb00 61 62 6c 65 20 6d 6f 64 75 6c 65 5d 2e 20 20 54  able module].  T
2eb10 68 65 20 66 69 65 6c 64 73 20 75 6e 64 65 72 20  he fields under 
2eb20 2a 2a 49 6e 70 75 74 73 2a 2a 20 61 72 65 20 74  **Inputs** are t
2eb30 68 65 0a 2a 2a 20 69 6e 70 75 74 73 20 74 6f 20  he.** inputs to 
2eb40 78 42 65 73 74 49 6e 64 65 78 20 61 6e 64 20 61  xBestIndex and a
2eb50 72 65 20 72 65 61 64 2d 6f 6e 6c 79 2e 20 20 78  re read-only.  x
2eb60 42 65 73 74 49 6e 64 65 78 20 69 6e 73 65 72 74  BestIndex insert
2eb70 73 20 69 74 73 0a 2a 2a 20 72 65 73 75 6c 74 73  s its.** results
2eb80 20 69 6e 74 6f 20 74 68 65 20 2a 2a 4f 75 74 70   into the **Outp
2eb90 75 74 73 2a 2a 20 66 69 65 6c 64 73 2e 0a 2a 2a  uts** fields..**
2eba0 0a 2a 2a 20 54 68 65 20 61 43 6f 6e 73 74 72 61  .** The aConstra
2ebb0 69 6e 74 5b 5d 20 61 72 72 61 79 20 72 65 63 6f  int[] array reco
2ebc0 72 64 73 20 57 48 45 52 45 20 63 6c 61 75 73 65  rds WHERE clause
2ebd0 20 63 6f 6e 73 74 72 61 69 6e 74 73 20 6f 66 20   constraints of 
2ebe0 74 68 65 20 66 6f 72 6d 3a 0a 2a 2a 0a 2a 2a 20  the form:.**.** 
2ebf0 3c 70 72 65 3e 63 6f 6c 75 6d 6e 20 4f 50 20 65  <pre>column OP e
2ec00 78 70 72 3c 2f 70 72 65 3e 0a 2a 2a 0a 2a 2a 20  xpr</pre>.**.** 
2ec10 77 68 65 72 65 20 4f 50 20 69 73 20 3d 2c 20 26  where OP is =, &
2ec20 6c 74 3b 2c 20 26 6c 74 3b 3d 2c 20 26 67 74 3b  lt;, &lt;=, &gt;
2ec30 2c 20 6f 72 20 26 67 74 3b 3d 2e 20 20 54 68 65  , or &gt;=.  The
2ec40 20 70 61 72 74 69 63 75 6c 61 72 20 6f 70 65 72   particular oper
2ec50 61 74 6f 72 20 69 73 0a 2a 2a 20 73 74 6f 72 65  ator is.** store
2ec60 64 20 69 6e 20 61 43 6f 6e 73 74 72 61 69 6e 74  d in aConstraint
2ec70 5b 5d 2e 6f 70 2e 20 20 54 68 65 20 69 6e 64 65  [].op.  The inde
2ec80 78 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20  x of the column 
2ec90 69 73 20 73 74 6f 72 65 64 20 69 6e 0a 2a 2a 20  is stored in.** 
2eca0 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 2e 69 43  aConstraint[].iC
2ecb0 6f 6c 75 6d 6e 2e 20 20 61 43 6f 6e 73 74 72 61  olumn.  aConstra
2ecc0 69 6e 74 5b 5d 2e 75 73 61 62 6c 65 20 69 73 20  int[].usable is 
2ecd0 54 52 55 45 20 69 66 20 74 68 65 0a 2a 2a 20 65  TRUE if the.** e
2ece0 78 70 72 20 6f 6e 20 74 68 65 20 72 69 67 68 74  xpr on the right
2ecf0 2d 68 61 6e 64 20 73 69 64 65 20 63 61 6e 20 62  -hand side can b
2ed00 65 20 65 76 61 6c 75 61 74 65 64 20 28 61 6e 64  e evaluated (and
2ed10 20 74 68 75 73 20 74 68 65 20 63 6f 6e 73 74 72   thus the constr
2ed20 61 69 6e 74 0a 2a 2a 20 69 73 20 75 73 61 62 6c  aint.** is usabl
2ed30 65 29 20 61 6e 64 20 66 61 6c 73 65 20 69 66 20  e) and false if 
2ed40 69 74 20 63 61 6e 6e 6f 74 2e 0a 2a 2a 0a 2a 2a  it cannot..**.**
2ed50 20 54 68 65 20 6f 70 74 69 6d 69 7a 65 72 20 61   The optimizer a
2ed60 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 69 6e 76  utomatically inv
2ed70 65 72 74 73 20 74 65 72 6d 73 20 6f 66 20 74 68  erts terms of th
2ed80 65 20 66 6f 72 6d 20 22 65 78 70 72 20 4f 50 20  e form "expr OP 
2ed90 63 6f 6c 75 6d 6e 22 0a 2a 2a 20 61 6e 64 20 6d  column".** and m
2eda0 61 6b 65 73 20 6f 74 68 65 72 20 73 69 6d 70 6c  akes other simpl
2edb0 69 66 69 63 61 74 69 6f 6e 73 20 74 6f 20 74 68  ifications to th
2edc0 65 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 69  e WHERE clause i
2edd0 6e 20 61 6e 20 61 74 74 65 6d 70 74 20 74 6f 0a  n an attempt to.
2ede0 2a 2a 20 67 65 74 20 61 73 20 6d 61 6e 79 20 57  ** get as many W
2edf0 48 45 52 45 20 63 6c 61 75 73 65 20 74 65 72 6d  HERE clause term
2ee00 73 20 69 6e 74 6f 20 74 68 65 20 66 6f 72 6d 20  s into the form 
2ee10 73 68 6f 77 6e 20 61 62 6f 76 65 20 61 73 20 70  shown above as p
2ee20 6f 73 73 69 62 6c 65 2e 0a 2a 2a 20 54 68 65 20  ossible..** The 
2ee30 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 20 61 72  aConstraint[] ar
2ee40 72 61 79 20 6f 6e 6c 79 20 72 65 70 6f 72 74 73  ray only reports
2ee50 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 74 65   WHERE clause te
2ee60 72 6d 73 20 69 6e 20 74 68 65 20 63 6f 72 72 65  rms in the corre
2ee70 63 74 0a 2a 2a 20 66 6f 72 6d 20 74 68 61 74 20  ct.** form that 
2ee80 72 65 66 65 72 20 74 6f 20 74 68 65 20 70 61 72  refer to the par
2ee90 74 69 63 75 6c 61 72 20 76 69 72 74 75 61 6c 20  ticular virtual 
2eea0 74 61 62 6c 65 20 62 65 69 6e 67 20 71 75 65 72  table being quer
2eeb0 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 66 6f 72  ied..**.** Infor
2eec0 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 74 68 65  mation about the
2eed0 20 4f 52 44 45 52 20 42 59 20 63 6c 61 75 73 65   ORDER BY clause
2eee0 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20 61 4f   is stored in aO
2eef0 72 64 65 72 42 79 5b 5d 2e 0a 2a 2a 20 45 61 63  rderBy[]..** Eac
2ef00 68 20 74 65 72 6d 20 6f 66 20 61 4f 72 64 65 72  h term of aOrder
2ef10 42 79 20 72 65 63 6f 72 64 73 20 61 20 63 6f 6c  By records a col
2ef20 75 6d 6e 20 6f 66 20 74 68 65 20 4f 52 44 45 52  umn of the ORDER
2ef30 20 42 59 20 63 6c 61 75 73 65 2e 0a 2a 2a 0a 2a   BY clause..**.*
2ef40 2a 20 54 68 65 20 5b 78 42 65 73 74 49 6e 64 65  * The [xBestInde
2ef50 78 5d 20 6d 65 74 68 6f 64 20 6d 75 73 74 20 66  x] method must f
2ef60 69 6c 6c 20 61 43 6f 6e 73 74 72 61 69 6e 74 55  ill aConstraintU
2ef70 73 61 67 65 5b 5d 20 77 69 74 68 20 69 6e 66 6f  sage[] with info
2ef80 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74  rmation.** about
2ef90 20 77 68 61 74 20 70 61 72 61 6d 65 74 65 72 73   what parameters
2efa0 20 74 6f 20 70 61 73 73 20 74 6f 20 78 46 69 6c   to pass to xFil
2efb0 74 65 72 2e 20 20 49 66 20 61 72 67 76 49 6e 64  ter.  If argvInd
2efc0 65 78 3e 30 20 74 68 65 6e 0a 2a 2a 20 74 68 65  ex>0 then.** the
2efd0 20 72 69 67 68 74 2d 68 61 6e 64 20 73 69 64 65   right-hand side
2efe0 20 6f 66 20 74 68 65 20 63 6f 72 72 65 73 70 6f   of the correspo
2eff0 6e 64 69 6e 67 20 61 43 6f 6e 73 74 72 61 69 6e  nding aConstrain
2f000 74 5b 5d 20 69 73 20 65 76 61 6c 75 61 74 65 64  t[] is evaluated
2f010 0a 2a 2a 20 61 6e 64 20 62 65 63 6f 6d 65 73 20  .** and becomes 
2f020 74 68 65 20 61 72 67 76 49 6e 64 65 78 2d 74 68  the argvIndex-th
2f030 20 65 6e 74 72 79 20 69 6e 20 61 72 67 76 2e 20   entry in argv. 
2f040 20 49 66 20 61 43 6f 6e 73 74 72 61 69 6e 74 55   If aConstraintU
2f050 73 61 67 65 5b 5d 2e 6f 6d 69 74 0a 2a 2a 20 69  sage[].omit.** i
2f060 73 20 74 72 75 65 2c 20 74 68 65 6e 20 74 68 65  s true, then the
2f070 20 63 6f 6e 73 74 72 61 69 6e 74 20 69 73 20 61   constraint is a
2f080 73 73 75 6d 65 64 20 74 6f 20 62 65 20 66 75 6c  ssumed to be ful
2f090 6c 79 20 68 61 6e 64 6c 65 64 20 62 79 20 74 68  ly handled by th
2f0a0 65 0a 2a 2a 20 76 69 72 74 75 61 6c 20 74 61 62  e.** virtual tab
2f0b0 6c 65 20 61 6e 64 20 69 73 20 6e 6f 74 20 63 68  le and is not ch
2f0c0 65 63 6b 65 64 20 61 67 61 69 6e 20 62 79 20 53  ecked again by S
2f0d0 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  QLite..**.** The
2f0e0 20 69 64 78 4e 75 6d 20 61 6e 64 20 69 64 78 50   idxNum and idxP
2f0f0 74 72 20 76 61 6c 75 65 73 20 61 72 65 20 72 65  tr values are re
2f100 63 6f 72 64 65 64 20 61 6e 64 20 70 61 73 73 65  corded and passe
2f110 64 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 5b 78  d into the.** [x
2f120 46 69 6c 74 65 72 5d 20 6d 65 74 68 6f 64 2e 0a  Filter] method..
2f130 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ** [sqlite3_free
2f140 28 29 5d 20 69 73 20 75 73 65 64 20 74 6f 20 66  ()] is used to f
2f150 72 65 65 20 69 64 78 50 74 72 20 69 66 20 61 6e  ree idxPtr if an
2f160 64 20 6f 6e 6c 79 20 69 66 66 0a 2a 2a 20 6e 65  d only iff.** ne
2f170 65 64 54 6f 46 72 65 65 49 64 78 50 74 72 20 69  edToFreeIdxPtr i
2f180 73 20 74 72 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  s true..**.** Th
2f190 65 20 6f 72 64 65 72 42 79 43 6f 6e 73 75 6d 65  e orderByConsume
2f1a0 64 20 6d 65 61 6e 73 20 74 68 61 74 20 6f 75 74  d means that out
2f1b0 70 75 74 20 66 72 6f 6d 20 5b 78 46 69 6c 74 65  put from [xFilte
2f1c0 72 5d 2f 5b 78 4e 65 78 74 5d 20 77 69 6c 6c 20  r]/[xNext] will 
2f1d0 6f 63 63 75 72 20 69 6e 0a 2a 2a 20 74 68 65 20  occur in.** the 
2f1e0 63 6f 72 72 65 63 74 20 6f 72 64 65 72 20 74 6f  correct order to
2f1f0 20 73 61 74 69 73 66 79 20 74 68 65 20 4f 52 44   satisfy the ORD
2f200 45 52 20 42 59 20 63 6c 61 75 73 65 20 73 6f 20  ER BY clause so 
2f210 74 68 61 74 20 6e 6f 20 73 65 70 61 72 61 74 65  that no separate
2f220 0a 2a 2a 20 73 6f 72 74 69 6e 67 20 73 74 65 70  .** sorting step
2f230 20 69 73 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a   is required..**
2f240 0a 2a 2a 20 54 68 65 20 65 73 74 69 6d 61 74 65  .** The estimate
2f250 64 43 6f 73 74 20 76 61 6c 75 65 20 69 73 20 61  dCost value is a
2f260 6e 20 65 73 74 69 6d 61 74 65 20 6f 66 20 74 68  n estimate of th
2f270 65 20 63 6f 73 74 20 6f 66 20 64 6f 69 6e 67 20  e cost of doing 
2f280 74 68 65 0a 2a 2a 20 70 61 72 74 69 63 75 6c 61  the.** particula
2f290 72 20 6c 6f 6f 6b 75 70 2e 20 20 41 20 66 75 6c  r lookup.  A ful
2f2a0 6c 20 73 63 61 6e 20 6f 66 20 61 20 74 61 62 6c  l scan of a tabl
2f2b0 65 20 77 69 74 68 20 4e 20 65 6e 74 72 69 65 73  e with N entries
2f2c0 20 73 68 6f 75 6c 64 20 68 61 76 65 0a 2a 2a 20   should have.** 
2f2d0 61 20 63 6f 73 74 20 6f 66 20 4e 2e 20 20 41 20  a cost of N.  A 
2f2e0 62 69 6e 61 72 79 20 73 65 61 72 63 68 20 6f 66  binary search of
2f2f0 20 61 20 74 61 62 6c 65 20 6f 66 20 4e 20 65 6e   a table of N en
2f300 74 72 69 65 73 20 73 68 6f 75 6c 64 20 68 61 76  tries should hav
2f310 65 20 61 0a 2a 2a 20 63 6f 73 74 20 6f 66 20 61  e a.** cost of a
2f320 70 70 72 6f 78 69 6d 61 74 65 6c 79 20 6c 6f 67  pproximately log
2f330 28 4e 29 2e 0a 2a 2f 0a 73 74 72 75 63 74 20 73  (N)..*/.struct s
2f340 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66  qlite3_index_inf
2f350 6f 20 7b 0a 20 20 2f 2a 20 49 6e 70 75 74 73 20  o {.  /* Inputs 
2f360 2a 2f 0a 20 20 69 6e 74 20 6e 43 6f 6e 73 74 72  */.  int nConstr
2f370 61 69 6e 74 3b 20 20 20 20 20 20 20 20 20 20 20  aint;           
2f380 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 65 6e 74  /* Number of ent
2f390 72 69 65 73 20 69 6e 20 61 43 6f 6e 73 74 72 61  ries in aConstra
2f3a0 69 6e 74 20 2a 2f 0a 20 20 73 74 72 75 63 74 20  int */.  struct 
2f3b0 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 63 6f  sqlite3_index_co
2f3c0 6e 73 74 72 61 69 6e 74 20 7b 0a 20 20 20 20 20  nstraint {.     
2f3d0 69 6e 74 20 69 43 6f 6c 75 6d 6e 3b 20 20 20 20  int iColumn;    
2f3e0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6f 6c            /* Col
2f3f0 75 6d 6e 20 6f 6e 20 6c 65 66 74 2d 68 61 6e 64  umn on left-hand
2f400 20 73 69 64 65 20 6f 66 20 63 6f 6e 73 74 72 61   side of constra
2f410 69 6e 74 20 2a 2f 0a 20 20 20 20 20 75 6e 73 69  int */.     unsi
2f420 67 6e 65 64 20 63 68 61 72 20 6f 70 3b 20 20 20  gned char op;   
2f430 20 20 20 20 20 20 2f 2a 20 43 6f 6e 73 74 72 61        /* Constra
2f440 69 6e 74 20 6f 70 65 72 61 74 6f 72 20 2a 2f 0a  int operator */.
2f450 20 20 20 20 20 75 6e 73 69 67 6e 65 64 20 63 68       unsigned ch
2f460 61 72 20 75 73 61 62 6c 65 3b 20 20 20 20 20 2f  ar usable;     /
2f470 2a 20 54 72 75 65 20 69 66 20 74 68 69 73 20 63  * True if this c
2f480 6f 6e 73 74 72 61 69 6e 74 20 69 73 20 75 73 61  onstraint is usa
2f490 62 6c 65 20 2a 2f 0a 20 20 20 20 20 69 6e 74 20  ble */.     int 
2f4a0 69 54 65 72 6d 4f 66 66 73 65 74 3b 20 20 20 20  iTermOffset;    
2f4b0 20 20 20 20 20 20 2f 2a 20 55 73 65 64 20 69 6e        /* Used in
2f4c0 74 65 72 6e 61 6c 6c 79 20 2d 20 78 42 65 73 74  ternally - xBest
2f4d0 49 6e 64 65 78 20 73 68 6f 75 6c 64 20 69 67 6e  Index should ign
2f4e0 6f 72 65 20 2a 2f 0a 20 20 7d 20 2a 61 43 6f 6e  ore */.  } *aCon
2f4f0 73 74 72 61 69 6e 74 3b 20 20 20 20 20 20 20 20  straint;        
2f500 20 20 20 20 2f 2a 20 54 61 62 6c 65 20 6f 66 20      /* Table of 
2f510 57 48 45 52 45 20 63 6c 61 75 73 65 20 63 6f 6e  WHERE clause con
2f520 73 74 72 61 69 6e 74 73 20 2a 2f 0a 20 20 69 6e  straints */.  in
2f530 74 20 6e 4f 72 64 65 72 42 79 3b 20 20 20 20 20  t nOrderBy;     
2f540 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62           /* Numb
2f550 65 72 20 6f 66 20 74 65 72 6d 73 20 69 6e 20 74  er of terms in t
2f560 68 65 20 4f 52 44 45 52 20 42 59 20 63 6c 61 75  he ORDER BY clau
2f570 73 65 20 2a 2f 0a 20 20 73 74 72 75 63 74 20 73  se */.  struct s
2f580 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 6f 72 64  qlite3_index_ord
2f590 65 72 62 79 20 7b 0a 20 20 20 20 20 69 6e 74 20  erby {.     int 
2f5a0 69 43 6f 6c 75 6d 6e 3b 20 20 20 20 20 20 20 20  iColumn;        
2f5b0 20 20 20 20 20 20 2f 2a 20 43 6f 6c 75 6d 6e 20        /* Column 
2f5c0 6e 75 6d 62 65 72 20 2a 2f 0a 20 20 20 20 20 75  number */.     u
2f5d0 6e 73 69 67 6e 65 64 20 63 68 61 72 20 64 65 73  nsigned char des
2f5e0 63 3b 20 20 20 20 20 20 20 2f 2a 20 54 72 75 65  c;       /* True
2f5f0 20 66 6f 72 20 44 45 53 43 2e 20 20 46 61 6c 73   for DESC.  Fals
2f600 65 20 66 6f 72 20 41 53 43 2e 20 2a 2f 0a 20 20  e for ASC. */.  
2f610 7d 20 2a 61 4f 72 64 65 72 42 79 3b 20 20 20 20  } *aOrderBy;    
2f620 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 54 68             /* Th
2f630 65 20 4f 52 44 45 52 20 42 59 20 63 6c 61 75 73  e ORDER BY claus
2f640 65 20 2a 2f 0a 20 20 2f 2a 20 4f 75 74 70 75 74  e */.  /* Output
2f650 73 20 2a 2f 0a 20 20 73 74 72 75 63 74 20 73 71  s */.  struct sq
2f660 6c 69 74 65 33 5f 69 6e 64 65 78 5f 63 6f 6e 73  lite3_index_cons
2f670 74 72 61 69 6e 74 5f 75 73 61 67 65 20 7b 0a 20  traint_usage {. 
2f680 20 20 20 69 6e 74 20 61 72 67 76 49 6e 64 65 78     int argvIndex
2f690 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 69  ;           /* i
2f6a0 66 20 3e 30 2c 20 63 6f 6e 73 74 72 61 69 6e 74  f >0, constraint
2f6b0 20 69 73 20 70 61 72 74 20 6f 66 20 61 72 67 76   is part of argv
2f6c0 20 74 6f 20 78 46 69 6c 74 65 72 20 2a 2f 0a 20   to xFilter */. 
2f6d0 20 20 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72     unsigned char
2f6e0 20 6f 6d 69 74 3b 20 20 20 20 20 20 2f 2a 20 44   omit;      /* D
2f6f0 6f 20 6e 6f 74 20 63 6f 64 65 20 61 20 74 65 73  o not code a tes
2f700 74 20 66 6f 72 20 74 68 69 73 20 63 6f 6e 73 74  t for this const
2f710 72 61 69 6e 74 20 2a 2f 0a 20 20 7d 20 2a 61 43  raint */.  } *aC
2f720 6f 6e 73 74 72 61 69 6e 74 55 73 61 67 65 3b 0a  onstraintUsage;.
2f730 20 20 69 6e 74 20 69 64 78 4e 75 6d 3b 20 20 20    int idxNum;   
2f740 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
2f750 4e 75 6d 62 65 72 20 75 73 65 64 20 74 6f 20 69  Number used to i
2f760 64 65 6e 74 69 66 79 20 74 68 65 20 69 6e 64 65  dentify the inde
2f770 78 20 2a 2f 0a 20 20 63 68 61 72 20 2a 69 64 78  x */.  char *idx
2f780 53 74 72 3b 20 20 20 20 20 20 20 20 20 20 20 20  Str;            
2f790 20 20 2f 2a 20 53 74 72 69 6e 67 2c 20 70 6f 73    /* String, pos
2f7a0 73 69 62 6c 79 20 6f 62 74 61 69 6e 65 64 20 66  sibly obtained f
2f7b0 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  rom sqlite3_mall
2f7c0 6f 63 20 2a 2f 0a 20 20 69 6e 74 20 6e 65 65 64  oc */.  int need
2f7d0 54 6f 46 72 65 65 49 64 78 53 74 72 3b 20 20 20  ToFreeIdxStr;   
2f7e0 20 20 20 2f 2a 20 46 72 65 65 20 69 64 78 53 74     /* Free idxSt
2f7f0 72 20 75 73 69 6e 67 20 73 71 6c 69 74 65 33 5f  r using sqlite3_
2f800 66 72 65 65 28 29 20 69 66 20 74 72 75 65 20 2a  free() if true *
2f810 2f 0a 20 20 69 6e 74 20 6f 72 64 65 72 42 79 43  /.  int orderByC
2f820 6f 6e 73 75 6d 65 64 3b 20 20 20 20 20 20 20 2f  onsumed;       /
2f830 2a 20 54 72 75 65 20 69 66 20 6f 75 74 70 75 74  * True if output
2f840 20 69 73 20 61 6c 72 65 61 64 79 20 6f 72 64 65   is already orde
2f850 72 65 64 20 2a 2f 0a 20 20 64 6f 75 62 6c 65 20  red */.  double 
2f860 65 73 74 69 6d 61 74 65 64 43 6f 73 74 3b 20 20  estimatedCost;  
2f870 20 20 20 20 2f 2a 20 45 73 74 69 6d 61 74 65 64      /* Estimated
2f880 20 63 6f 73 74 20 6f 66 20 75 73 69 6e 67 20 74   cost of using t
2f890 68 69 73 20 69 6e 64 65 78 20 2a 2f 0a 7d 3b 0a  his index */.};.
2f8a0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
2f8b0 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f  NDEX_CONSTRAINT_
2f8c0 45 51 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20  EQ    2.#define 
2f8d0 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e  SQLITE_INDEX_CON
2f8e0 53 54 52 41 49 4e 54 5f 47 54 20 20 20 20 34 0a  STRAINT_GT    4.
2f8f0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
2f900 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f  NDEX_CONSTRAINT_
2f910 4c 45 20 20 20 20 38 0a 23 64 65 66 69 6e 65 20  LE    8.#define 
2f920 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e  SQLITE_INDEX_CON
2f930 53 54 52 41 49 4e 54 5f 4c 54 20 20 20 20 31 36  STRAINT_LT    16
2f940 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2f950 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54  INDEX_CONSTRAINT
2f960 5f 47 45 20 20 20 20 33 32 0a 23 64 65 66 69 6e  _GE    32.#defin
2f970 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43  e SQLITE_INDEX_C
2f980 4f 4e 53 54 52 41 49 4e 54 5f 4d 41 54 43 48 20  ONSTRAINT_MATCH 
2f990 36 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  64../*.** CAPI3R
2f9a0 45 46 3a 20 52 65 67 69 73 74 65 72 20 41 20 56  EF: Register A V
2f9b0 69 72 74 75 61 6c 20 54 61 62 6c 65 20 49 6d 70  irtual Table Imp
2f9c0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 7b 48 31 38  lementation {H18
2f9d0 32 30 30 7d 20 3c 53 32 30 34 30 30 3e 0a 2a 2a  200} <S20400>.**
2f9e0 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a   EXPERIMENTAL.**
2f9f0 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65  .** This routine
2fa00 20 69 73 20 75 73 65 64 20 74 6f 20 72 65 67 69   is used to regi
2fa10 73 74 65 72 20 61 20 6e 65 77 20 5b 76 69 72 74  ster a new [virt
2fa20 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65  ual table module
2fa30 5d 20 6e 61 6d 65 2e 0a 2a 2a 20 4d 6f 64 75 6c  ] name..** Modul
2fa40 65 20 6e 61 6d 65 73 20 6d 75 73 74 20 62 65 20  e names must be 
2fa50 72 65 67 69 73 74 65 72 65 64 20 62 65 66 6f 72  registered befor
2fa60 65 0a 2a 2a 20 63 72 65 61 74 69 6e 67 20 61 20  e.** creating a 
2fa70 6e 65 77 20 5b 76 69 72 74 75 61 6c 20 74 61 62  new [virtual tab
2fa80 6c 65 5d 20 75 73 69 6e 67 20 74 68 65 20 6d 6f  le] using the mo
2fa90 64 75 6c 65 2c 20 6f 72 20 62 65 66 6f 72 65 20  dule, or before 
2faa0 75 73 69 6e 67 20 61 0a 2a 2a 20 70 72 65 65 78  using a.** preex
2fab0 69 73 74 69 6e 67 20 5b 76 69 72 74 75 61 6c 20  isting [virtual 
2fac0 74 61 62 6c 65 5d 20 66 6f 72 20 74 68 65 20 6d  table] for the m
2fad0 6f 64 75 6c 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  odule..**.** The
2fae0 20 6d 6f 64 75 6c 65 20 6e 61 6d 65 20 69 73 20   module name is 
2faf0 72 65 67 69 73 74 65 72 65 64 20 6f 6e 20 74 68  registered on th
2fb00 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
2fb10 65 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65  ection] specifie
2fb20 64 0a 2a 2a 20 62 79 20 74 68 65 20 66 69 72 73  d.** by the firs
2fb30 74 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54 68  t parameter.  Th
2fb40 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6d 6f  e name of the mo
2fb50 64 75 6c 65 20 69 73 20 67 69 76 65 6e 20 62 79  dule is given by
2fb60 20 74 68 65 20 0a 2a 2a 20 73 65 63 6f 6e 64 20   the .** second 
2fb70 70 61 72 61 6d 65 74 65 72 2e 20 20 54 68 65 20  parameter.  The 
2fb80 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
2fb90 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 0a  is a pointer to.
2fba0 2a 2a 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74  ** the implement
2fbb0 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 5b 76 69  ation of the [vi
2fbc0 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75  rtual table modu
2fbd0 6c 65 5d 2e 20 20 20 54 68 65 20 66 6f 75 72 74  le].   The fourt
2fbe0 68 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 69  h.** parameter i
2fbf0 73 20 61 6e 20 61 72 62 69 74 72 61 72 79 20 63  s an arbitrary c
2fc00 6c 69 65 6e 74 20 64 61 74 61 20 70 6f 69 6e 74  lient data point
2fc10 65 72 20 74 68 61 74 20 69 73 20 70 61 73 73 65  er that is passe
2fc20 64 20 74 68 72 6f 75 67 68 0a 2a 2a 20 69 6e 74  d through.** int
2fc30 6f 20 74 68 65 20 5b 78 43 72 65 61 74 65 5d 20  o the [xCreate] 
2fc40 61 6e 64 20 5b 78 43 6f 6e 6e 65 63 74 5d 20 6d  and [xConnect] m
2fc50 65 74 68 6f 64 73 20 6f 66 20 74 68 65 20 76 69  ethods of the vi
2fc60 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75  rtual table modu
2fc70 6c 65 0a 2a 2a 20 77 68 65 6e 20 61 20 6e 65 77  le.** when a new
2fc80 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69   virtual table i
2fc90 73 20 62 65 20 62 65 69 6e 67 20 63 72 65 61 74  s be being creat
2fca0 65 64 20 6f 72 20 72 65 69 6e 69 74 69 61 6c 69  ed or reinitiali
2fcb0 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  zed..**.** This 
2fcc0 69 6e 74 65 72 66 61 63 65 20 68 61 73 20 65 78  interface has ex
2fcd0 61 63 74 6c 79 20 74 68 65 20 73 61 6d 65 20 65  actly the same e
2fce0 66 66 65 63 74 20 61 73 20 63 61 6c 6c 69 6e 67  ffect as calling
2fcf0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  .** [sqlite3_cre
2fd00 61 74 65 5f 6d 6f 64 75 6c 65 5f 76 32 28 29 5d  ate_module_v2()]
2fd10 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 63 6c 69   with a NULL cli
2fd20 65 6e 74 20 64 61 74 61 20 64 65 73 74 72 75 63  ent data destruc
2fd30 74 6f 72 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45  tor..*/.SQLITE_E
2fd40 58 50 45 52 49 4d 45 4e 54 41 4c 20 69 6e 74 20  XPERIMENTAL int 
2fd50 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d  sqlite3_create_m
2fd60 6f 64 75 6c 65 28 0a 20 20 73 71 6c 69 74 65 33  odule(.  sqlite3
2fd70 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
2fd80 20 20 20 20 2f 2a 20 53 51 4c 69 74 65 20 63 6f      /* SQLite co
2fd90 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 72 65 67 69  nnection to regi
2fda0 73 74 65 72 20 6d 6f 64 75 6c 65 20 77 69 74 68  ster module with
2fdb0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
2fdc0 20 2a 7a 4e 61 6d 65 2c 20 20 20 20 20 20 20 20   *zName,        
2fdd0 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 65 20   /* Name of the 
2fde0 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  module */.  cons
2fdf0 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65  t sqlite3_module
2fe00 20 2a 70 2c 20 20 20 2f 2a 20 4d 65 74 68 6f 64   *p,   /* Method
2fe10 73 20 66 6f 72 20 74 68 65 20 6d 6f 64 75 6c 65  s for the module
2fe20 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 43 6c 69   */.  void *pCli
2fe30 65 6e 74 44 61 74 61 20 20 20 20 20 20 20 20 20  entData         
2fe40 20 2f 2a 20 43 6c 69 65 6e 74 20 64 61 74 61 20   /* Client data 
2fe50 66 6f 72 20 78 43 72 65 61 74 65 2f 78 43 6f 6e  for xCreate/xCon
2fe60 6e 65 63 74 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a  nect */.);../*.*
2fe70 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 67 69  * CAPI3REF: Regi
2fe80 73 74 65 72 20 41 20 56 69 72 74 75 61 6c 20 54  ster A Virtual T
2fe90 61 62 6c 65 20 49 6d 70 6c 65 6d 65 6e 74 61 74  able Implementat
2fea0 69 6f 6e 20 7b 48 31 38 32 31 30 7d 20 3c 53 32  ion {H18210} <S2
2feb0 30 34 30 30 3e 0a 2a 2a 20 45 58 50 45 52 49 4d  0400>.** EXPERIM
2fec0 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 69 73  ENTAL.**.** This
2fed0 20 72 6f 75 74 69 6e 65 20 69 73 20 69 64 65 6e   routine is iden
2fee0 74 69 63 61 6c 20 74 6f 20 74 68 65 20 5b 73 71  tical to the [sq
2fef0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64  lite3_create_mod
2ff00 75 6c 65 28 29 5d 20 6d 65 74 68 6f 64 2c 0a 2a  ule()] method,.*
2ff10 2a 20 65 78 63 65 70 74 20 74 68 61 74 20 69 74  * except that it
2ff20 20 68 61 73 20 61 6e 20 65 78 74 72 61 20 70 61   has an extra pa
2ff30 72 61 6d 65 74 65 72 20 74 6f 20 73 70 65 63 69  rameter to speci
2ff40 66 79 20 0a 2a 2a 20 61 20 64 65 73 74 72 75 63  fy .** a destruc
2ff50 74 6f 72 20 66 75 6e 63 74 69 6f 6e 20 66 6f 72  tor function for
2ff60 20 74 68 65 20 63 6c 69 65 6e 74 20 64 61 74 61   the client data
2ff70 20 70 6f 69 6e 74 65 72 2e 20 20 53 51 4c 69 74   pointer.  SQLit
2ff80 65 20 77 69 6c 6c 0a 2a 2a 20 69 6e 76 6f 6b 65  e will.** invoke
2ff90 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20   the destructor 
2ffa0 66 75 6e 63 74 69 6f 6e 20 28 69 66 20 69 74 20  function (if it 
2ffb0 69 73 20 6e 6f 74 20 4e 55 4c 4c 29 20 77 68 65  is not NULL) whe
2ffc0 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 6e 6f 20 6c  n SQLite.** no l
2ffd0 6f 6e 67 65 72 20 6e 65 65 64 73 20 74 68 65 20  onger needs the 
2ffe0 70 43 6c 69 65 6e 74 44 61 74 61 20 70 6f 69 6e  pClientData poin
2fff0 74 65 72 2e 20 20 0a 2a 2f 0a 53 51 4c 49 54 45  ter.  .*/.SQLITE
30000 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 69 6e  _EXPERIMENTAL in
30010 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  t sqlite3_create
30020 5f 6d 6f 64 75 6c 65 5f 76 32 28 0a 20 20 73 71  _module_v2(.  sq
30030 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
30040 20 20 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 69           /* SQLi
30050 74 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f  te connection to
30060 20 72 65 67 69 73 74 65 72 20 6d 6f 64 75 6c 65   register module
30070 20 77 69 74 68 20 2a 2f 0a 20 20 63 6f 6e 73 74   with */.  const
30080 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 20 20   char *zName,   
30090 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66        /* Name of
300a0 20 74 68 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20   the module */. 
300b0 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 6d   const sqlite3_m
300c0 6f 64 75 6c 65 20 2a 70 2c 20 20 20 2f 2a 20 4d  odule *p,   /* M
300d0 65 74 68 6f 64 73 20 66 6f 72 20 74 68 65 20 6d  ethods for the m
300e0 6f 64 75 6c 65 20 2a 2f 0a 20 20 76 6f 69 64 20  odule */.  void 
300f0 2a 70 43 6c 69 65 6e 74 44 61 74 61 2c 20 20 20  *pClientData,   
30100 20 20 20 20 20 20 2f 2a 20 43 6c 69 65 6e 74 20        /* Client 
30110 64 61 74 61 20 66 6f 72 20 78 43 72 65 61 74 65  data for xCreate
30120 2f 78 43 6f 6e 6e 65 63 74 20 2a 2f 0a 20 20 76  /xConnect */.  v
30130 6f 69 64 28 2a 78 44 65 73 74 72 6f 79 29 28 76  oid(*xDestroy)(v
30140 6f 69 64 2a 29 20 20 20 20 20 2f 2a 20 4d 6f 64  oid*)     /* Mod
30150 75 6c 65 20 64 65 73 74 72 75 63 74 6f 72 20 66  ule destructor f
30160 75 6e 63 74 69 6f 6e 20 2a 2f 0a 29 3b 0a 0a 2f  unction */.);../
30170 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 56  *.** CAPI3REF: V
30180 69 72 74 75 61 6c 20 54 61 62 6c 65 20 49 6e 73  irtual Table Ins
30190 74 61 6e 63 65 20 4f 62 6a 65 63 74 20 7b 48 31  tance Object {H1
301a0 38 30 31 30 7d 20 3c 53 32 30 34 30 30 3e 0a 2a  8010} <S20400>.*
301b0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c 69  * KEYWORDS: sqli
301c0 74 65 33 5f 76 74 61 62 0a 2a 2a 20 45 58 50 45  te3_vtab.** EXPE
301d0 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 45  RIMENTAL.**.** E
301e0 76 65 72 79 20 5b 76 69 72 74 75 61 6c 20 74 61  very [virtual ta
301f0 62 6c 65 20 6d 6f 64 75 6c 65 5d 20 69 6d 70 6c  ble module] impl
30200 65 6d 65 6e 74 61 74 69 6f 6e 20 75 73 65 73 20  ementation uses 
30210 61 20 73 75 62 63 6c 61 73 73 0a 2a 2a 20 6f 66  a subclass.** of
30220 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73   the following s
30230 74 72 75 63 74 75 72 65 20 74 6f 20 64 65 73 63  tructure to desc
30240 72 69 62 65 20 61 20 70 61 72 74 69 63 75 6c 61  ribe a particula
30250 72 20 69 6e 73 74 61 6e 63 65 0a 2a 2a 20 6f 66  r instance.** of
30260 20 74 68 65 20 5b 76 69 72 74 75 61 6c 20 74 61   the [virtual ta
30270 62 6c 65 5d 2e 20 20 45 61 63 68 20 73 75 62 63  ble].  Each subc
30280 6c 61 73 73 20 77 69 6c 6c 0a 2a 2a 20 62 65 20  lass will.** be 
30290 74 61 69 6c 6f 72 65 64 20 74 6f 20 74 68 65 20  tailored to the 
302a0 73 70 65 63 69 66 69 63 20 6e 65 65 64 73 20 6f  specific needs o
302b0 66 20 74 68 65 20 6d 6f 64 75 6c 65 20 69 6d 70  f the module imp
302c0 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 0a 2a 2a 20  lementation..** 
302d0 54 68 65 20 70 75 72 70 6f 73 65 20 6f 66 20 74  The purpose of t
302e0 68 69 73 20 73 75 70 65 72 63 6c 61 73 73 20 69  his superclass i
302f0 73 20 74 6f 20 64 65 66 69 6e 65 20 63 65 72 74  s to define cert
30300 61 69 6e 20 66 69 65 6c 64 73 20 74 68 61 74 20  ain fields that 
30310 61 72 65 0a 2a 2a 20 63 6f 6d 6d 6f 6e 20 74 6f  are.** common to
30320 20 61 6c 6c 20 6d 6f 64 75 6c 65 20 69 6d 70 6c   all module impl
30330 65 6d 65 6e 74 61 74 69 6f 6e 73 2e 0a 2a 2a 0a  ementations..**.
30340 2a 2a 20 56 69 72 74 75 61 6c 20 74 61 62 6c 65  ** Virtual table
30350 73 20 6d 65 74 68 6f 64 73 20 63 61 6e 20 73 65  s methods can se
30360 74 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61  t an error messa
30370 67 65 20 62 79 20 61 73 73 69 67 6e 69 6e 67 20  ge by assigning 
30380 61 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 62 74 61  a.** string obta
30390 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74  ined from [sqlit
303a0 65 33 5f 6d 70 72 69 6e 74 66 28 29 5d 20 74 6f  e3_mprintf()] to
303b0 20 7a 45 72 72 4d 73 67 2e 20 20 54 68 65 20 6d   zErrMsg.  The m
303c0 65 74 68 6f 64 20 73 68 6f 75 6c 64 0a 2a 2a 20  ethod should.** 
303d0 74 61 6b 65 20 63 61 72 65 20 74 68 61 74 20 61  take care that a
303e0 6e 79 20 70 72 69 6f 72 20 73 74 72 69 6e 67 20  ny prior string 
303f0 69 73 20 66 72 65 65 64 20 62 79 20 61 20 63 61  is freed by a ca
30400 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66  ll to [sqlite3_f
30410 72 65 65 28 29 5d 0a 2a 2a 20 70 72 69 6f 72 20  ree()].** prior 
30420 74 6f 20 61 73 73 69 67 6e 69 6e 67 20 61 20 6e  to assigning a n
30430 65 77 20 73 74 72 69 6e 67 20 74 6f 20 7a 45 72  ew string to zEr
30440 72 4d 73 67 2e 20 20 41 66 74 65 72 20 74 68 65  rMsg.  After the
30450 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 0a 2a   error message.*
30460 2a 20 69 73 20 64 65 6c 69 76 65 72 65 64 20 75  * is delivered u
30470 70 20 74 6f 20 74 68 65 20 63 6c 69 65 6e 74 20  p to the client 
30480 61 70 70 6c 69 63 61 74 69 6f 6e 2c 20 74 68 65  application, the
30490 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 20   string will be 
304a0 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a  automatically.**
304b0 20 66 72 65 65 64 20 62 79 20 73 71 6c 69 74 65   freed by sqlite
304c0 33 5f 66 72 65 65 28 29 20 61 6e 64 20 74 68 65  3_free() and the
304d0 20 7a 45 72 72 4d 73 67 20 66 69 65 6c 64 20 77   zErrMsg field w
304e0 69 6c 6c 20 62 65 20 7a 65 72 6f 65 64 2e 0a 2a  ill be zeroed..*
304f0 2f 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  /.struct sqlite3
30500 5f 76 74 61 62 20 7b 0a 20 20 63 6f 6e 73 74 20  _vtab {.  const 
30510 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20 2a  sqlite3_module *
30520 70 4d 6f 64 75 6c 65 3b 20 20 2f 2a 20 54 68 65  pModule;  /* The
30530 20 6d 6f 64 75 6c 65 20 66 6f 72 20 74 68 69 73   module for this
30540 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 2a   virtual table *
30550 2f 0a 20 20 69 6e 74 20 6e 52 65 66 3b 20 20 20  /.  int nRef;   
30560 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
30570 20 20 20 20 2f 2a 20 55 73 65 64 20 69 6e 74 65      /* Used inte
30580 72 6e 61 6c 6c 79 20 2a 2f 0a 20 20 63 68 61 72  rnally */.  char
30590 20 2a 7a 45 72 72 4d 73 67 3b 20 20 20 20 20 20   *zErrMsg;      
305a0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 45              /* E
305b0 72 72 6f 72 20 6d 65 73 73 61 67 65 20 66 72 6f  rror message fro
305c0 6d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74  m sqlite3_mprint
305d0 66 28 29 20 2a 2f 0a 20 20 2f 2a 20 56 69 72 74  f() */.  /* Virt
305e0 75 61 6c 20 74 61 62 6c 65 20 69 6d 70 6c 65 6d  ual table implem
305f0 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c 6c 20 74  entations will t
30600 79 70 69 63 61 6c 6c 79 20 61 64 64 20 61 64 64  ypically add add
30610 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20 2a  itional fields *
30620 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.};../*.** CAPI
30630 33 52 45 46 3a 20 56 69 72 74 75 61 6c 20 54 61  3REF: Virtual Ta
30640 62 6c 65 20 43 75 72 73 6f 72 20 4f 62 6a 65 63  ble Cursor Objec
30650 74 20 20 7b 48 31 38 30 32 30 7d 20 3c 53 32 30  t  {H18020} <S20
30660 34 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  400>.** KEYWORDS
30670 3a 20 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63  : sqlite3_vtab_c
30680 75 72 73 6f 72 20 7b 76 69 72 74 75 61 6c 20 74  ursor {virtual t
30690 61 62 6c 65 20 63 75 72 73 6f 72 7d 0a 2a 2a 20  able cursor}.** 
306a0 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a  EXPERIMENTAL.**.
306b0 2a 2a 20 45 76 65 72 79 20 5b 76 69 72 74 75 61  ** Every [virtua
306c0 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 5d 20  l table module] 
306d0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 75  implementation u
306e0 73 65 73 20 61 20 73 75 62 63 6c 61 73 73 20 6f  ses a subclass o
306f0 66 20 74 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 69  f the.** followi
30700 6e 67 20 73 74 72 75 63 74 75 72 65 20 74 6f 20  ng structure to 
30710 64 65 73 63 72 69 62 65 20 63 75 72 73 6f 72 73  describe cursors
30720 20 74 68 61 74 20 70 6f 69 6e 74 20 69 6e 74 6f   that point into
30730 20 74 68 65 0a 2a 2a 20 5b 76 69 72 74 75 61 6c   the.** [virtual
30740 20 74 61 62 6c 65 5d 20 61 6e 64 20 61 72 65 20   table] and are 
30750 75 73 65 64 0a 2a 2a 20 74 6f 20 6c 6f 6f 70 20  used.** to loop 
30760 74 68 72 6f 75 67 68 20 74 68 65 20 76 69 72 74  through the virt
30770 75 61 6c 20 74 61 62 6c 65 2e 20 20 43 75 72 73  ual table.  Curs
30780 6f 72 73 20 61 72 65 20 63 72 65 61 74 65 64 20  ors are created 
30790 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71  using the.** [sq
307a0 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 2e 78 4f 70  lite3_module.xOp
307b0 65 6e 20 7c 20 78 4f 70 65 6e 5d 20 6d 65 74 68  en | xOpen] meth
307c0 6f 64 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65  od of the module
307d0 20 61 6e 64 20 61 72 65 20 64 65 73 74 72 6f 79   and are destroy
307e0 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 5b 73 71  ed.** by the [sq
307f0 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 2e 78 43 6c  lite3_module.xCl
30800 6f 73 65 20 7c 20 78 43 6c 6f 73 65 5d 20 6d 65  ose | xClose] me
30810 74 68 6f 64 2e 20 20 43 75 73 73 6f 72 73 20 61  thod.  Cussors a
30820 72 65 20 75 73 65 64 0a 2a 2a 20 62 79 20 74 68  re used.** by th
30830 65 20 5b 78 46 69 6c 74 65 72 5d 2c 20 5b 78 4e  e [xFilter], [xN
30840 65 78 74 5d 2c 20 5b 78 45 6f 66 5d 2c 20 5b 78  ext], [xEof], [x
30850 43 6f 6c 75 6d 6e 5d 2c 20 61 6e 64 20 5b 78 52  Column], and [xR
30860 6f 77 69 64 5d 20 6d 65 74 68 6f 64 73 0a 2a 2a  owid] methods.**
30870 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 2e 20   of the module. 
30880 20 45 61 63 68 20 6d 6f 64 75 6c 65 20 69 6d 70   Each module imp
30890 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 6c 6c  lementation will
308a0 20 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20 63   define.** the c
308b0 6f 6e 74 65 6e 74 20 6f 66 20 61 20 63 75 72 73  ontent of a curs
308c0 6f 72 20 73 74 72 75 63 74 75 72 65 20 74 6f 20  or structure to 
308d0 73 75 69 74 20 69 74 73 20 6f 77 6e 20 6e 65 65  suit its own nee
308e0 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73  ds..**.** This s
308f0 75 70 65 72 63 6c 61 73 73 20 65 78 69 73 74 73  uperclass exists
30900 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 64 65 66   in order to def
30910 69 6e 65 20 66 69 65 6c 64 73 20 6f 66 20 74 68  ine fields of th
30920 65 20 63 75 72 73 6f 72 20 74 68 61 74 0a 2a 2a  e cursor that.**
30930 20 61 72 65 20 63 6f 6d 6d 6f 6e 20 74 6f 20 61   are common to a
30940 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ll implementatio
30950 6e 73 2e 0a 2a 2f 0a 73 74 72 75 63 74 20 73 71  ns..*/.struct sq
30960 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f  lite3_vtab_curso
30970 72 20 7b 0a 20 20 73 71 6c 69 74 65 33 5f 76 74  r {.  sqlite3_vt
30980 61 62 20 2a 70 56 74 61 62 3b 20 20 20 20 20 20  ab *pVtab;      
30990 2f 2a 20 56 69 72 74 75 61 6c 20 74 61 62 6c 65  /* Virtual table
309a0 20 6f 66 20 74 68 69 73 20 63 75 72 73 6f 72 20   of this cursor 
309b0 2a 2f 0a 20 20 2f 2a 20 56 69 72 74 75 61 6c 20  */.  /* Virtual 
309c0 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61  table implementa
309d0 74 69 6f 6e 73 20 77 69 6c 6c 20 74 79 70 69 63  tions will typic
309e0 61 6c 6c 79 20 61 64 64 20 61 64 64 69 74 69 6f  ally add additio
309f0 6e 61 6c 20 66 69 65 6c 64 73 20 2a 2f 0a 7d 3b  nal fields */.};
30a00 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
30a10 3a 20 44 65 63 6c 61 72 65 20 54 68 65 20 53 63  : Declare The Sc
30a20 68 65 6d 61 20 4f 66 20 41 20 56 69 72 74 75 61  hema Of A Virtua
30a30 6c 20 54 61 62 6c 65 20 7b 48 31 38 32 38 30 7d  l Table {H18280}
30a40 20 3c 53 32 30 34 30 30 3e 0a 2a 2a 20 45 58 50   <S20400>.** EXP
30a50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20  ERIMENTAL.**.** 
30a60 54 68 65 20 5b 78 43 72 65 61 74 65 5d 20 61 6e  The [xCreate] an
30a70 64 20 5b 78 43 6f 6e 6e 65 63 74 5d 20 6d 65 74  d [xConnect] met
30a80 68 6f 64 73 20 6f 66 20 61 0a 2a 2a 20 5b 76 69  hods of a.** [vi
30a90 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75  rtual table modu
30aa0 6c 65 5d 20 63 61 6c 6c 20 74 68 69 73 20 69 6e  le] call this in
30ab0 74 65 72 66 61 63 65 0a 2a 2a 20 74 6f 20 64 65  terface.** to de
30ac0 63 6c 61 72 65 20 74 68 65 20 66 6f 72 6d 61 74  clare the format
30ad0 20 28 74 68 65 20 6e 61 6d 65 73 20 61 6e 64 20   (the names and 
30ae0 64 61 74 61 74 79 70 65 73 20 6f 66 20 74 68 65  datatypes of the
30af0 20 63 6f 6c 75 6d 6e 73 29 20 6f 66 0a 2a 2a 20   columns) of.** 
30b00 74 68 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c  the virtual tabl
30b10 65 73 20 74 68 65 79 20 69 6d 70 6c 65 6d 65 6e  es they implemen
30b20 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 50  t..*/.SQLITE_EXP
30b30 45 52 49 4d 45 4e 54 41 4c 20 69 6e 74 20 73 71  ERIMENTAL int sq
30b40 6c 69 74 65 33 5f 64 65 63 6c 61 72 65 5f 76 74  lite3_declare_vt
30b50 61 62 28 73 71 6c 69 74 65 33 2a 2c 20 63 6f 6e  ab(sqlite3*, con
30b60 73 74 20 63 68 61 72 20 2a 7a 53 51 4c 29 3b 0a  st char *zSQL);.
30b70 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
30b80 20 4f 76 65 72 6c 6f 61 64 20 41 20 46 75 6e 63   Overload A Func
30b90 74 69 6f 6e 20 46 6f 72 20 41 20 56 69 72 74 75  tion For A Virtu
30ba0 61 6c 20 54 61 62 6c 65 20 7b 48 31 38 33 30 30  al Table {H18300
30bb0 7d 20 3c 53 32 30 34 30 30 3e 0a 2a 2a 20 45 58  } <S20400>.** EX
30bc0 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a  PERIMENTAL.**.**
30bd0 20 56 69 72 74 75 61 6c 20 74 61 62 6c 65 73 20   Virtual tables 
30be0 63 61 6e 20 70 72 6f 76 69 64 65 20 61 6c 74 65  can provide alte
30bf0 72 6e 61 74 69 76 65 20 69 6d 70 6c 65 6d 65 6e  rnative implemen
30c00 74 61 74 69 6f 6e 73 20 6f 66 20 66 75 6e 63 74  tations of funct
30c10 69 6f 6e 73 0a 2a 2a 20 75 73 69 6e 67 20 74 68  ions.** using th
30c20 65 20 5b 78 46 69 6e 64 46 75 6e 63 74 69 6f 6e  e [xFindFunction
30c30 5d 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20  ] method of the 
30c40 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d  [virtual table m
30c50 6f 64 75 6c 65 5d 2e 20 20 0a 2a 2a 20 42 75 74  odule].  .** But
30c60 20 67 6c 6f 62 61 6c 20 76 65 72 73 69 6f 6e 73   global versions
30c70 20 6f 66 20 74 68 6f 73 65 20 66 75 6e 63 74 69   of those functi
30c80 6f 6e 73 0a 2a 2a 20 6d 75 73 74 20 65 78 69 73  ons.** must exis
30c90 74 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 62 65  t in order to be
30ca0 20 6f 76 65 72 6c 6f 61 64 65 64 2e 0a 2a 2a 0a   overloaded..**.
30cb0 2a 2a 20 54 68 69 73 20 41 50 49 20 6d 61 6b 65  ** This API make
30cc0 73 20 73 75 72 65 20 61 20 67 6c 6f 62 61 6c 20  s sure a global 
30cd0 76 65 72 73 69 6f 6e 20 6f 66 20 61 20 66 75 6e  version of a fun
30ce0 63 74 69 6f 6e 20 77 69 74 68 20 61 20 70 61 72  ction with a par
30cf0 74 69 63 75 6c 61 72 0a 2a 2a 20 6e 61 6d 65 20  ticular.** name 
30d00 61 6e 64 20 6e 75 6d 62 65 72 20 6f 66 20 70 61  and number of pa
30d10 72 61 6d 65 74 65 72 73 20 65 78 69 73 74 73 2e  rameters exists.
30d20 20 20 49 66 20 6e 6f 20 73 75 63 68 20 66 75 6e    If no such fun
30d30 63 74 69 6f 6e 20 65 78 69 73 74 73 0a 2a 2a 20  ction exists.** 
30d40 62 65 66 6f 72 65 20 74 68 69 73 20 41 50 49 20  before this API 
30d50 69 73 20 63 61 6c 6c 65 64 2c 20 61 20 6e 65 77  is called, a new
30d60 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 72 65   function is cre
30d70 61 74 65 64 2e 20 20 54 68 65 20 69 6d 70 6c 65  ated.  The imple
30d80 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20  mentation.** of 
30d90 74 68 65 20 6e 65 77 20 66 75 6e 63 74 69 6f 6e  the new function
30da0 20 61 6c 77 61 79 73 20 63 61 75 73 65 73 20 61   always causes a
30db0 6e 20 65 78 63 65 70 74 69 6f 6e 20 74 6f 20 62  n exception to b
30dc0 65 20 74 68 72 6f 77 6e 2e 20 20 53 6f 0a 2a 2a  e thrown.  So.**
30dd0 20 74 68 65 20 6e 65 77 20 66 75 6e 63 74 69 6f   the new functio
30de0 6e 20 69 73 20 6e 6f 74 20 67 6f 6f 64 20 66 6f  n is not good fo
30df0 72 20 61 6e 79 74 68 69 6e 67 20 62 79 20 69 74  r anything by it
30e00 73 65 6c 66 2e 20 20 49 74 73 20 6f 6e 6c 79 0a  self.  Its only.
30e10 2a 2a 20 70 75 72 70 6f 73 65 20 69 73 20 74 6f  ** purpose is to
30e20 20 62 65 20 61 20 70 6c 61 63 65 68 6f 6c 64 65   be a placeholde
30e30 72 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20  r function that 
30e40 63 61 6e 20 62 65 20 6f 76 65 72 6c 6f 61 64 65  can be overloade
30e50 64 0a 2a 2a 20 62 79 20 61 20 5b 76 69 72 74 75  d.** by a [virtu
30e60 61 6c 20 74 61 62 6c 65 5d 2e 0a 2a 2f 0a 53 51  al table]..*/.SQ
30e70 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41  LITE_EXPERIMENTA
30e80 4c 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 76  L int sqlite3_ov
30e90 65 72 6c 6f 61 64 5f 66 75 6e 63 74 69 6f 6e 28  erload_function(
30ea0 73 71 6c 69 74 65 33 2a 2c 20 63 6f 6e 73 74 20  sqlite3*, const 
30eb0 63 68 61 72 20 2a 7a 46 75 6e 63 4e 61 6d 65 2c  char *zFuncName,
30ec0 20 69 6e 74 20 6e 41 72 67 29 3b 0a 0a 2f 2a 0a   int nArg);../*.
30ed0 2a 2a 20 54 68 65 20 69 6e 74 65 72 66 61 63 65  ** The interface
30ee0 20 74 6f 20 74 68 65 20 76 69 72 74 75 61 6c 2d   to the virtual-
30ef0 74 61 62 6c 65 20 6d 65 63 68 61 6e 69 73 6d 20  table mechanism 
30f00 64 65 66 69 6e 65 64 20 61 62 6f 76 65 20 28 62  defined above (b
30f10 61 63 6b 20 75 70 0a 2a 2a 20 74 6f 20 61 20 63  ack up.** to a c
30f20 6f 6d 6d 65 6e 74 20 72 65 6d 61 72 6b 61 62 6c  omment remarkabl
30f30 79 20 73 69 6d 69 6c 61 72 20 74 6f 20 74 68 69  y similar to thi
30f40 73 20 6f 6e 65 29 20 69 73 20 63 75 72 72 65 6e  s one) is curren
30f50 74 6c 79 20 63 6f 6e 73 69 64 65 72 65 64 0a 2a  tly considered.*
30f60 2a 20 74 6f 20 62 65 20 65 78 70 65 72 69 6d 65  * to be experime
30f70 6e 74 61 6c 2e 20 20 54 68 65 20 69 6e 74 65 72  ntal.  The inter
30f80 66 61 63 65 20 6d 69 67 68 74 20 63 68 61 6e 67  face might chang
30f90 65 20 69 6e 20 69 6e 63 6f 6d 70 61 74 69 62 6c  e in incompatibl
30fa0 65 20 77 61 79 73 2e 0a 2a 2a 20 49 66 20 74 68  e ways..** If th
30fb0 69 73 20 69 73 20 61 20 70 72 6f 62 6c 65 6d 20  is is a problem 
30fc0 66 6f 72 20 79 6f 75 2c 20 64 6f 20 6e 6f 74 20  for you, do not 
30fd0 75 73 65 20 74 68 65 20 69 6e 74 65 72 66 61 63  use the interfac
30fe0 65 20 61 74 20 74 68 69 73 20 74 69 6d 65 2e 0a  e at this time..
30ff0 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 76  **.** When the v
31000 69 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65 63  irtual-table mec
31010 68 61 6e 69 73 6d 20 73 74 61 62 69 6c 69 7a 65  hanism stabilize
31020 73 2c 20 77 65 20 77 69 6c 6c 20 64 65 63 6c 61  s, we will decla
31030 72 65 20 74 68 65 0a 2a 2a 20 69 6e 74 65 72 66  re the.** interf
31040 61 63 65 20 66 69 78 65 64 2c 20 73 75 70 70 6f  ace fixed, suppo
31050 72 74 20 69 74 20 69 6e 64 65 66 69 6e 69 74 65  rt it indefinite
31060 6c 79 2c 20 61 6e 64 20 72 65 6d 6f 76 65 20 74  ly, and remove t
31070 68 69 73 20 63 6f 6d 6d 65 6e 74 2e 0a 2a 2a 0a  his comment..**.
31080 2a 2a 2a 2a 2a 2a 20 45 58 50 45 52 49 4d 45 4e  ****** EXPERIMEN
31090 54 41 4c 20 2d 20 73 75 62 6a 65 63 74 20 74 6f  TAL - subject to
310a0 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75 74 20   change without 
310b0 6e 6f 74 69 63 65 20 2a 2a 2a 2a 2a 2a 2a 2a 2a  notice *********
310c0 2a 2a 2a 2a 2a 0a 2a 2f 0a 0a 2f 2a 0a 2a 2a 20  *****.*/../*.** 
310d0 43 41 50 49 33 52 45 46 3a 20 41 20 48 61 6e 64  CAPI3REF: A Hand
310e0 6c 65 20 54 6f 20 41 6e 20 4f 70 65 6e 20 42 4c  le To An Open BL
310f0 4f 42 20 7b 48 31 37 38 30 30 7d 20 3c 53 33 30  OB {H17800} <S30
31100 32 33 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  230>.** KEYWORDS
31110 3a 20 7b 42 4c 4f 42 20 68 61 6e 64 6c 65 7d 20  : {BLOB handle} 
31120 7b 42 4c 4f 42 20 68 61 6e 64 6c 65 73 7d 0a 2a  {BLOB handles}.*
31130 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65  *.** An instance
31140 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20   of this object 
31150 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 6f 70  represents an op
31160 65 6e 20 42 4c 4f 42 20 6f 6e 20 77 68 69 63 68  en BLOB on which
31170 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f  .** [sqlite3_blo
31180 62 5f 6f 70 65 6e 20 7c 20 69 6e 63 72 65 6d 65  b_open | increme
31190 6e 74 61 6c 20 42 4c 4f 42 20 49 2f 4f 5d 20 63  ntal BLOB I/O] c
311a0 61 6e 20 62 65 20 70 65 72 66 6f 72 6d 65 64 2e  an be performed.
311b0 0a 2a 2a 20 4f 62 6a 65 63 74 73 20 6f 66 20 74  .** Objects of t
311c0 68 69 73 20 74 79 70 65 20 61 72 65 20 63 72 65  his type are cre
311d0 61 74 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  ated by [sqlite3
311e0 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d 0a 2a 2a  _blob_open()].**
311f0 20 61 6e 64 20 64 65 73 74 72 6f 79 65 64 20 62   and destroyed b
31200 79 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  y [sqlite3_blob_
31210 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 20 54 68 65  close()]..** The
31220 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 72   [sqlite3_blob_r
31230 65 61 64 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  ead()] and [sqli
31240 74 65 33 5f 62 6c 6f 62 5f 77 72 69 74 65 28 29  te3_blob_write()
31250 5d 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  ] interfaces.** 
31260 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 72  can be used to r
31270 65 61 64 20 6f 72 20 77 72 69 74 65 20 73 6d 61  ead or write sma
31280 6c 6c 20 73 75 62 73 65 63 74 69 6f 6e 73 20 6f  ll subsections o
31290 66 20 74 68 65 20 42 4c 4f 42 2e 0a 2a 2a 20 54  f the BLOB..** T
312a0 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  he [sqlite3_blob
312b0 5f 62 79 74 65 73 28 29 5d 20 69 6e 74 65 72 66  _bytes()] interf
312c0 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ace returns the 
312d0 73 69 7a 65 20 6f 66 20 74 68 65 20 42 4c 4f 42  size of the BLOB
312e0 20 69 6e 20 62 79 74 65 73 2e 0a 2a 2f 0a 74 79   in bytes..*/.ty
312f0 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
31300 69 74 65 33 5f 62 6c 6f 62 20 73 71 6c 69 74 65  ite3_blob sqlite
31310 33 5f 62 6c 6f 62 3b 0a 0a 2f 2a 0a 2a 2a 20 43  3_blob;../*.** C
31320 41 50 49 33 52 45 46 3a 20 4f 70 65 6e 20 41 20  API3REF: Open A 
31330 42 4c 4f 42 20 46 6f 72 20 49 6e 63 72 65 6d 65  BLOB For Increme
31340 6e 74 61 6c 20 49 2f 4f 20 7b 48 31 37 38 31 30  ntal I/O {H17810
31350 7d 20 3c 53 33 30 32 33 30 3e 0a 2a 2a 0a 2a 2a  } <S30230>.**.**
31360 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 73   This interfaces
31370 20 6f 70 65 6e 73 20 61 20 5b 42 4c 4f 42 20 68   opens a [BLOB h
31380 61 6e 64 6c 65 20 7c 20 68 61 6e 64 6c 65 5d 20  andle | handle] 
31390 74 6f 20 74 68 65 20 42 4c 4f 42 20 6c 6f 63 61  to the BLOB loca
313a0 74 65 64 0a 2a 2a 20 69 6e 20 72 6f 77 20 69 52  ted.** in row iR
313b0 6f 77 2c 20 63 6f 6c 75 6d 6e 20 7a 43 6f 6c 75  ow, column zColu
313c0 6d 6e 2c 20 74 61 62 6c 65 20 7a 54 61 62 6c 65  mn, table zTable
313d0 20 69 6e 20 64 61 74 61 62 61 73 65 20 7a 44 62   in database zDb
313e0 3b 0a 2a 2a 20 69 6e 20 6f 74 68 65 72 20 77 6f  ;.** in other wo
313f0 72 64 73 2c 20 74 68 65 20 73 61 6d 65 20 42 4c  rds, the same BL
31400 4f 42 20 74 68 61 74 20 77 6f 75 6c 64 20 62 65  OB that would be
31410 20 73 65 6c 65 63 74 65 64 20 62 79 3a 0a 2a 2a   selected by:.**
31420 0a 2a 2a 20 3c 70 72 65 3e 0a 2a 2a 20 20 20 20  .** <pre>.**    
31430 20 53 45 4c 45 43 54 20 7a 43 6f 6c 75 6d 6e 20   SELECT zColumn 
31440 46 52 4f 4d 20 7a 44 62 2e 7a 54 61 62 6c 65 20  FROM zDb.zTable 
31450 57 48 45 52 45 20 5b 72 6f 77 69 64 5d 20 3d 20  WHERE [rowid] = 
31460 69 52 6f 77 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 20  iRow;.** </pre> 
31470 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 49 66 20 74  {END}.**.** If t
31480 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74  he flags paramet
31490 65 72 20 69 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20  er is non-zero, 
314a0 74 68 65 6e 20 74 68 65 20 42 4c 4f 42 20 69 73  then the BLOB is
314b0 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64   opened for read
314c0 0a 2a 2a 20 61 6e 64 20 77 72 69 74 65 20 61 63  .** and write ac
314d0 63 65 73 73 2e 20 49 66 20 69 74 20 69 73 20 7a  cess. If it is z
314e0 65 72 6f 2c 20 74 68 65 20 42 4c 4f 42 20 69 73  ero, the BLOB is
314f0 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64   opened for read
31500 20 61 63 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 4e   access..**.** N
31510 6f 74 65 20 74 68 61 74 20 74 68 65 20 64 61 74  ote that the dat
31520 61 62 61 73 65 20 6e 61 6d 65 20 69 73 20 6e 6f  abase name is no
31530 74 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 74  t the filename t
31540 68 61 74 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20  hat contains.** 
31550 74 68 65 20 64 61 74 61 62 61 73 65 20 62 75 74  the database but
31560 20 72 61 74 68 65 72 20 74 68 65 20 73 79 6d 62   rather the symb
31570 6f 6c 69 63 20 6e 61 6d 65 20 6f 66 20 74 68 65  olic name of the
31580 20 64 61 74 61 62 61 73 65 20 74 68 61 74 0a 2a   database that.*
31590 2a 20 69 73 20 61 73 73 69 67 6e 65 64 20 77 68  * is assigned wh
315a0 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
315b0 69 73 20 63 6f 6e 6e 65 63 74 65 64 20 75 73 69  is connected usi
315c0 6e 67 20 5b 41 54 54 41 43 48 5d 2e 0a 2a 2a 20  ng [ATTACH]..** 
315d0 46 6f 72 20 74 68 65 20 6d 61 69 6e 20 64 61 74  For the main dat
315e0 61 62 61 73 65 20 66 69 6c 65 2c 20 74 68 65 20  abase file, the 
315f0 64 61 74 61 62 61 73 65 20 6e 61 6d 65 20 69 73  database name is
31600 20 22 6d 61 69 6e 22 2e 0a 2a 2a 20 46 6f 72 20   "main"..** For 
31610 54 45 4d 50 20 74 61 62 6c 65 73 2c 20 74 68 65  TEMP tables, the
31620 20 64 61 74 61 62 61 73 65 20 6e 61 6d 65 20 69   database name i
31630 73 20 22 74 65 6d 70 22 2e 0a 2a 2a 0a 2a 2a 20  s "temp"..**.** 
31640 4f 6e 20 73 75 63 63 65 73 73 2c 20 5b 53 51 4c  On success, [SQL
31650 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72  ITE_OK] is retur
31660 6e 65 64 20 61 6e 64 20 74 68 65 20 6e 65 77 20  ned and the new 
31670 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 69 73  [BLOB handle] is
31680 20 77 72 69 74 74 65 6e 0a 2a 2a 20 74 6f 20 2a   written.** to *
31690 70 70 42 6c 6f 62 2e 20 4f 74 68 65 72 77 69 73  ppBlob. Otherwis
316a0 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65  e an [error code
316b0 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 61 6e  ] is returned an
316c0 64 20 2a 70 70 42 6c 6f 62 20 69 73 20 73 65 74  d *ppBlob is set
316d0 0a 2a 2a 20 74 6f 20 62 65 20 61 20 6e 75 6c 6c  .** to be a null
316e0 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 20 54 68 69   pointer..** Thi
316f0 73 20 66 75 6e 63 74 69 6f 6e 20 73 65 74 73 20  s function sets 
31700 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
31710 6e 6e 65 63 74 69 6f 6e 5d 20 65 72 72 6f 72 20  nnection] error 
31720 63 6f 64 65 20 61 6e 64 20 6d 65 73 73 61 67 65  code and message
31730 0a 2a 2a 20 61 63 63 65 73 73 69 62 6c 65 20 76  .** accessible v
31740 69 61 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63  ia [sqlite3_errc
31750 6f 64 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  ode()] and [sqli
31760 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 20 61 6e  te3_errmsg()] an
31770 64 20 72 65 6c 61 74 65 64 0a 2a 2a 20 66 75 6e  d related.** fun
31780 63 74 69 6f 6e 73 2e 20 20 4e 6f 74 65 20 74 68  ctions.  Note th
31790 61 74 20 74 68 65 20 2a 70 70 42 6c 6f 62 20 76  at the *ppBlob v
317a0 61 72 69 61 62 6c 65 20 69 73 20 61 6c 77 61 79  ariable is alway
317b0 73 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 69 6e  s initialized in
317c0 20 61 0a 2a 2a 20 77 61 79 20 74 68 61 74 20 6d   a.** way that m
317d0 61 6b 65 73 20 69 74 20 73 61 66 65 20 74 6f 20  akes it safe to 
317e0 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f  invoke [sqlite3_
317f0 62 6c 6f 62 5f 63 6c 6f 73 65 28 29 5d 20 6f 6e  blob_close()] on
31800 20 2a 70 70 42 6c 6f 62 0a 2a 2a 20 72 65 67 61   *ppBlob.** rega
31810 72 64 6c 65 73 73 20 6f 66 20 74 68 65 20 73 75  rdless of the su
31820 63 63 65 73 73 20 6f 72 20 66 61 69 6c 75 72 65  ccess or failure
31830 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65   of this routine
31840 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 72  ..**.** If the r
31850 6f 77 20 74 68 61 74 20 61 20 42 4c 4f 42 20 68  ow that a BLOB h
31860 61 6e 64 6c 65 20 70 6f 69 6e 74 73 20 74 6f 20  andle points to 
31870 69 73 20 6d 6f 64 69 66 69 65 64 20 62 79 20 61  is modified by a
31880 6e 0a 2a 2a 20 5b 55 50 44 41 54 45 5d 2c 20 5b  n.** [UPDATE], [
31890 44 45 4c 45 54 45 5d 2c 20 6f 72 20 62 79 20 5b  DELETE], or by [
318a0 4f 4e 20 43 4f 4e 46 4c 49 43 54 5d 20 73 69 64  ON CONFLICT] sid
318b0 65 2d 65 66 66 65 63 74 73 0a 2a 2a 20 74 68 65  e-effects.** the
318c0 6e 20 74 68 65 20 42 4c 4f 42 20 68 61 6e 64 6c  n the BLOB handl
318d0 65 20 69 73 20 6d 61 72 6b 65 64 20 61 73 20 22  e is marked as "
318e0 65 78 70 69 72 65 64 22 2e 0a 2a 2a 20 54 68 69  expired"..** Thi
318f0 73 20 69 73 20 74 72 75 65 20 69 66 20 61 6e 79  s is true if any
31900 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72   column of the r
31910 6f 77 20 69 73 20 63 68 61 6e 67 65 64 2c 20 65  ow is changed, e
31920 76 65 6e 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20  ven a column.** 
31930 6f 74 68 65 72 20 74 68 61 6e 20 74 68 65 20 6f  other than the o
31940 6e 65 20 74 68 65 20 42 4c 4f 42 20 68 61 6e 64  ne the BLOB hand
31950 6c 65 20 69 73 20 6f 70 65 6e 20 6f 6e 2e 0a 2a  le is open on..*
31960 2a 20 43 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  * Calls to [sqli
31970 74 65 33 5f 62 6c 6f 62 5f 72 65 61 64 28 29 5d  te3_blob_read()]
31980 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 6c   and [sqlite3_bl
31990 6f 62 5f 77 72 69 74 65 28 29 5d 20 66 6f 72 0a  ob_write()] for.
319a0 2a 2a 20 61 20 65 78 70 69 72 65 64 20 42 4c 4f  ** a expired BLO
319b0 42 20 68 61 6e 64 6c 65 20 66 61 69 6c 20 77 69  B handle fail wi
319c0 74 68 20 61 6e 20 72 65 74 75 72 6e 20 63 6f 64  th an return cod
319d0 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 41 42 4f  e of [SQLITE_ABO
319e0 52 54 5d 2e 0a 2a 2a 20 43 68 61 6e 67 65 73 20  RT]..** Changes 
319f0 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 61 20 42  written into a B
31a00 4c 4f 42 20 70 72 69 6f 72 20 74 6f 20 74 68 65  LOB prior to the
31a10 20 42 4c 4f 42 20 65 78 70 69 72 69 6e 67 20 61   BLOB expiring a
31a20 72 65 20 6e 6f 74 0a 2a 2a 20 72 6f 6c 6c 62 61  re not.** rollba
31a30 63 6b 20 62 79 20 74 68 65 20 65 78 70 69 72 61  ck by the expira
31a40 74 69 6f 6e 20 6f 66 20 74 68 65 20 42 4c 4f 42  tion of the BLOB
31a50 2e 20 20 53 75 63 68 20 63 68 61 6e 67 65 73 20  .  Such changes 
31a60 77 69 6c 6c 20 65 76 65 6e 74 75 61 6c 6c 79 0a  will eventually.
31a70 2a 2a 20 63 6f 6d 6d 69 74 20 69 66 20 74 68 65  ** commit if the
31a80 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e   transaction con
31a90 74 69 6e 75 65 73 20 74 6f 20 63 6f 6d 70 6c 65  tinues to comple
31aa0 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 55 73 65 20  tion..**.** Use 
31ab0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f  the [sqlite3_blo
31ac0 62 5f 62 79 74 65 73 28 29 5d 20 69 6e 74 65 72  b_bytes()] inter
31ad0 66 61 63 65 20 74 6f 20 64 65 74 65 72 6d 69 6e  face to determin
31ae0 65 20 74 68 65 20 73 69 7a 65 20 6f 66 0a 2a 2a  e the size of.**
31af0 20 74 68 65 20 6f 70 65 6e 65 64 20 62 6c 6f 62   the opened blob
31b00 2e 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20 61  .  The size of a
31b10 20 62 6c 6f 62 20 6d 61 79 20 6e 6f 74 20 62 65   blob may not be
31b20 20 63 68 61 6e 67 65 64 20 62 79 20 74 68 69 73   changed by this
31b30 0a 2a 2a 20 75 6e 64 65 72 66 61 63 65 2e 20 20  .** underface.  
31b40 55 73 65 20 74 68 65 20 5b 55 50 44 41 54 45 5d  Use the [UPDATE]
31b50 20 53 51 4c 20 63 6f 6d 6d 61 6e 64 20 74 6f 20   SQL command to 
31b60 63 68 61 6e 67 65 20 74 68 65 20 73 69 7a 65 20  change the size 
31b70 6f 66 20 61 0a 2a 2a 20 62 6c 6f 62 2e 0a 2a 2a  of a.** blob..**
31b80 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33  .** The [sqlite3
31b90 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 29  _bind_zeroblob()
31ba0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72  ] and [sqlite3_r
31bb0 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 29  esult_zeroblob()
31bc0 5d 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  ] interfaces.** 
31bd0 61 6e 64 20 74 68 65 20 62 75 69 6c 74 2d 69 6e  and the built-in
31be0 20 5b 7a 65 72 6f 62 6c 6f 62 5d 20 53 51 4c 20   [zeroblob] SQL 
31bf0 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20 62 65 20  function can be 
31c00 75 73 65 64 2c 20 69 66 20 64 65 73 69 72 65 64  used, if desired
31c10 2c 0a 2a 2a 20 74 6f 20 63 72 65 61 74 65 20 61  ,.** to create a
31c20 6e 20 65 6d 70 74 79 2c 20 7a 65 72 6f 2d 66 69  n empty, zero-fi
31c30 6c 6c 65 64 20 62 6c 6f 62 20 69 6e 20 77 68 69  lled blob in whi
31c40 63 68 20 74 6f 20 72 65 61 64 20 6f 72 20 77 72  ch to read or wr
31c50 69 74 65 20 75 73 69 6e 67 0a 2a 2a 20 74 68 69  ite using.** thi
31c60 73 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a  s interface..**.
31c70 2a 2a 20 54 6f 20 61 76 6f 69 64 20 61 20 72 65  ** To avoid a re
31c80 73 6f 75 72 63 65 20 6c 65 61 6b 2c 20 65 76 65  source leak, eve
31c90 72 79 20 6f 70 65 6e 20 5b 42 4c 4f 42 20 68 61  ry open [BLOB ha
31ca0 6e 64 6c 65 5d 20 73 68 6f 75 6c 64 20 65 76 65  ndle] should eve
31cb0 6e 74 75 61 6c 6c 79 0a 2a 2a 20 62 65 20 72 65  ntually.** be re
31cc0 6c 65 61 73 65 64 20 62 79 20 61 20 63 61 6c 6c  leased by a call
31cd0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f   to [sqlite3_blo
31ce0 62 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 0a 2a  b_close()]..**.*
31cf0 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a  * Requirements:.
31d00 2a 2a 20 5b 48 31 37 38 31 33 5d 20 5b 48 31 37  ** [H17813] [H17
31d10 38 31 34 5d 20 5b 48 31 37 38 31 36 5d 20 5b 48  814] [H17816] [H
31d20 31 37 38 31 39 5d 20 5b 48 31 37 38 32 31 5d 20  17819] [H17821] 
31d30 5b 48 31 37 38 32 34 5d 0a 2a 2f 0a 69 6e 74 20  [H17824].*/.int 
31d40 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65  sqlite3_blob_ope
31d50 6e 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20  n(.  sqlite3*,. 
31d60 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44 62   const char *zDb
31d70 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  ,.  const char *
31d80 7a 54 61 62 6c 65 2c 0a 20 20 63 6f 6e 73 74 20  zTable,.  const 
31d90 63 68 61 72 20 2a 7a 43 6f 6c 75 6d 6e 2c 0a 20  char *zColumn,. 
31da0 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69   sqlite3_int64 i
31db0 52 6f 77 2c 0a 20 20 69 6e 74 20 66 6c 61 67 73  Row,.  int flags
31dc0 2c 0a 20 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62  ,.  sqlite3_blob
31dd0 20 2a 2a 70 70 42 6c 6f 62 0a 29 3b 0a 0a 2f 2a   **ppBlob.);../*
31de0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6c  .** CAPI3REF: Cl
31df0 6f 73 65 20 41 20 42 4c 4f 42 20 48 61 6e 64 6c  ose A BLOB Handl
31e00 65 20 7b 48 31 37 38 33 30 7d 20 3c 53 33 30 32  e {H17830} <S302
31e10 33 30 3e 0a 2a 2a 0a 2a 2a 20 43 6c 6f 73 65 73  30>.**.** Closes
31e20 20 61 6e 20 6f 70 65 6e 20 5b 42 4c 4f 42 20 68   an open [BLOB h
31e30 61 6e 64 6c 65 5d 2e 0a 2a 2a 0a 2a 2a 20 43 6c  andle]..**.** Cl
31e40 6f 73 69 6e 67 20 61 20 42 4c 4f 42 20 73 68 61  osing a BLOB sha
31e50 6c 6c 20 63 61 75 73 65 20 74 68 65 20 63 75 72  ll cause the cur
31e60 72 65 6e 74 20 74 72 61 6e 73 61 63 74 69 6f 6e  rent transaction
31e70 20 74 6f 20 63 6f 6d 6d 69 74 0a 2a 2a 20 69 66   to commit.** if
31e80 20 74 68 65 72 65 20 61 72 65 20 6e 6f 20 6f 74   there are no ot
31e90 68 65 72 20 42 4c 4f 42 73 2c 20 6e 6f 20 70 65  her BLOBs, no pe
31ea0 6e 64 69 6e 67 20 70 72 65 70 61 72 65 64 20 73  nding prepared s
31eb0 74 61 74 65 6d 65 6e 74 73 2c 20 61 6e 64 20 74  tatements, and t
31ec0 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63  he.** database c
31ed0 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 69 6e 20  onnection is in 
31ee0 5b 61 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65  [autocommit mode
31ef0 5d 2e 0a 2a 2a 20 49 66 20 61 6e 79 20 77 72 69  ]..** If any wri
31f00 74 65 73 20 77 65 72 65 20 6d 61 64 65 20 74 6f  tes were made to
31f10 20 74 68 65 20 42 4c 4f 42 2c 20 74 68 65 79 20   the BLOB, they 
31f20 6d 69 67 68 74 20 62 65 20 68 65 6c 64 20 69 6e  might be held in
31f30 20 63 61 63 68 65 0a 2a 2a 20 75 6e 74 69 6c 20   cache.** until 
31f40 74 68 65 20 63 6c 6f 73 65 20 6f 70 65 72 61 74  the close operat
31f50 69 6f 6e 20 69 66 20 74 68 65 79 20 77 69 6c 6c  ion if they will
31f60 20 66 69 74 2e 0a 2a 2a 0a 2a 2a 20 43 6c 6f 73   fit..**.** Clos
31f70 69 6e 67 20 74 68 65 20 42 4c 4f 42 20 6f 66 74  ing the BLOB oft
31f80 65 6e 20 66 6f 72 63 65 73 20 74 68 65 20 63 68  en forces the ch
31f90 61 6e 67 65 73 0a 2a 2a 20 6f 75 74 20 74 6f 20  anges.** out to 
31fa0 64 69 73 6b 20 61 6e 64 20 73 6f 20 69 66 20 61  disk and so if a
31fb0 6e 79 20 49 2f 4f 20 65 72 72 6f 72 73 20 6f 63  ny I/O errors oc
31fc0 63 75 72 2c 20 74 68 65 79 20 77 69 6c 6c 20 6c  cur, they will l
31fd0 69 6b 65 6c 79 20 6f 63 63 75 72 0a 2a 2a 20 61  ikely occur.** a
31fe0 74 20 74 68 65 20 74 69 6d 65 20 77 68 65 6e 20  t the time when 
31ff0 74 68 65 20 42 4c 4f 42 20 69 73 20 63 6c 6f 73  the BLOB is clos
32000 65 64 2e 20 20 41 6e 79 20 65 72 72 6f 72 73 20  ed.  Any errors 
32010 74 68 61 74 20 6f 63 63 75 72 20 64 75 72 69 6e  that occur durin
32020 67 0a 2a 2a 20 63 6c 6f 73 69 6e 67 20 61 72 65  g.** closing are
32030 20 72 65 70 6f 72 74 65 64 20 61 73 20 61 20 6e   reported as a n
32040 6f 6e 2d 7a 65 72 6f 20 72 65 74 75 72 6e 20 76  on-zero return v
32050 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  alue..**.** The 
32060 42 4c 4f 42 20 69 73 20 63 6c 6f 73 65 64 20 75  BLOB is closed u
32070 6e 63 6f 6e 64 69 74 69 6f 6e 61 6c 6c 79 2e 20  nconditionally. 
32080 20 45 76 65 6e 20 69 66 20 74 68 69 73 20 72 6f   Even if this ro
32090 75 74 69 6e 65 20 72 65 74 75 72 6e 73 0a 2a 2a  utine returns.**
320a0 20 61 6e 20 65 72 72 6f 72 20 63 6f 64 65 2c 20   an error code, 
320b0 74 68 65 20 42 4c 4f 42 20 69 73 20 73 74 69 6c  the BLOB is stil
320c0 6c 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20  l closed..**.** 
320d0 43 61 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f 75  Calling this rou
320e0 74 69 6e 65 20 77 69 74 68 20 61 20 6e 75 6c 6c  tine with a null
320f0 20 70 6f 69 6e 74 65 72 20 28 77 68 69 63 68 20   pointer (which 
32100 61 73 20 77 6f 75 6c 64 20 62 65 20 72 65 74 75  as would be retu
32110 72 6e 65 64 0a 2a 2a 20 62 79 20 66 61 69 6c 65  rned.** by faile
32120 64 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  d call to [sqlit
32130 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d 29  e3_blob_open()])
32140 20 69 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e   is a harmless n
32150 6f 2d 6f 70 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75  o-op..**.** Requ
32160 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31  irements:.** [H1
32170 37 38 33 33 5d 20 5b 48 31 37 38 33 36 5d 20 5b  7833] [H17836] [
32180 48 31 37 38 33 39 5d 0a 2a 2f 0a 69 6e 74 20 73  H17839].*/.int s
32190 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73  qlite3_blob_clos
321a0 65 28 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 2a  e(sqlite3_blob *
321b0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
321c0 45 46 3a 20 52 65 74 75 72 6e 20 54 68 65 20 53  EF: Return The S
321d0 69 7a 65 20 4f 66 20 41 6e 20 4f 70 65 6e 20 42  ize Of An Open B
321e0 4c 4f 42 20 7b 48 31 37 38 34 30 7d 20 3c 53 33  LOB {H17840} <S3
321f0 30 32 33 30 3e 0a 2a 2a 0a 2a 2a 20 52 65 74 75  0230>.**.** Retu
32200 72 6e 73 20 74 68 65 20 73 69 7a 65 20 69 6e 20  rns the size in 
32210 62 79 74 65 73 20 6f 66 20 74 68 65 20 42 4c 4f  bytes of the BLO
32220 42 20 61 63 63 65 73 73 69 62 6c 65 20 76 69 61  B accessible via
32230 20 74 68 65 20 0a 2a 2a 20 73 75 63 63 65 73 73   the .** success
32240 66 75 6c 6c 79 20 6f 70 65 6e 65 64 20 5b 42 4c  fully opened [BL
32250 4f 42 20 68 61 6e 64 6c 65 5d 20 69 6e 20 69 74  OB handle] in it
32260 73 20 6f 6e 6c 79 20 61 72 67 75 6d 65 6e 74 2e  s only argument.
32270 20 20 54 68 65 0a 2a 2a 20 69 6e 63 72 65 6d 65    The.** increme
32280 6e 74 61 6c 20 62 6c 6f 62 20 49 2f 4f 20 72 6f  ntal blob I/O ro
32290 75 74 69 6e 65 73 20 63 61 6e 20 6f 6e 6c 79 20  utines can only 
322a0 72 65 61 64 20 6f 72 20 6f 76 65 72 77 72 69 74  read or overwrit
322b0 69 6e 67 20 65 78 69 73 74 69 6e 67 0a 2a 2a 20  ing existing.** 
322c0 62 6c 6f 62 20 63 6f 6e 74 65 6e 74 3b 20 74 68  blob content; th
322d0 65 79 20 63 61 6e 6e 6f 74 20 63 68 61 6e 67 65  ey cannot change
322e0 20 74 68 65 20 73 69 7a 65 20 6f 66 20 61 20 62   the size of a b
322f0 6c 6f 62 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  lob..**.** This 
32300 72 6f 75 74 69 6e 65 20 6f 6e 6c 79 20 77 6f 72  routine only wor
32310 6b 73 20 6f 6e 20 61 20 5b 42 4c 4f 42 20 68 61  ks on a [BLOB ha
32320 6e 64 6c 65 5d 20 77 68 69 63 68 20 68 61 73 20  ndle] which has 
32330 62 65 65 6e 20 63 72 65 61 74 65 64 0a 2a 2a 20  been created.** 
32340 62 79 20 61 20 70 72 69 6f 72 20 73 75 63 63 65  by a prior succe
32350 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73  ssful call to [s
32360 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e  qlite3_blob_open
32370 28 29 5d 20 61 6e 64 20 77 68 69 63 68 20 68 61  ()] and which ha
32380 73 20 6e 6f 74 0a 2a 2a 20 62 65 65 6e 20 63 6c  s not.** been cl
32390 6f 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  osed by [sqlite3
323a0 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 29 5d 2e 20  _blob_close()]. 
323b0 20 50 61 73 73 69 6e 67 20 61 6e 79 20 6f 74 68   Passing any oth
323c0 65 72 20 70 6f 69 6e 74 65 72 20 69 6e 0a 2a 2a  er pointer in.**
323d0 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65   to this routine
323e0 20 72 65 73 75 6c 74 73 20 69 6e 20 75 6e 64 65   results in unde
323f0 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62  fined and probab
32400 6c 79 20 75 6e 64 65 73 69 72 61 62 6c 65 20 62  ly undesirable b
32410 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 52  ehavior..**.** R
32420 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20  equirements:.** 
32430 5b 48 31 37 38 34 33 5d 0a 2a 2f 0a 69 6e 74 20  [H17843].*/.int 
32440 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 62 79 74  sqlite3_blob_byt
32450 65 73 28 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20  es(sqlite3_blob 
32460 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
32470 52 45 46 3a 20 52 65 61 64 20 44 61 74 61 20 46  REF: Read Data F
32480 72 6f 6d 20 41 20 42 4c 4f 42 20 49 6e 63 72 65  rom A BLOB Incre
32490 6d 65 6e 74 61 6c 6c 79 20 7b 48 31 37 38 35 30  mentally {H17850
324a0 7d 20 3c 53 33 30 32 33 30 3e 0a 2a 2a 0a 2a 2a  } <S30230>.**.**
324b0 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 69   This function i
324c0 73 20 75 73 65 64 20 74 6f 20 72 65 61 64 20 64  s used to read d
324d0 61 74 61 20 66 72 6f 6d 20 61 6e 20 6f 70 65 6e  ata from an open
324e0 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 69   [BLOB handle] i
324f0 6e 74 6f 20 61 0a 2a 2a 20 63 61 6c 6c 65 72 2d  nto a.** caller-
32500 73 75 70 70 6c 69 65 64 20 62 75 66 66 65 72 2e  supplied buffer.
32510 20 4e 20 62 79 74 65 73 20 6f 66 20 64 61 74 61   N bytes of data
32520 20 61 72 65 20 63 6f 70 69 65 64 20 69 6e 74 6f   are copied into
32530 20 62 75 66 66 65 72 20 5a 0a 2a 2a 20 66 72 6f   buffer Z.** fro
32540 6d 20 74 68 65 20 6f 70 65 6e 20 42 4c 4f 42 2c  m the open BLOB,
32550 20 73 74 61 72 74 69 6e 67 20 61 74 20 6f 66 66   starting at off
32560 73 65 74 20 69 4f 66 66 73 65 74 2e 0a 2a 2a 0a  set iOffset..**.
32570 2a 2a 20 49 66 20 6f 66 66 73 65 74 20 69 4f 66  ** If offset iOf
32580 66 73 65 74 20 69 73 20 6c 65 73 73 20 74 68 61  fset is less tha
32590 6e 20 4e 20 62 79 74 65 73 20 66 72 6f 6d 20 74  n N bytes from t
325a0 68 65 20 65 6e 64 20 6f 66 20 74 68 65 20 42 4c  he end of the BL
325b0 4f 42 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45  OB,.** [SQLITE_E
325c0 52 52 4f 52 5d 20 69 73 20 72 65 74 75 72 6e 65  RROR] is returne
325d0 64 20 61 6e 64 20 6e 6f 20 64 61 74 61 20 69 73  d and no data is
325e0 20 72 65 61 64 2e 20 20 49 66 20 4e 20 6f 72 20   read.  If N or 
325f0 69 4f 66 66 73 65 74 20 69 73 0a 2a 2a 20 6c 65  iOffset is.** le
32600 73 73 20 74 68 61 6e 20 7a 65 72 6f 2c 20 5b 53  ss than zero, [S
32610 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 73 20  QLITE_ERROR] is 
32620 72 65 74 75 72 6e 65 64 20 61 6e 64 20 6e 6f 20  returned and no 
32630 64 61 74 61 20 69 73 20 72 65 61 64 2e 0a 2a 2a  data is read..**
32640 20 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   The size of the
32650 20 62 6c 6f 62 20 28 61 6e 64 20 68 65 6e 63 65   blob (and hence
32660 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 76 61 6c   the maximum val
32670 75 65 20 6f 66 20 4e 2b 69 4f 66 66 73 65 74 29  ue of N+iOffset)
32680 0a 2a 2a 20 63 61 6e 20 62 65 20 64 65 74 65 72  .** can be deter
32690 6d 69 6e 65 64 20 75 73 69 6e 67 20 74 68 65 20  mined using the 
326a0 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 62 79  [sqlite3_blob_by
326b0 74 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65  tes()] interface
326c0 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 74 74 65 6d  ..**.** An attem
326d0 70 74 20 74 6f 20 72 65 61 64 20 66 72 6f 6d 20  pt to read from 
326e0 61 6e 20 65 78 70 69 72 65 64 20 5b 42 4c 4f 42  an expired [BLOB
326f0 20 68 61 6e 64 6c 65 5d 20 66 61 69 6c 73 20 77   handle] fails w
32700 69 74 68 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 20  ith an.** error 
32710 63 6f 64 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f  code of [SQLITE_
32720 41 42 4f 52 54 5d 2e 0a 2a 2a 0a 2a 2a 20 4f 6e  ABORT]..**.** On
32730 20 73 75 63 63 65 73 73 2c 20 53 51 4c 49 54 45   success, SQLITE
32740 5f 4f 4b 20 69 73 20 72 65 74 75 72 6e 65 64 2e  _OK is returned.
32750 0a 2a 2a 20 4f 74 68 65 72 77 69 73 65 2c 20 61  .** Otherwise, a
32760 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f  n [error code] o
32770 72 20 61 6e 20 5b 65 78 74 65 6e 64 65 64 20 65  r an [extended e
32780 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65  rror code] is re
32790 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  turned..**.** Th
327a0 69 73 20 72 6f 75 74 69 6e 65 20 6f 6e 6c 79 20  is routine only 
327b0 77 6f 72 6b 73 20 6f 6e 20 61 20 5b 42 4c 4f 42  works on a [BLOB
327c0 20 68 61 6e 64 6c 65 5d 20 77 68 69 63 68 20 68   handle] which h
327d0 61 73 20 62 65 65 6e 20 63 72 65 61 74 65 64 0a  as been created.
327e0 2a 2a 20 62 79 20 61 20 70 72 69 6f 72 20 73 75  ** by a prior su
327f0 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f  ccessful call to
32800 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f   [sqlite3_blob_o
32810 70 65 6e 28 29 5d 20 61 6e 64 20 77 68 69 63 68  pen()] and which
32820 20 68 61 73 20 6e 6f 74 0a 2a 2a 20 62 65 65 6e   has not.** been
32830 20 63 6c 6f 73 65 64 20 62 79 20 5b 73 71 6c 69   closed by [sqli
32840 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 29  te3_blob_close()
32850 5d 2e 20 20 50 61 73 73 69 6e 67 20 61 6e 79 20  ].  Passing any 
32860 6f 74 68 65 72 20 70 6f 69 6e 74 65 72 20 69 6e  other pointer in
32870 0a 2a 2a 20 74 6f 20 74 68 69 73 20 72 6f 75 74  .** to this rout
32880 69 6e 65 20 72 65 73 75 6c 74 73 20 69 6e 20 75  ine results in u
32890 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f  ndefined and pro
328a0 62 61 62 6c 79 20 75 6e 64 65 73 69 72 61 62 6c  bably undesirabl
328b0 65 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a  e behavior..**.*
328c0 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
328d0 69 74 65 33 5f 62 6c 6f 62 5f 77 72 69 74 65 28  ite3_blob_write(
328e0 29 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72  )]..**.** Requir
328f0 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 37 38  ements:.** [H178
32900 35 33 5d 20 5b 48 31 37 38 35 36 5d 20 5b 48 31  53] [H17856] [H1
32910 37 38 35 39 5d 20 5b 48 31 37 38 36 32 5d 20 5b  7859] [H17862] [
32920 48 31 37 38 36 33 5d 20 5b 48 31 37 38 36 35 5d  H17863] [H17865]
32930 20 5b 48 31 37 38 36 38 5d 0a 2a 2f 0a 69 6e 74   [H17868].*/.int
32940 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 72 65   sqlite3_blob_re
32950 61 64 28 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20  ad(sqlite3_blob 
32960 2a 2c 20 76 6f 69 64 20 2a 5a 2c 20 69 6e 74 20  *, void *Z, int 
32970 4e 2c 20 69 6e 74 20 69 4f 66 66 73 65 74 29 3b  N, int iOffset);
32980 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
32990 3a 20 57 72 69 74 65 20 44 61 74 61 20 49 6e 74  : Write Data Int
329a0 6f 20 41 20 42 4c 4f 42 20 49 6e 63 72 65 6d 65  o A BLOB Increme
329b0 6e 74 61 6c 6c 79 20 7b 48 31 37 38 37 30 7d 20  ntally {H17870} 
329c0 3c 53 33 30 32 33 30 3e 0a 2a 2a 0a 2a 2a 20 54  <S30230>.**.** T
329d0 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  his function is 
329e0 75 73 65 64 20 74 6f 20 77 72 69 74 65 20 64 61  used to write da
329f0 74 61 20 69 6e 74 6f 20 61 6e 20 6f 70 65 6e 20  ta into an open 
32a00 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 66 72  [BLOB handle] fr
32a10 6f 6d 20 61 0a 2a 2a 20 63 61 6c 6c 65 72 2d 73  om a.** caller-s
32a20 75 70 70 6c 69 65 64 20 62 75 66 66 65 72 2e 20  upplied buffer. 
32a30 4e 20 62 79 74 65 73 20 6f 66 20 64 61 74 61 20  N bytes of data 
32a40 61 72 65 20 63 6f 70 69 65 64 20 66 72 6f 6d 20  are copied from 
32a50 74 68 65 20 62 75 66 66 65 72 20 5a 0a 2a 2a 20  the buffer Z.** 
32a60 69 6e 74 6f 20 74 68 65 20 6f 70 65 6e 20 42 4c  into the open BL
32a70 4f 42 2c 20 73 74 61 72 74 69 6e 67 20 61 74 20  OB, starting at 
32a80 6f 66 66 73 65 74 20 69 4f 66 66 73 65 74 2e 0a  offset iOffset..
32a90 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 5b 42 4c  **.** If the [BL
32aa0 4f 42 20 68 61 6e 64 6c 65 5d 20 70 61 73 73 65  OB handle] passe
32ab0 64 20 61 73 20 74 68 65 20 66 69 72 73 74 20 61  d as the first a
32ac0 72 67 75 6d 65 6e 74 20 77 61 73 20 6e 6f 74 20  rgument was not 
32ad0 6f 70 65 6e 65 64 20 66 6f 72 0a 2a 2a 20 77 72  opened for.** wr
32ae0 69 74 69 6e 67 20 28 74 68 65 20 66 6c 61 67 73  iting (the flags
32af0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73   parameter to [s
32b00 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e  qlite3_blob_open
32b10 28 29 5d 20 77 61 73 20 7a 65 72 6f 29 2c 0a 2a  ()] was zero),.*
32b20 2a 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20  * this function 
32b30 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
32b40 52 45 41 44 4f 4e 4c 59 5d 2e 0a 2a 2a 0a 2a 2a  READONLY]..**.**
32b50 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 6d   This function m
32b60 61 79 20 6f 6e 6c 79 20 6d 6f 64 69 66 79 20 74  ay only modify t
32b70 68 65 20 63 6f 6e 74 65 6e 74 73 20 6f 66 20 74  he contents of t
32b80 68 65 20 42 4c 4f 42 3b 20 69 74 20 69 73 0a 2a  he BLOB; it is.*
32b90 2a 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74  * not possible t
32ba0 6f 20 69 6e 63 72 65 61 73 65 20 74 68 65 20 73  o increase the s
32bb0 69 7a 65 20 6f 66 20 61 20 42 4c 4f 42 20 75 73  ize of a BLOB us
32bc0 69 6e 67 20 74 68 69 73 20 41 50 49 2e 0a 2a 2a  ing this API..**
32bd0 20 49 66 20 6f 66 66 73 65 74 20 69 4f 66 66 73   If offset iOffs
32be0 65 74 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20  et is less than 
32bf0 4e 20 62 79 74 65 73 20 66 72 6f 6d 20 74 68 65  N bytes from the
32c00 20 65 6e 64 20 6f 66 20 74 68 65 20 42 4c 4f 42   end of the BLOB
32c10 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52  ,.** [SQLITE_ERR
32c20 4f 52 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20  OR] is returned 
32c30 61 6e 64 20 6e 6f 20 64 61 74 61 20 69 73 20 77  and no data is w
32c40 72 69 74 74 65 6e 2e 20 20 49 66 20 4e 20 69 73  ritten.  If N is
32c50 0a 2a 2a 20 6c 65 73 73 20 74 68 61 6e 20 7a 65  .** less than ze
32c60 72 6f 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  ro [SQLITE_ERROR
32c70 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 61 6e  ] is returned an
32c80 64 20 6e 6f 20 64 61 74 61 20 69 73 20 77 72 69  d no data is wri
32c90 74 74 65 6e 2e 0a 2a 2a 20 54 68 65 20 73 69 7a  tten..** The siz
32ca0 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 28 61  e of the BLOB (a
32cb0 6e 64 20 68 65 6e 63 65 20 74 68 65 20 6d 61 78  nd hence the max
32cc0 69 6d 75 6d 20 76 61 6c 75 65 20 6f 66 20 4e 2b  imum value of N+
32cd0 69 4f 66 66 73 65 74 29 0a 2a 2a 20 63 61 6e 20  iOffset).** can 
32ce0 62 65 20 64 65 74 65 72 6d 69 6e 65 64 20 75 73  be determined us
32cf0 69 6e 67 20 74 68 65 20 5b 73 71 6c 69 74 65 33  ing the [sqlite3
32d00 5f 62 6c 6f 62 5f 62 79 74 65 73 28 29 5d 20 69  _blob_bytes()] i
32d10 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  nterface..**.** 
32d20 41 6e 20 61 74 74 65 6d 70 74 20 74 6f 20 77 72  An attempt to wr
32d30 69 74 65 20 74 6f 20 61 6e 20 65 78 70 69 72 65  ite to an expire
32d40 64 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20  d [BLOB handle] 
32d50 66 61 69 6c 73 20 77 69 74 68 20 61 6e 0a 2a 2a  fails with an.**
32d60 20 65 72 72 6f 72 20 63 6f 64 65 20 6f 66 20 5b   error code of [
32d70 53 51 4c 49 54 45 5f 41 42 4f 52 54 5d 2e 20 20  SQLITE_ABORT].  
32d80 57 72 69 74 65 73 20 74 6f 20 74 68 65 20 42 4c  Writes to the BL
32d90 4f 42 20 74 68 61 74 20 6f 63 63 75 72 72 65 64  OB that occurred
32da0 0a 2a 2a 20 62 65 66 6f 72 65 20 74 68 65 20 5b  .** before the [
32db0 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 65 78 70  BLOB handle] exp
32dc0 69 72 65 64 20 61 72 65 20 6e 6f 74 20 72 6f 6c  ired are not rol
32dd0 6c 65 64 20 62 61 63 6b 20 62 79 20 74 68 65 0a  led back by the.
32de0 2a 2a 20 65 78 70 69 72 61 74 69 6f 6e 20 6f 66  ** expiration of
32df0 20 74 68 65 20 68 61 6e 64 6c 65 2c 20 74 68 6f   the handle, tho
32e00 75 67 68 20 6f 66 20 63 6f 75 72 73 65 20 74 68  ugh of course th
32e10 6f 73 65 20 63 68 61 6e 67 65 73 20 6d 69 67 68  ose changes migh
32e20 74 0a 2a 2a 20 68 61 76 65 20 62 65 65 6e 20 6f  t.** have been o
32e30 76 65 72 77 72 69 74 74 65 6e 20 62 79 20 74 68  verwritten by th
32e40 65 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74  e statement that
32e50 20 65 78 70 69 72 65 64 20 74 68 65 20 42 4c 4f   expired the BLO
32e60 42 20 68 61 6e 64 6c 65 0a 2a 2a 20 6f 72 20 62  B handle.** or b
32e70 79 20 6f 74 68 65 72 20 69 6e 64 65 70 65 6e 64  y other independ
32e80 65 6e 74 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a  ent statements..
32e90 2a 2a 0a 2a 2a 20 4f 6e 20 73 75 63 63 65 73 73  **.** On success
32ea0 2c 20 53 51 4c 49 54 45 5f 4f 4b 20 69 73 20 72  , SQLITE_OK is r
32eb0 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 4f 74 68 65  eturned..** Othe
32ec0 72 77 69 73 65 2c 20 61 6e 20 20 5b 65 72 72 6f  rwise, an  [erro
32ed0 72 20 63 6f 64 65 5d 20 6f 72 20 61 6e 20 5b 65  r code] or an [e
32ee0 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f  xtended error co
32ef0 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e  de] is returned.
32f00 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74  .**.** This rout
32f10 69 6e 65 20 6f 6e 6c 79 20 77 6f 72 6b 73 20 6f  ine only works o
32f20 6e 20 61 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65  n a [BLOB handle
32f30 5d 20 77 68 69 63 68 20 68 61 73 20 62 65 65 6e  ] which has been
32f40 20 63 72 65 61 74 65 64 0a 2a 2a 20 62 79 20 61   created.** by a
32f50 20 70 72 69 6f 72 20 73 75 63 63 65 73 73 66 75   prior successfu
32f60 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  l call to [sqlit
32f70 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d 20  e3_blob_open()] 
32f80 61 6e 64 20 77 68 69 63 68 20 68 61 73 20 6e 6f  and which has no
32f90 74 0a 2a 2a 20 62 65 65 6e 20 63 6c 6f 73 65 64  t.** been closed
32fa0 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f   by [sqlite3_blo
32fb0 62 5f 63 6c 6f 73 65 28 29 5d 2e 20 20 50 61 73  b_close()].  Pas
32fc0 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 70  sing any other p
32fd0 6f 69 6e 74 65 72 20 69 6e 0a 2a 2a 20 74 6f 20  ointer in.** to 
32fe0 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 73  this routine res
32ff0 75 6c 74 73 20 69 6e 20 75 6e 64 65 66 69 6e 65  ults in undefine
33000 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 75  d and probably u
33010 6e 64 65 73 69 72 61 62 6c 65 20 62 65 68 61 76  ndesirable behav
33020 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ior..**.** See a
33030 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 6c  lso: [sqlite3_bl
33040 6f 62 5f 72 65 61 64 28 29 5d 2e 0a 2a 2a 0a 2a  ob_read()]..**.*
33050 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a  * Requirements:.
33060 2a 2a 20 5b 48 31 37 38 37 33 5d 20 5b 48 31 37  ** [H17873] [H17
33070 38 37 34 5d 20 5b 48 31 37 38 37 35 5d 20 5b 48  874] [H17875] [H
33080 31 37 38 37 36 5d 20 5b 48 31 37 38 37 37 5d 20  17876] [H17877] 
33090 5b 48 31 37 38 37 39 5d 20 5b 48 31 37 38 38 32  [H17879] [H17882
330a0 5d 20 5b 48 31 37 38 38 35 5d 0a 2a 2a 20 5b 48  ] [H17885].** [H
330b0 31 37 38 38 38 5d 0a 2a 2f 0a 69 6e 74 20 73 71  17888].*/.int sq
330c0 6c 69 74 65 33 5f 62 6c 6f 62 5f 77 72 69 74 65  lite3_blob_write
330d0 28 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 2a 2c  (sqlite3_blob *,
330e0 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 2c 20   const void *z, 
330f0 69 6e 74 20 6e 2c 20 69 6e 74 20 69 4f 66 66 73  int n, int iOffs
33100 65 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  et);../*.** CAPI
33110 33 52 45 46 3a 20 56 69 72 74 75 61 6c 20 46 69  3REF: Virtual Fi
33120 6c 65 20 53 79 73 74 65 6d 20 4f 62 6a 65 63 74  le System Object
33130 73 20 7b 48 31 31 32 30 30 7d 20 3c 53 32 30 31  s {H11200} <S201
33140 30 30 3e 0a 2a 2a 0a 2a 2a 20 41 20 76 69 72 74  00>.**.** A virt
33150 75 61 6c 20 66 69 6c 65 73 79 73 74 65 6d 20 28  ual filesystem (
33160 56 46 53 29 20 69 73 20 61 6e 20 5b 73 71 6c 69  VFS) is an [sqli
33170 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 0a  te3_vfs] object.
33180 2a 2a 20 74 68 61 74 20 53 51 4c 69 74 65 20 75  ** that SQLite u
33190 73 65 73 20 74 6f 20 69 6e 74 65 72 61 63 74 0a  ses to interact.
331a0 2a 2a 20 77 69 74 68 20 74 68 65 20 75 6e 64 65  ** with the unde
331b0 72 6c 79 69 6e 67 20 6f 70 65 72 61 74 69 6e 67  rlying operating
331c0 20 73 79 73 74 65 6d 2e 20 20 4d 6f 73 74 20 53   system.  Most S
331d0 51 4c 69 74 65 20 62 75 69 6c 64 73 20 63 6f 6d  QLite builds com
331e0 65 20 77 69 74 68 20 61 0a 2a 2a 20 73 69 6e 67  e with a.** sing
331f0 6c 65 20 64 65 66 61 75 6c 74 20 56 46 53 20 74  le default VFS t
33200 68 61 74 20 69 73 20 61 70 70 72 6f 70 72 69 61  hat is appropria
33210 74 65 20 66 6f 72 20 74 68 65 20 68 6f 73 74 20  te for the host 
33220 63 6f 6d 70 75 74 65 72 2e 0a 2a 2a 20 4e 65 77  computer..** New
33230 20 56 46 53 65 73 20 63 61 6e 20 62 65 20 72 65   VFSes can be re
33240 67 69 73 74 65 72 65 64 20 61 6e 64 20 65 78 69  gistered and exi
33250 73 74 69 6e 67 20 56 46 53 65 73 20 63 61 6e 20  sting VFSes can 
33260 62 65 20 75 6e 72 65 67 69 73 74 65 72 65 64 2e  be unregistered.
33270 0a 2a 2a 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e  .** The followin
33280 67 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  g interfaces are
33290 20 70 72 6f 76 69 64 65 64 2e 0a 2a 2a 0a 2a 2a   provided..**.**
332a0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73   The sqlite3_vfs
332b0 5f 66 69 6e 64 28 29 20 69 6e 74 65 72 66 61 63  _find() interfac
332c0 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  e returns a poin
332d0 74 65 72 20 74 6f 20 61 20 56 46 53 20 67 69 76  ter to a VFS giv
332e0 65 6e 20 69 74 73 20 6e 61 6d 65 2e 0a 2a 2a 20  en its name..** 
332f0 4e 61 6d 65 73 20 61 72 65 20 63 61 73 65 20 73  Names are case s
33300 65 6e 73 69 74 69 76 65 2e 0a 2a 2a 20 4e 61 6d  ensitive..** Nam
33310 65 73 20 61 72 65 20 7a 65 72 6f 2d 74 65 72 6d  es are zero-term
33320 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72  inated UTF-8 str
33330 69 6e 67 73 2e 0a 2a 2a 20 49 66 20 74 68 65 72  ings..** If ther
33340 65 20 69 73 20 6e 6f 20 6d 61 74 63 68 2c 20 61  e is no match, a
33350 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73   NULL pointer is
33360 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 49 66   returned..** If
33370 20 7a 56 66 73 4e 61 6d 65 20 69 73 20 4e 55 4c   zVfsName is NUL
33380 4c 20 74 68 65 6e 20 74 68 65 20 64 65 66 61 75  L then the defau
33390 6c 74 20 56 46 53 20 69 73 20 72 65 74 75 72 6e  lt VFS is return
333a0 65 64 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 56 46  ed..**.** New VF
333b0 53 65 73 20 61 72 65 20 72 65 67 69 73 74 65 72  Ses are register
333c0 65 64 20 77 69 74 68 20 73 71 6c 69 74 65 33 5f  ed with sqlite3_
333d0 76 66 73 5f 72 65 67 69 73 74 65 72 28 29 2e 0a  vfs_register()..
333e0 2a 2a 20 45 61 63 68 20 6e 65 77 20 56 46 53 20  ** Each new VFS 
333f0 62 65 63 6f 6d 65 73 20 74 68 65 20 64 65 66 61  becomes the defa
33400 75 6c 74 20 56 46 53 20 69 66 20 74 68 65 20 6d  ult VFS if the m
33410 61 6b 65 44 66 6c 74 20 66 6c 61 67 20 69 73 20  akeDflt flag is 
33420 73 65 74 2e 0a 2a 2a 20 54 68 65 20 73 61 6d 65  set..** The same
33430 20 56 46 53 20 63 61 6e 20 62 65 20 72 65 67 69   VFS can be regi
33440 73 74 65 72 65 64 20 6d 75 6c 74 69 70 6c 65 20  stered multiple 
33450 74 69 6d 65 73 20 77 69 74 68 6f 75 74 20 69 6e  times without in
33460 6a 75 72 79 2e 0a 2a 2a 20 54 6f 20 6d 61 6b 65  jury..** To make
33470 20 61 6e 20 65 78 69 73 74 69 6e 67 20 56 46 53   an existing VFS
33480 20 69 6e 74 6f 20 74 68 65 20 64 65 66 61 75 6c   into the defaul
33490 74 20 56 46 53 2c 20 72 65 67 69 73 74 65 72 20  t VFS, register 
334a0 69 74 20 61 67 61 69 6e 0a 2a 2a 20 77 69 74 68  it again.** with
334b0 20 74 68 65 20 6d 61 6b 65 44 66 6c 74 20 66 6c   the makeDflt fl
334c0 61 67 20 73 65 74 2e 20 20 49 66 20 74 77 6f 20  ag set.  If two 
334d0 64 69 66 66 65 72 65 6e 74 20 56 46 53 65 73 20  different VFSes 
334e0 77 69 74 68 20 74 68 65 0a 2a 2a 20 73 61 6d 65  with the.** same
334f0 20 6e 61 6d 65 20 61 72 65 20 72 65 67 69 73 74   name are regist
33500 65 72 65 64 2c 20 74 68 65 20 62 65 68 61 76 69  ered, the behavi
33510 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  or is undefined.
33520 20 20 49 66 20 61 0a 2a 2a 20 56 46 53 20 69 73    If a.** VFS is
33530 20 72 65 67 69 73 74 65 72 65 64 20 77 69 74 68   registered with
33540 20 61 20 6e 61 6d 65 20 74 68 61 74 20 69 73 20   a name that is 
33550 4e 55 4c 4c 20 6f 72 20 61 6e 20 65 6d 70 74 79  NULL or an empty
33560 20 73 74 72 69 6e 67 2c 0a 2a 2a 20 74 68 65 6e   string,.** then
33570 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73   the behavior is
33580 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
33590 2a 20 55 6e 72 65 67 69 73 74 65 72 20 61 20 56  * Unregister a V
335a0 46 53 20 77 69 74 68 20 74 68 65 20 73 71 6c 69  FS with the sqli
335b0 74 65 33 5f 76 66 73 5f 75 6e 72 65 67 69 73 74  te3_vfs_unregist
335c0 65 72 28 29 20 69 6e 74 65 72 66 61 63 65 2e 0a  er() interface..
335d0 2a 2a 20 49 66 20 74 68 65 20 64 65 66 61 75 6c  ** If the defaul
335e0 74 20 56 46 53 20 69 73 20 75 6e 72 65 67 69 73  t VFS is unregis
335f0 74 65 72 65 64 2c 20 61 6e 6f 74 68 65 72 20 56  tered, another V
33600 46 53 20 69 73 20 63 68 6f 73 65 6e 20 61 73 0a  FS is chosen as.
33610 2a 2a 20 74 68 65 20 64 65 66 61 75 6c 74 2e 20  ** the default. 
33620 20 54 68 65 20 63 68 6f 69 63 65 20 66 6f 72 20   The choice for 
33630 74 68 65 20 6e 65 77 20 56 46 53 20 69 73 20 61  the new VFS is a
33640 72 62 69 74 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20  rbitrary..**.** 
33650 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a  Requirements:.**
33660 20 5b 48 31 31 32 30 33 5d 20 5b 48 31 31 32 30   [H11203] [H1120
33670 36 5d 20 5b 48 31 31 32 30 39 5d 20 5b 48 31 31  6] [H11209] [H11
33680 32 31 32 5d 20 5b 48 31 31 32 31 35 5d 20 5b 48  212] [H11215] [H
33690 31 31 32 31 38 5d 0a 2a 2f 0a 73 71 6c 69 74 65  11218].*/.sqlite
336a0 33 5f 76 66 73 20 2a 73 71 6c 69 74 65 33 5f 76  3_vfs *sqlite3_v
336b0 66 73 5f 66 69 6e 64 28 63 6f 6e 73 74 20 63 68  fs_find(const ch
336c0 61 72 20 2a 7a 56 66 73 4e 61 6d 65 29 3b 0a 69  ar *zVfsName);.i
336d0 6e 74 20 73 71 6c 69 74 65 33 5f 76 66 73 5f 72  nt sqlite3_vfs_r
336e0 65 67 69 73 74 65 72 28 73 71 6c 69 74 65 33 5f  egister(sqlite3_
336f0 76 66 73 2a 2c 20 69 6e 74 20 6d 61 6b 65 44 66  vfs*, int makeDf
33700 6c 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  lt);.int sqlite3
33710 5f 76 66 73 5f 75 6e 72 65 67 69 73 74 65 72 28  _vfs_unregister(
33720 73 71 6c 69 74 65 33 5f 76 66 73 2a 29 3b 0a 0a  sqlite3_vfs*);..
33730 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
33740 4d 75 74 65 78 65 73 20 7b 48 31 37 30 30 30 7d  Mutexes {H17000}
33750 20 3c 53 32 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20   <S20000>.**.** 
33760 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20  The SQLite core 
33770 75 73 65 73 20 74 68 65 73 65 20 72 6f 75 74 69  uses these routi
33780 6e 65 73 20 66 6f 72 20 74 68 72 65 61 64 0a 2a  nes for thread.*
33790 2a 20 73 79 6e 63 68 72 6f 6e 69 7a 61 74 69 6f  * synchronizatio
337a0 6e 2e 20 54 68 6f 75 67 68 20 74 68 65 79 20 61  n. Though they a
337b0 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20  re intended for 
337c0 69 6e 74 65 72 6e 61 6c 0a 2a 2a 20 75 73 65 20  internal.** use 
337d0 62 79 20 53 51 4c 69 74 65 2c 20 63 6f 64 65 20  by SQLite, code 
337e0 74 68 61 74 20 6c 69 6e 6b 73 20 61 67 61 69 6e  that links again
337f0 73 74 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20  st SQLite is.** 
33800 70 65 72 6d 69 74 74 65 64 20 74 6f 20 75 73 65  permitted to use
33810 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f   any of these ro
33820 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  utines..**.** Th
33830 65 20 53 51 4c 69 74 65 20 73 6f 75 72 63 65 20  e SQLite source 
33840 63 6f 64 65 20 63 6f 6e 74 61 69 6e 73 20 6d 75  code contains mu
33850 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74  ltiple implement
33860 61 74 69 6f 6e 73 0a 2a 2a 20 6f 66 20 74 68 65  ations.** of the
33870 73 65 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65  se mutex routine
33880 73 2e 20 20 41 6e 20 61 70 70 72 6f 70 72 69 61  s.  An appropria
33890 74 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  te implementatio
338a0 6e 0a 2a 2a 20 69 73 20 73 65 6c 65 63 74 65 64  n.** is selected
338b0 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 61   automatically a
338c0 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 2e 20  t compile-time. 
338d0 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a   The following.*
338e0 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
338f0 73 20 61 72 65 20 61 76 61 69 6c 61 62 6c 65 20  s are available 
33900 69 6e 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f  in the SQLite co
33910 72 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  re:.**.** <ul>.*
33920 2a 20 3c 6c 69 3e 20 20 20 53 51 4c 49 54 45 5f  * <li>   SQLITE_
33930 4d 55 54 45 58 5f 4f 53 32 0a 2a 2a 20 3c 6c 69  MUTEX_OS2.** <li
33940 3e 20 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58  >   SQLITE_MUTEX
33950 5f 50 54 48 52 45 41 44 0a 2a 2a 20 3c 6c 69 3e  _PTHREAD.** <li>
33960 20 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f     SQLITE_MUTEX_
33970 57 33 32 0a 2a 2a 20 3c 6c 69 3e 20 20 20 53 51  W32.** <li>   SQ
33980 4c 49 54 45 5f 4d 55 54 45 58 5f 4e 4f 4f 50 0a  LITE_MUTEX_NOOP.
33990 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54  ** </ul>.**.** T
339a0 68 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  he SQLITE_MUTEX_
339b0 4e 4f 4f 50 20 69 6d 70 6c 65 6d 65 6e 74 61 74  NOOP implementat
339c0 69 6f 6e 20 69 73 20 61 20 73 65 74 20 6f 66 20  ion is a set of 
339d0 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 74 68 61 74  routines.** that
339e0 20 64 6f 65 73 20 6e 6f 20 72 65 61 6c 20 6c 6f   does no real lo
339f0 63 6b 69 6e 67 20 61 6e 64 20 69 73 20 61 70 70  cking and is app
33a00 72 6f 70 72 69 61 74 65 20 66 6f 72 20 75 73 65  ropriate for use
33a10 20 69 6e 0a 2a 2a 20 61 20 73 69 6e 67 6c 65 2d   in.** a single-
33a20 74 68 72 65 61 64 65 64 20 61 70 70 6c 69 63 61  threaded applica
33a30 74 69 6f 6e 2e 20 20 54 68 65 20 53 51 4c 49 54  tion.  The SQLIT
33a40 45 5f 4d 55 54 45 58 5f 4f 53 32 2c 0a 2a 2a 20  E_MUTEX_OS2,.** 
33a50 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 50 54 48  SQLITE_MUTEX_PTH
33a60 52 45 41 44 2c 20 61 6e 64 20 53 51 4c 49 54 45  READ, and SQLITE
33a70 5f 4d 55 54 45 58 5f 57 33 32 20 69 6d 70 6c 65  _MUTEX_W32 imple
33a80 6d 65 6e 74 61 74 69 6f 6e 73 0a 2a 2a 20 61 72  mentations.** ar
33a90 65 20 61 70 70 72 6f 70 72 69 61 74 65 20 66 6f  e appropriate fo
33aa0 72 20 75 73 65 20 6f 6e 20 4f 53 2f 32 2c 20 55  r use on OS/2, U
33ab0 6e 69 78 2c 20 61 6e 64 20 57 69 6e 64 6f 77 73  nix, and Windows
33ac0 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 53 51 4c 69 74  ..**.** If SQLit
33ad0 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
33ae0 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 4d 55  th the SQLITE_MU
33af0 54 45 58 5f 41 50 50 44 45 46 20 70 72 65 70 72  TEX_APPDEF prepr
33b00 6f 63 65 73 73 6f 72 0a 2a 2a 20 6d 61 63 72 6f  ocessor.** macro
33b10 20 64 65 66 69 6e 65 64 20 28 77 69 74 68 20 22   defined (with "
33b20 2d 44 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 41  -DSQLITE_MUTEX_A
33b30 50 50 44 45 46 3d 31 22 29 2c 20 74 68 65 6e 20  PPDEF=1"), then 
33b40 6e 6f 20 6d 75 74 65 78 0a 2a 2a 20 69 6d 70 6c  no mutex.** impl
33b50 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 69 6e  ementation is in
33b60 63 6c 75 64 65 64 20 77 69 74 68 20 74 68 65 20  cluded with the 
33b70 6c 69 62 72 61 72 79 2e 20 49 6e 20 74 68 69 73  library. In this
33b80 20 63 61 73 65 20 74 68 65 0a 2a 2a 20 61 70 70   case the.** app
33b90 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 73 75  lication must su
33ba0 70 70 6c 79 20 61 20 63 75 73 74 6f 6d 20 6d 75  pply a custom mu
33bb0 74 65 78 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  tex implementati
33bc0 6f 6e 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20  on using the.** 
33bd0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
33be0 55 54 45 58 5d 20 6f 70 74 69 6f 6e 20 6f 66 20  UTEX] option of 
33bf0 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66  the sqlite3_conf
33c00 69 67 28 29 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  ig() function.**
33c10 20 62 65 66 6f 72 65 20 63 61 6c 6c 69 6e 67 20   before calling 
33c20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
33c30 7a 65 28 29 20 6f 72 20 61 6e 79 20 6f 74 68 65  ze() or any othe
33c40 72 20 70 75 62 6c 69 63 20 73 71 6c 69 74 65 33  r public sqlite3
33c50 5f 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74 68  _.** function th
33c60 61 74 20 63 61 6c 6c 73 20 73 71 6c 69 74 65 33  at calls sqlite3
33c70 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 0a 2a  _initialize()..*
33c80 2a 0a 2a 2a 20 7b 48 31 37 30 31 31 7d 20 54 68  *.** {H17011} Th
33c90 65 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  e sqlite3_mutex_
33ca0 61 6c 6c 6f 63 28 29 20 72 6f 75 74 69 6e 65 20  alloc() routine 
33cb0 61 6c 6c 6f 63 61 74 65 73 20 61 20 6e 65 77 0a  allocates a new.
33cc0 2a 2a 20 6d 75 74 65 78 20 61 6e 64 20 72 65 74  ** mutex and ret
33cd0 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
33ce0 6f 20 69 74 2e 20 7b 48 31 37 30 31 32 7d 20 49  o it. {H17012} I
33cf0 66 20 69 74 20 72 65 74 75 72 6e 73 20 4e 55 4c  f it returns NUL
33d00 4c 0a 2a 2a 20 74 68 61 74 20 6d 65 61 6e 73 20  L.** that means 
33d10 74 68 61 74 20 61 20 6d 75 74 65 78 20 63 6f 75  that a mutex cou
33d20 6c 64 20 6e 6f 74 20 62 65 20 61 6c 6c 6f 63 61  ld not be alloca
33d30 74 65 64 2e 20 7b 48 31 37 30 31 33 7d 20 53 51  ted. {H17013} SQ
33d40 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 75 6e 77  Lite.** will unw
33d50 69 6e 64 20 69 74 73 20 73 74 61 63 6b 20 61 6e  ind its stack an
33d60 64 20 72 65 74 75 72 6e 20 61 6e 20 65 72 72 6f  d return an erro
33d70 72 2e 20 7b 48 31 37 30 31 34 7d 20 54 68 65 20  r. {H17014} The 
33d80 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 73  argument.** to s
33d90 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c  qlite3_mutex_all
33da0 6f 63 28 29 20 69 73 20 6f 6e 65 20 6f 66 20 74  oc() is one of t
33db0 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e  hese integer con
33dc0 73 74 61 6e 74 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75  stants:.**.** <u
33dd0 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49  l>.** <li>  SQLI
33de0 54 45 5f 4d 55 54 45 58 5f 46 41 53 54 0a 2a 2a  TE_MUTEX_FAST.**
33df0 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55   <li>  SQLITE_MU
33e00 54 45 58 5f 52 45 43 55 52 53 49 56 45 0a 2a 2a  TEX_RECURSIVE.**
33e10 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55   <li>  SQLITE_MU
33e20 54 45 58 5f 53 54 41 54 49 43 5f 4d 41 53 54 45  TEX_STATIC_MASTE
33e30 52 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54  R.** <li>  SQLIT
33e40 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d  E_MUTEX_STATIC_M
33e50 45 4d 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49  EM.** <li>  SQLI
33e60 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f  TE_MUTEX_STATIC_
33e70 4d 45 4d 32 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51  MEM2.** <li>  SQ
33e80 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49  LITE_MUTEX_STATI
33e90 43 5f 50 52 4e 47 0a 2a 2a 20 3c 6c 69 3e 20 20  C_PRNG.** <li>  
33ea0 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41  SQLITE_MUTEX_STA
33eb0 54 49 43 5f 4c 52 55 0a 2a 2a 20 3c 6c 69 3e 20  TIC_LRU.** <li> 
33ec0 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54   SQLITE_MUTEX_ST
33ed0 41 54 49 43 5f 4c 52 55 32 0a 2a 2a 20 3c 2f 75  ATIC_LRU2.** </u
33ee0 6c 3e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 30 31 35  l>.**.** {H17015
33ef0 7d 20 54 68 65 20 66 69 72 73 74 20 74 77 6f 20  } The first two 
33f00 63 6f 6e 73 74 61 6e 74 73 20 63 61 75 73 65 20  constants cause 
33f10 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c  sqlite3_mutex_al
33f20 6c 6f 63 28 29 20 74 6f 20 63 72 65 61 74 65 0a  loc() to create.
33f30 2a 2a 20 61 20 6e 65 77 20 6d 75 74 65 78 2e 20  ** a new mutex. 
33f40 20 54 68 65 20 6e 65 77 20 6d 75 74 65 78 20 69   The new mutex i
33f50 73 20 72 65 63 75 72 73 69 76 65 20 77 68 65 6e  s recursive when
33f60 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45   SQLITE_MUTEX_RE
33f70 43 55 52 53 49 56 45 0a 2a 2a 20 69 73 20 75 73  CURSIVE.** is us
33f80 65 64 20 62 75 74 20 6e 6f 74 20 6e 65 63 65 73  ed but not neces
33f90 73 61 72 69 6c 79 20 73 6f 20 77 68 65 6e 20 53  sarily so when S
33fa0 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 54  QLITE_MUTEX_FAST
33fb0 20 69 73 20 75 73 65 64 2e 20 7b 45 4e 44 7d 0a   is used. {END}.
33fc0 2a 2a 20 54 68 65 20 6d 75 74 65 78 20 69 6d 70  ** The mutex imp
33fd0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 64 6f 65 73  lementation does
33fe0 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 6d 61 6b   not need to mak
33ff0 65 20 61 20 64 69 73 74 69 6e 63 74 69 6f 6e 0a  e a distinction.
34000 2a 2a 20 62 65 74 77 65 65 6e 20 53 51 4c 49 54  ** between SQLIT
34010 45 5f 4d 55 54 45 58 5f 52 45 43 55 52 53 49 56  E_MUTEX_RECURSIV
34020 45 20 61 6e 64 20 53 51 4c 49 54 45 5f 4d 55 54  E and SQLITE_MUT
34030 45 58 5f 46 41 53 54 20 69 66 20 69 74 20 64 6f  EX_FAST if it do
34040 65 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74 20 74  es.** not want t
34050 6f 2e 20 20 7b 48 31 37 30 31 36 7d 20 42 75 74  o.  {H17016} But
34060 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e 6c   SQLite will onl
34070 79 20 72 65 71 75 65 73 74 20 61 20 72 65 63 75  y request a recu
34080 72 73 69 76 65 20 6d 75 74 65 78 20 69 6e 0a 2a  rsive mutex in.*
34090 2a 20 63 61 73 65 73 20 77 68 65 72 65 20 69 74  * cases where it
340a0 20 72 65 61 6c 6c 79 20 6e 65 65 64 73 20 6f 6e   really needs on
340b0 65 2e 20 20 7b 45 4e 44 7d 20 49 66 20 61 20 66  e.  {END} If a f
340c0 61 73 74 65 72 20 6e 6f 6e 2d 72 65 63 75 72 73  aster non-recurs
340d0 69 76 65 20 6d 75 74 65 78 0a 2a 2a 20 69 6d 70  ive mutex.** imp
340e0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 61  lementation is a
340f0 76 61 69 6c 61 62 6c 65 20 6f 6e 20 74 68 65 20  vailable on the 
34100 68 6f 73 74 20 70 6c 61 74 66 6f 72 6d 2c 20 74  host platform, t
34110 68 65 20 6d 75 74 65 78 20 73 75 62 73 79 73 74  he mutex subsyst
34120 65 6d 0a 2a 2a 20 6d 69 67 68 74 20 72 65 74 75  em.** might retu
34130 72 6e 20 73 75 63 68 20 61 20 6d 75 74 65 78 20  rn such a mutex 
34140 69 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f 20 53  in response to S
34150 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 54  QLITE_MUTEX_FAST
34160 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 30 31 37 7d  ..**.** {H17017}
34170 20 54 68 65 20 6f 74 68 65 72 20 61 6c 6c 6f 77   The other allow
34180 65 64 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f  ed parameters to
34190 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61   sqlite3_mutex_a
341a0 6c 6c 6f 63 28 29 20 65 61 63 68 20 72 65 74 75  lloc() each retu
341b0 72 6e 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20  rn.** a pointer 
341c0 74 6f 20 61 20 73 74 61 74 69 63 20 70 72 65 65  to a static pree
341d0 78 69 73 74 69 6e 67 20 6d 75 74 65 78 2e 20 7b  xisting mutex. {
341e0 45 4e 44 7d 20 20 46 6f 75 72 20 73 74 61 74 69  END}  Four stati
341f0 63 20 6d 75 74 65 78 65 73 20 61 72 65 0a 2a 2a  c mutexes are.**
34200 20 75 73 65 64 20 62 79 20 74 68 65 20 63 75 72   used by the cur
34210 72 65 6e 74 20 76 65 72 73 69 6f 6e 20 6f 66 20  rent version of 
34220 53 51 4c 69 74 65 2e 20 20 46 75 74 75 72 65 20  SQLite.  Future 
34230 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
34240 74 65 0a 2a 2a 20 6d 61 79 20 61 64 64 20 61 64  te.** may add ad
34250 64 69 74 69 6f 6e 61 6c 20 73 74 61 74 69 63 20  ditional static 
34260 6d 75 74 65 78 65 73 2e 20 20 53 74 61 74 69 63  mutexes.  Static
34270 20 6d 75 74 65 78 65 73 20 61 72 65 20 66 6f 72   mutexes are for
34280 20 69 6e 74 65 72 6e 61 6c 0a 2a 2a 20 75 73 65   internal.** use
34290 20 62 79 20 53 51 4c 69 74 65 20 6f 6e 6c 79 2e   by SQLite only.
342a0 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74    Applications t
342b0 68 61 74 20 75 73 65 20 53 51 4c 69 74 65 20 6d  hat use SQLite m
342c0 75 74 65 78 65 73 20 73 68 6f 75 6c 64 0a 2a 2a  utexes should.**
342d0 20 75 73 65 20 6f 6e 6c 79 20 74 68 65 20 64 79   use only the dy
342e0 6e 61 6d 69 63 20 6d 75 74 65 78 65 73 20 72 65  namic mutexes re
342f0 74 75 72 6e 65 64 20 62 79 20 53 51 4c 49 54 45  turned by SQLITE
34300 5f 4d 55 54 45 58 5f 46 41 53 54 20 6f 72 0a 2a  _MUTEX_FAST or.*
34310 2a 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52  * SQLITE_MUTEX_R
34320 45 43 55 52 53 49 56 45 2e 0a 2a 2a 0a 2a 2a 20  ECURSIVE..**.** 
34330 7b 48 31 37 30 31 38 7d 20 4e 6f 74 65 20 74 68  {H17018} Note th
34340 61 74 20 69 66 20 6f 6e 65 20 6f 66 20 74 68 65  at if one of the
34350 20 64 79 6e 61 6d 69 63 20 6d 75 74 65 78 20 70   dynamic mutex p
34360 61 72 61 6d 65 74 65 72 73 20 28 53 51 4c 49 54  arameters (SQLIT
34370 45 5f 4d 55 54 45 58 5f 46 41 53 54 0a 2a 2a 20  E_MUTEX_FAST.** 
34380 6f 72 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  or SQLITE_MUTEX_
34390 52 45 43 55 52 53 49 56 45 29 20 69 73 20 75 73  RECURSIVE) is us
343a0 65 64 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  ed then sqlite3_
343b0 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 0a 2a 2a  mutex_alloc().**
343c0 20 72 65 74 75 72 6e 73 20 61 20 64 69 66 66 65   returns a diffe
343d0 72 65 6e 74 20 6d 75 74 65 78 20 6f 6e 20 65 76  rent mutex on ev
343e0 65 72 79 20 63 61 6c 6c 2e 20 20 7b 48 31 37 30  ery call.  {H170
343f0 33 34 7d 20 42 75 74 20 66 6f 72 20 74 68 65 20  34} But for the 
34400 73 74 61 74 69 63 0a 2a 2a 20 6d 75 74 65 78 20  static.** mutex 
34410 74 79 70 65 73 2c 20 74 68 65 20 73 61 6d 65 20  types, the same 
34420 6d 75 74 65 78 20 69 73 20 72 65 74 75 72 6e 65  mutex is returne
34430 64 20 6f 6e 20 65 76 65 72 79 20 63 61 6c 6c 20  d on every call 
34440 74 68 61 74 20 68 61 73 0a 2a 2a 20 74 68 65 20  that has.** the 
34450 73 61 6d 65 20 74 79 70 65 20 6e 75 6d 62 65 72  same type number
34460 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 30 31 39 7d  ..**.** {H17019}
34470 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 75 74   The sqlite3_mut
34480 65 78 5f 66 72 65 65 28 29 20 72 6f 75 74 69 6e  ex_free() routin
34490 65 20 64 65 61 6c 6c 6f 63 61 74 65 73 20 61 20  e deallocates a 
344a0 70 72 65 76 69 6f 75 73 6c 79 0a 2a 2a 20 61 6c  previously.** al
344b0 6c 6f 63 61 74 65 64 20 64 79 6e 61 6d 69 63 20  located dynamic 
344c0 6d 75 74 65 78 2e 20 7b 48 31 37 30 32 30 7d 20  mutex. {H17020} 
344d0 53 51 4c 69 74 65 20 69 73 20 63 61 72 65 66 75  SQLite is carefu
344e0 6c 20 74 6f 20 64 65 61 6c 6c 6f 63 61 74 65 20  l to deallocate 
344f0 65 76 65 72 79 0a 2a 2a 20 64 79 6e 61 6d 69 63  every.** dynamic
34500 20 6d 75 74 65 78 20 74 68 61 74 20 69 74 20 61   mutex that it a
34510 6c 6c 6f 63 61 74 65 73 2e 20 7b 41 31 37 30 32  llocates. {A1702
34520 31 7d 20 54 68 65 20 64 79 6e 61 6d 69 63 20 6d  1} The dynamic m
34530 75 74 65 78 65 73 20 6d 75 73 74 20 6e 6f 74 20  utexes must not 
34540 62 65 20 69 6e 0a 2a 2a 20 75 73 65 20 77 68 65  be in.** use whe
34550 6e 20 74 68 65 79 20 61 72 65 20 64 65 61 6c 6c  n they are deall
34560 6f 63 61 74 65 64 2e 20 7b 41 31 37 30 32 32 7d  ocated. {A17022}
34570 20 41 74 74 65 6d 70 74 69 6e 67 20 74 6f 20 64   Attempting to d
34580 65 61 6c 6c 6f 63 61 74 65 20 61 20 73 74 61 74  eallocate a stat
34590 69 63 0a 2a 2a 20 6d 75 74 65 78 20 72 65 73 75  ic.** mutex resu
345a0 6c 74 73 20 69 6e 20 75 6e 64 65 66 69 6e 65 64  lts in undefined
345b0 20 62 65 68 61 76 69 6f 72 2e 20 7b 48 31 37 30   behavior. {H170
345c0 32 33 7d 20 53 51 4c 69 74 65 20 6e 65 76 65 72  23} SQLite never
345d0 20 64 65 61 6c 6c 6f 63 61 74 65 73 0a 2a 2a 20   deallocates.** 
345e0 61 20 73 74 61 74 69 63 20 6d 75 74 65 78 2e 20  a static mutex. 
345f0 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20  {END}.**.** The 
34600 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e  sqlite3_mutex_en
34610 74 65 72 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ter() and sqlite
34620 33 5f 6d 75 74 65 78 5f 74 72 79 28 29 20 72 6f  3_mutex_try() ro
34630 75 74 69 6e 65 73 20 61 74 74 65 6d 70 74 0a 2a  utines attempt.*
34640 2a 20 74 6f 20 65 6e 74 65 72 20 61 20 6d 75 74  * to enter a mut
34650 65 78 2e 20 7b 48 31 37 30 32 34 7d 20 49 66 20  ex. {H17024} If 
34660 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64 20 69  another thread i
34670 73 20 61 6c 72 65 61 64 79 20 77 69 74 68 69 6e  s already within
34680 20 74 68 65 20 6d 75 74 65 78 2c 0a 2a 2a 20 73   the mutex,.** s
34690 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74  qlite3_mutex_ent
346a0 65 72 28 29 20 77 69 6c 6c 20 62 6c 6f 63 6b 20  er() will block 
346b0 61 6e 64 20 73 71 6c 69 74 65 33 5f 6d 75 74 65  and sqlite3_mute
346c0 78 5f 74 72 79 28 29 20 77 69 6c 6c 20 72 65 74  x_try() will ret
346d0 75 72 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f 42 55  urn.** SQLITE_BU
346e0 53 59 2e 20 7b 48 31 37 30 32 35 7d 20 20 54 68  SY. {H17025}  Th
346f0 65 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  e sqlite3_mutex_
34700 74 72 79 28 29 20 69 6e 74 65 72 66 61 63 65 20  try() interface 
34710 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
34720 4f 4b 5d 0a 2a 2a 20 75 70 6f 6e 20 73 75 63 63  OK].** upon succ
34730 65 73 73 66 75 6c 20 65 6e 74 72 79 2e 20 20 7b  essful entry.  {
34740 48 31 37 30 32 36 7d 20 4d 75 74 65 78 65 73 20  H17026} Mutexes 
34750 63 72 65 61 74 65 64 20 75 73 69 6e 67 0a 2a 2a  created using.**
34760 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45   SQLITE_MUTEX_RE
34770 43 55 52 53 49 56 45 20 63 61 6e 20 62 65 20 65  CURSIVE can be e
34780 6e 74 65 72 65 64 20 6d 75 6c 74 69 70 6c 65 20  ntered multiple 
34790 74 69 6d 65 73 20 62 79 20 74 68 65 20 73 61 6d  times by the sam
347a0 65 20 74 68 72 65 61 64 2e 0a 2a 2a 20 7b 48 31  e thread..** {H1
347b0 37 30 32 37 7d 20 49 6e 20 73 75 63 68 20 63 61  7027} In such ca
347c0 73 65 73 20 74 68 65 2c 0a 2a 2a 20 6d 75 74 65  ses the,.** mute
347d0 78 20 6d 75 73 74 20 62 65 20 65 78 69 74 65 64  x must be exited
347e0 20 61 6e 20 65 71 75 61 6c 20 6e 75 6d 62 65 72   an equal number
347f0 20 6f 66 20 74 69 6d 65 73 20 62 65 66 6f 72 65   of times before
34800 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64 0a   another thread.
34810 2a 2a 20 63 61 6e 20 65 6e 74 65 72 2e 20 20 7b  ** can enter.  {
34820 41 31 37 30 32 38 7d 20 49 66 20 74 68 65 20 73  A17028} If the s
34830 61 6d 65 20 74 68 72 65 61 64 20 74 72 69 65 73  ame thread tries
34840 20 74 6f 20 65 6e 74 65 72 20 61 6e 79 20 6f 74   to enter any ot
34850 68 65 72 0a 2a 2a 20 6b 69 6e 64 20 6f 66 20 6d  her.** kind of m
34860 75 74 65 78 20 6d 6f 72 65 20 74 68 61 6e 20 6f  utex more than o
34870 6e 63 65 2c 20 74 68 65 20 62 65 68 61 76 69 6f  nce, the behavio
34880 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  r is undefined..
34890 2a 2a 20 7b 48 31 37 30 32 39 7d 20 53 51 4c 69  ** {H17029} SQLi
348a0 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 65 78  te will never ex
348b0 68 69 62 69 74 0a 2a 2a 20 73 75 63 68 20 62 65  hibit.** such be
348c0 68 61 76 69 6f 72 20 69 6e 20 69 74 73 20 6f 77  havior in its ow
348d0 6e 20 75 73 65 20 6f 66 20 6d 75 74 65 78 65 73  n use of mutexes
348e0 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 73 79 73  ..**.** Some sys
348f0 74 65 6d 73 20 28 66 6f 72 20 65 78 61 6d 70 6c  tems (for exampl
34900 65 2c 20 57 69 6e 64 6f 77 73 20 39 35 29 20 64  e, Windows 95) d
34910 6f 20 6e 6f 74 20 73 75 70 70 6f 72 74 20 74 68  o not support th
34920 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 69  e operation.** i
34930 6d 70 6c 65 6d 65 6e 74 65 64 20 62 79 20 73 71  mplemented by sq
34940 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74 72 79 28  lite3_mutex_try(
34950 29 2e 20 20 4f 6e 20 74 68 6f 73 65 20 73 79 73  ).  On those sys
34960 74 65 6d 73 2c 20 73 71 6c 69 74 65 33 5f 6d 75  tems, sqlite3_mu
34970 74 65 78 5f 74 72 79 28 29 0a 2a 2a 20 77 69 6c  tex_try().** wil
34980 6c 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 20  l always return 
34990 53 51 4c 49 54 45 5f 42 55 53 59 2e 20 20 7b 48  SQLITE_BUSY.  {H
349a0 31 37 30 33 30 7d 20 54 68 65 20 53 51 4c 69 74  17030} The SQLit
349b0 65 20 63 6f 72 65 20 6f 6e 6c 79 20 65 76 65 72  e core only ever
349c0 20 75 73 65 73 0a 2a 2a 20 73 71 6c 69 74 65 33   uses.** sqlite3
349d0 5f 6d 75 74 65 78 5f 74 72 79 28 29 20 61 73 20  _mutex_try() as 
349e0 61 6e 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 20  an optimization 
349f0 73 6f 20 74 68 69 73 20 69 73 20 61 63 63 65 70  so this is accep
34a00 74 61 62 6c 65 20 62 65 68 61 76 69 6f 72 2e 0a  table behavior..
34a10 2a 2a 0a 2a 2a 20 7b 48 31 37 30 33 31 7d 20 54  **.** {H17031} T
34a20 68 65 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  he sqlite3_mutex
34a30 5f 6c 65 61 76 65 28 29 20 72 6f 75 74 69 6e 65  _leave() routine
34a40 20 65 78 69 74 73 20 61 20 6d 75 74 65 78 20 74   exits a mutex t
34a50 68 61 74 20 77 61 73 0a 2a 2a 20 70 72 65 76 69  hat was.** previ
34a60 6f 75 73 6c 79 20 65 6e 74 65 72 65 64 20 62 79  ously entered by
34a70 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64   the same thread
34a80 2e 20 20 7b 41 31 37 30 33 32 7d 20 54 68 65 20  .  {A17032} The 
34a90 62 65 68 61 76 69 6f 72 0a 2a 2a 20 69 73 20 75  behavior.** is u
34aa0 6e 64 65 66 69 6e 65 64 20 69 66 20 74 68 65 20  ndefined if the 
34ab0 6d 75 74 65 78 20 69 73 20 6e 6f 74 20 63 75 72  mutex is not cur
34ac0 72 65 6e 74 6c 79 20 65 6e 74 65 72 65 64 20 62  rently entered b
34ad0 79 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 69 6e 67  y the.** calling
34ae0 20 74 68 72 65 61 64 20 6f 72 20 69 73 20 6e 6f   thread or is no
34af0 74 20 63 75 72 72 65 6e 74 6c 79 20 61 6c 6c 6f  t currently allo
34b00 63 61 74 65 64 2e 20 20 7b 48 31 37 30 33 33 7d  cated.  {H17033}
34b10 20 53 51 4c 69 74 65 20 77 69 6c 6c 0a 2a 2a 20   SQLite will.** 
34b20 6e 65 76 65 72 20 64 6f 20 65 69 74 68 65 72 2e  never do either.
34b30 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 49 66 20   {END}.**.** If 
34b40 74 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  the argument to 
34b50 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e  sqlite3_mutex_en
34b60 74 65 72 28 29 2c 20 73 71 6c 69 74 65 33 5f 6d  ter(), sqlite3_m
34b70 75 74 65 78 5f 74 72 79 28 29 2c 20 6f 72 0a 2a  utex_try(), or.*
34b80 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  * sqlite3_mutex_
34b90 6c 65 61 76 65 28 29 20 69 73 20 61 20 4e 55 4c  leave() is a NUL
34ba0 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20  L pointer, then 
34bb0 61 6c 6c 20 74 68 72 65 65 20 72 6f 75 74 69 6e  all three routin
34bc0 65 73 0a 2a 2a 20 62 65 68 61 76 65 20 61 73 20  es.** behave as 
34bd0 6e 6f 2d 6f 70 73 2e 0a 2a 2a 0a 2a 2a 20 53 65  no-ops..**.** Se
34be0 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33  e also: [sqlite3
34bf0 5f 6d 75 74 65 78 5f 68 65 6c 64 28 29 5d 20 61  _mutex_held()] a
34c00 6e 64 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  nd [sqlite3_mute
34c10 78 5f 6e 6f 74 68 65 6c 64 28 29 5d 2e 0a 2a 2f  x_notheld()]..*/
34c20 0a 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a  .sqlite3_mutex *
34c30 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c  sqlite3_mutex_al
34c40 6c 6f 63 28 69 6e 74 29 3b 0a 76 6f 69 64 20 73  loc(int);.void s
34c50 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 66 72 65  qlite3_mutex_fre
34c60 65 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 2a  e(sqlite3_mutex*
34c70 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
34c80 6d 75 74 65 78 5f 65 6e 74 65 72 28 73 71 6c 69  mutex_enter(sqli
34c90 74 65 33 5f 6d 75 74 65 78 2a 29 3b 0a 69 6e 74  te3_mutex*);.int
34ca0 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74   sqlite3_mutex_t
34cb0 72 79 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  ry(sqlite3_mutex
34cc0 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  *);.void sqlite3
34cd0 5f 6d 75 74 65 78 5f 6c 65 61 76 65 28 73 71 6c  _mutex_leave(sql
34ce0 69 74 65 33 5f 6d 75 74 65 78 2a 29 3b 0a 0a 2f  ite3_mutex*);../
34cf0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d  *.** CAPI3REF: M
34d00 75 74 65 78 20 4d 65 74 68 6f 64 73 20 4f 62 6a  utex Methods Obj
34d10 65 63 74 20 7b 48 31 37 31 32 30 7d 20 3c 53 32  ect {H17120} <S2
34d20 30 31 33 30 3e 0a 2a 2a 20 45 58 50 45 52 49 4d  0130>.** EXPERIM
34d30 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 41 6e 20 69  ENTAL.**.** An i
34d40 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20  nstance of this 
34d50 73 74 72 75 63 74 75 72 65 20 64 65 66 69 6e 65  structure define
34d60 73 20 74 68 65 20 6c 6f 77 2d 6c 65 76 65 6c 20  s the low-level 
34d70 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 75 73 65 64  routines.** used
34d80 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 61 6e 64   to allocate and
34d90 20 75 73 65 20 6d 75 74 65 78 65 73 2e 0a 2a 2a   use mutexes..**
34da0 0a 2a 2a 20 55 73 75 61 6c 6c 79 2c 20 74 68 65  .** Usually, the
34db0 20 64 65 66 61 75 6c 74 20 6d 75 74 65 78 20 69   default mutex i
34dc0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 70  mplementations p
34dd0 72 6f 76 69 64 65 64 20 62 79 20 53 51 4c 69 74  rovided by SQLit
34de0 65 20 61 72 65 0a 2a 2a 20 73 75 66 66 69 63 69  e are.** suffici
34df0 65 6e 74 2c 20 68 6f 77 65 76 65 72 20 74 68 65  ent, however the
34e00 20 75 73 65 72 20 68 61 73 20 74 68 65 20 6f 70   user has the op
34e10 74 69 6f 6e 20 6f 66 20 73 75 62 73 74 69 74 75  tion of substitu
34e20 74 69 6e 67 20 61 20 63 75 73 74 6f 6d 0a 2a 2a  ting a custom.**
34e30 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
34e40 66 6f 72 20 73 70 65 63 69 61 6c 69 7a 65 64 20  for specialized 
34e50 64 65 70 6c 6f 79 6d 65 6e 74 73 20 6f 72 20 73  deployments or s
34e60 79 73 74 65 6d 73 20 66 6f 72 20 77 68 69 63 68  ystems for which
34e70 20 53 51 4c 69 74 65 0a 2a 2a 20 64 6f 65 73 20   SQLite.** does 
34e80 6e 6f 74 20 70 72 6f 76 69 64 65 20 61 20 73 75  not provide a su
34e90 69 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74  itable implement
34ea0 61 74 69 6f 6e 2e 20 49 6e 20 74 68 69 73 20 63  ation. In this c
34eb0 61 73 65 2c 20 74 68 65 20 75 73 65 72 0a 2a 2a  ase, the user.**
34ec0 20 63 72 65 61 74 65 73 20 61 6e 64 20 70 6f 70   creates and pop
34ed0 75 6c 61 74 65 73 20 61 6e 20 69 6e 73 74 61 6e  ulates an instan
34ee0 63 65 20 6f 66 20 74 68 69 73 20 73 74 72 75 63  ce of this struc
34ef0 74 75 72 65 20 74 6f 20 70 61 73 73 0a 2a 2a 20  ture to pass.** 
34f00 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  to sqlite3_confi
34f10 67 28 29 20 61 6c 6f 6e 67 20 77 69 74 68 20 74  g() along with t
34f20 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  he [SQLITE_CONFI
34f30 47 5f 4d 55 54 45 58 5d 20 6f 70 74 69 6f 6e 2e  G_MUTEX] option.
34f40 0a 2a 2a 20 41 64 64 69 74 69 6f 6e 61 6c 6c 79  .** Additionally
34f50 2c 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  , an instance of
34f60 20 74 68 69 73 20 73 74 72 75 63 74 75 72 65 20   this structure 
34f70 63 61 6e 20 62 65 20 75 73 65 64 20 61 73 20 61  can be used as a
34f80 6e 0a 2a 2a 20 6f 75 74 70 75 74 20 76 61 72 69  n.** output vari
34f90 61 62 6c 65 20 77 68 65 6e 20 71 75 65 72 79 69  able when queryi
34fa0 6e 67 20 74 68 65 20 73 79 73 74 65 6d 20 66 6f  ng the system fo
34fb0 72 20 74 68 65 20 63 75 72 72 65 6e 74 20 6d 75  r the current mu
34fc0 74 65 78 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  tex.** implement
34fd0 61 74 69 6f 6e 2c 20 75 73 69 6e 67 20 74 68 65  ation, using the
34fe0 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
34ff0 47 45 54 4d 55 54 45 58 5d 20 6f 70 74 69 6f 6e  GETMUTEX] option
35000 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d 75 74  ..**.** The xMut
35010 65 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 64 65  exInit method de
35020 66 69 6e 65 64 20 62 79 20 74 68 69 73 20 73 74  fined by this st
35030 72 75 63 74 75 72 65 20 69 73 20 69 6e 76 6f 6b  ructure is invok
35040 65 64 20 61 73 0a 2a 2a 20 70 61 72 74 20 6f 66  ed as.** part of
35050 20 73 79 73 74 65 6d 20 69 6e 69 74 69 61 6c 69   system initiali
35060 7a 61 74 69 6f 6e 20 62 79 20 74 68 65 20 73 71  zation by the sq
35070 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
35080 28 29 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20  () function..** 
35090 7b 48 31 37 30 30 31 7d 20 54 68 65 20 78 4d 75  {H17001} The xMu
350a0 74 65 78 49 6e 69 74 20 72 6f 75 74 69 6e 65 20  texInit routine 
350b0 73 68 61 6c 6c 20 62 65 20 63 61 6c 6c 65 64 20  shall be called 
350c0 62 79 20 53 51 4c 69 74 65 20 6f 6e 63 65 20 66  by SQLite once f
350d0 6f 72 20 65 61 63 68 0a 2a 2a 20 65 66 66 65 63  or each.** effec
350e0 74 69 76 65 20 63 61 6c 6c 20 74 6f 20 5b 73 71  tive call to [sq
350f0 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
35100 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  ()]..**.** The x
35110 4d 75 74 65 78 45 6e 64 20 6d 65 74 68 6f 64 20  MutexEnd method 
35120 64 65 66 69 6e 65 64 20 62 79 20 74 68 69 73 20  defined by this 
35130 73 74 72 75 63 74 75 72 65 20 69 73 20 69 6e 76  structure is inv
35140 6f 6b 65 64 20 61 73 0a 2a 2a 20 70 61 72 74 20  oked as.** part 
35150 6f 66 20 73 79 73 74 65 6d 20 73 68 75 74 64 6f  of system shutdo
35160 77 6e 20 62 79 20 74 68 65 20 73 71 6c 69 74 65  wn by the sqlite
35170 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 66 75 6e  3_shutdown() fun
35180 63 74 69 6f 6e 2e 20 54 68 65 0a 2a 2a 20 69 6d  ction. The.** im
35190 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
351a0 74 68 69 73 20 6d 65 74 68 6f 64 20 69 73 20 65  this method is e
351b0 78 70 65 63 74 65 64 20 74 6f 20 72 65 6c 65 61  xpected to relea
351c0 73 65 20 61 6c 6c 20 6f 75 74 73 74 61 6e 64 69  se all outstandi
351d0 6e 67 0a 2a 2a 20 72 65 73 6f 75 72 63 65 73 20  ng.** resources 
351e0 6f 62 74 61 69 6e 65 64 20 62 79 20 74 68 65 20  obtained by the 
351f0 6d 75 74 65 78 20 6d 65 74 68 6f 64 73 20 69 6d  mutex methods im
35200 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2c 20 65 73  plementation, es
35210 70 65 63 69 61 6c 6c 79 0a 2a 2a 20 74 68 6f 73  pecially.** thos
35220 65 20 6f 62 74 61 69 6e 65 64 20 62 79 20 74 68  e obtained by th
35230 65 20 78 4d 75 74 65 78 49 6e 69 74 20 6d 65 74  e xMutexInit met
35240 68 6f 64 2e 20 7b 48 31 37 30 30 33 7d 20 54 68  hod. {H17003} Th
35250 65 20 78 4d 75 74 65 78 45 6e 64 28 29 0a 2a 2a  e xMutexEnd().**
35260 20 69 6e 74 65 72 66 61 63 65 20 73 68 61 6c 6c   interface shall
35270 20 62 65 20 69 6e 76 6f 6b 65 64 20 6f 6e 63 65   be invoked once
35280 20 66 6f 72 20 65 61 63 68 20 63 61 6c 6c 20 74   for each call t
35290 6f 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64  o [sqlite3_shutd
352a0 6f 77 6e 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68  own()]..**.** Th
352b0 65 20 72 65 6d 61 69 6e 69 6e 67 20 73 65 76 65  e remaining seve
352c0 6e 20 6d 65 74 68 6f 64 73 20 64 65 66 69 6e 65  n methods define
352d0 64 20 62 79 20 74 68 69 73 20 73 74 72 75 63 74  d by this struct
352e0 75 72 65 20 28 78 4d 75 74 65 78 41 6c 6c 6f 63  ure (xMutexAlloc
352f0 2c 0a 2a 2a 20 78 4d 75 74 65 78 46 72 65 65 2c  ,.** xMutexFree,
35300 20 78 4d 75 74 65 78 45 6e 74 65 72 2c 20 78 4d   xMutexEnter, xM
35310 75 74 65 78 54 72 79 2c 20 78 4d 75 74 65 78 4c  utexTry, xMutexL
35320 65 61 76 65 2c 20 78 4d 75 74 65 78 48 65 6c 64  eave, xMutexHeld
35330 20 61 6e 64 0a 2a 2a 20 78 4d 75 74 65 78 4e 6f   and.** xMutexNo
35340 74 68 65 6c 64 29 20 69 6d 70 6c 65 6d 65 6e 74  theld) implement
35350 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 69   the following i
35360 6e 74 65 72 66 61 63 65 73 20 28 72 65 73 70 65  nterfaces (respe
35370 63 74 69 76 65 6c 79 29 3a 0a 2a 2a 0a 2a 2a 20  ctively):.**.** 
35380 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 20  <ul>.**   <li>  
35390 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61  [sqlite3_mutex_a
353a0 6c 6c 6f 63 28 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a  lloc()] </li>.**
353b0 20 20 20 3c 6c 69 3e 20 20 5b 73 71 6c 69 74 65     <li>  [sqlite
353c0 33 5f 6d 75 74 65 78 5f 66 72 65 65 28 29 5d 20  3_mutex_free()] 
353d0 3c 2f 6c 69 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20  </li>.**   <li> 
353e0 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
353f0 65 6e 74 65 72 28 29 5d 20 3c 2f 6c 69 3e 0a 2a  enter()] </li>.*
35400 2a 20 20 20 3c 6c 69 3e 20 20 5b 73 71 6c 69 74  *   <li>  [sqlit
35410 65 33 5f 6d 75 74 65 78 5f 74 72 79 28 29 5d 20  e3_mutex_try()] 
35420 3c 2f 6c 69 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20  </li>.**   <li> 
35430 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
35440 6c 65 61 76 65 28 29 5d 20 3c 2f 6c 69 3e 0a 2a  leave()] </li>.*
35450 2a 20 20 20 3c 6c 69 3e 20 20 5b 73 71 6c 69 74  *   <li>  [sqlit
35460 65 33 5f 6d 75 74 65 78 5f 68 65 6c 64 28 29 5d  e3_mutex_held()]
35470 20 3c 2f 6c 69 3e 0a 2a 2a 20 20 20 3c 6c 69 3e   </li>.**   <li>
35480 20 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78    [sqlite3_mutex
35490 5f 6e 6f 74 68 65 6c 64 28 29 5d 20 3c 2f 6c 69  _notheld()] </li
354a0 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  >.** </ul>.**.**
354b0 20 54 68 65 20 6f 6e 6c 79 20 64 69 66 66 65 72   The only differ
354c0 65 6e 63 65 20 69 73 20 74 68 61 74 20 74 68 65  ence is that the
354d0 20 70 75 62 6c 69 63 20 73 71 6c 69 74 65 33 5f   public sqlite3_
354e0 58 58 58 20 66 75 6e 63 74 69 6f 6e 73 20 65 6e  XXX functions en
354f0 75 6d 65 72 61 74 65 64 0a 2a 2a 20 61 62 6f 76  umerated.** abov
35500 65 20 73 69 6c 65 6e 74 6c 79 20 69 67 6e 6f 72  e silently ignor
35510 65 20 61 6e 79 20 69 6e 76 6f 63 61 74 69 6f 6e  e any invocation
35520 73 20 74 68 61 74 20 70 61 73 73 20 61 20 4e 55  s that pass a NU
35530 4c 4c 20 70 6f 69 6e 74 65 72 20 69 6e 73 74 65  LL pointer inste
35540 61 64 0a 2a 2a 20 6f 66 20 61 20 76 61 6c 69 64  ad.** of a valid
35550 20 6d 75 74 65 78 20 68 61 6e 64 6c 65 2e 20 54   mutex handle. T
35560 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
35570 6e 73 20 6f 66 20 74 68 65 20 6d 65 74 68 6f 64  ns of the method
35580 73 20 64 65 66 69 6e 65 64 0a 2a 2a 20 62 79 20  s defined.** by 
35590 74 68 69 73 20 73 74 72 75 63 74 75 72 65 20 61  this structure a
355a0 72 65 20 6e 6f 74 20 72 65 71 75 69 72 65 64 20  re not required 
355b0 74 6f 20 68 61 6e 64 6c 65 20 74 68 69 73 20 63  to handle this c
355c0 61 73 65 2c 20 74 68 65 20 72 65 73 75 6c 74 73  ase, the results
355d0 0a 2a 2a 20 6f 66 20 70 61 73 73 69 6e 67 20 61  .** of passing a
355e0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 6e   NULL pointer in
355f0 73 74 65 61 64 20 6f 66 20 61 20 76 61 6c 69 64  stead of a valid
35600 20 6d 75 74 65 78 20 68 61 6e 64 6c 65 20 61 72   mutex handle ar
35610 65 20 75 6e 64 65 66 69 6e 65 64 0a 2a 2a 20 28  e undefined.** (
35620 69 2e 65 2e 20 69 74 20 69 73 20 61 63 63 65 70  i.e. it is accep
35630 74 61 62 6c 65 20 74 6f 20 70 72 6f 76 69 64 65  table to provide
35640 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69   an implementati
35650 6f 6e 20 74 68 61 74 20 73 65 67 66 61 75 6c 74  on that segfault
35660 73 20 69 66 0a 2a 2a 20 69 74 20 69 73 20 70 61  s if.** it is pa
35670 73 73 65 64 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  ssed a NULL poin
35680 74 65 72 29 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  ter)..*/.typedef
35690 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
356a0 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 20 73 71  mutex_methods sq
356b0 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68  lite3_mutex_meth
356c0 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69  ods;.struct sqli
356d0 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64  te3_mutex_method
356e0 73 20 7b 0a 20 20 69 6e 74 20 28 2a 78 4d 75 74  s {.  int (*xMut
356f0 65 78 49 6e 69 74 29 28 76 6f 69 64 29 3b 0a 20  exInit)(void);. 
35700 20 69 6e 74 20 28 2a 78 4d 75 74 65 78 45 6e 64   int (*xMutexEnd
35710 29 28 76 6f 69 64 29 3b 0a 20 20 73 71 6c 69 74  )(void);.  sqlit
35720 65 33 5f 6d 75 74 65 78 20 2a 28 2a 78 4d 75 74  e3_mutex *(*xMut
35730 65 78 41 6c 6c 6f 63 29 28 69 6e 74 29 3b 0a 20  exAlloc)(int);. 
35740 20 76 6f 69 64 20 28 2a 78 4d 75 74 65 78 46 72   void (*xMutexFr
35750 65 65 29 28 73 71 6c 69 74 65 33 5f 6d 75 74 65  ee)(sqlite3_mute
35760 78 20 2a 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78  x *);.  void (*x
35770 4d 75 74 65 78 45 6e 74 65 72 29 28 73 71 6c 69  MutexEnter)(sqli
35780 74 65 33 5f 6d 75 74 65 78 20 2a 29 3b 0a 20 20  te3_mutex *);.  
35790 69 6e 74 20 28 2a 78 4d 75 74 65 78 54 72 79 29  int (*xMutexTry)
357a0 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a  (sqlite3_mutex *
357b0 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 4d 75 74  );.  void (*xMut
357c0 65 78 4c 65 61 76 65 29 28 73 71 6c 69 74 65 33  exLeave)(sqlite3
357d0 5f 6d 75 74 65 78 20 2a 29 3b 0a 20 20 69 6e 74  _mutex *);.  int
357e0 20 28 2a 78 4d 75 74 65 78 48 65 6c 64 29 28 73   (*xMutexHeld)(s
357f0 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a 29 3b  qlite3_mutex *);
35800 0a 20 20 69 6e 74 20 28 2a 78 4d 75 74 65 78 4e  .  int (*xMutexN
35810 6f 74 68 65 6c 64 29 28 73 71 6c 69 74 65 33 5f  otheld)(sqlite3_
35820 6d 75 74 65 78 20 2a 29 3b 0a 7d 3b 0a 0a 2f 2a  mutex *);.};../*
35830 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 75  .** CAPI3REF: Mu
35840 74 65 78 20 56 65 72 69 66 69 63 61 74 69 6f 6e  tex Verification
35850 20 52 6f 75 74 69 6e 65 73 20 7b 48 31 37 30 38   Routines {H1708
35860 30 7d 20 3c 53 32 30 31 33 30 3e 20 3c 53 33 30  0} <S20130> <S30
35870 38 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  800>.**.** The s
35880 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 68 65 6c  qlite3_mutex_hel
35890 64 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  d() and sqlite3_
358a0 6d 75 74 65 78 5f 6e 6f 74 68 65 6c 64 28 29 20  mutex_notheld() 
358b0 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 61 72 65 20  routines.** are 
358c0 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65  intended for use
358d0 20 69 6e 73 69 64 65 20 61 73 73 65 72 74 28 29   inside assert()
358e0 20 73 74 61 74 65 6d 65 6e 74 73 2e 20 7b 48 31   statements. {H1
358f0 37 30 38 31 7d 20 54 68 65 20 53 51 4c 69 74 65  7081} The SQLite
35900 20 63 6f 72 65 0a 2a 2a 20 6e 65 76 65 72 20 75   core.** never u
35910 73 65 73 20 74 68 65 73 65 20 72 6f 75 74 69 6e  ses these routin
35920 65 73 20 65 78 63 65 70 74 20 69 6e 73 69 64 65  es except inside
35930 20 61 6e 20 61 73 73 65 72 74 28 29 20 61 6e 64   an assert() and
35940 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a   applications.**
35950 20 61 72 65 20 61 64 76 69 73 65 64 20 74 6f 20   are advised to 
35960 66 6f 6c 6c 6f 77 20 74 68 65 20 6c 65 61 64 20  follow the lead 
35970 6f 66 20 74 68 65 20 63 6f 72 65 2e 20 20 7b 48  of the core.  {H
35980 31 37 30 38 32 7d 20 54 68 65 20 63 6f 72 65 20  17082} The core 
35990 6f 6e 6c 79 0a 2a 2a 20 70 72 6f 76 69 64 65 73  only.** provides
359a0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
359b0 20 66 6f 72 20 74 68 65 73 65 20 72 6f 75 74 69   for these routi
359c0 6e 65 73 20 77 68 65 6e 20 69 74 20 69 73 20 63  nes when it is c
359d0 6f 6d 70 69 6c 65 64 0a 2a 2a 20 77 69 74 68 20  ompiled.** with 
359e0 74 68 65 20 53 51 4c 49 54 45 5f 44 45 42 55 47  the SQLITE_DEBUG
359f0 20 66 6c 61 67 2e 20 20 7b 41 31 37 30 38 37 7d   flag.  {A17087}
35a00 20 45 78 74 65 72 6e 61 6c 20 6d 75 74 65 78 20   External mutex 
35a10 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 0a  implementations.
35a20 2a 2a 20 61 72 65 20 6f 6e 6c 79 20 72 65 71 75  ** are only requ
35a30 69 72 65 64 20 74 6f 20 70 72 6f 76 69 64 65 20  ired to provide 
35a40 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 69  these routines i
35a50 66 20 53 51 4c 49 54 45 5f 44 45 42 55 47 20 69  f SQLITE_DEBUG i
35a60 73 0a 2a 2a 20 64 65 66 69 6e 65 64 20 61 6e 64  s.** defined and
35a70 20 69 66 20 4e 44 45 42 55 47 20 69 73 20 6e 6f   if NDEBUG is no
35a80 74 20 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  t defined..**.**
35a90 20 7b 48 31 37 30 38 33 7d 20 54 68 65 73 65 20   {H17083} These 
35aa0 72 6f 75 74 69 6e 65 73 20 73 68 6f 75 6c 64 20  routines should 
35ab0 72 65 74 75 72 6e 20 74 72 75 65 20 69 66 20 74  return true if t
35ac0 68 65 20 6d 75 74 65 78 20 69 6e 20 74 68 65 69  he mutex in thei
35ad0 72 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 69 73  r argument.** is
35ae0 20 68 65 6c 64 20 6f 72 20 6e 6f 74 20 68 65 6c   held or not hel
35af0 64 2c 20 72 65 73 70 65 63 74 69 76 65 6c 79 2c  d, respectively,
35b00 20 62 79 20 74 68 65 20 63 61 6c 6c 69 6e 67 20   by the calling 
35b10 74 68 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 7b 58  thread..**.** {X
35b20 31 37 30 38 34 7d 20 54 68 65 20 69 6d 70 6c 65  17084} The imple
35b30 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 6e 6f 74  mentation is not
35b40 20 72 65 71 75 69 72 65 64 20 74 6f 20 70 72 6f   required to pro
35b50 76 69 64 65 64 20 76 65 72 73 69 6f 6e 73 20 6f  vided versions o
35b60 66 20 74 68 65 73 65 0a 2a 2a 20 72 6f 75 74 69  f these.** routi
35b70 6e 65 73 20 74 68 61 74 20 61 63 74 75 61 6c 6c  nes that actuall
35b80 79 20 77 6f 72 6b 2e 20 49 66 20 74 68 65 20 69  y work. If the i
35b90 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 64 6f  mplementation do
35ba0 65 73 20 6e 6f 74 20 70 72 6f 76 69 64 65 20 77  es not provide w
35bb0 6f 72 6b 69 6e 67 0a 2a 2a 20 76 65 72 73 69 6f  orking.** versio
35bc0 6e 73 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  ns of these rout
35bd0 69 6e 65 73 2c 20 69 74 20 73 68 6f 75 6c 64 20  ines, it should 
35be0 61 74 20 6c 65 61 73 74 20 70 72 6f 76 69 64 65  at least provide
35bf0 20 73 74 75 62 73 20 74 68 61 74 20 61 6c 77 61   stubs that alwa
35c00 79 73 0a 2a 2a 20 72 65 74 75 72 6e 20 74 72 75  ys.** return tru
35c10 65 20 73 6f 20 74 68 61 74 20 6f 6e 65 20 64 6f  e so that one do
35c20 65 73 20 6e 6f 74 20 67 65 74 20 73 70 75 72 69  es not get spuri
35c30 6f 75 73 20 61 73 73 65 72 74 69 6f 6e 20 66 61  ous assertion fa
35c40 69 6c 75 72 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48  ilures..**.** {H
35c50 31 37 30 38 35 7d 20 49 66 20 74 68 65 20 61 72  17085} If the ar
35c60 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65  gument to sqlite
35c70 33 5f 6d 75 74 65 78 5f 68 65 6c 64 28 29 20 69  3_mutex_held() i
35c80 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
35c90 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 72 6f 75   then.** the rou
35ca0 74 69 6e 65 20 73 68 6f 75 6c 64 20 72 65 74 75  tine should retu
35cb0 72 6e 20 31 2e 20 20 7b 45 4e 44 7d 20 54 68 69  rn 1.  {END} Thi
35cc0 73 20 73 65 65 6d 73 20 63 6f 75 6e 74 65 72 2d  s seems counter-
35cd0 69 6e 74 75 69 74 69 76 65 20 73 69 6e 63 65 0a  intuitive since.
35ce0 2a 2a 20 63 6c 65 61 72 6c 79 20 74 68 65 20 6d  ** clearly the m
35cf0 75 74 65 78 20 63 61 6e 6e 6f 74 20 62 65 20 68  utex cannot be h
35d00 65 6c 64 20 69 66 20 69 74 20 64 6f 65 73 20 6e  eld if it does n
35d10 6f 74 20 65 78 69 73 74 2e 20 20 42 75 74 20 74  ot exist.  But t
35d20 68 65 0a 2a 2a 20 74 68 65 20 72 65 61 73 6f 6e  he.** the reason
35d30 20 74 68 65 20 6d 75 74 65 78 20 64 6f 65 73 20   the mutex does 
35d40 6e 6f 74 20 65 78 69 73 74 20 69 73 20 62 65 63  not exist is bec
35d50 61 75 73 65 20 74 68 65 20 62 75 69 6c 64 20 69  ause the build i
35d60 73 20 6e 6f 74 0a 2a 2a 20 75 73 69 6e 67 20 6d  s not.** using m
35d70 75 74 65 78 65 73 2e 20 20 41 6e 64 20 77 65 20  utexes.  And we 
35d80 64 6f 20 6e 6f 74 20 77 61 6e 74 20 74 68 65 20  do not want the 
35d90 61 73 73 65 72 74 28 29 20 63 6f 6e 74 61 69 6e  assert() contain
35da0 69 6e 67 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 20  ing the.** call 
35db0 74 6f 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  to sqlite3_mutex
35dc0 5f 68 65 6c 64 28 29 20 74 6f 20 66 61 69 6c 2c  _held() to fail,
35dd0 20 73 6f 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 72   so a non-zero r
35de0 65 74 75 72 6e 20 69 73 0a 2a 2a 20 74 68 65 20  eturn is.** the 
35df0 61 70 70 72 6f 70 72 69 61 74 65 20 74 68 69 6e  appropriate thin
35e00 67 20 74 6f 20 64 6f 2e 20 20 7b 48 31 37 30 38  g to do.  {H1708
35e10 36 7d 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6d  6} The sqlite3_m
35e20 75 74 65 78 5f 6e 6f 74 68 65 6c 64 28 29 0a 2a  utex_notheld().*
35e30 2a 20 69 6e 74 65 72 66 61 63 65 20 73 68 6f 75  * interface shou
35e40 6c 64 20 61 6c 73 6f 20 72 65 74 75 72 6e 20 31  ld also return 1
35e50 20 77 68 65 6e 20 67 69 76 65 6e 20 61 20 4e 55   when given a NU
35e60 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2f 0a 69  LL pointer..*/.i
35e70 6e 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  nt sqlite3_mutex
35e80 5f 68 65 6c 64 28 73 71 6c 69 74 65 33 5f 6d 75  _held(sqlite3_mu
35e90 74 65 78 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  tex*);.int sqlit
35ea0 65 33 5f 6d 75 74 65 78 5f 6e 6f 74 68 65 6c 64  e3_mutex_notheld
35eb0 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 2a 29  (sqlite3_mutex*)
35ec0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
35ed0 46 3a 20 4d 75 74 65 78 20 54 79 70 65 73 20 7b  F: Mutex Types {
35ee0 48 31 37 30 30 31 7d 20 3c 48 31 37 30 30 30 3e  H17001} <H17000>
35ef0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69  .**.** The [sqli
35f00 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28  te3_mutex_alloc(
35f10 29 5d 20 69 6e 74 65 72 66 61 63 65 20 74 61 6b  )] interface tak
35f20 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  es a single argu
35f30 6d 65 6e 74 0a 2a 2a 20 77 68 69 63 68 20 69 73  ment.** which is
35f40 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 69 6e   one of these in
35f50 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 2e  teger constants.
35f60 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 74 20 6f  .**.** The set o
35f70 66 20 73 74 61 74 69 63 20 6d 75 74 65 78 65 73  f static mutexes
35f80 20 6d 61 79 20 63 68 61 6e 67 65 20 66 72 6f 6d   may change from
35f90 20 6f 6e 65 20 53 51 4c 69 74 65 20 72 65 6c 65   one SQLite rele
35fa0 61 73 65 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 65  ase to the.** ne
35fb0 78 74 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e  xt.  Application
35fc0 73 20 74 68 61 74 20 6f 76 65 72 72 69 64 65 20  s that override 
35fd0 74 68 65 20 62 75 69 6c 74 2d 69 6e 20 6d 75 74  the built-in mut
35fe0 65 78 20 6c 6f 67 69 63 20 6d 75 73 74 20 62 65  ex logic must be
35ff0 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 74 6f 20  .** prepared to 
36000 61 63 63 6f 6d 6d 6f 64 61 74 65 20 61 64 64 69  accommodate addi
36010 74 69 6f 6e 61 6c 20 73 74 61 74 69 63 20 6d 75  tional static mu
36020 74 65 78 65 73 2e 0a 2a 2f 0a 23 64 65 66 69 6e  texes..*/.#defin
36030 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46  e SQLITE_MUTEX_F
36040 41 53 54 20 20 20 20 20 20 20 20 20 20 20 20 20  AST             
36050 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
36060 5f 4d 55 54 45 58 5f 52 45 43 55 52 53 49 56 45  _MUTEX_RECURSIVE
36070 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e          1.#defin
36080 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53  e SQLITE_MUTEX_S
36090 54 41 54 49 43 5f 4d 41 53 54 45 52 20 20 20 20  TATIC_MASTER    
360a0 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
360b0 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 45  _MUTEX_STATIC_ME
360c0 4d 20 20 20 20 20 20 20 33 20 20 2f 2a 20 73 71  M       3  /* sq
360d0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 2a  lite3_malloc() *
360e0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
360f0 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 45  _MUTEX_STATIC_ME
36100 4d 32 20 20 20 20 20 20 34 20 20 2f 2a 20 4e 4f  M2      4  /* NO
36110 54 20 55 53 45 44 20 2a 2f 0a 23 64 65 66 69 6e  T USED */.#defin
36120 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53  e SQLITE_MUTEX_S
36130 54 41 54 49 43 5f 4f 50 45 4e 20 20 20 20 20 20  TATIC_OPEN      
36140 34 20 20 2f 2a 20 73 71 6c 69 74 65 33 42 74 72  4  /* sqlite3Btr
36150 65 65 4f 70 65 6e 28 29 20 2a 2f 0a 23 64 65 66  eeOpen() */.#def
36160 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58  ine SQLITE_MUTEX
36170 5f 53 54 41 54 49 43 5f 50 52 4e 47 20 20 20 20  _STATIC_PRNG    
36180 20 20 35 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f    5  /* sqlite3_
36190 72 61 6e 64 6f 6d 28 29 20 2a 2f 0a 23 64 65 66  random() */.#def
361a0 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58  ine SQLITE_MUTEX
361b0 5f 53 54 41 54 49 43 5f 4c 52 55 20 20 20 20 20  _STATIC_LRU     
361c0 20 20 36 20 20 2f 2a 20 6c 72 75 20 70 61 67 65    6  /* lru page
361d0 20 6c 69 73 74 20 2a 2f 0a 23 64 65 66 69 6e 65   list */.#define
361e0 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54   SQLITE_MUTEX_ST
361f0 41 54 49 43 5f 4c 52 55 32 20 20 20 20 20 20 37  ATIC_LRU2      7
36200 20 20 2f 2a 20 6c 72 75 20 70 61 67 65 20 6c 69    /* lru page li
36210 73 74 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  st */../*.** CAP
36220 49 33 52 45 46 3a 20 52 65 74 72 69 65 76 65 20  I3REF: Retrieve 
36230 74 68 65 20 6d 75 74 65 78 20 66 6f 72 20 61 20  the mutex for a 
36240 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
36250 69 6f 6e 20 7b 48 31 37 30 30 32 7d 20 3c 48 31  ion {H17002} <H1
36260 37 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  7000>.**.** This
36270 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
36280 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 68 65  ns a pointer the
36290 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d   [sqlite3_mutex]
362a0 20 6f 62 6a 65 63 74 20 74 68 61 74 20 0a 2a 2a   object that .**
362b0 20 73 65 72 69 61 6c 69 7a 65 73 20 61 63 63 65   serializes acce
362c0 73 73 20 74 6f 20 74 68 65 20 5b 64 61 74 61 62  ss to the [datab
362d0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
362e0 67 69 76 65 6e 20 69 6e 20 74 68 65 20 61 72 67  given in the arg
362f0 75 6d 65 6e 74 0a 2a 2a 20 77 68 65 6e 20 74 68  ument.** when th
36300 65 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  e [threading mod
36310 65 5d 20 69 73 20 53 65 72 69 61 6c 69 7a 65 64  e] is Serialized
36320 2e 0a 2a 2a 20 49 66 20 74 68 65 20 5b 74 68 72  ..** If the [thr
36330 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 69 73 20  eading mode] is 
36340 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 20 6f 72  Single-thread or
36350 20 4d 75 6c 74 69 2d 74 68 72 65 61 64 20 74 68   Multi-thread th
36360 65 6e 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69  en this.** routi
36370 6e 65 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c  ne returns a NUL
36380 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2f 0a 73 71  L pointer..*/.sq
36390 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a 73 71 6c  lite3_mutex *sql
363a0 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 28 73 71  ite3_db_mutex(sq
363b0 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  lite3*);../*.** 
363c0 43 41 50 49 33 52 45 46 3a 20 4c 6f 77 2d 4c 65  CAPI3REF: Low-Le
363d0 76 65 6c 20 43 6f 6e 74 72 6f 6c 20 4f 66 20 44  vel Control Of D
363e0 61 74 61 62 61 73 65 20 46 69 6c 65 73 20 7b 48  atabase Files {H
363f0 31 31 33 30 30 7d 20 3c 53 33 30 38 30 30 3e 0a  11300} <S30800>.
36400 2a 2a 0a 2a 2a 20 7b 48 31 31 33 30 31 7d 20 54  **.** {H11301} T
36410 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  he [sqlite3_file
36420 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e 74 65  _control()] inte
36430 72 66 61 63 65 20 6d 61 6b 65 73 20 61 20 64 69  rface makes a di
36440 72 65 63 74 20 63 61 6c 6c 20 74 6f 20 74 68 65  rect call to the
36450 0a 2a 2a 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  .** xFileControl
36460 20 6d 65 74 68 6f 64 20 66 6f 72 20 74 68 65 20   method for the 
36470 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
36480 6f 64 73 5d 20 6f 62 6a 65 63 74 20 61 73 73 6f  ods] object asso
36490 63 69 61 74 65 64 0a 2a 2a 20 77 69 74 68 20 61  ciated.** with a
364a0 20 70 61 72 74 69 63 75 6c 61 72 20 64 61 74 61   particular data
364b0 62 61 73 65 20 69 64 65 6e 74 69 66 69 65 64 20  base identified 
364c0 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72  by the second ar
364d0 67 75 6d 65 6e 74 2e 20 7b 48 31 31 33 30 32 7d  gument. {H11302}
364e0 20 54 68 65 0a 2a 2a 20 6e 61 6d 65 20 6f 66 20   The.** name of 
364f0 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  the database is 
36500 74 68 65 20 6e 61 6d 65 20 61 73 73 69 67 6e 65  the name assigne
36510 64 20 74 6f 20 74 68 65 20 64 61 74 61 62 61 73  d to the databas
36520 65 20 62 79 20 74 68 65 0a 2a 2a 20 3c 61 20 68  e by the.** <a h
36530 72 65 66 3d 22 6c 61 6e 67 5f 61 74 74 61 63 68  ref="lang_attach
36540 2e 68 74 6d 6c 22 3e 41 54 54 41 43 48 3c 2f 61  .html">ATTACH</a
36550 3e 20 53 51 4c 20 63 6f 6d 6d 61 6e 64 20 74 68  > SQL command th
36560 61 74 20 6f 70 65 6e 65 64 20 74 68 65 0a 2a 2a  at opened the.**
36570 20 64 61 74 61 62 61 73 65 2e 20 7b 48 31 31 33   database. {H113
36580 30 33 7d 20 54 6f 20 63 6f 6e 74 72 6f 6c 20 74  03} To control t
36590 68 65 20 6d 61 69 6e 20 64 61 74 61 62 61 73 65  he main database
365a0 20 66 69 6c 65 2c 20 75 73 65 20 74 68 65 20 6e   file, use the n
365b0 61 6d 65 20 22 6d 61 69 6e 22 0a 2a 2a 20 6f 72  ame "main".** or
365c0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
365d0 20 7b 48 31 31 33 30 34 7d 20 54 68 65 20 74 68   {H11304} The th
365e0 69 72 64 20 61 6e 64 20 66 6f 75 72 74 68 20 70  ird and fourth p
365f0 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68 69  arameters to thi
36600 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 61 72 65  s routine.** are
36610 20 70 61 73 73 65 64 20 64 69 72 65 63 74 6c 79   passed directly
36620 20 74 68 72 6f 75 67 68 20 74 6f 20 74 68 65 20   through to the 
36630 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 69 72 64  second and third
36640 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66 0a 2a   parameters of.*
36650 2a 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72  * the xFileContr
36660 6f 6c 20 6d 65 74 68 6f 64 2e 20 20 7b 48 31 31  ol method.  {H11
36670 33 30 35 7d 20 54 68 65 20 72 65 74 75 72 6e 20  305} The return 
36680 76 61 6c 75 65 20 6f 66 20 74 68 65 20 78 46 69  value of the xFi
36690 6c 65 43 6f 6e 74 72 6f 6c 0a 2a 2a 20 6d 65 74  leControl.** met
366a0 68 6f 64 20 62 65 63 6f 6d 65 73 20 74 68 65 20  hod becomes the 
366b0 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20  return value of 
366c0 74 68 69 73 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a  this routine..**
366d0 0a 2a 2a 20 7b 48 31 31 33 30 36 7d 20 49 66 20  .** {H11306} If 
366e0 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  the second param
366f0 65 74 65 72 20 28 7a 44 62 4e 61 6d 65 29 20 64  eter (zDbName) d
36700 6f 65 73 20 6e 6f 74 20 6d 61 74 63 68 20 74 68  oes not match th
36710 65 20 6e 61 6d 65 20 6f 66 20 61 6e 79 0a 2a 2a  e name of any.**
36720 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 20 66   open database f
36730 69 6c 65 2c 20 74 68 65 6e 20 53 51 4c 49 54 45  ile, then SQLITE
36740 5f 45 52 52 4f 52 20 69 73 20 72 65 74 75 72 6e  _ERROR is return
36750 65 64 2e 20 7b 48 31 31 33 30 37 7d 20 54 68 69  ed. {H11307} Thi
36760 73 20 65 72 72 6f 72 0a 2a 2a 20 63 6f 64 65 20  s error.** code 
36770 69 73 20 6e 6f 74 20 72 65 6d 65 6d 62 65 72 65  is not remembere
36780 64 20 61 6e 64 20 77 69 6c 6c 20 6e 6f 74 20 62  d and will not b
36790 65 20 72 65 63 61 6c 6c 65 64 20 62 79 20 5b 73  e recalled by [s
367a0 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29  qlite3_errcode()
367b0 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33  ].** or [sqlite3
367c0 5f 65 72 72 6d 73 67 28 29 5d 2e 20 7b 41 31 31  _errmsg()]. {A11
367d0 33 30 38 7d 20 54 68 65 20 75 6e 64 65 72 6c 79  308} The underly
367e0 69 6e 67 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  ing xFileControl
367f0 20 6d 65 74 68 6f 64 20 6d 69 67 68 74 0a 2a 2a   method might.**
36800 20 61 6c 73 6f 20 72 65 74 75 72 6e 20 53 51 4c   also return SQL
36810 49 54 45 5f 45 52 52 4f 52 2e 20 20 7b 41 31 31  ITE_ERROR.  {A11
36820 33 30 39 7d 20 54 68 65 72 65 20 69 73 20 6e 6f  309} There is no
36830 20 77 61 79 20 74 6f 20 64 69 73 74 69 6e 67 75   way to distingu
36840 69 73 68 20 62 65 74 77 65 65 6e 0a 2a 2a 20 61  ish between.** a
36850 6e 20 69 6e 63 6f 72 72 65 63 74 20 7a 44 62 4e  n incorrect zDbN
36860 61 6d 65 20 61 6e 64 20 61 6e 20 53 51 4c 49 54  ame and an SQLIT
36870 45 5f 45 52 52 4f 52 20 72 65 74 75 72 6e 20 66  E_ERROR return f
36880 72 6f 6d 20 74 68 65 20 75 6e 64 65 72 6c 79 69  rom the underlyi
36890 6e 67 0a 2a 2a 20 78 46 69 6c 65 43 6f 6e 74 72  ng.** xFileContr
368a0 6f 6c 20 6d 65 74 68 6f 64 2e 20 7b 45 4e 44 7d  ol method. {END}
368b0 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
368c0 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c   [SQLITE_FCNTL_L
368d0 4f 43 4b 53 54 41 54 45 5d 0a 2a 2f 0a 69 6e 74  OCKSTATE].*/.int
368e0 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f   sqlite3_file_co
368f0 6e 74 72 6f 6c 28 73 71 6c 69 74 65 33 2a 2c 20  ntrol(sqlite3*, 
36900 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44 62 4e  const char *zDbN
36910 61 6d 65 2c 20 69 6e 74 20 6f 70 2c 20 76 6f 69  ame, int op, voi
36920 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  d*);../*.** CAPI
36930 33 52 45 46 3a 20 54 65 73 74 69 6e 67 20 49 6e  3REF: Testing In
36940 74 65 72 66 61 63 65 20 7b 48 31 31 34 30 30 7d  terface {H11400}
36950 20 3c 53 33 30 38 30 30 3e 0a 2a 2a 0a 2a 2a 20   <S30800>.**.** 
36960 54 68 65 20 73 71 6c 69 74 65 33 5f 74 65 73 74  The sqlite3_test
36970 5f 63 6f 6e 74 72 6f 6c 28 29 20 69 6e 74 65 72  _control() inter
36980 66 61 63 65 20 69 73 20 75 73 65 64 20 74 6f 20  face is used to 
36990 72 65 61 64 20 6f 75 74 20 69 6e 74 65 72 6e 61  read out interna
369a0 6c 0a 2a 2a 20 73 74 61 74 65 20 6f 66 20 53 51  l.** state of SQ
369b0 4c 69 74 65 20 61 6e 64 20 74 6f 20 69 6e 6a 65  Lite and to inje
369c0 63 74 20 66 61 75 6c 74 73 20 69 6e 74 6f 20 53  ct faults into S
369d0 51 4c 69 74 65 20 66 6f 72 20 74 65 73 74 69 6e  QLite for testin
369e0 67 0a 2a 2a 20 70 75 72 70 6f 73 65 73 2e 20 20  g.** purposes.  
369f0 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
36a00 74 65 72 20 69 73 20 61 6e 20 6f 70 65 72 61 74  ter is an operat
36a10 69 6f 6e 20 63 6f 64 65 20 74 68 61 74 20 64 65  ion code that de
36a20 74 65 72 6d 69 6e 65 73 0a 2a 2a 20 74 68 65 20  termines.** the 
36a30 6e 75 6d 62 65 72 2c 20 6d 65 61 6e 69 6e 67 2c  number, meaning,
36a40 20 61 6e 64 20 6f 70 65 72 61 74 69 6f 6e 20 6f   and operation o
36a50 66 20 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74  f all subsequent
36a60 20 70 61 72 61 6d 65 74 65 72 73 2e 0a 2a 2a 0a   parameters..**.
36a70 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63  ** This interfac
36a80 65 20 69 73 20 6e 6f 74 20 66 6f 72 20 75 73 65  e is not for use
36a90 20 62 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 73   by applications
36aa0 2e 20 20 49 74 20 65 78 69 73 74 73 20 73 6f 6c  .  It exists sol
36ab0 65 6c 79 0a 2a 2a 20 66 6f 72 20 76 65 72 69 66  ely.** for verif
36ac0 79 69 6e 67 20 74 68 65 20 63 6f 72 72 65 63 74  ying the correct
36ad0 20 6f 70 65 72 61 74 69 6f 6e 20 6f 66 20 74 68   operation of th
36ae0 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79  e SQLite library
36af0 2e 20 20 44 65 70 65 6e 64 69 6e 67 0a 2a 2a 20  .  Depending.** 
36b00 6f 6e 20 68 6f 77 20 74 68 65 20 53 51 4c 69 74  on how the SQLit
36b10 65 20 6c 69 62 72 61 72 79 20 69 73 20 63 6f 6d  e library is com
36b20 70 69 6c 65 64 2c 20 74 68 69 73 20 69 6e 74 65  piled, this inte
36b30 72 66 61 63 65 20 6d 69 67 68 74 20 6e 6f 74 20  rface might not 
36b40 65 78 69 73 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  exist..**.** The
36b50 20 64 65 74 61 69 6c 73 20 6f 66 20 74 68 65 20   details of the 
36b60 6f 70 65 72 61 74 69 6f 6e 20 63 6f 64 65 73 2c  operation codes,
36b70 20 74 68 65 69 72 20 6d 65 61 6e 69 6e 67 73 2c   their meanings,
36b80 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 73 0a   the parameters.
36b90 2a 2a 20 74 68 65 79 20 74 61 6b 65 2c 20 61 6e  ** they take, an
36ba0 64 20 77 68 61 74 20 74 68 65 79 20 64 6f 20 61  d what they do a
36bb0 72 65 20 61 6c 6c 20 73 75 62 6a 65 63 74 20 74  re all subject t
36bc0 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75 74  o change without
36bd0 20 6e 6f 74 69 63 65 2e 0a 2a 2a 20 55 6e 6c 69   notice..** Unli
36be0 6b 65 20 6d 6f 73 74 20 6f 66 20 74 68 65 20 53  ke most of the S
36bf0 51 4c 69 74 65 20 41 50 49 2c 20 74 68 69 73 20  QLite API, this 
36c00 66 75 6e 63 74 69 6f 6e 20 69 73 20 6e 6f 74 20  function is not 
36c10 67 75 61 72 61 6e 74 65 65 64 20 74 6f 0a 2a 2a  guaranteed to.**
36c20 20 6f 70 65 72 61 74 65 20 63 6f 6e 73 69 73 74   operate consist
36c30 65 6e 74 6c 79 20 66 72 6f 6d 20 6f 6e 65 20 72  ently from one r
36c40 65 6c 65 61 73 65 20 74 6f 20 74 68 65 20 6e 65  elease to the ne
36c50 78 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  xt..*/.int sqlit
36c60 65 33 5f 74 65 73 74 5f 63 6f 6e 74 72 6f 6c 28  e3_test_control(
36c70 69 6e 74 20 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a 2f  int op, ...);../
36c80 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54  *.** CAPI3REF: T
36c90 65 73 74 69 6e 67 20 49 6e 74 65 72 66 61 63 65  esting Interface
36ca0 20 4f 70 65 72 61 74 69 6f 6e 20 43 6f 64 65 73   Operation Codes
36cb0 20 7b 48 31 31 34 31 30 7d 20 3c 48 31 31 34 30   {H11410} <H1140
36cc0 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63  0>.**.** These c
36cd0 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 74 68 65  onstants are the
36ce0 20 76 61 6c 69 64 20 6f 70 65 72 61 74 69 6f 6e   valid operation
36cf0 20 63 6f 64 65 20 70 61 72 61 6d 65 74 65 72 73   code parameters
36d00 20 75 73 65 64 0a 2a 2a 20 61 73 20 74 68 65 20   used.** as the 
36d10 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
36d20 6f 20 5b 73 71 6c 69 74 65 33 5f 74 65 73 74 5f  o [sqlite3_test_
36d30 63 6f 6e 74 72 6f 6c 28 29 5d 2e 0a 2a 2a 0a 2a  control()]..**.*
36d40 2a 20 54 68 65 73 65 20 70 61 72 61 6d 65 74 65  * These paramete
36d50 72 73 20 61 6e 64 20 74 68 65 69 72 20 6d 65 61  rs and their mea
36d60 6e 69 6e 67 73 20 61 72 65 20 73 75 62 6a 65 63  nings are subjec
36d70 74 20 74 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 77  t to change.** w
36d80 69 74 68 6f 75 74 20 6e 6f 74 69 63 65 2e 20 20  ithout notice.  
36d90 54 68 65 73 65 20 76 61 6c 75 65 73 20 61 72 65  These values are
36da0 20 66 6f 72 20 74 65 73 74 69 6e 67 20 70 75 72   for testing pur
36db0 70 6f 73 65 73 20 6f 6e 6c 79 2e 0a 2a 2a 20 41  poses only..** A
36dc0 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75  pplications shou
36dd0 6c 64 20 6e 6f 74 20 75 73 65 20 61 6e 79 20 6f  ld not use any o
36de0 66 20 74 68 65 73 65 20 70 61 72 61 6d 65 74 65  f these paramete
36df0 72 73 20 6f 72 20 74 68 65 0a 2a 2a 20 5b 73 71  rs or the.** [sq
36e00 6c 69 74 65 33 5f 74 65 73 74 5f 63 6f 6e 74 72  lite3_test_contr
36e10 6f 6c 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e  ol()] interface.
36e20 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
36e30 54 45 5f 54 45 53 54 43 54 52 4c 5f 50 52 4e 47  TE_TESTCTRL_PRNG
36e40 5f 53 41 56 45 20 20 20 20 20 20 20 20 20 20 20  _SAVE           
36e50 20 20 20 20 20 35 0a 23 64 65 66 69 6e 65 20 53       5.#define S
36e60 51 4c 49 54 45 5f 54 45 53 54 43 54 52 4c 5f 50  QLITE_TESTCTRL_P
36e70 52 4e 47 5f 52 45 53 54 4f 52 45 20 20 20 20 20  RNG_RESTORE     
36e80 20 20 20 20 20 20 20 20 36 0a 23 64 65 66 69 6e          6.#defin
36e90 65 20 53 51 4c 49 54 45 5f 54 45 53 54 43 54 52  e SQLITE_TESTCTR
36ea0 4c 5f 50 52 4e 47 5f 52 45 53 45 54 20 20 20 20  L_PRNG_RESET    
36eb0 20 20 20 20 20 20 20 20 20 20 20 37 0a 23 64 65             7.#de
36ec0 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 53 54  fine SQLITE_TEST
36ed0 43 54 52 4c 5f 42 49 54 56 45 43 5f 54 45 53 54  CTRL_BITVEC_TEST
36ee0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 38 0a                8.
36ef0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54  #define SQLITE_T
36f00 45 53 54 43 54 52 4c 5f 46 41 55 4c 54 5f 49 4e  ESTCTRL_FAULT_IN
36f10 53 54 41 4c 4c 20 20 20 20 20 20 20 20 20 20 20  STALL           
36f20 20 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   9.#define SQLIT
36f30 45 5f 54 45 53 54 43 54 52 4c 5f 42 45 4e 49 47  E_TESTCTRL_BENIG
36f40 4e 5f 4d 41 4c 4c 4f 43 5f 48 4f 4f 4b 53 20 20  N_MALLOC_HOOKS  
36f50 20 20 20 31 30 0a 23 64 65 66 69 6e 65 20 53 51     10.#define SQ
36f60 4c 49 54 45 5f 54 45 53 54 43 54 52 4c 5f 50 45  LITE_TESTCTRL_PE
36f70 4e 44 49 4e 47 5f 42 59 54 45 20 20 20 20 20 20  NDING_BYTE      
36f80 20 20 20 20 20 20 31 31 0a 23 64 65 66 69 6e 65        11.#define
36f90 20 53 51 4c 49 54 45 5f 54 45 53 54 43 54 52 4c   SQLITE_TESTCTRL
36fa0 5f 41 53 53 45 52 54 20 20 20 20 20 20 20 20 20  _ASSERT         
36fb0 20 20 20 20 20 20 20 20 20 31 32 0a 23 64 65 66           12.#def
36fc0 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 53 54 43  ine SQLITE_TESTC
36fd0 54 52 4c 5f 41 4c 57 41 59 53 20 20 20 20 20 20  TRL_ALWAYS      
36fe0 20 20 20 20 20 20 20 20 20 20 20 20 31 33 0a 0a              13..
36ff0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
37000 53 51 4c 69 74 65 20 52 75 6e 74 69 6d 65 20 53  SQLite Runtime S
37010 74 61 74 75 73 20 7b 48 31 37 32 30 30 7d 20 3c  tatus {H17200} <
37020 53 36 30 32 30 30 3e 0a 2a 2a 20 45 58 50 45 52  S60200>.** EXPER
37030 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68  IMENTAL.**.** Th
37040 69 73 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  is interface is 
37050 75 73 65 64 20 74 6f 20 72 65 74 72 69 65 76 65  used to retrieve
37060 20 72 75 6e 74 69 6d 65 20 73 74 61 74 75 73 20   runtime status 
37070 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61  information.** a
37080 62 6f 75 74 20 74 68 65 20 70 72 65 66 6f 72 6d  bout the preform
37090 61 6e 63 65 20 6f 66 20 53 51 4c 69 74 65 2c 20  ance of SQLite, 
370a0 61 6e 64 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 74  and optionally t
370b0 6f 20 72 65 73 65 74 20 76 61 72 69 6f 75 73 0a  o reset various.
370c0 2a 2a 20 68 69 67 68 77 61 74 65 72 20 6d 61 72  ** highwater mar
370d0 6b 73 2e 20 20 54 68 65 20 66 69 72 73 74 20 61  ks.  The first a
370e0 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e  rgument is an in
370f0 74 65 67 65 72 20 63 6f 64 65 20 66 6f 72 0a 2a  teger code for.*
37100 2a 20 74 68 65 20 73 70 65 63 69 66 69 63 20 70  * the specific p
37110 61 72 61 6d 65 74 65 72 20 74 6f 20 6d 65 61 73  arameter to meas
37120 75 72 65 2e 20 20 52 65 63 6f 67 6e 69 7a 65 64  ure.  Recognized
37130 20 69 6e 74 65 67 65 72 20 63 6f 64 65 73 0a 2a   integer codes.*
37140 2a 20 61 72 65 20 6f 66 20 74 68 65 20 66 6f 72  * are of the for
37150 6d 20 5b 53 51 4c 49 54 45 5f 53 54 41 54 55 53  m [SQLITE_STATUS
37160 5f 4d 45 4d 4f 52 59 5f 55 53 45 44 20 7c 20 53  _MEMORY_USED | S
37170 51 4c 49 54 45 5f 53 54 41 54 55 53 5f 2e 2e 2e  QLITE_STATUS_...
37180 5d 2e 0a 2a 2a 20 54 68 65 20 63 75 72 72 65 6e  ]..** The curren
37190 74 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 70  t value of the p
371a0 61 72 61 6d 65 74 65 72 20 69 73 20 72 65 74 75  arameter is retu
371b0 72 6e 65 64 20 69 6e 74 6f 20 2a 70 43 75 72 72  rned into *pCurr
371c0 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 68 69 67 68  ent..** The high
371d0 65 73 74 20 72 65 63 6f 72 64 65 64 20 76 61 6c  est recorded val
371e0 75 65 20 69 73 20 72 65 74 75 72 6e 65 64 20 69  ue is returned i
371f0 6e 20 2a 70 48 69 67 68 77 61 74 65 72 2e 20 20  n *pHighwater.  
37200 49 66 20 74 68 65 0a 2a 2a 20 72 65 73 65 74 46  If the.** resetF
37210 6c 61 67 20 69 73 20 74 72 75 65 2c 20 74 68 65  lag is true, the
37220 6e 20 74 68 65 20 68 69 67 68 65 73 74 20 72 65  n the highest re
37230 63 6f 72 64 20 76 61 6c 75 65 20 69 73 20 72 65  cord value is re
37240 73 65 74 20 61 66 74 65 72 0a 2a 2a 20 2a 70 48  set after.** *pH
37250 69 67 68 77 61 74 65 72 20 69 73 20 77 72 69 74  ighwater is writ
37260 74 65 6e 2e 20 53 6f 6d 65 20 70 61 72 61 6d 65  ten. Some parame
37270 74 65 72 73 20 64 6f 20 6e 6f 74 20 72 65 63 6f  ters do not reco
37280 72 64 20 74 68 65 20 68 69 67 68 65 73 74 0a 2a  rd the highest.*
37290 2a 20 76 61 6c 75 65 2e 20 20 46 6f 72 20 74 68  * value.  For th
372a0 6f 73 65 20 70 61 72 61 6d 65 74 65 72 73 0a 2a  ose parameters.*
372b0 2a 20 6e 6f 74 68 69 6e 67 20 69 73 20 77 72 69  * nothing is wri
372c0 74 74 65 6e 20 69 6e 74 6f 20 2a 70 48 69 67 68  tten into *pHigh
372d0 77 61 74 65 72 20 61 6e 64 20 74 68 65 20 72 65  water and the re
372e0 73 65 74 46 6c 61 67 20 69 73 20 69 67 6e 6f 72  setFlag is ignor
372f0 65 64 2e 0a 2a 2a 20 4f 74 68 65 72 20 70 61 72  ed..** Other par
37300 61 6d 65 74 65 72 73 20 72 65 63 6f 72 64 20 6f  ameters record o
37310 6e 6c 79 20 74 68 65 20 68 69 67 68 77 61 74 65  nly the highwate
37320 72 20 6d 61 72 6b 20 61 6e 64 20 6e 6f 74 20 74  r mark and not t
37330 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 76 61  he current.** va
37340 6c 75 65 2e 20 20 46 6f 72 20 74 68 65 73 65 20  lue.  For these 
37350 6c 61 74 74 65 72 20 70 61 72 61 6d 65 74 65 72  latter parameter
37360 73 20 6e 6f 74 68 69 6e 67 20 69 73 20 77 72 69  s nothing is wri
37370 74 74 65 6e 20 69 6e 74 6f 20 2a 70 43 75 72 72  tten into *pCurr
37380 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ent..**.** This 
37390 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
373a0 53 51 4c 49 54 45 5f 4f 4b 20 6f 6e 20 73 75 63  SQLITE_OK on suc
373b0 63 65 73 73 20 61 6e 64 20 61 20 6e 6f 6e 2d 7a  cess and a non-z
373c0 65 72 6f 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f  ero.** [error co
373d0 64 65 5d 20 6f 6e 20 66 61 69 6c 75 72 65 2e 0a  de] on failure..
373e0 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69  **.** This routi
373f0 6e 65 20 69 73 20 74 68 72 65 61 64 73 61 66 65  ne is threadsafe
37400 20 62 75 74 20 69 73 20 6e 6f 74 20 61 74 6f 6d   but is not atom
37410 69 63 2e 20 20 54 68 69 73 20 72 6f 75 74 69 6e  ic.  This routin
37420 65 20 63 61 6e 0a 2a 2a 20 63 61 6c 6c 65 64 20  e can.** called 
37430 77 68 69 6c 65 20 6f 74 68 65 72 20 74 68 72 65  while other thre
37440 61 64 73 20 61 72 65 20 72 75 6e 6e 69 6e 67 20  ads are running 
37450 74 68 65 20 73 61 6d 65 20 6f 72 20 64 69 66 66  the same or diff
37460 65 72 65 6e 74 20 53 51 4c 69 74 65 0a 2a 2a 20  erent SQLite.** 
37470 69 6e 74 65 72 66 61 63 65 73 2e 20 20 48 6f 77  interfaces.  How
37480 65 76 65 72 20 74 68 65 20 76 61 6c 75 65 73 20  ever the values 
37490 72 65 74 75 72 6e 65 64 20 69 6e 20 2a 70 43 75  returned in *pCu
374a0 72 72 65 6e 74 20 61 6e 64 0a 2a 2a 20 2a 70 48  rrent and.** *pH
374b0 69 67 68 77 61 74 65 72 20 72 65 66 6c 65 63 74  ighwater reflect
374c0 20 74 68 65 20 73 74 61 74 75 73 20 6f 66 20 53   the status of S
374d0 51 4c 69 74 65 20 61 74 20 64 69 66 66 65 72 65  QLite at differe
374e0 6e 74 20 70 6f 69 6e 74 73 20 69 6e 20 74 69 6d  nt points in tim
374f0 65 0a 2a 2a 20 61 6e 64 20 69 74 20 69 73 20 70  e.** and it is p
37500 6f 73 73 69 62 6c 65 20 74 68 61 74 20 61 6e 6f  ossible that ano
37510 74 68 65 72 20 74 68 72 65 61 64 20 6d 69 67 68  ther thread migh
37520 74 20 63 68 61 6e 67 65 20 74 68 65 20 70 61 72  t change the par
37530 61 6d 65 74 65 72 0a 2a 2a 20 69 6e 20 62 65 74  ameter.** in bet
37540 77 65 65 6e 20 74 68 65 20 74 69 6d 65 73 20 77  ween the times w
37550 68 65 6e 20 2a 70 43 75 72 72 65 6e 74 20 61 6e  hen *pCurrent an
37560 64 20 2a 70 48 69 67 68 77 61 74 65 72 20 61 72  d *pHighwater ar
37570 65 20 77 72 69 74 74 65 6e 2e 0a 2a 2a 0a 2a 2a  e written..**.**
37580 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
37590 74 65 33 5f 64 62 5f 73 74 61 74 75 73 28 29 5d  te3_db_status()]
375a0 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 50 45 52  .*/.SQLITE_EXPER
375b0 49 4d 45 4e 54 41 4c 20 69 6e 74 20 73 71 6c 69  IMENTAL int sqli
375c0 74 65 33 5f 73 74 61 74 75 73 28 69 6e 74 20 6f  te3_status(int o
375d0 70 2c 20 69 6e 74 20 2a 70 43 75 72 72 65 6e 74  p, int *pCurrent
375e0 2c 20 69 6e 74 20 2a 70 48 69 67 68 77 61 74 65  , int *pHighwate
375f0 72 2c 20 69 6e 74 20 72 65 73 65 74 46 6c 61 67  r, int resetFlag
37600 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  );.../*.** CAPI3
37610 52 45 46 3a 20 53 74 61 74 75 73 20 50 61 72 61  REF: Status Para
37620 6d 65 74 65 72 73 20 7b 48 31 37 32 35 30 7d 20  meters {H17250} 
37630 3c 48 31 37 32 30 30 3e 0a 2a 2a 20 45 58 50 45  <H17200>.** EXPE
37640 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54  RIMENTAL.**.** T
37650 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e  hese integer con
37660 73 74 61 6e 74 73 20 64 65 73 69 67 6e 61 74 65  stants designate
37670 20 76 61 72 69 6f 75 73 20 72 75 6e 2d 74 69 6d   various run-tim
37680 65 20 73 74 61 74 75 73 20 70 61 72 61 6d 65 74  e status paramet
37690 65 72 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20  ers.** that can 
376a0 62 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b  be returned by [
376b0 73 71 6c 69 74 65 33 5f 73 74 61 74 75 73 28 29  sqlite3_status()
376c0 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a  ]..**.** <dl>.**
376d0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 53 54 41 54   <dt>SQLITE_STAT
376e0 55 53 5f 4d 45 4d 4f 52 59 5f 55 53 45 44 3c 2f  US_MEMORY_USED</
376f0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20  dt>.** <dd>This 
37700 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
37710 20 63 75 72 72 65 6e 74 20 61 6d 6f 75 6e 74 20   current amount 
37720 6f 66 20 6d 65 6d 6f 72 79 20 63 68 65 63 6b 65  of memory checke
37730 64 20 6f 75 74 0a 2a 2a 20 75 73 69 6e 67 20 5b  d out.** using [
37740 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
37750 5d 2c 20 65 69 74 68 65 72 20 64 69 72 65 63 74  ], either direct
37760 6c 79 20 6f 72 20 69 6e 64 69 72 65 63 74 6c 79  ly or indirectly
37770 2e 20 20 54 68 65 0a 2a 2a 20 66 69 67 75 72 65  .  The.** figure
37780 20 69 6e 63 6c 75 64 65 73 20 63 61 6c 6c 73 20   includes calls 
37790 6d 61 64 65 20 74 6f 20 5b 73 71 6c 69 74 65 33  made to [sqlite3
377a0 5f 6d 61 6c 6c 6f 63 28 29 5d 20 62 79 20 74 68  _malloc()] by th
377b0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a  e application.**
377c0 20 61 6e 64 20 69 6e 74 65 72 6e 61 6c 20 6d 65   and internal me
377d0 6d 6f 72 79 20 75 73 61 67 65 20 62 79 20 74 68  mory usage by th
377e0 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79  e SQLite library
377f0 2e 20 20 53 63 72 61 74 63 68 20 6d 65 6d 6f 72  .  Scratch memor
37800 79 0a 2a 2a 20 63 6f 6e 74 72 6f 6c 6c 65 64 20  y.** controlled 
37810 62 79 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  by [SQLITE_CONFI
37820 47 5f 53 43 52 41 54 43 48 5d 20 61 6e 64 20 61  G_SCRATCH] and a
37830 75 78 69 6c 69 61 72 79 20 70 61 67 65 2d 63 61  uxiliary page-ca
37840 63 68 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 63 6f  che.** memory co
37850 6e 74 72 6f 6c 6c 65 64 20 62 79 20 5b 53 51 4c  ntrolled by [SQL
37860 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43  ITE_CONFIG_PAGEC
37870 41 43 48 45 5d 20 69 73 20 6e 6f 74 20 69 6e 63  ACHE] is not inc
37880 6c 75 64 65 64 20 69 6e 0a 2a 2a 20 74 68 69 73  luded in.** this
37890 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54 68 65   parameter.  The
378a0 20 61 6d 6f 75 6e 74 20 72 65 74 75 72 6e 65 64   amount returned
378b0 20 69 73 20 74 68 65 20 73 75 6d 20 6f 66 20 74   is the sum of t
378c0 68 65 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a  he allocation.**
378d0 20 73 69 7a 65 73 20 61 73 20 72 65 70 6f 72 74   sizes as report
378e0 65 64 20 62 79 20 74 68 65 20 78 53 69 7a 65 20  ed by the xSize 
378f0 6d 65 74 68 6f 64 20 69 6e 20 5b 73 71 6c 69 74  method in [sqlit
37900 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 2e  e3_mem_methods].
37910 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
37920 53 51 4c 49 54 45 5f 53 54 41 54 55 53 5f 4d 41  SQLITE_STATUS_MA
37930 4c 4c 4f 43 5f 53 49 5a 45 3c 2f 64 74 3e 0a 2a  LLOC_SIZE</dt>.*
37940 2a 20 3c 64 64 3e 54 68 69 73 20 70 61 72 61 6d  * <dd>This param
37950 65 74 65 72 20 72 65 63 6f 72 64 73 20 74 68 65  eter records the
37960 20 6c 61 72 67 65 73 74 20 6d 65 6d 6f 72 79 20   largest memory 
37970 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 65  allocation reque
37980 73 74 0a 2a 2a 20 68 61 6e 64 65 64 20 74 6f 20  st.** handed to 
37990 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
379a0 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72  )] or [sqlite3_r
379b0 65 61 6c 6c 6f 63 28 29 5d 20 28 6f 72 20 74 68  ealloc()] (or th
379c0 65 69 72 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 20  eir.** internal 
379d0 65 71 75 69 76 61 6c 65 6e 74 73 29 2e 20 20 4f  equivalents).  O
379e0 6e 6c 79 20 74 68 65 20 76 61 6c 75 65 20 72 65  nly the value re
379f0 74 75 72 6e 65 64 20 69 6e 20 74 68 65 0a 2a 2a  turned in the.**
37a00 20 2a 70 48 69 67 68 77 61 74 65 72 20 70 61 72   *pHighwater par
37a10 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74  ameter to [sqlit
37a20 65 33 5f 73 74 61 74 75 73 28 29 5d 20 69 73 20  e3_status()] is 
37a30 6f 66 20 69 6e 74 65 72 65 73 74 2e 20 20 0a 2a  of interest.  .*
37a40 2a 20 54 68 65 20 76 61 6c 75 65 20 77 72 69 74  * The value writ
37a50 74 65 6e 20 69 6e 74 6f 20 74 68 65 20 2a 70 43  ten into the *pC
37a60 75 72 72 65 6e 74 20 70 61 72 61 6d 65 74 65 72  urrent parameter
37a70 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 3c 2f   is undefined.</
37a80 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51  dd>.**.** <dt>SQ
37a90 4c 49 54 45 5f 53 54 41 54 55 53 5f 50 41 47 45  LITE_STATUS_PAGE
37aa0 43 41 43 48 45 5f 55 53 45 44 3c 2f 64 74 3e 0a  CACHE_USED</dt>.
37ab0 2a 2a 20 3c 64 64 3e 54 68 69 73 20 70 61 72 61  ** <dd>This para
37ac0 6d 65 74 65 72 20 72 65 74 75 72 6e 73 20 74 68  meter returns th
37ad0 65 20 6e 75 6d 62 65 72 20 6f 66 20 70 61 67 65  e number of page
37ae0 73 20 75 73 65 64 20 6f 75 74 20 6f 66 20 74 68  s used out of th
37af0 65 0a 2a 2a 20 5b 70 61 67 65 63 61 63 68 65 20  e.** [pagecache 
37b00 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
37b10 5d 20 74 68 61 74 20 77 61 73 20 63 6f 6e 66 69  ] that was confi
37b20 67 75 72 65 64 20 75 73 69 6e 67 20 0a 2a 2a 20  gured using .** 
37b30 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  [SQLITE_CONFIG_P
37b40 41 47 45 43 41 43 48 45 5d 2e 20 20 54 68 65 0a  AGECACHE].  The.
37b50 2a 2a 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  ** value returne
37b60 64 20 69 73 20 69 6e 20 70 61 67 65 73 2c 20 6e  d is in pages, n
37b70 6f 74 20 69 6e 20 62 79 74 65 73 2e 3c 2f 64 64  ot in bytes.</dd
37b80 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
37b90 54 45 5f 53 54 41 54 55 53 5f 50 41 47 45 43 41  TE_STATUS_PAGECA
37ba0 43 48 45 5f 4f 56 45 52 46 4c 4f 57 3c 2f 64 74  CHE_OVERFLOW</dt
37bb0 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 70 61  >.** <dd>This pa
37bc0 72 61 6d 65 74 65 72 20 72 65 74 75 72 6e 73 20  rameter returns 
37bd0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
37be0 74 65 73 20 6f 66 20 70 61 67 65 20 63 61 63 68  tes of page cach
37bf0 65 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  e.** allocation 
37c00 77 68 69 63 68 20 63 6f 75 6c 64 20 6e 6f 74 20  which could not 
37c10 62 65 20 73 74 61 74 69 73 66 69 65 64 20 62 79  be statisfied by
37c20 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e   the [SQLITE_CON
37c30 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d 0a 2a  FIG_PAGECACHE].*
37c40 2a 20 62 75 66 66 65 72 20 61 6e 64 20 77 68 65  * buffer and whe
37c50 72 65 20 66 6f 72 63 65 64 20 74 6f 20 6f 76 65  re forced to ove
37c60 72 66 6c 6f 77 20 74 6f 20 5b 73 71 6c 69 74 65  rflow to [sqlite
37c70 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 20 54 68  3_malloc()].  Th
37c80 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 76 61  e.** returned va
37c90 6c 75 65 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c  lue includes all
37ca0 6f 63 61 74 69 6f 6e 73 20 74 68 61 74 20 6f 76  ocations that ov
37cb0 65 72 66 6c 6f 77 65 64 20 62 65 63 61 75 73 65  erflowed because
37cc0 20 74 68 65 79 0a 2a 2a 20 77 68 65 72 65 20 74   they.** where t
37cd0 6f 6f 20 6c 61 72 67 65 20 28 74 68 65 79 20 77  oo large (they w
37ce0 65 72 65 20 6c 61 72 67 65 72 20 74 68 61 6e 20  ere larger than 
37cf0 74 68 65 20 22 73 7a 22 20 70 61 72 61 6d 65 74  the "sz" paramet
37d00 65 72 20 74 6f 0a 2a 2a 20 5b 53 51 4c 49 54 45  er to.** [SQLITE
37d10 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48  _CONFIG_PAGECACH
37d20 45 5d 29 20 61 6e 64 20 61 6c 6c 6f 63 61 74 69  E]) and allocati
37d30 6f 6e 73 20 74 68 61 74 20 6f 76 65 72 66 6c 6f  ons that overflo
37d40 77 65 64 20 62 65 63 61 75 73 65 0a 2a 2a 20 6e  wed because.** n
37d50 6f 20 73 70 61 63 65 20 77 61 73 20 6c 65 66 74  o space was left
37d60 20 69 6e 20 74 68 65 20 70 61 67 65 20 63 61 63   in the page cac
37d70 68 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  he.</dd>.**.** <
37d80 64 74 3e 53 51 4c 49 54 45 5f 53 54 41 54 55 53  dt>SQLITE_STATUS
37d90 5f 50 41 47 45 43 41 43 48 45 5f 53 49 5a 45 3c  _PAGECACHE_SIZE<
37da0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73  /dt>.** <dd>This
37db0 20 70 61 72 61 6d 65 74 65 72 20 72 65 63 6f 72   parameter recor
37dc0 64 73 20 74 68 65 20 6c 61 72 67 65 73 74 20 6d  ds the largest m
37dd0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
37de0 20 72 65 71 75 65 73 74 0a 2a 2a 20 68 61 6e 64   request.** hand
37df0 65 64 20 74 6f 20 5b 70 61 67 65 63 61 63 68 65  ed to [pagecache
37e00 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
37e10 72 5d 2e 20 20 4f 6e 6c 79 20 74 68 65 20 76 61  r].  Only the va
37e20 6c 75 65 20 72 65 74 75 72 6e 65 64 20 69 6e 20  lue returned in 
37e30 74 68 65 0a 2a 2a 20 2a 70 48 69 67 68 77 61 74  the.** *pHighwat
37e40 65 72 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  er parameter to 
37e50 5b 73 71 6c 69 74 65 33 5f 73 74 61 74 75 73 28  [sqlite3_status(
37e60 29 5d 20 69 73 20 6f 66 20 69 6e 74 65 72 65 73  )] is of interes
37e70 74 2e 20 20 0a 2a 2a 20 54 68 65 20 76 61 6c 75  t.  .** The valu
37e80 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74  e written into t
37e90 68 65 20 2a 70 43 75 72 72 65 6e 74 20 70 61 72  he *pCurrent par
37ea0 61 6d 65 74 65 72 20 69 73 20 75 6e 64 65 66 69  ameter is undefi
37eb0 6e 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ned.</dd>.**.** 
37ec0 3c 64 74 3e 53 51 4c 49 54 45 5f 53 54 41 54 55  <dt>SQLITE_STATU
37ed0 53 5f 53 43 52 41 54 43 48 5f 55 53 45 44 3c 2f  S_SCRATCH_USED</
37ee0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20  dt>.** <dd>This 
37ef0 70 61 72 61 6d 65 74 65 72 20 72 65 74 75 72 6e  parameter return
37f00 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
37f10 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 75 73 65 64  allocations used
37f20 20 6f 75 74 20 6f 66 20 74 68 65 0a 2a 2a 20 5b   out of the.** [
37f30 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 20 61  scratch memory a
37f40 6c 6c 6f 63 61 74 6f 72 5d 20 63 6f 6e 66 69 67  llocator] config
37f50 75 72 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 53  ured using.** [S
37f60 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52  QLITE_CONFIG_SCR
37f70 41 54 43 48 5d 2e 20 20 54 68 65 20 76 61 6c 75  ATCH].  The valu
37f80 65 20 72 65 74 75 72 6e 65 64 20 69 73 20 69 6e  e returned is in
37f90 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2c 20 6e 6f   allocations, no
37fa0 74 0a 2a 2a 20 69 6e 20 62 79 74 65 73 2e 20 20  t.** in bytes.  
37fb0 53 69 6e 63 65 20 61 20 73 69 6e 67 6c 65 20 74  Since a single t
37fc0 68 72 65 61 64 20 6d 61 79 20 6f 6e 6c 79 20 68  hread may only h
37fd0 61 76 65 20 6f 6e 65 20 73 63 72 61 74 63 68 20  ave one scratch 
37fe0 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 75  allocation.** ou
37ff0 74 73 74 61 6e 64 69 6e 67 20 61 74 20 74 69 6d  tstanding at tim
38000 65 2c 20 74 68 69 73 20 70 61 72 61 6d 65 74 65  e, this paramete
38010 72 20 61 6c 73 6f 20 72 65 70 6f 72 74 73 20 74  r also reports t
38020 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 74 68 72  he number of thr
38030 65 61 64 73 0a 2a 2a 20 75 73 69 6e 67 20 73 63  eads.** using sc
38040 72 61 74 63 68 20 6d 65 6d 6f 72 79 20 61 74 20  ratch memory at 
38050 74 68 65 20 73 61 6d 65 20 74 69 6d 65 2e 3c 2f  the same time.</
38060 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51  dd>.**.** <dt>SQ
38070 4c 49 54 45 5f 53 54 41 54 55 53 5f 53 43 52 41  LITE_STATUS_SCRA
38080 54 43 48 5f 4f 56 45 52 46 4c 4f 57 3c 2f 64 74  TCH_OVERFLOW</dt
38090 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 70 61  >.** <dd>This pa
380a0 72 61 6d 65 74 65 72 20 72 65 74 75 72 6e 73 20  rameter returns 
380b0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
380c0 74 65 73 20 6f 66 20 73 63 72 61 74 63 68 20 6d  tes of scratch m
380d0 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74  emory.** allocat
380e0 69 6f 6e 20 77 68 69 63 68 20 63 6f 75 6c 64 20  ion which could 
380f0 6e 6f 74 20 62 65 20 73 74 61 74 69 73 66 69 65  not be statisfie
38100 64 20 62 79 20 74 68 65 20 5b 53 51 4c 49 54 45  d by the [SQLITE
38110 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d  _CONFIG_SCRATCH]
38120 0a 2a 2a 20 62 75 66 66 65 72 20 61 6e 64 20 77  .** buffer and w
38130 68 65 72 65 20 66 6f 72 63 65 64 20 74 6f 20 6f  here forced to o
38140 76 65 72 66 6c 6f 77 20 74 6f 20 5b 73 71 6c 69  verflow to [sqli
38150 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 20  te3_malloc()].  
38160 54 68 65 20 76 61 6c 75 65 73 0a 2a 2a 20 72 65  The values.** re
38170 74 75 72 6e 65 64 20 69 6e 63 6c 75 64 65 20 6f  turned include o
38180 76 65 72 66 6c 6f 77 73 20 62 65 63 61 75 73 65  verflows because
38190 20 74 68 65 20 72 65 71 75 65 73 74 65 64 20 61   the requested a
381a0 6c 6c 6f 63 61 74 69 6f 6e 20 77 61 73 20 74 6f  llocation was to
381b0 6f 0a 2a 2a 20 6c 61 72 67 65 72 20 28 74 68 61  o.** larger (tha
381c0 74 20 69 73 2c 20 62 65 63 61 75 73 65 20 74 68  t is, because th
381d0 65 20 72 65 71 75 65 73 74 65 64 20 61 6c 6c 6f  e requested allo
381e0 63 61 74 69 6f 6e 20 77 61 73 20 6c 61 72 67 65  cation was large
381f0 72 20 74 68 61 6e 20 74 68 65 0a 2a 2a 20 22 73  r than the.** "s
38200 7a 22 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  z" parameter to 
38210 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  [SQLITE_CONFIG_S
38220 43 52 41 54 43 48 5d 29 20 61 6e 64 20 62 65 63  CRATCH]) and bec
38230 61 75 73 65 20 6e 6f 20 73 63 72 61 74 63 68 20  ause no scratch 
38240 62 75 66 66 65 72 0a 2a 2a 20 73 6c 6f 74 73 20  buffer.** slots 
38250 77 65 72 65 20 61 76 61 69 6c 61 62 6c 65 2e 0a  were available..
38260 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  ** </dd>.**.** <
38270 64 74 3e 53 51 4c 49 54 45 5f 53 54 41 54 55 53  dt>SQLITE_STATUS
38280 5f 53 43 52 41 54 43 48 5f 53 49 5a 45 3c 2f 64  _SCRATCH_SIZE</d
38290 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 70  t>.** <dd>This p
382a0 61 72 61 6d 65 74 65 72 20 72 65 63 6f 72 64 73  arameter records
382b0 20 74 68 65 20 6c 61 72 67 65 73 74 20 6d 65 6d   the largest mem
382c0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72  ory allocation r
382d0 65 71 75 65 73 74 0a 2a 2a 20 68 61 6e 64 65 64  equest.** handed
382e0 20 74 6f 20 5b 73 63 72 61 74 63 68 20 6d 65 6d   to [scratch mem
382f0 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d 2e 20  ory allocator]. 
38300 20 4f 6e 6c 79 20 74 68 65 20 76 61 6c 75 65 20   Only the value 
38310 72 65 74 75 72 6e 65 64 20 69 6e 20 74 68 65 0a  returned in the.
38320 2a 2a 20 2a 70 48 69 67 68 77 61 74 65 72 20 70  ** *pHighwater p
38330 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c  arameter to [sql
38340 69 74 65 33 5f 73 74 61 74 75 73 28 29 5d 20 69  ite3_status()] i
38350 73 20 6f 66 20 69 6e 74 65 72 65 73 74 2e 20 20  s of interest.  
38360 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 20 77 72  .** The value wr
38370 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 20 2a  itten into the *
38380 70 43 75 72 72 65 6e 74 20 70 61 72 61 6d 65 74  pCurrent paramet
38390 65 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  er is undefined.
383a0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
383b0 53 51 4c 49 54 45 5f 53 54 41 54 55 53 5f 50 41  SQLITE_STATUS_PA
383c0 52 53 45 52 5f 53 54 41 43 4b 3c 2f 64 74 3e 0a  RSER_STACK</dt>.
383d0 2a 2a 20 3c 64 64 3e 54 68 69 73 20 70 61 72 61  ** <dd>This para
383e0 6d 65 74 65 72 20 72 65 63 6f 72 64 73 20 74 68  meter records th
383f0 65 20 64 65 65 70 65 73 74 20 70 61 72 73 65 72  e deepest parser
38400 20 73 74 61 63 6b 2e 20 20 49 74 20 69 73 20 6f   stack.  It is o
38410 6e 6c 79 0a 2a 2a 20 6d 65 61 6e 69 6e 67 66 75  nly.** meaningfu
38420 6c 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 63  l if SQLite is c
38430 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 59 59  ompiled with [YY
38440 54 52 41 43 4b 4d 41 58 53 54 41 43 4b 44 45 50  TRACKMAXSTACKDEP
38450 54 48 5d 2e 3c 2f 64 64 3e 0a 2a 2a 20 3c 2f 64  TH].</dd>.** </d
38460 6c 3e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 73 74 61  l>.**.** New sta
38470 74 75 73 20 70 61 72 61 6d 65 74 65 72 73 20 6d  tus parameters m
38480 61 79 20 62 65 20 61 64 64 65 64 20 66 72 6f 6d  ay be added from
38490 20 74 69 6d 65 20 74 6f 20 74 69 6d 65 2e 0a 2a   time to time..*
384a0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
384b0 5f 53 54 41 54 55 53 5f 4d 45 4d 4f 52 59 5f 55  _STATUS_MEMORY_U
384c0 53 45 44 20 20 20 20 20 20 20 20 20 20 30 0a 23  SED          0.#
384d0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 54  define SQLITE_ST
384e0 41 54 55 53 5f 50 41 47 45 43 41 43 48 45 5f 55  ATUS_PAGECACHE_U
384f0 53 45 44 20 20 20 20 20 20 20 31 0a 23 64 65 66  SED       1.#def
38500 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 41 54 55  ine SQLITE_STATU
38510 53 5f 50 41 47 45 43 41 43 48 45 5f 4f 56 45 52  S_PAGECACHE_OVER
38520 46 4c 4f 57 20 20 20 32 0a 23 64 65 66 69 6e 65  FLOW   2.#define
38530 20 53 51 4c 49 54 45 5f 53 54 41 54 55 53 5f 53   SQLITE_STATUS_S
38540 43 52 41 54 43 48 5f 55 53 45 44 20 20 20 20 20  CRATCH_USED     
38550 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51      3.#define SQ
38560 4c 49 54 45 5f 53 54 41 54 55 53 5f 53 43 52 41  LITE_STATUS_SCRA
38570 54 43 48 5f 4f 56 45 52 46 4c 4f 57 20 20 20 20  TCH_OVERFLOW    
38580 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   4.#define SQLIT
38590 45 5f 53 54 41 54 55 53 5f 4d 41 4c 4c 4f 43 5f  E_STATUS_MALLOC_
385a0 53 49 5a 45 20 20 20 20 20 20 20 20 20 20 35 0a  SIZE          5.
385b0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
385c0 54 41 54 55 53 5f 50 41 52 53 45 52 5f 53 54 41  TATUS_PARSER_STA
385d0 43 4b 20 20 20 20 20 20 20 20 20 36 0a 23 64 65  CK         6.#de
385e0 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 41 54  fine SQLITE_STAT
385f0 55 53 5f 50 41 47 45 43 41 43 48 45 5f 53 49 5a  US_PAGECACHE_SIZ
38600 45 20 20 20 20 20 20 20 37 0a 23 64 65 66 69 6e  E       7.#defin
38610 65 20 53 51 4c 49 54 45 5f 53 54 41 54 55 53 5f  e SQLITE_STATUS_
38620 53 43 52 41 54 43 48 5f 53 49 5a 45 20 20 20 20  SCRATCH_SIZE    
38630 20 20 20 20 20 38 0a 0a 2f 2a 0a 2a 2a 20 43 41       8../*.** CA
38640 50 49 33 52 45 46 3a 20 44 61 74 61 62 61 73 65  PI3REF: Database
38650 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 53 74 61 74   Connection Stat
38660 75 73 20 7b 48 31 37 35 30 30 7d 20 3c 53 36 30  us {H17500} <S60
38670 32 30 30 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 45  200>.** EXPERIME
38680 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  NTAL.**.** This 
38690 69 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 65  interface is use
386a0 64 20 74 6f 20 72 65 74 72 69 65 76 65 20 72 75  d to retrieve ru
386b0 6e 74 69 6d 65 20 73 74 61 74 75 73 20 69 6e 66  ntime status inf
386c0 6f 72 6d 61 74 69 6f 6e 20 0a 2a 2a 20 61 62 6f  ormation .** abo
386d0 75 74 20 61 20 73 69 6e 67 6c 65 20 5b 64 61 74  ut a single [dat
386e0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
386f0 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20 61 72  ].  The first ar
38700 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a  gument is the.**
38710 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
38720 74 69 6f 6e 20 6f 62 6a 65 63 74 20 74 6f 20 62  tion object to b
38730 65 20 69 6e 74 65 72 72 6f 67 61 74 65 64 2e 20  e interrogated. 
38740 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   The second argu
38750 6d 65 6e 74 0a 2a 2a 20 69 73 20 74 68 65 20 70  ment.** is the p
38760 61 72 61 6d 65 74 65 72 20 74 6f 20 69 6e 74 65  arameter to inte
38770 72 72 6f 67 61 74 65 2e 20 20 43 75 72 72 65 6e  rrogate.  Curren
38780 74 6c 79 2c 20 74 68 65 20 6f 6e 6c 79 20 61 6c  tl