System.Data.SQLite
Hex Artifact Content
Not logged in

Artifact ade761ae5566c39e3b103d3a1ccd54ec1a1ce43c:


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 33 37 20 32 30 30 38 2f 30 39 2f 30  v 1.37 2008/09/0
05f0: 32 20 31 35 3a 34 36 3a 31 34 20 72 6d 73 69 6d  2 15:46:14 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 41 64 64 20 74 68 65 20 61  ./*.** Add the a
0750: 62 69 6c 69 74 79 20 74 6f 20 6d 61 72 6b 20 69  bility to mark i
0760: 6e 74 65 72 66 61 63 65 73 20 61 73 20 64 65 70  nterfaces as dep
0770: 72 65 63 61 74 65 64 2e 0a 2a 2f 0a 23 69 66 20  recated..*/.#if 
0780: 28 5f 5f 47 4e 55 43 5f 5f 20 3e 20 33 20 7c 7c  (__GNUC__ > 3 ||
0790: 20 28 5f 5f 47 4e 55 43 5f 5f 20 3d 3d 20 33 20   (__GNUC__ == 3 
07a0: 26 26 20 5f 5f 47 4e 55 43 5f 4d 49 4e 4f 52 5f  && __GNUC_MINOR_
07b0: 5f 20 3e 3d 20 31 29 29 0a 20 20 2f 2a 20 47 43  _ >= 1)).  /* GC
07c0: 43 20 61 64 64 65 64 20 74 68 65 20 64 65 70 72  C added the depr
07d0: 65 63 61 74 65 64 20 61 74 74 72 69 62 75 74 65  ecated attribute
07e0: 20 69 6e 20 76 65 72 73 69 6f 6e 20 33 2e 31 20   in version 3.1 
07f0: 2a 2f 0a 20 20 23 64 65 66 69 6e 65 20 53 51 4c  */.  #define SQL
0800: 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 5f  ITE_DEPRECATED _
0810: 5f 61 74 74 72 69 62 75 74 65 5f 5f 20 28 28 64  _attribute__ ((d
0820: 65 70 72 65 63 61 74 65 64 29 29 0a 23 65 6c 69  eprecated)).#eli
0830: 66 20 64 65 66 69 6e 65 64 28 5f 4d 53 43 5f 56  f defined(_MSC_V
0840: 45 52 29 0a 20 20 23 64 65 66 69 6e 65 20 53 51  ER).  #define SQ
0850: 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20  LITE_DEPRECATED 
0860: 5f 5f 64 65 63 6c 73 70 65 63 28 64 65 70 72 65  __declspec(depre
0870: 63 61 74 65 64 29 0a 23 65 6c 73 65 0a 20 20 23  cated).#else.  #
0880: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45  define SQLITE_DE
0890: 50 52 45 43 41 54 45 44 0a 23 65 6e 64 69 66 0a  PRECATED.#endif.
08a0: 0a 2f 2a 0a 2a 2a 20 41 64 64 20 74 68 65 20 61  ./*.** Add the a
08b0: 62 69 6c 69 74 79 20 74 6f 20 6d 61 72 6b 20 69  bility to mark i
08c0: 6e 74 65 72 66 61 63 65 73 20 61 73 20 65 78 70  nterfaces as exp
08d0: 65 72 69 6d 65 6e 74 61 6c 2e 0a 2a 2f 0a 23 69  erimental..*/.#i
08e0: 66 20 28 5f 5f 47 4e 55 43 5f 5f 20 3e 20 34 20  f (__GNUC__ > 4 
08f0: 7c 7c 20 28 5f 5f 47 4e 55 43 5f 5f 20 3d 3d 20  || (__GNUC__ == 
0900: 34 20 26 26 20 5f 5f 47 4e 55 43 5f 4d 49 4e 4f  4 && __GNUC_MINO
0910: 52 5f 5f 20 3e 3d 20 33 29 29 0a 20 20 2f 2a 20  R__ >= 3)).  /* 
0920: 49 20 63 61 6e 20 63 6f 6e 66 69 72 6d 20 74 68  I can confirm th
0930: 61 74 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 77  at it does not w
0940: 6f 72 6b 20 6f 6e 20 76 65 72 73 69 6f 6e 20 34  ork on version 4
0950: 2e 31 2e 30 2e 2e 2e 20 2a 2f 0a 20 20 2f 2a 20  .1.0... */.  /* 
0960: 46 69 72 73 74 20 61 70 70 65 61 72 73 20 69 6e  First appears in
0970: 20 47 43 43 20 64 6f 63 73 20 66 6f 72 20 76 65   GCC docs for ve
0980: 72 73 69 6f 6e 20 34 2e 33 2e 30 20 2a 2f 0a 20  rsion 4.3.0 */. 
0990: 20 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f   #define SQLITE_
09a0: 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 5f 5f 61  EXPERIMENTAL __a
09b0: 74 74 72 69 62 75 74 65 5f 5f 20 28 28 77 61 72  ttribute__ ((war
09c0: 6e 69 6e 67 20 28 22 69 73 20 65 78 70 65 72 69  ning ("is experi
09d0: 6d 65 6e 74 61 6c 22 29 29 29 0a 23 65 6c 69 66  mental"))).#elif
09e0: 20 64 65 66 69 6e 65 64 28 5f 4d 53 43 5f 56 45   defined(_MSC_VE
09f0: 52 29 0a 20 20 23 64 65 66 69 6e 65 20 53 51 4c  R).  #define SQL
0a00: 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c  ITE_EXPERIMENTAL
0a10: 20 5f 5f 64 65 63 6c 73 70 65 63 28 64 65 70 72   __declspec(depr
0a20: 65 63 61 74 65 64 28 22 77 61 73 20 64 65 63 6c  ecated("was decl
0a30: 61 72 65 64 20 65 78 70 65 72 69 6d 65 6e 74 61  ared experimenta
0a40: 6c 22 29 29 0a 23 65 6c 73 65 0a 20 20 23 64 65  l")).#else.  #de
0a50: 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 58 50 45  fine SQLITE_EXPE
0a60: 52 49 4d 45 4e 54 41 4c 0a 23 65 6e 64 69 66 0a  RIMENTAL.#endif.
0a70: 0a 2f 2a 0a 2a 2a 20 45 6e 73 75 72 65 20 74 68  ./*.** Ensure th
0a80: 65 73 65 20 73 79 6d 62 6f 6c 73 20 77 65 72 65  ese symbols were
0a90: 20 6e 6f 74 20 64 65 66 69 6e 65 64 20 62 79 20   not defined by 
0aa0: 73 6f 6d 65 20 70 72 65 76 69 6f 75 73 20 68 65  some previous he
0ab0: 61 64 65 72 20 66 69 6c 65 2e 0a 2a 2f 0a 23 69  ader file..*/.#i
0ac0: 66 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53  fdef SQLITE_VERS
0ad0: 49 4f 4e 0a 23 20 75 6e 64 65 66 20 53 51 4c 49  ION.# undef SQLI
0ae0: 54 45 5f 56 45 52 53 49 4f 4e 0a 23 65 6e 64 69  TE_VERSION.#endi
0af0: 66 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f  f.#ifdef SQLITE_
0b00: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 0a 23  VERSION_NUMBER.#
0b10: 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 56 45   undef SQLITE_VE
0b20: 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 0a 23 65 6e  RSION_NUMBER.#en
0b30: 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  dif../*.** CAPI3
0b40: 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d  REF: Compile-Tim
0b50: 65 20 4c 69 62 72 61 72 79 20 56 65 72 73 69 6f  e Library Versio
0b60: 6e 20 4e 75 6d 62 65 72 73 20 7b 48 31 30 30 31  n Numbers {H1001
0b70: 30 7d 20 3c 53 36 30 31 30 30 3e 0a 2a 2a 0a 2a  0} <S60100>.**.*
0b80: 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 56 45 52  * The SQLITE_VER
0b90: 53 49 4f 4e 20 61 6e 64 20 53 51 4c 49 54 45 5f  SION and SQLITE_
0ba0: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 23  VERSION_NUMBER #
0bb0: 64 65 66 69 6e 65 73 20 69 6e 0a 2a 2a 20 74 68  defines in.** th
0bc0: 65 20 73 71 6c 69 74 65 33 2e 68 20 66 69 6c 65  e sqlite3.h file
0bd0: 20 73 70 65 63 69 66 79 20 74 68 65 20 76 65 72   specify the ver
0be0: 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65 20 77  sion of SQLite w
0bf0: 69 74 68 20 77 68 69 63 68 0a 2a 2a 20 74 68 61  ith which.** tha
0c00: 74 20 68 65 61 64 65 72 20 66 69 6c 65 20 69 73  t header file is
0c10: 20 61 73 73 6f 63 69 61 74 65 64 2e 0a 2a 2a 0a   associated..**.
0c20: 2a 2a 20 54 68 65 20 22 76 65 72 73 69 6f 6e 22  ** The "version"
0c30: 20 6f 66 20 53 51 4c 69 74 65 20 69 73 20 61 20   of SQLite is a 
0c40: 73 74 72 69 6e 67 20 6f 66 20 74 68 65 20 66 6f  string of the fo
0c50: 72 6d 20 22 58 2e 59 2e 5a 22 2e 0a 2a 2a 20 54  rm "X.Y.Z"..** T
0c60: 68 65 20 70 68 72 61 73 65 20 22 61 6c 70 68 61  he phrase "alpha
0c70: 22 20 6f 72 20 22 62 65 74 61 22 20 6d 69 67 68  " or "beta" migh
0c80: 74 20 62 65 20 61 70 70 65 6e 64 65 64 20 61 66  t be appended af
0c90: 74 65 72 20 74 68 65 20 5a 2e 0a 2a 2a 20 54 68  ter the Z..** Th
0ca0: 65 20 58 20 76 61 6c 75 65 20 69 73 20 6d 61 6a  e X value is maj
0cb0: 6f 72 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65  or version numbe
0cc0: 72 20 61 6c 77 61 79 73 20 33 20 69 6e 20 53 51  r always 3 in SQ
0cd0: 4c 69 74 65 33 2e 0a 2a 2a 20 54 68 65 20 58 20  Lite3..** The X 
0ce0: 76 61 6c 75 65 20 6f 6e 6c 79 20 63 68 61 6e 67  value only chang
0cf0: 65 73 20 77 68 65 6e 20 62 61 63 6b 77 61 72 64  es when backward
0d00: 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20  s compatibility 
0d10: 69 73 0a 2a 2a 20 62 72 6f 6b 65 6e 20 61 6e 64  is.** broken and
0d20: 20 77 65 20 69 6e 74 65 6e 64 20 74 6f 20 6e 65   we intend to ne
0d30: 76 65 72 20 62 72 65 61 6b 20 62 61 63 6b 77 61  ver break backwa
0d40: 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  rds compatibilit
0d50: 79 2e 0a 2a 2a 20 54 68 65 20 59 20 76 61 6c 75  y..** The Y valu
0d60: 65 20 69 73 20 74 68 65 20 6d 69 6e 6f 72 20 76  e is the minor v
0d70: 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 61 6e  ersion number an
0d80: 64 20 6f 6e 6c 79 20 63 68 61 6e 67 65 73 20 77  d only changes w
0d90: 68 65 6e 0a 2a 2a 20 74 68 65 72 65 20 61 72 65  hen.** there are
0da0: 20 6d 61 6a 6f 72 20 66 65 61 74 75 72 65 20 65   major feature e
0db0: 6e 68 61 6e 63 65 6d 65 6e 74 73 20 74 68 61 74  nhancements that
0dc0: 20 61 72 65 20 66 6f 72 77 61 72 64 73 20 63 6f   are forwards co
0dd0: 6d 70 61 74 69 62 6c 65 0a 2a 2a 20 62 75 74 20  mpatible.** but 
0de0: 6e 6f 74 20 62 61 63 6b 77 61 72 64 73 20 63 6f  not backwards co
0df0: 6d 70 61 74 69 62 6c 65 2e 0a 2a 2a 20 54 68 65  mpatible..** The
0e00: 20 5a 20 76 61 6c 75 65 20 69 73 20 74 68 65 20   Z value is the 
0e10: 72 65 6c 65 61 73 65 20 6e 75 6d 62 65 72 20 61  release number a
0e20: 6e 64 20 69 73 20 69 6e 63 72 65 6d 65 6e 74 65  nd is incremente
0e30: 64 20 77 69 74 68 0a 2a 2a 20 65 61 63 68 20 72  d with.** each r
0e40: 65 6c 65 61 73 65 20 62 75 74 20 72 65 73 65 74  elease but reset
0e50: 73 20 62 61 63 6b 20 74 6f 20 30 20 77 68 65 6e  s back to 0 when
0e60: 65 76 65 72 20 59 20 69 73 20 69 6e 63 72 65 6d  ever Y is increm
0e70: 65 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  ented..**.** See
0e80: 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
0e90: 6c 69 62 76 65 72 73 69 6f 6e 28 29 5d 20 61 6e  libversion()] an
0ea0: 64 20 5b 73 71 6c 69 74 65 33 5f 6c 69 62 76 65  d [sqlite3_libve
0eb0: 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 5d 2e  rsion_number()].
0ec0: 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
0ed0: 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 30 31 31  S:.**.** {H10011
0ee0: 7d 20 54 68 65 20 53 51 4c 49 54 45 5f 56 45 52  } The SQLITE_VER
0ef0: 53 49 4f 4e 20 23 64 65 66 69 6e 65 20 69 6e 20  SION #define in 
0f00: 74 68 65 20 73 71 6c 69 74 65 33 2e 68 20 68 65  the sqlite3.h he
0f10: 61 64 65 72 20 66 69 6c 65 20 73 68 61 6c 6c 0a  ader file shall.
0f20: 2a 2a 20 20 20 20 20 20 20 20 20 20 65 76 61 6c  **          eval
0f30: 75 61 74 65 20 74 6f 20 61 20 73 74 72 69 6e 67  uate to a string
0f40: 20 6c 69 74 65 72 61 6c 20 74 68 61 74 20 69 73   literal that is
0f50: 20 74 68 65 20 53 51 4c 69 74 65 20 76 65 72 73   the SQLite vers
0f60: 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ion.**          
0f70: 77 69 74 68 20 77 68 69 63 68 20 74 68 65 20 68  with which the h
0f80: 65 61 64 65 72 20 66 69 6c 65 20 69 73 20 61 73  eader file is as
0f90: 73 6f 63 69 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20  sociated..**.** 
0fa0: 7b 48 31 30 30 31 34 7d 20 54 68 65 20 53 51 4c  {H10014} The SQL
0fb0: 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42  ITE_VERSION_NUMB
0fc0: 45 52 20 23 64 65 66 69 6e 65 20 73 68 61 6c 6c  ER #define shall
0fd0: 20 72 65 73 6f 6c 76 65 20 74 6f 20 61 6e 20 69   resolve to an i
0fe0: 6e 74 65 67 65 72 0a 2a 2a 20 20 20 20 20 20 20  nteger.**       
0ff0: 20 20 20 77 69 74 68 20 74 68 65 20 76 61 6c 75     with the valu
1000: 65 20 28 58 2a 31 30 30 30 30 30 30 20 2b 20 59  e (X*1000000 + Y
1010: 2a 31 30 30 30 20 2b 20 5a 29 20 77 68 65 72 65  *1000 + Z) where
1020: 20 58 2c 20 59 2c 20 61 6e 64 20 5a 0a 2a 2a 20   X, Y, and Z.** 
1030: 20 20 20 20 20 20 20 20 20 61 72 65 20 74 68 65           are the
1040: 20 6d 61 6a 6f 72 20 76 65 72 73 69 6f 6e 2c 20   major version, 
1050: 6d 69 6e 6f 72 20 76 65 72 73 69 6f 6e 2c 20 61  minor version, a
1060: 6e 64 20 72 65 6c 65 61 73 65 20 6e 75 6d 62 65  nd release numbe
1070: 72 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  r..*/.#define SQ
1080: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 20 20 20 20  LITE_VERSION    
1090: 20 20 20 20 20 22 33 2e 36 2e 32 22 0a 23 64 65       "3.6.2".#de
10a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 56 45 52 53  fine SQLITE_VERS
10b0: 49 4f 4e 5f 4e 55 4d 42 45 52 20 20 33 30 30 36  ION_NUMBER  3006
10c0: 30 30 32 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  002../*.** CAPI3
10d0: 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69  REF: Run-Time Li
10e0: 62 72 61 72 79 20 56 65 72 73 69 6f 6e 20 4e 75  brary Version Nu
10f0: 6d 62 65 72 73 20 7b 48 31 30 30 32 30 7d 20 3c  mbers {H10020} <
1100: 53 36 30 31 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f  S60100>.** KEYWO
1110: 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 76 65 72  RDS: sqlite3_ver
1120: 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  sion.**.** These
1130: 20 66 65 61 74 75 72 65 73 20 70 72 6f 76 69 64   features provid
1140: 65 20 74 68 65 20 73 61 6d 65 20 69 6e 66 6f 72  e the same infor
1150: 6d 61 74 69 6f 6e 20 61 73 20 74 68 65 20 5b 53  mation as the [S
1160: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 0a 2a  QLITE_VERSION].*
1170: 2a 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 56 45  * and [SQLITE_VE
1180: 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 20 23 64  RSION_NUMBER] #d
1190: 65 66 69 6e 65 73 20 69 6e 20 74 68 65 20 68 65  efines in the he
11a0: 61 64 65 72 2c 20 62 75 74 20 61 72 65 20 61 73  ader, but are as
11b0: 73 6f 63 69 61 74 65 64 0a 2a 2a 20 77 69 74 68  sociated.** with
11c0: 20 74 68 65 20 6c 69 62 72 61 72 79 20 69 6e 73   the library ins
11d0: 74 65 61 64 20 6f 66 20 74 68 65 20 68 65 61 64  tead of the head
11e0: 65 72 20 66 69 6c 65 2e 20 20 43 61 75 74 69 6f  er file.  Cautio
11f0: 75 73 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d  us programmers m
1200: 69 67 68 74 0a 2a 2a 20 69 6e 63 6c 75 64 65 20  ight.** include 
1210: 61 20 63 68 65 63 6b 20 69 6e 20 74 68 65 69 72  a check in their
1220: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20   application to 
1230: 76 65 72 69 66 79 20 74 68 61 74 0a 2a 2a 20 73  verify that.** s
1240: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f  qlite3_libversio
1250: 6e 5f 6e 75 6d 62 65 72 28 29 20 61 6c 77 61 79  n_number() alway
1260: 73 20 72 65 74 75 72 6e 73 20 74 68 65 20 76 61  s returns the va
1270: 6c 75 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 56  lue.** [SQLITE_V
1280: 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2e 0a  ERSION_NUMBER]..
1290: 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
12a0: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 20 66  3_libversion() f
12b0: 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
12c0: 74 68 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61  the same informa
12d0: 74 69 6f 6e 20 61 73 20 69 73 0a 2a 2a 20 69 6e  tion as is.** in
12e0: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 65 72   the sqlite3_ver
12f0: 73 69 6f 6e 5b 5d 20 73 74 72 69 6e 67 20 63 6f  sion[] string co
1300: 6e 73 74 61 6e 74 2e 20 20 54 68 65 20 66 75 6e  nstant.  The fun
1310: 63 74 69 6f 6e 20 69 73 20 70 72 6f 76 69 64 65  ction is provide
1320: 64 0a 2a 2a 20 66 6f 72 20 75 73 65 20 69 6e 20  d.** for use in 
1330: 44 4c 4c 73 20 73 69 6e 63 65 20 44 4c 4c 20 75  DLLs since DLL u
1340: 73 65 72 73 20 75 73 75 61 6c 6c 79 20 64 6f 20  sers usually do 
1350: 6e 6f 74 20 68 61 76 65 20 64 69 72 65 63 74 20  not have direct 
1360: 61 63 63 65 73 73 20 74 6f 20 73 74 72 69 6e 67  access to string
1370: 0a 2a 2a 20 63 6f 6e 73 74 61 6e 74 73 20 77 69  .** constants wi
1380: 74 68 69 6e 20 74 68 65 20 44 4c 4c 2e 0a 2a 2a  thin the DLL..**
1390: 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
13a0: 2a 2a 0a 2a 2a 20 7b 48 31 30 30 32 31 7d 20 54  **.** {H10021} T
13b0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 69 62 76  he [sqlite3_libv
13c0: 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 5d  ersion_number()]
13d0: 20 69 6e 74 65 72 66 61 63 65 20 73 68 61 6c 6c   interface shall
13e0: 20 72 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20 20   return.**      
13f0: 20 20 20 20 61 6e 20 69 6e 74 65 67 65 72 20 65      an integer e
1400: 71 75 61 6c 20 74 6f 20 5b 53 51 4c 49 54 45 5f  qual to [SQLITE_
1410: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2e  VERSION_NUMBER].
1420: 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 30 32 32 7d 20  .**.** {H10022} 
1430: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 65 72  The [sqlite3_ver
1440: 73 69 6f 6e 5d 20 73 74 72 69 6e 67 20 63 6f 6e  sion] string con
1450: 73 74 61 6e 74 20 73 68 61 6c 6c 20 63 6f 6e 74  stant shall cont
1460: 61 69 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ain.**          
1470: 74 68 65 20 74 65 78 74 20 6f 66 20 74 68 65 20  the text of the 
1480: 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d  [SQLITE_VERSION]
1490: 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b   string..**.** {
14a0: 48 31 30 30 32 33 7d 20 54 68 65 20 5b 73 71 6c  H10023} The [sql
14b0: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28  ite3_libversion(
14c0: 29 5d 20 66 75 6e 63 74 69 6f 6e 20 73 68 61 6c  )] function shal
14d0: 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20  l return.**     
14e0: 20 20 20 20 20 61 20 70 6f 69 6e 74 65 72 20 74       a pointer t
14f0: 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  o the [sqlite3_v
1500: 65 72 73 69 6f 6e 5d 20 73 74 72 69 6e 67 20 63  ersion] string c
1510: 6f 6e 73 74 61 6e 74 2e 0a 2a 2f 0a 53 51 4c 49  onstant..*/.SQLI
1520: 54 45 5f 45 58 54 45 52 4e 20 63 6f 6e 73 74 20  TE_EXTERN const 
1530: 63 68 61 72 20 73 71 6c 69 74 65 33 5f 76 65 72  char sqlite3_ver
1540: 73 69 6f 6e 5b 5d 3b 0a 63 6f 6e 73 74 20 63 68  sion[];.const ch
1550: 61 72 20 2a 73 71 6c 69 74 65 33 5f 6c 69 62 76  ar *sqlite3_libv
1560: 65 72 73 69 6f 6e 28 76 6f 69 64 29 3b 0a 69 6e  ersion(void);.in
1570: 74 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72  t sqlite3_libver
1580: 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 76 6f 69 64  sion_number(void
1590: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
15a0: 45 46 3a 20 54 65 73 74 20 54 6f 20 53 65 65 20  EF: Test To See 
15b0: 49 66 20 54 68 65 20 4c 69 62 72 61 72 79 20 49  If The Library I
15c0: 73 20 54 68 72 65 61 64 73 61 66 65 20 7b 48 31  s Threadsafe {H1
15d0: 30 31 30 30 7d 20 3c 53 36 30 31 30 30 3e 0a 2a  0100} <S60100>.*
15e0: 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63 61 6e 20  *.** SQLite can 
15f0: 62 65 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  be compiled with
1600: 20 6f 72 20 77 69 74 68 6f 75 74 20 6d 75 74 65   or without mute
1610: 78 65 73 2e 20 20 57 68 65 6e 0a 2a 2a 20 74 68  xes.  When.** th
1620: 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  e [SQLITE_THREAD
1630: 53 41 46 45 5d 20 43 20 70 72 65 70 72 6f 63 65  SAFE] C preproce
1640: 73 73 6f 72 20 6d 61 63 72 6f 20 69 73 20 74 72  ssor macro is tr
1650: 75 65 2c 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61  ue, mutexes.** a
1660: 72 65 20 65 6e 61 62 6c 65 64 20 61 6e 64 20 53  re enabled and S
1670: 51 4c 69 74 65 20 69 73 20 74 68 72 65 61 64 73  QLite is threads
1680: 61 66 65 2e 20 20 57 68 65 6e 20 74 68 61 74 20  afe.  When that 
1690: 6d 61 63 72 6f 20 69 73 20 66 61 6c 73 65 2c 0a  macro is false,.
16a0: 2a 2a 20 74 68 65 20 6d 75 74 65 78 65 73 20 61  ** the mutexes a
16b0: 72 65 20 6f 6d 69 74 74 65 64 2e 20 20 57 69 74  re omitted.  Wit
16c0: 68 6f 75 74 20 74 68 65 20 6d 75 74 65 78 65 73  hout the mutexes
16d0: 2c 20 69 74 20 69 73 20 6e 6f 74 20 73 61 66 65  , it is not safe
16e0: 0a 2a 2a 20 74 6f 20 75 73 65 20 53 51 4c 69 74  .** to use SQLit
16f0: 65 20 63 6f 6e 63 75 72 72 65 6e 74 6c 79 20 66  e concurrently f
1700: 72 6f 6d 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e  rom more than on
1710: 65 20 74 68 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20  e thread..**.** 
1720: 45 6e 61 62 6c 69 6e 67 20 6d 75 74 65 78 65 73  Enabling mutexes
1730: 20 69 6e 63 75 72 73 20 61 20 6d 65 61 73 75 72   incurs a measur
1740: 61 62 6c 65 20 70 65 72 66 6f 72 6d 61 6e 63 65  able performance
1750: 20 70 65 6e 61 6c 74 79 2e 0a 2a 2a 20 53 6f 20   penalty..** So 
1760: 69 66 20 73 70 65 65 64 20 69 73 20 6f 66 20 75  if speed is of u
1770: 74 6d 6f 73 74 20 69 6d 70 6f 72 74 61 6e 63 65  tmost importance
1780: 2c 20 69 74 20 6d 61 6b 65 73 20 73 65 6e 73 65  , it makes sense
1790: 20 74 6f 20 64 69 73 61 62 6c 65 0a 2a 2a 20 74   to disable.** t
17a0: 68 65 20 6d 75 74 65 78 65 73 2e 20 20 42 75 74  he mutexes.  But
17b0: 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 73 61 66   for maximum saf
17c0: 65 74 79 2c 20 6d 75 74 65 78 65 73 20 73 68 6f  ety, mutexes sho
17d0: 75 6c 64 20 62 65 20 65 6e 61 62 6c 65 64 2e 0a  uld be enabled..
17e0: 2a 2a 20 54 68 65 20 64 65 66 61 75 6c 74 20 62  ** The default b
17f0: 65 68 61 76 69 6f 72 20 69 73 20 66 6f 72 20 6d  ehavior is for m
1800: 75 74 65 78 65 73 20 74 6f 20 62 65 20 65 6e 61  utexes to be ena
1810: 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  bled..**.** This
1820: 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62   interface can b
1830: 65 20 75 73 65 64 20 62 79 20 61 20 70 72 6f 67  e used by a prog
1840: 72 61 6d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65  ram to make sure
1850: 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 76 65 72   that the.** ver
1860: 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65 20 74  sion of SQLite t
1870: 68 61 74 20 69 74 20 69 73 20 6c 69 6e 6b 69 6e  hat it is linkin
1880: 67 20 61 67 61 69 6e 73 74 20 77 61 73 20 63 6f  g against was co
1890: 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74  mpiled with.** t
18a0: 68 65 20 64 65 73 69 72 65 64 20 73 65 74 74 69  he desired setti
18b0: 6e 67 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54  ng of the [SQLIT
18c0: 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 6d 61  E_THREADSAFE] ma
18d0: 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  cro..**.** This 
18e0: 69 6e 74 65 72 66 61 63 65 20 6f 6e 6c 79 20 72  interface only r
18f0: 65 70 6f 72 74 73 20 6f 6e 20 74 68 65 20 63 6f  eports on the co
1900: 6d 70 69 6c 65 2d 74 69 6d 65 20 6d 75 74 65 78  mpile-time mutex
1910: 20 73 65 74 74 69 6e 67 0a 2a 2a 20 6f 66 20 74   setting.** of t
1920: 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  he [SQLITE_THREA
1930: 44 53 41 46 45 5d 20 66 6c 61 67 2e 20 20 49 66  DSAFE] flag.  If
1940: 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
1950: 6c 65 64 20 77 69 74 68 0a 2a 2a 20 53 51 4c 49  led with.** SQLI
1960: 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 31 20  TE_THREADSAFE=1 
1970: 74 68 65 6e 20 6d 75 74 65 78 65 73 20 61 72 65  then mutexes are
1980: 20 65 6e 61 62 6c 65 64 20 62 79 20 64 65 66 61   enabled by defa
1990: 75 6c 74 20 62 75 74 0a 2a 2a 20 63 61 6e 20 62  ult but.** can b
19a0: 65 20 66 75 6c 6c 79 20 6f 72 20 70 61 72 74 69  e fully or parti
19b0: 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 20 75 73  ally disabled us
19c0: 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73  ing a call to [s
19d0: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
19e0: 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 76 65 72  .** with the ver
19f0: 62 73 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  bs [SQLITE_CONFI
1a00: 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 2c  G_SINGLETHREAD],
1a10: 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
1a20: 4d 55 4c 54 49 54 48 52 45 41 44 5d 2c 0a 2a 2a  MULTITHREAD],.**
1a30: 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46   or [SQLITE_CONF
1a40: 49 47 5f 4d 55 54 45 58 5d 2e 20 20 54 68 65 20  IG_MUTEX].  The 
1a50: 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20  return value of 
1a60: 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 73 68  this function sh
1a70: 6f 77 73 0a 2a 2a 20 6f 6e 6c 79 20 74 68 65 20  ows.** only the 
1a80: 64 65 66 61 75 6c 74 20 63 6f 6d 70 69 6c 65 2d  default compile-
1a90: 74 69 6d 65 20 73 65 74 74 69 6e 67 2c 20 6e 6f  time setting, no
1aa0: 74 20 61 6e 79 20 72 75 6e 2d 74 69 6d 65 20 63  t any run-time c
1ab0: 68 61 6e 67 65 73 0a 2a 2a 20 74 6f 20 74 68 61  hanges.** to tha
1ac0: 74 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a  t setting..**.**
1ad0: 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
1ae0: 2a 2a 20 7b 48 31 30 31 30 31 7d 20 54 68 65 20  ** {H10101} The 
1af0: 5b 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73  [sqlite3_threads
1b00: 61 66 65 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20  afe()] function 
1b10: 73 68 61 6c 6c 20 72 65 74 75 72 6e 20 6e 6f 6e  shall return non
1b20: 7a 65 72 6f 20 69 66 0a 2a 2a 20 20 20 20 20 20  zero if.**      
1b30: 20 20 20 20 53 51 4c 69 74 65 20 77 61 73 20 63      SQLite was c
1b40: 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65  ompiled with the
1b50: 20 69 74 73 20 6d 75 74 65 78 65 73 20 65 6e 61   its mutexes ena
1b60: 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 0a  bled by default.
1b70: 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 7a  **          or z
1b80: 65 72 6f 20 69 66 20 53 51 4c 69 74 65 20 77 61  ero if SQLite wa
1b90: 73 20 63 6f 6d 70 69 6c 65 64 20 73 75 63 68 20  s compiled such 
1ba0: 74 68 61 74 20 6d 75 74 65 78 65 73 20 61 72 65  that mutexes are
1bb0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70 65 72  .**          per
1bc0: 6d 61 6e 65 6e 74 6c 79 20 64 69 73 61 62 6c 65  manently disable
1bd0: 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 31 30 32  d..**.** {H10102
1be0: 7d 20 54 68 65 20 76 61 6c 75 65 20 72 65 74 75  } The value retu
1bf0: 72 6e 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c  rned by the [sql
1c00: 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28  ite3_threadsafe(
1c10: 29 5d 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 20  )] function.**  
1c20: 20 20 20 20 20 20 20 20 73 68 61 6c 6c 20 6e 6f          shall no
1c30: 74 20 63 68 61 6e 67 65 20 77 68 65 6e 20 6d 75  t change when mu
1c40: 74 65 78 20 73 65 74 74 69 6e 67 20 61 72 65 20  tex setting are 
1c50: 6d 6f 64 69 66 69 65 64 20 61 74 0a 2a 2a 20 20  modified at.**  
1c60: 20 20 20 20 20 20 20 20 72 75 6e 74 69 6d 65 20          runtime 
1c70: 75 73 69 6e 67 20 74 68 65 20 5b 73 71 6c 69 74  using the [sqlit
1c80: 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74  e3_config()] int
1c90: 65 72 66 61 63 65 20 61 6e 64 20 0a 2a 2a 20 20  erface and .**  
1ca0: 20 20 20 20 20 20 20 20 65 73 70 65 63 69 61 6c          especial
1cb0: 6c 79 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43  ly the [SQLITE_C
1cc0: 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45  ONFIG_SINGLETHRE
1cd0: 41 44 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  AD],.**         
1ce0: 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
1cf0: 4d 55 4c 54 49 54 48 52 45 41 44 5d 2c 20 5b 53  MULTITHREAD], [S
1d00: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52  QLITE_CONFIG_SER
1d10: 49 41 4c 49 5a 45 44 5d 2c 0a 2a 2a 20 20 20 20  IALIZED],.**    
1d20: 20 20 20 20 20 20 61 6e 64 20 5b 53 51 4c 49 54        and [SQLIT
1d30: 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 5d 20  E_CONFIG_MUTEX] 
1d40: 76 65 72 62 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71  verbs..*/.int sq
1d50: 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 65  lite3_threadsafe
1d60: 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  (void);../*.** C
1d70: 41 50 49 33 52 45 46 3a 20 44 61 74 61 62 61 73  API3REF: Databas
1d80: 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 48 61 6e  e Connection Han
1d90: 64 6c 65 20 7b 48 31 32 30 30 30 7d 20 3c 53 34  dle {H12000} <S4
1da0: 30 32 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44  0200>.** KEYWORD
1db0: 53 3a 20 7b 64 61 74 61 62 61 73 65 20 63 6f 6e  S: {database con
1dc0: 6e 65 63 74 69 6f 6e 7d 20 7b 64 61 74 61 62 61  nection} {databa
1dd0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 7d 0a  se connections}.
1de0: 2a 2a 0a 2a 2a 20 45 61 63 68 20 6f 70 65 6e 20  **.** Each open 
1df0: 53 51 4c 69 74 65 20 64 61 74 61 62 61 73 65 20  SQLite database 
1e00: 69 73 20 72 65 70 72 65 73 65 6e 74 65 64 20 62  is represented b
1e10: 79 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  y a pointer to a
1e20: 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 0a 2a 2a  n instance of.**
1e30: 20 74 68 65 20 6f 70 61 71 75 65 20 73 74 72 75   the opaque stru
1e40: 63 74 75 72 65 20 6e 61 6d 65 64 20 22 73 71 6c  cture named "sql
1e50: 69 74 65 33 22 2e 20 20 49 74 20 69 73 20 75 73  ite3".  It is us
1e60: 65 66 75 6c 20 74 6f 20 74 68 69 6e 6b 20 6f 66  eful to think of
1e70: 20 61 6e 20 73 71 6c 69 74 65 33 0a 2a 2a 20 70   an sqlite3.** p
1e80: 6f 69 6e 74 65 72 20 61 73 20 61 6e 20 6f 62 6a  ointer as an obj
1e90: 65 63 74 2e 20 20 54 68 65 20 5b 73 71 6c 69 74  ect.  The [sqlit
1ea0: 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c  e3_open()], [sql
1eb0: 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20  ite3_open16()], 
1ec0: 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
1ed0: 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72  open_v2()] inter
1ee0: 66 61 63 65 73 20 61 72 65 20 69 74 73 20 63 6f  faces are its co
1ef0: 6e 73 74 72 75 63 74 6f 72 73 2c 20 61 6e 64 20  nstructors, and 
1f00: 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29  [sqlite3_close()
1f10: 5d 0a 2a 2a 20 69 73 20 69 74 73 20 64 65 73 74  ].** is its dest
1f20: 72 75 63 74 6f 72 2e 20 20 54 68 65 72 65 20 61  ructor.  There a
1f30: 72 65 20 6d 61 6e 79 20 6f 74 68 65 72 20 69 6e  re many other in
1f40: 74 65 72 66 61 63 65 73 20 28 73 75 63 68 20 61  terfaces (such a
1f50: 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  s.** [sqlite3_pr
1f60: 65 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71  epare_v2()], [sq
1f70: 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
1f80: 63 74 69 6f 6e 28 29 5d 2c 20 61 6e 64 0a 2a 2a  ction()], and.**
1f90: 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74   [sqlite3_busy_t
1fa0: 69 6d 65 6f 75 74 28 29 5d 20 74 6f 20 6e 61 6d  imeout()] to nam
1fb0: 65 20 62 75 74 20 74 68 72 65 65 29 20 74 68 61  e but three) tha
1fc0: 74 20 61 72 65 20 6d 65 74 68 6f 64 73 20 6f 6e  t are methods on
1fd0: 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 20 6f   an.** sqlite3 o
1fe0: 62 6a 65 63 74 2e 0a 2a 2f 0a 74 79 70 65 64 65  bject..*/.typede
1ff0: 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
2000: 20 73 71 6c 69 74 65 33 3b 0a 0a 2f 2a 0a 2a 2a   sqlite3;../*.**
2010: 20 43 41 50 49 33 52 45 46 3a 20 36 34 2d 42 69   CAPI3REF: 64-Bi
2020: 74 20 49 6e 74 65 67 65 72 20 54 79 70 65 73 20  t Integer Types 
2030: 7b 48 31 30 32 30 30 7d 20 3c 53 31 30 31 31 30  {H10200} <S10110
2040: 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73  >.** KEYWORDS: s
2050: 71 6c 69 74 65 5f 69 6e 74 36 34 20 73 71 6c 69  qlite_int64 sqli
2060: 74 65 5f 75 69 6e 74 36 34 0a 2a 2a 0a 2a 2a 20  te_uint64.**.** 
2070: 42 65 63 61 75 73 65 20 74 68 65 72 65 20 69 73  Because there is
2080: 20 6e 6f 20 63 72 6f 73 73 2d 70 6c 61 74 66 6f   no cross-platfo
2090: 72 6d 20 77 61 79 20 74 6f 20 73 70 65 63 69 66  rm way to specif
20a0: 79 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72  y 64-bit integer
20b0: 20 74 79 70 65 73 0a 2a 2a 20 53 51 4c 69 74 65   types.** SQLite
20c0: 20 69 6e 63 6c 75 64 65 73 20 74 79 70 65 64 65   includes typede
20d0: 66 73 20 66 6f 72 20 36 34 2d 62 69 74 20 73 69  fs for 64-bit si
20e0: 67 6e 65 64 20 61 6e 64 20 75 6e 73 69 67 6e 65  gned and unsigne
20f0: 64 20 69 6e 74 65 67 65 72 73 2e 0a 2a 2a 0a 2a  d integers..**.*
2100: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e  * The sqlite3_in
2110: 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  t64 and sqlite3_
2120: 75 69 6e 74 36 34 20 61 72 65 20 74 68 65 20 70  uint64 are the p
2130: 72 65 66 65 72 72 65 64 20 74 79 70 65 20 64 65  referred type de
2140: 66 69 6e 69 74 69 6f 6e 73 2e 0a 2a 2a 20 54 68  finitions..** Th
2150: 65 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 61  e sqlite_int64 a
2160: 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34  nd sqlite_uint64
2170: 20 74 79 70 65 73 20 61 72 65 20 73 75 70 70 6f   types are suppo
2180: 72 74 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72  rted for backwar
2190: 64 73 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c  ds.** compatibil
21a0: 69 74 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20  ity only..**.** 
21b0: 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
21c0: 2a 20 7b 48 31 30 32 30 31 7d 20 54 68 65 20 5b  * {H10201} The [
21d0: 73 71 6c 69 74 65 5f 69 6e 74 36 34 5d 20 61 6e  sqlite_int64] an
21e0: 64 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  d [sqlite3_int64
21f0: 5d 20 74 79 70 65 20 73 68 61 6c 6c 20 73 70 65  ] type shall spe
2200: 63 69 66 79 0a 2a 2a 20 20 20 20 20 20 20 20 20  cify.**         
2210: 20 61 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64   a 64-bit signed
2220: 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20   integer..**.** 
2230: 7b 48 31 30 32 30 32 7d 20 54 68 65 20 5b 73 71  {H10202} The [sq
2240: 6c 69 74 65 5f 75 69 6e 74 36 34 5d 20 61 6e 64  lite_uint64] and
2250: 20 5b 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34   [sqlite3_uint64
2260: 5d 20 74 79 70 65 20 73 68 61 6c 6c 20 73 70 65  ] type shall spe
2270: 63 69 66 79 0a 2a 2a 20 20 20 20 20 20 20 20 20  cify.**         
2280: 20 61 20 36 34 2d 62 69 74 20 75 6e 73 69 67 6e   a 64-bit unsign
2290: 65 64 20 69 6e 74 65 67 65 72 2e 0a 2a 2f 0a 23  ed integer..*/.#
22a0: 69 66 64 65 66 20 53 51 4c 49 54 45 5f 49 4e 54  ifdef SQLITE_INT
22b0: 36 34 5f 54 59 50 45 0a 20 20 74 79 70 65 64 65  64_TYPE.  typede
22c0: 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54  f SQLITE_INT64_T
22d0: 59 50 45 20 73 71 6c 69 74 65 5f 69 6e 74 36 34  YPE sqlite_int64
22e0: 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73 69  ;.  typedef unsi
22f0: 67 6e 65 64 20 53 51 4c 49 54 45 5f 49 4e 54 36  gned SQLITE_INT6
2300: 34 5f 54 59 50 45 20 73 71 6c 69 74 65 5f 75 69  4_TYPE sqlite_ui
2310: 6e 74 36 34 3b 0a 23 65 6c 69 66 20 64 65 66 69  nt64;.#elif defi
2320: 6e 65 64 28 5f 4d 53 43 5f 56 45 52 29 20 7c 7c  ned(_MSC_VER) ||
2330: 20 64 65 66 69 6e 65 64 28 5f 5f 42 4f 52 4c 41   defined(__BORLA
2340: 4e 44 43 5f 5f 29 0a 20 20 74 79 70 65 64 65 66  NDC__).  typedef
2350: 20 5f 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 5f   __int64 sqlite_
2360: 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66  int64;.  typedef
2370: 20 75 6e 73 69 67 6e 65 64 20 5f 5f 69 6e 74 36   unsigned __int6
2380: 34 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b  4 sqlite_uint64;
2390: 0a 23 65 6c 73 65 0a 20 20 74 79 70 65 64 65 66  .#else.  typedef
23a0: 20 6c 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73   long long int s
23b0: 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74  qlite_int64;.  t
23c0: 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20  ypedef unsigned 
23d0: 6c 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71  long long int sq
23e0: 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6e  lite_uint64;.#en
23f0: 64 69 66 0a 74 79 70 65 64 65 66 20 73 71 6c 69  dif.typedef sqli
2400: 74 65 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33  te_int64 sqlite3
2410: 5f 69 6e 74 36 34 3b 0a 74 79 70 65 64 65 66 20  _int64;.typedef 
2420: 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 20 73 71  sqlite_uint64 sq
2430: 6c 69 74 65 33 5f 75 69 6e 74 36 34 3b 0a 0a 2f  lite3_uint64;../
2440: 2a 0a 2a 2a 20 49 66 20 63 6f 6d 70 69 6c 69 6e  *.** If compilin
2450: 67 20 66 6f 72 20 61 20 70 72 6f 63 65 73 73 6f  g for a processo
2460: 72 20 74 68 61 74 20 6c 61 63 6b 73 20 66 6c 6f  r that lacks flo
2470: 61 74 69 6e 67 20 70 6f 69 6e 74 20 73 75 70 70  ating point supp
2480: 6f 72 74 2c 0a 2a 2a 20 73 75 62 73 74 69 74 75  ort,.** substitu
2490: 74 65 20 69 6e 74 65 67 65 72 20 66 6f 72 20 66  te integer for f
24a0: 6c 6f 61 74 69 6e 67 2d 70 6f 69 6e 74 2e 0a 2a  loating-point..*
24b0: 2f 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f  /.#ifdef SQLITE_
24c0: 4f 4d 49 54 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f  OMIT_FLOATING_PO
24d0: 49 4e 54 0a 23 20 64 65 66 69 6e 65 20 64 6f 75  INT.# define dou
24e0: 62 6c 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  ble sqlite3_int6
24f0: 34 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20  4.#endif../*.** 
2500: 43 41 50 49 33 52 45 46 3a 20 43 6c 6f 73 69 6e  CAPI3REF: Closin
2510: 67 20 41 20 44 61 74 61 62 61 73 65 20 43 6f 6e  g A Database Con
2520: 6e 65 63 74 69 6f 6e 20 7b 48 31 32 30 31 30 7d  nection {H12010}
2530: 20 3c 53 33 30 31 30 30 3e 3c 53 34 30 32 30 30   <S30100><S40200
2540: 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75  >.**.** This rou
2550: 74 69 6e 65 20 69 73 20 74 68 65 20 64 65 73 74  tine is the dest
2560: 72 75 63 74 6f 72 20 66 6f 72 20 74 68 65 20 5b  ructor for the [
2570: 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2e  sqlite3] object.
2580: 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69  .**.** Applicati
2590: 6f 6e 73 20 73 68 6f 75 6c 64 20 5b 73 71 6c 69  ons should [sqli
25a0: 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66  te3_finalize | f
25b0: 69 6e 61 6c 69 7a 65 5d 20 61 6c 6c 20 5b 70 72  inalize] all [pr
25c0: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
25d0: 73 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74  s].** and [sqlit
25e0: 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 20 7c 20  e3_blob_close | 
25f0: 63 6c 6f 73 65 5d 20 61 6c 6c 20 5b 42 4c 4f 42  close] all [BLOB
2600: 20 68 61 6e 64 6c 65 73 5d 20 61 73 73 6f 63 69   handles] associ
2610: 61 74 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65  ated with.** the
2620: 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63   [sqlite3] objec
2630: 74 20 70 72 69 6f 72 20 74 6f 20 61 74 74 65 6d  t prior to attem
2640: 70 74 69 6e 67 20 74 6f 20 63 6c 6f 73 65 20 74  pting to close t
2650: 68 65 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 54 68  he object..** Th
2660: 65 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f  e [sqlite3_next_
2670: 73 74 6d 74 28 29 5d 20 69 6e 74 65 72 66 61 63  stmt()] interfac
2680: 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  e can be used to
2690: 20 6c 6f 63 61 74 65 20 61 6c 6c 0a 2a 2a 20 5b   locate all.** [
26a0: 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
26b0: 6e 74 73 5d 20 61 73 73 6f 63 69 61 74 65 64 20  nts] associated 
26c0: 77 69 74 68 20 61 20 5b 64 61 74 61 62 61 73 65  with a [database
26d0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 66 20   connection] if 
26e0: 64 65 73 69 72 65 64 2e 0a 2a 2a 20 54 79 70 69  desired..** Typi
26f0: 63 61 6c 20 63 6f 64 65 20 6d 69 67 68 74 20 6c  cal code might l
2700: 6f 6f 6b 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a  ook like this:.*
2710: 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
2720: 3e 3c 70 72 65 3e 0a 2a 2a 20 73 71 6c 69 74 65  ><pre>.** sqlite
2730: 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 3b 0a 2a  3_stmt *pStmt;.*
2740: 2a 20 77 68 69 6c 65 28 20 28 70 53 74 6d 74 20  * while( (pStmt 
2750: 3d 20 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73  = sqlite3_next_s
2760: 74 6d 74 28 64 62 2c 20 30 29 29 21 3d 30 20 29  tmt(db, 0))!=0 )
2770: 7b 0a 2a 2a 20 26 6e 62 73 70 3b 20 20 20 73 71  {.** &nbsp;   sq
2780: 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 70  lite3_finalize(p
2790: 53 74 6d 74 29 3b 0a 2a 2a 20 7d 0a 2a 2a 20 3c  Stmt);.** }.** <
27a0: 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
27b0: 65 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 5b 73 71 6c  e>.**.** If [sql
27c0: 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20 69 73  ite3_close()] is
27d0: 20 69 6e 76 6f 6b 65 64 20 77 68 69 6c 65 20 61   invoked while a
27e0: 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20   transaction is 
27f0: 6f 70 65 6e 2c 0a 2a 2a 20 74 68 65 20 74 72 61  open,.** the tra
2800: 6e 73 61 63 74 69 6f 6e 20 69 73 20 61 75 74 6f  nsaction is auto
2810: 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64  matically rolled
2820: 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56   back..**.** INV
2830: 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
2840: 48 31 32 30 31 31 7d 20 41 20 73 75 63 63 65 73  H12011} A succes
2850: 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71  sful call to [sq
2860: 6c 69 74 65 33 5f 63 6c 6f 73 65 28 43 29 5d 20  lite3_close(C)] 
2870: 73 68 61 6c 6c 20 64 65 73 74 72 6f 79 20 74 68  shall destroy th
2880: 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 64  e.**          [d
2890: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
28a0: 6f 6e 5d 20 6f 62 6a 65 63 74 20 43 2e 0a 2a 2a  on] object C..**
28b0: 0a 2a 2a 20 7b 48 31 32 30 31 32 7d 20 41 20 73  .** {H12012} A s
28c0: 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74  uccessful call t
28d0: 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  o [sqlite3_close
28e0: 28 43 29 5d 20 73 68 61 6c 6c 20 72 65 74 75 72  (C)] shall retur
28f0: 6e 20 53 51 4c 49 54 45 5f 4f 4b 2e 0a 2a 2a 0a  n SQLITE_OK..**.
2900: 2a 2a 20 7b 48 31 32 30 31 33 7d 20 41 20 73 75  ** {H12013} A su
2910: 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f  ccessful call to
2920: 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28   [sqlite3_close(
2930: 43 29 5d 20 73 68 61 6c 6c 20 72 65 6c 65 61 73  C)] shall releas
2940: 65 20 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20  e all.**        
2950: 20 20 6d 65 6d 6f 72 79 20 61 6e 64 20 73 79 73    memory and sys
2960: 74 65 6d 20 72 65 73 6f 75 72 63 65 73 20 61 73  tem resources as
2970: 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 5b 64  sociated with [d
2980: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2990: 6f 6e 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  on].**          
29a0: 43 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 30 31 34  C..**.** {H12014
29b0: 7d 20 41 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  } A call to [sql
29c0: 69 74 65 33 5f 63 6c 6f 73 65 28 43 29 5d 20 6f  ite3_close(C)] o
29d0: 6e 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f  n a [database co
29e0: 6e 6e 65 63 74 69 6f 6e 5d 20 43 20 74 68 61 74  nnection] C that
29f0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 68 61 73  .**          has
2a00: 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 70 65   one or more ope
2a10: 6e 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  n [prepared stat
2a20: 65 6d 65 6e 74 73 5d 20 73 68 61 6c 6c 20 66 61  ements] shall fa
2a30: 69 6c 20 77 69 74 68 0a 2a 2a 20 20 20 20 20 20  il with.**      
2a40: 20 20 20 20 61 6e 20 5b 53 51 4c 49 54 45 5f 42      an [SQLITE_B
2a50: 55 53 59 5d 20 65 72 72 6f 72 20 63 6f 64 65 2e  USY] error code.
2a60: 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 30 31 35 7d 20  .**.** {H12015} 
2a70: 41 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  A call to [sqlit
2a80: 65 33 5f 63 6c 6f 73 65 28 43 29 5d 20 77 68 65  e3_close(C)] whe
2a90: 72 65 20 43 20 69 73 20 61 20 4e 55 4c 4c 20 70  re C is a NULL p
2aa0: 6f 69 6e 74 65 72 20 73 68 61 6c 6c 0a 2a 2a 20  ointer shall.** 
2ab0: 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 20           return 
2ac0: 53 51 4c 49 54 45 5f 4f 4b 2e 0a 2a 2a 0a 2a 2a  SQLITE_OK..**.**
2ad0: 20 7b 48 31 32 30 31 39 7d 20 57 68 65 6e 20 5b   {H12019} When [
2ae0: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 43 29  sqlite3_close(C)
2af0: 5d 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 20  ] is invoked on 
2b00: 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  a [database conn
2b10: 65 63 74 69 6f 6e 5d 20 43 0a 2a 2a 20 20 20 20  ection] C.**    
2b20: 20 20 20 20 20 20 74 68 61 74 20 68 61 73 20 61        that has a
2b30: 20 70 65 6e 64 69 6e 67 20 74 72 61 6e 73 61 63   pending transac
2b40: 74 69 6f 6e 2c 20 74 68 65 20 74 72 61 6e 73 61  tion, the transa
2b50: 63 74 69 6f 6e 20 73 68 61 6c 6c 20 62 65 0a 2a  ction shall be.*
2b60: 2a 20 20 20 20 20 20 20 20 20 20 72 6f 6c 6c 65  *          rolle
2b70: 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 41 53  d back..**.** AS
2b80: 53 55 4d 50 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a  SUMPTIONS:.**.**
2b90: 20 7b 41 31 32 30 31 36 7d 20 54 68 65 20 43 20   {A12016} The C 
2ba0: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71  parameter to [sq
2bb0: 6c 69 74 65 33 5f 63 6c 6f 73 65 28 43 29 5d 20  lite3_close(C)] 
2bc0: 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 20 61  must be either a
2bd0: 20 4e 55 4c 4c 0a 2a 2a 20 20 20 20 20 20 20 20   NULL.**        
2be0: 20 20 70 6f 69 6e 74 65 72 20 6f 72 20 61 6e 20    pointer or an 
2bf0: 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74  [sqlite3] object
2c00: 20 70 6f 69 6e 74 65 72 20 6f 62 74 61 69 6e 65   pointer obtaine
2c10: 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 72  d.**          fr
2c20: 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  om [sqlite3_open
2c30: 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ()], [sqlite3_op
2c40: 65 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 20  en16()], or.**  
2c50: 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
2c60: 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20 61 6e 64  _open_v2()], and
2c70: 20 6e 6f 74 20 70 72 65 76 69 6f 75 73 6c 79 20   not previously 
2c80: 63 6c 6f 73 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73  closed..*/.int s
2c90: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 73 71 6c  qlite3_close(sql
2ca0: 69 74 65 33 20 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  ite3 *);../*.** 
2cb0: 54 68 65 20 74 79 70 65 20 66 6f 72 20 61 20 63  The type for a c
2cc0: 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
2cd0: 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20 6c 65 67  ..** This is leg
2ce0: 61 63 79 20 61 6e 64 20 64 65 70 72 65 63 61 74  acy and deprecat
2cf0: 65 64 2e 20 20 49 74 20 69 73 20 69 6e 63 6c 75  ed.  It is inclu
2d00: 64 65 64 20 66 6f 72 20 68 69 73 74 6f 72 69 63  ded for historic
2d10: 61 6c 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c  al.** compatibil
2d20: 69 74 79 20 61 6e 64 20 69 73 20 6e 6f 74 20 64  ity and is not d
2d30: 6f 63 75 6d 65 6e 74 65 64 2e 0a 2a 2f 0a 74 79  ocumented..*/.ty
2d40: 70 65 64 65 66 20 69 6e 74 20 28 2a 73 71 6c 69  pedef int (*sqli
2d50: 74 65 33 5f 63 61 6c 6c 62 61 63 6b 29 28 76 6f  te3_callback)(vo
2d60: 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 20  id*,int,char**, 
2d70: 63 68 61 72 2a 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  char**);../*.** 
2d80: 43 41 50 49 33 52 45 46 3a 20 4f 6e 65 2d 53 74  CAPI3REF: One-St
2d90: 65 70 20 51 75 65 72 79 20 45 78 65 63 75 74 69  ep Query Executi
2da0: 6f 6e 20 49 6e 74 65 72 66 61 63 65 20 7b 48 31  on Interface {H1
2db0: 32 31 30 30 7d 20 3c 53 31 30 30 30 30 3e 0a 2a  2100} <S10000>.*
2dc0: 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
2dd0: 5f 65 78 65 63 28 29 20 69 6e 74 65 72 66 61 63  _exec() interfac
2de0: 65 20 69 73 20 61 20 63 6f 6e 76 65 6e 69 65 6e  e is a convenien
2df0: 74 20 77 61 79 20 6f 66 20 72 75 6e 6e 69 6e 67  t way of running
2e00: 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20   one or more.** 
2e10: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 77  SQL statements w
2e20: 69 74 68 6f 75 74 20 68 61 76 69 6e 67 20 74 6f  ithout having to
2e30: 20 77 72 69 74 65 20 61 20 6c 6f 74 20 6f 66 20   write a lot of 
2e40: 43 20 63 6f 64 65 2e 20 20 54 68 65 20 55 54 46  C code.  The UTF
2e50: 2d 38 20 65 6e 63 6f 64 65 64 0a 2a 2a 20 53 51  -8 encoded.** SQ
2e60: 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65  L statements are
2e70: 20 70 61 73 73 65 64 20 69 6e 20 61 73 20 74 68   passed in as th
2e80: 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
2e90: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78  er to sqlite3_ex
2ea0: 65 63 28 29 2e 0a 2a 2a 20 54 68 65 20 73 74 61  ec()..** The sta
2eb0: 74 65 6d 65 6e 74 73 20 61 72 65 20 65 76 61 6c  tements are eval
2ec0: 75 61 74 65 64 20 6f 6e 65 20 62 79 20 6f 6e 65  uated one by one
2ed0: 20 75 6e 74 69 6c 20 65 69 74 68 65 72 20 61 6e   until either an
2ee0: 20 65 72 72 6f 72 20 6f 72 0a 2a 2a 20 61 6e 20   error or.** an 
2ef0: 69 6e 74 65 72 72 75 70 74 20 69 73 20 65 6e 63  interrupt is enc
2f00: 6f 75 6e 74 65 72 65 64 2c 20 6f 72 20 75 6e 74  ountered, or unt
2f10: 69 6c 20 74 68 65 79 20 61 72 65 20 61 6c 6c 20  il they are all 
2f20: 64 6f 6e 65 2e 20 20 54 68 65 20 33 72 64 20 70  done.  The 3rd p
2f30: 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69 73 20 61  arameter.** is a
2f40: 6e 20 6f 70 74 69 6f 6e 61 6c 20 63 61 6c 6c 62  n optional callb
2f50: 61 63 6b 20 74 68 61 74 20 69 73 20 69 6e 76 6f  ack that is invo
2f60: 6b 65 64 20 6f 6e 63 65 20 66 6f 72 20 65 61 63  ked once for eac
2f70: 68 20 72 6f 77 20 6f 66 20 61 6e 79 20 71 75 65  h row of any que
2f80: 72 79 0a 2a 2a 20 72 65 73 75 6c 74 73 20 70 72  ry.** results pr
2f90: 6f 64 75 63 65 64 20 62 79 20 74 68 65 20 53 51  oduced by the SQ
2fa0: 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 20 20 54  L statements.  T
2fb0: 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72  he 5th parameter
2fc0: 20 74 65 6c 6c 73 20 77 68 65 72 65 0a 2a 2a 20   tells where.** 
2fd0: 74 6f 20 77 72 69 74 65 20 61 6e 79 20 65 72 72  to write any err
2fe0: 6f 72 20 6d 65 73 73 61 67 65 73 2e 0a 2a 2a 0a  or messages..**.
2ff0: 2a 2a 20 54 68 65 20 65 72 72 6f 72 20 6d 65 73  ** The error mes
3000: 73 61 67 65 20 70 61 73 73 65 64 20 62 61 63 6b  sage passed back
3010: 20 74 68 72 6f 75 67 68 20 74 68 65 20 35 74 68   through the 5th
3020: 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 68 65   parameter is he
3030: 6c 64 0a 2a 2a 20 69 6e 20 6d 65 6d 6f 72 79 20  ld.** in memory 
3040: 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73  obtained from [s
3050: 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
3060: 2e 20 20 54 6f 20 61 76 6f 69 64 20 61 20 6d 65  .  To avoid a me
3070: 6d 6f 72 79 20 6c 65 61 6b 2c 0a 2a 2a 20 74 68  mory leak,.** th
3080: 65 20 63 61 6c 6c 69 6e 67 20 61 70 70 6c 69 63  e calling applic
3090: 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 63 61 6c  ation should cal
30a0: 6c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  l [sqlite3_free(
30b0: 29 5d 20 6f 6e 20 61 6e 79 20 65 72 72 6f 72 0a  )] on any error.
30c0: 2a 2a 20 6d 65 73 73 61 67 65 20 72 65 74 75 72  ** message retur
30d0: 6e 65 64 20 74 68 72 6f 75 67 68 20 74 68 65 20  ned through the 
30e0: 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 77 68  5th parameter wh
30f0: 65 6e 20 69 74 20 68 61 73 20 66 69 6e 69 73 68  en it has finish
3100: 65 64 20 75 73 69 6e 67 0a 2a 2a 20 74 68 65 20  ed using.** the 
3110: 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a  error message..*
3120: 2a 0a 2a 2a 20 49 66 20 74 68 65 20 53 51 4c 20  *.** If the SQL 
3130: 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 74 68 65  statement in the
3140: 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69   2nd parameter i
3150: 73 20 4e 55 4c 4c 20 6f 72 20 61 6e 20 65 6d 70  s NULL or an emp
3160: 74 79 20 73 74 72 69 6e 67 0a 2a 2a 20 6f 72 20  ty string.** or 
3170: 61 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e  a string contain
3180: 69 6e 67 20 6f 6e 6c 79 20 77 68 69 74 65 73 70  ing only whitesp
3190: 61 63 65 20 61 6e 64 20 63 6f 6d 6d 65 6e 74 73  ace and comments
31a0: 2c 20 74 68 65 6e 20 6e 6f 20 53 51 4c 0a 2a 2a  , then no SQL.**
31b0: 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20   statements are 
31c0: 65 76 61 6c 75 61 74 65 64 20 61 6e 64 20 74 68  evaluated and th
31d0: 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6e 6f  e database is no
31e0: 74 20 63 68 61 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a  t changed..**.**
31f0: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65   The sqlite3_exe
3200: 63 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73  c() interface is
3210: 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 69 6e 20   implemented in 
3220: 74 65 72 6d 73 20 6f 66 0a 2a 2a 20 5b 73 71 6c  terms of.** [sql
3230: 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
3240: 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  )], [sqlite3_ste
3250: 70 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74  p()], and [sqlit
3260: 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a  e3_finalize()]..
3270: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 65  ** The sqlite3_e
3280: 78 65 63 28 29 20 72 6f 75 74 69 6e 65 20 64 6f  xec() routine do
3290: 65 73 20 6e 6f 74 68 69 6e 67 20 74 6f 20 74 68  es nothing to th
32a0: 65 20 64 61 74 61 62 61 73 65 20 74 68 61 74 20  e database that 
32b0: 63 61 6e 6e 6f 74 20 62 65 20 64 6f 6e 65 0a 2a  cannot be done.*
32c0: 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 70 72  * by [sqlite3_pr
32d0: 65 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71  epare_v2()], [sq
32e0: 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 20 61  lite3_step()], a
32f0: 6e 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  nd [sqlite3_fina
3300: 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49  lize()]..**.** I
3310: 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
3320: 20 7b 48 31 32 31 30 31 7d 20 41 20 73 75 63 63   {H12101} A succ
3330: 65 73 73 66 75 6c 20 69 6e 76 6f 63 61 74 69 6f  essful invocatio
3340: 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 65 78  n of [sqlite3_ex
3350: 65 63 28 44 2c 53 2c 43 2c 41 2c 45 29 5d 0a 2a  ec(D,S,C,A,E)].*
3360: 2a 20 20 20 20 20 20 20 20 20 20 73 68 61 6c 6c  *          shall
3370: 20 73 65 71 75 65 6e 74 69 61 6c 6c 79 20 65 76   sequentially ev
3380: 61 6c 75 61 74 65 20 61 6c 6c 20 6f 66 20 74 68  aluate all of th
3390: 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 2c  e UTF-8 encoded,
33a0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 65 6d  .**          sem
33b0: 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 65 64  icolon-separated
33c0: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
33d0: 69 6e 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d  in the zero-term
33e0: 69 6e 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 20  inated.**       
33f0: 20 20 20 73 74 72 69 6e 67 20 53 20 77 69 74 68     string S with
3400: 69 6e 20 74 68 65 20 63 6f 6e 74 65 78 74 20 6f  in the context o
3410: 66 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  f the [database 
3420: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2e 0a 2a  connection] D..*
3430: 2a 0a 2a 2a 20 7b 48 31 32 31 30 32 7d 20 49 66  *.** {H12102} If
3440: 20 74 68 65 20 53 20 70 61 72 61 6d 65 74 65 72   the S parameter
3450: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 78 65   to [sqlite3_exe
3460: 63 28 44 2c 53 2c 43 2c 41 2c 45 29 5d 20 69 73  c(D,S,C,A,E)] is
3470: 20 4e 55 4c 4c 20 74 68 65 6e 0a 2a 2a 20 20 20   NULL then.**   
3480: 20 20 20 20 20 20 20 74 68 65 20 61 63 74 69 6f         the actio
3490: 6e 73 20 6f 66 20 74 68 65 20 69 6e 74 65 72 66  ns of the interf
34a0: 61 63 65 20 73 68 61 6c 6c 20 62 65 20 74 68 65  ace shall be the
34b0: 20 73 61 6d 65 20 61 73 20 69 66 20 74 68 65 0a   same as if the.
34c0: 2a 2a 20 20 20 20 20 20 20 20 20 20 53 20 70 61  **          S pa
34d0: 72 61 6d 65 74 65 72 20 77 65 72 65 20 61 6e 20  rameter were an 
34e0: 65 6d 70 74 79 20 73 74 72 69 6e 67 2e 0a 2a 2a  empty string..**
34f0: 0a 2a 2a 20 7b 48 31 32 31 30 34 7d 20 54 68 65  .** {H12104} The
3500: 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66   return value of
3510: 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29   [sqlite3_exec()
3520: 5d 20 73 68 61 6c 6c 20 62 65 20 5b 53 51 4c 49  ] shall be [SQLI
3530: 54 45 5f 4f 4b 5d 20 69 66 20 61 6c 6c 0a 2a 2a  TE_OK] if all.**
3540: 20 20 20 20 20 20 20 20 20 20 53 51 4c 20 73 74            SQL st
3550: 61 74 65 6d 65 6e 74 73 20 72 75 6e 20 73 75 63  atements run suc
3560: 63 65 73 73 66 75 6c 6c 79 20 61 6e 64 20 74 6f  cessfully and to
3570: 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a   completion..**.
3580: 2a 2a 20 7b 48 31 32 31 30 35 7d 20 54 68 65 20  ** {H12105} The 
3590: 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20  return value of 
35a0: 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d  [sqlite3_exec()]
35b0: 20 73 68 61 6c 6c 20 62 65 20 61 6e 20 61 70 70   shall be an app
35c0: 72 6f 70 72 69 61 74 65 0a 2a 2a 20 20 20 20 20  ropriate.**     
35d0: 20 20 20 20 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65       non-zero [e
35e0: 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 6e  rror code] if an
35f0: 79 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  y SQL statement 
3600: 66 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  fails..**.** {H1
3610: 32 31 30 37 7d 20 49 66 20 6f 6e 65 20 6f 72 20  2107} If one or 
3620: 6d 6f 72 65 20 6f 66 20 74 68 65 20 53 51 4c 20  more of the SQL 
3630: 73 74 61 74 65 6d 65 6e 74 73 20 68 61 6e 64 65  statements hande
3640: 64 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 78  d to [sqlite3_ex
3650: 65 63 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20  ec()].**        
3660: 20 20 72 65 74 75 72 6e 20 72 65 73 75 6c 74 73    return results
3670: 20 61 6e 64 20 74 68 65 20 33 72 64 20 70 61 72   and the 3rd par
3680: 61 6d 65 74 65 72 20 69 73 20 6e 6f 74 20 4e 55  ameter is not NU
3690: 4c 4c 2c 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20  LL, then.**     
36a0: 20 20 20 20 20 74 68 65 20 63 61 6c 6c 62 61 63       the callbac
36b0: 6b 20 66 75 6e 63 74 69 6f 6e 20 73 70 65 63 69  k function speci
36c0: 66 69 65 64 20 62 79 20 74 68 65 20 33 72 64 20  fied by the 3rd 
36d0: 70 61 72 61 6d 65 74 65 72 20 73 68 61 6c 6c 20  parameter shall 
36e0: 62 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  be.**          i
36f0: 6e 76 6f 6b 65 64 20 6f 6e 63 65 20 66 6f 72 20  nvoked once for 
3700: 65 61 63 68 20 72 6f 77 20 6f 66 20 72 65 73 75  each row of resu
3710: 6c 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 31 31  lt..**.** {H1211
3720: 30 7d 20 49 66 20 74 68 65 20 63 61 6c 6c 62 61  0} If the callba
3730: 63 6b 20 72 65 74 75 72 6e 73 20 61 20 6e 6f 6e  ck returns a non
3740: 2d 7a 65 72 6f 20 76 61 6c 75 65 20 74 68 65 6e  -zero value then
3750: 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29   [sqlite3_exec()
3760: 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 68  ].**          sh
3770: 61 6c 6c 20 61 62 6f 72 74 20 74 68 65 20 53 51  all abort the SQ
3780: 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 74 20 69  L statement it i
3790: 73 20 63 75 72 72 65 6e 74 6c 79 20 65 76 61 6c  s currently eval
37a0: 75 61 74 69 6e 67 2c 0a 2a 2a 20 20 20 20 20 20  uating,.**      
37b0: 20 20 20 20 73 6b 69 70 20 61 6c 6c 20 73 75 62      skip all sub
37c0: 73 65 71 75 65 6e 74 20 53 51 4c 20 73 74 61 74  sequent SQL stat
37d0: 65 6d 65 6e 74 73 2c 20 61 6e 64 20 72 65 74 75  ements, and retu
37e0: 72 6e 20 5b 53 51 4c 49 54 45 5f 41 42 4f 52 54  rn [SQLITE_ABORT
37f0: 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 31 31 33  ]..**.** {H12113
3800: 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 65  } The [sqlite3_e
3810: 78 65 63 28 29 5d 20 72 6f 75 74 69 6e 65 20 73  xec()] routine s
3820: 68 61 6c 6c 20 70 61 73 73 20 69 74 73 20 34 74  hall pass its 4t
3830: 68 20 70 61 72 61 6d 65 74 65 72 20 74 68 72 6f  h parameter thro
3840: 75 67 68 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ugh.**          
3850: 61 73 20 74 68 65 20 31 73 74 20 70 61 72 61 6d  as the 1st param
3860: 65 74 65 72 20 6f 66 20 74 68 65 20 63 61 6c 6c  eter of the call
3870: 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  back..**.** {H12
3880: 31 31 36 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  116} The [sqlite
3890: 33 5f 65 78 65 63 28 29 5d 20 72 6f 75 74 69 6e  3_exec()] routin
38a0: 65 20 73 68 61 6c 6c 20 73 65 74 20 74 68 65 20  e shall set the 
38b0: 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66  2nd parameter of
38c0: 20 69 74 73 0a 2a 2a 20 20 20 20 20 20 20 20 20   its.**         
38d0: 20 63 61 6c 6c 62 61 63 6b 20 74 6f 20 62 65 20   callback to be 
38e0: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f  the number of co
38f0: 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 63 75 72  lumns in the cur
3900: 72 65 6e 74 20 72 6f 77 20 6f 66 0a 2a 2a 20 20  rent row of.**  
3910: 20 20 20 20 20 20 20 20 72 65 73 75 6c 74 2e 0a          result..
3920: 2a 2a 0a 2a 2a 20 7b 48 31 32 31 31 39 7d 20 54  **.** {H12119} T
3930: 68 65 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63  he [sqlite3_exec
3940: 28 29 5d 20 72 6f 75 74 69 6e 65 20 73 68 61 6c  ()] routine shal
3950: 6c 20 73 65 74 20 74 68 65 20 33 72 64 20 70 61  l set the 3rd pa
3960: 72 61 6d 65 74 65 72 20 6f 66 20 69 74 73 0a 2a  rameter of its.*
3970: 2a 20 20 20 20 20 20 20 20 20 20 63 61 6c 6c 62  *          callb
3980: 61 63 6b 20 74 6f 20 62 65 20 61 6e 20 61 72 72  ack to be an arr
3990: 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74  ay of pointers t
39a0: 6f 20 73 74 72 69 6e 67 73 20 68 6f 6c 64 69 6e  o strings holdin
39b0: 67 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  g the.**        
39c0: 20 20 76 61 6c 75 65 73 20 66 6f 72 20 65 61 63    values for eac
39d0: 68 20 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 20  h column in the 
39e0: 63 75 72 72 65 6e 74 20 72 65 73 75 6c 74 20 73  current result s
39f0: 65 74 20 72 6f 77 20 61 73 0a 2a 2a 20 20 20 20  et row as.**    
3a00: 20 20 20 20 20 20 6f 62 74 61 69 6e 65 64 20 66        obtained f
3a10: 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  rom [sqlite3_col
3a20: 75 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a  umn_text()]..**.
3a30: 2a 2a 20 7b 48 31 32 31 32 32 7d 20 54 68 65 20  ** {H12122} The 
3a40: 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d  [sqlite3_exec()]
3a50: 20 72 6f 75 74 69 6e 65 20 73 68 61 6c 6c 20 73   routine shall s
3a60: 65 74 20 74 68 65 20 34 74 68 20 70 61 72 61 6d  et the 4th param
3a70: 65 74 65 72 20 6f 66 20 69 74 73 0a 2a 2a 20 20  eter of its.**  
3a80: 20 20 20 20 20 20 20 20 63 61 6c 6c 62 61 63 6b          callback
3a90: 20 74 6f 20 62 65 20 61 6e 20 61 72 72 61 79 20   to be an array 
3aa0: 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73  of pointers to s
3ab0: 74 72 69 6e 67 73 20 68 6f 6c 64 69 6e 67 20 74  trings holding t
3ac0: 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e  he.**          n
3ad0: 61 6d 65 73 20 6f 66 20 72 65 73 75 6c 74 20 63  ames of result c
3ae0: 6f 6c 75 6d 6e 73 20 61 73 20 6f 62 74 61 69 6e  olumns as obtain
3af0: 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
3b00: 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 5d 2e  _column_name()].
3b10: 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 31 32 35 7d 20  .**.** {H12125} 
3b20: 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d  If the 3rd param
3b30: 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33  eter to [sqlite3
3b40: 5f 65 78 65 63 28 29 5d 20 69 73 20 4e 55 4c 4c  _exec()] is NULL
3b50: 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20   then.**        
3b60: 20 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28    [sqlite3_exec(
3b70: 29 5d 20 73 68 61 6c 6c 20 73 69 6c 65 6e 74 6c  )] shall silentl
3b80: 79 20 64 69 73 63 61 72 64 20 71 75 65 72 79 20  y discard query 
3b90: 72 65 73 75 6c 74 73 2e 0a 2a 2a 0a 2a 2a 20 7b  results..**.** {
3ba0: 48 31 32 31 33 31 7d 20 49 66 20 61 6e 20 65 72  H12131} If an er
3bb0: 72 6f 72 20 6f 63 63 75 72 73 20 77 68 69 6c 65  ror occurs while
3bc0: 20 70 61 72 73 69 6e 67 20 6f 72 20 65 76 61 6c   parsing or eval
3bd0: 75 61 74 69 6e 67 20 61 6e 79 20 6f 66 20 74 68  uating any of th
3be0: 65 20 53 51 4c 0a 2a 2a 20 20 20 20 20 20 20 20  e SQL.**        
3bf0: 20 20 73 74 61 74 65 6d 65 6e 74 73 20 69 6e 20    statements in 
3c00: 74 68 65 20 53 20 70 61 72 61 6d 65 74 65 72 20  the S parameter 
3c10: 6f 66 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63  of [sqlite3_exec
3c20: 28 44 2c 53 2c 43 2c 41 2c 45 29 5d 20 61 6e 64  (D,S,C,A,E)] and
3c30: 20 69 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   if.**          
3c40: 74 68 65 20 45 20 70 61 72 61 6d 65 74 65 72 20  the E parameter 
3c50: 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65  is not NULL, the
3c60: 6e 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28  n [sqlite3_exec(
3c70: 29 5d 20 73 68 61 6c 6c 20 73 74 6f 72 65 0a 2a  )] shall store.*
3c80: 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20 2a 45  *          in *E
3c90: 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20   an appropriate 
3ca0: 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 77 72  error message wr
3cb0: 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72  itten into memor
3cc0: 79 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 20 20  y obtained.**   
3cd0: 20 20 20 20 20 20 20 66 72 6f 6d 20 5b 73 71 6c         from [sql
3ce0: 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a  ite3_malloc()]..
3cf0: 2a 2a 0a 2a 2a 20 7b 48 31 32 31 33 34 7d 20 54  **.** {H12134} T
3d00: 68 65 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63  he [sqlite3_exec
3d10: 28 44 2c 53 2c 43 2c 41 2c 45 29 5d 20 72 6f 75  (D,S,C,A,E)] rou
3d20: 74 69 6e 65 20 73 68 61 6c 6c 20 73 65 74 20 74  tine shall set t
3d30: 68 65 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 20  he value of.**  
3d40: 20 20 20 20 20 20 20 20 2a 45 20 74 6f 20 4e 55          *E to NU
3d50: 4c 4c 20 69 66 20 45 20 69 73 20 6e 6f 74 20 4e  LL if E is not N
3d60: 55 4c 4c 20 61 6e 64 20 74 68 65 72 65 20 61 72  ULL and there ar
3d70: 65 20 6e 6f 20 65 72 72 6f 72 73 2e 0a 2a 2a 0a  e no errors..**.
3d80: 2a 2a 20 7b 48 31 32 31 33 37 7d 20 54 68 65 20  ** {H12137} The 
3d90: 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 44 2c  [sqlite3_exec(D,
3da0: 53 2c 43 2c 41 2c 45 29 5d 20 66 75 6e 63 74 69  S,C,A,E)] functi
3db0: 6f 6e 20 73 68 61 6c 6c 20 73 65 74 20 74 68 65  on shall set the
3dc0: 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 0a 2a 2a   [error code].**
3dd0: 20 20 20 20 20 20 20 20 20 20 61 6e 64 20 6d 65            and me
3de0: 73 73 61 67 65 20 61 63 63 65 73 73 69 62 6c 65  ssage accessible
3df0: 20 76 69 61 20 5b 73 71 6c 69 74 65 33 5f 65 72   via [sqlite3_er
3e00: 72 63 6f 64 65 28 29 5d 2c 0a 2a 2a 20 20 20 20  rcode()],.**    
3e10: 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 65        [sqlite3_e
3e20: 72 72 6d 73 67 28 29 5d 2c 20 61 6e 64 20 5b 73  rrmsg()], and [s
3e30: 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28  qlite3_errmsg16(
3e40: 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 31 33  )]..**.** {H1213
3e50: 38 7d 20 49 66 20 74 68 65 20 53 20 70 61 72 61  8} If the S para
3e60: 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65  meter to [sqlite
3e70: 33 5f 65 78 65 63 28 44 2c 53 2c 43 2c 41 2c 45  3_exec(D,S,C,A,E
3e80: 29 5d 20 69 73 20 4e 55 4c 4c 20 6f 72 20 61 6e  )] is NULL or an
3e90: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 65 6d 70  .**          emp
3ea0: 74 79 20 73 74 72 69 6e 67 20 6f 72 20 63 6f 6e  ty string or con
3eb0: 74 61 69 6e 73 20 6e 6f 74 68 69 6e 67 20 6f 74  tains nothing ot
3ec0: 68 65 72 20 74 68 61 6e 20 77 68 69 74 65 73 70  her than whitesp
3ed0: 61 63 65 2c 20 63 6f 6d 6d 65 6e 74 73 2c 0a 2a  ace, comments,.*
3ee0: 2a 20 20 20 20 20 20 20 20 20 20 61 6e 64 2f 6f  *          and/o
3ef0: 72 20 73 65 6d 69 63 6f 6c 6f 6e 73 2c 20 74 68  r semicolons, th
3f00: 65 6e 20 72 65 73 75 6c 74 73 20 6f 66 20 5b 73  en results of [s
3f10: 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29  qlite3_errcode()
3f20: 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  ],.**          [
3f30: 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29  sqlite3_errmsg()
3f40: 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ], and [sqlite3_
3f50: 65 72 72 6d 73 67 31 36 28 29 5d 0a 2a 2a 20 20  errmsg16()].**  
3f60: 20 20 20 20 20 20 20 20 73 68 61 6c 6c 20 72 65          shall re
3f70: 73 65 74 20 74 6f 20 69 6e 64 69 63 61 74 65 20  set to indicate 
3f80: 6e 6f 20 65 72 72 6f 72 73 2e 0a 2a 2a 0a 2a 2a  no errors..**.**
3f90: 20 41 53 53 55 4d 50 54 49 4f 4e 53 3a 0a 2a 2a   ASSUMPTIONS:.**
3fa0: 0a 2a 2a 20 7b 41 31 32 31 34 31 7d 20 54 68 65  .** {A12141} The
3fb0: 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
3fc0: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 78 65   to [sqlite3_exe
3fd0: 63 28 29 5d 20 6d 75 73 74 20 62 65 20 61 6e 20  c()] must be an 
3fe0: 76 61 6c 69 64 20 61 6e 64 20 6f 70 65 6e 0a 2a  valid and open.*
3ff0: 2a 20 20 20 20 20 20 20 20 20 20 5b 64 61 74 61  *          [data
4000: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
4010: 2e 0a 2a 2a 0a 2a 2a 20 7b 41 31 32 31 34 32 7d  ..**.** {A12142}
4020: 20 54 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   The database co
4030: 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f  nnection must no
4040: 74 20 62 65 20 63 6c 6f 73 65 64 20 77 68 69 6c  t be closed whil
4050: 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  e.**          [s
4060: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 69  qlite3_exec()] i
4070: 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a  s running..**.**
4080: 20 7b 41 31 32 31 34 33 7d 20 54 68 65 20 63 61   {A12143} The ca
4090: 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 73  lling function s
40a0: 68 6f 75 6c 64 20 75 73 65 20 5b 73 71 6c 69 74  hould use [sqlit
40b0: 65 33 5f 66 72 65 65 28 29 5d 20 74 6f 20 66 72  e3_free()] to fr
40c0: 65 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  ee.**          t
40d0: 68 65 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 2a  he memory that *
40e0: 65 72 72 6d 73 67 20 69 73 20 6c 65 66 74 20 70  errmsg is left p
40f0: 6f 69 6e 74 69 6e 67 20 61 74 20 6f 6e 63 65 20  ointing at once 
4100: 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 20 20 20  the error.**    
4110: 20 20 20 20 20 20 6d 65 73 73 61 67 65 20 69 73        message is
4120: 20 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65 65 64 65   no longer neede
4130: 64 2e 0a 2a 2a 0a 2a 2a 20 7b 41 31 32 31 34 35  d..**.** {A12145
4140: 7d 20 54 68 65 20 53 51 4c 20 73 74 61 74 65 6d  } The SQL statem
4150: 65 6e 74 20 74 65 78 74 20 69 6e 20 74 68 65 20  ent text in the 
4160: 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  2nd parameter to
4170: 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29   [sqlite3_exec()
4180: 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 75  ].**          mu
4190: 73 74 20 72 65 6d 61 69 6e 20 75 6e 63 68 61 6e  st remain unchan
41a0: 67 65 64 20 77 68 69 6c 65 20 5b 73 71 6c 69 74  ged while [sqlit
41b0: 65 33 5f 65 78 65 63 28 29 5d 20 69 73 20 72 75  e3_exec()] is ru
41c0: 6e 6e 69 6e 67 2e 0a 2a 2f 0a 69 6e 74 20 73 71  nning..*/.int sq
41d0: 6c 69 74 65 33 5f 65 78 65 63 28 0a 20 20 73 71  lite3_exec(.  sq
41e0: 6c 69 74 65 33 2a 2c 20 20 20 20 20 20 20 20 20  lite3*,         
41f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4200: 20 20 20 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f           /* An o
4210: 70 65 6e 20 64 61 74 61 62 61 73 65 20 2a 2f 0a  pen database */.
4220: 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71    const char *sq
4230: 6c 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  l,              
4240: 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
4250: 53 51 4c 20 74 6f 20 62 65 20 65 76 61 6c 75 61  SQL to be evalua
4260: 74 65 64 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 63  ted */.  int (*c
4270: 61 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69  allback)(void*,i
4280: 6e 74 2c 63 68 61 72 2a 2a 2c 63 68 61 72 2a 2a  nt,char**,char**
4290: 29 2c 20 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20  ),  /* Callback 
42a0: 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f  function */.  vo
42b0: 69 64 20 2a 2c 20 20 20 20 20 20 20 20 20 20 20  id *,           
42c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
42d0: 20 20 20 20 20 20 20 20 20 2f 2a 20 31 73 74 20           /* 1st 
42e0: 61 72 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c  argument to call
42f0: 62 61 63 6b 20 2a 2f 0a 20 20 63 68 61 72 20 2a  back */.  char *
4300: 2a 65 72 72 6d 73 67 20 20 20 20 20 20 20 20 20  *errmsg         
4310: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4320: 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d 73       /* Error ms
4330: 67 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a  g written here *
4340: 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.);../*.** CAPI
4350: 33 52 45 46 3a 20 52 65 73 75 6c 74 20 43 6f 64  3REF: Result Cod
4360: 65 73 20 7b 48 31 30 32 31 30 7d 20 3c 53 31 30  es {H10210} <S10
4370: 37 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  700>.** KEYWORDS
4380: 3a 20 53 51 4c 49 54 45 5f 4f 4b 20 7b 65 72 72  : SQLITE_OK {err
4390: 6f 72 20 63 6f 64 65 7d 20 7b 65 72 72 6f 72 20  or code} {error 
43a0: 63 6f 64 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52  codes}.** KEYWOR
43b0: 44 53 3a 20 7b 72 65 73 75 6c 74 20 63 6f 64 65  DS: {result code
43c0: 7d 20 7b 72 65 73 75 6c 74 20 63 6f 64 65 73 7d  } {result codes}
43d0: 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53 51 4c 69  .**.** Many SQLi
43e0: 74 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74  te functions ret
43f0: 75 72 6e 20 61 6e 20 69 6e 74 65 67 65 72 20 72  urn an integer r
4400: 65 73 75 6c 74 20 63 6f 64 65 20 66 72 6f 6d 20  esult code from 
4410: 74 68 65 20 73 65 74 20 73 68 6f 77 6e 0a 2a 2a  the set shown.**
4420: 20 68 65 72 65 20 69 6e 20 6f 72 64 65 72 20 74   here in order t
4430: 6f 20 69 6e 64 69 63 61 74 65 73 20 73 75 63 63  o indicates succ
4440: 65 73 73 20 6f 72 20 66 61 69 6c 75 72 65 2e 0a  ess or failure..
4450: 2a 2a 0a 2a 2a 20 4e 65 77 20 65 72 72 6f 72 20  **.** New error 
4460: 63 6f 64 65 73 20 6d 61 79 20 62 65 20 61 64 64  codes may be add
4470: 65 64 20 69 6e 20 66 75 74 75 72 65 20 76 65 72  ed in future ver
4480: 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e  sions of SQLite.
4490: 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
44a0: 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52   [SQLITE_IOERR_R
44b0: 45 41 44 20 7c 20 65 78 74 65 6e 64 65 64 20 72  EAD | extended r
44c0: 65 73 75 6c 74 20 63 6f 64 65 73 5d 0a 2a 2f 0a  esult codes].*/.
44d0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
44e0: 4b 20 20 20 20 20 20 20 20 20 20 20 30 20 20 20  K           0   
44f0: 2f 2a 20 53 75 63 63 65 73 73 66 75 6c 20 72 65  /* Successful re
4500: 73 75 6c 74 20 2a 2f 0a 2f 2a 20 62 65 67 69 6e  sult */./* begin
4510: 6e 69 6e 67 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f  ning-of-error-co
4520: 64 65 73 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  des */.#define S
4530: 51 4c 49 54 45 5f 45 52 52 4f 52 20 20 20 20 20  QLITE_ERROR     
4540: 20 20 20 31 20 20 20 2f 2a 20 53 51 4c 20 65 72     1   /* SQL er
4550: 72 6f 72 20 6f 72 20 6d 69 73 73 69 6e 67 20 64  ror or missing d
4560: 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 65 66 69  atabase */.#defi
4570: 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 52 4e  ne SQLITE_INTERN
4580: 41 4c 20 20 20 20 20 32 20 20 20 2f 2a 20 49 6e  AL     2   /* In
4590: 74 65 72 6e 61 6c 20 6c 6f 67 69 63 20 65 72 72  ternal logic err
45a0: 6f 72 20 69 6e 20 53 51 4c 69 74 65 20 2a 2f 0a  or in SQLite */.
45b0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50  #define SQLITE_P
45c0: 45 52 4d 20 20 20 20 20 20 20 20 20 33 20 20 20  ERM         3   
45d0: 2f 2a 20 41 63 63 65 73 73 20 70 65 72 6d 69 73  /* Access permis
45e0: 73 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f 0a 23  sion denied */.#
45f0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 42  define SQLITE_AB
4600: 4f 52 54 20 20 20 20 20 20 20 20 34 20 20 20 2f  ORT        4   /
4610: 2a 20 43 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69  * Callback routi
4620: 6e 65 20 72 65 71 75 65 73 74 65 64 20 61 6e 20  ne requested an 
4630: 61 62 6f 72 74 20 2a 2f 0a 23 64 65 66 69 6e 65  abort */.#define
4640: 20 53 51 4c 49 54 45 5f 42 55 53 59 20 20 20 20   SQLITE_BUSY    
4650: 20 20 20 20 20 35 20 20 20 2f 2a 20 54 68 65 20       5   /* The 
4660: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 69 73  database file is
4670: 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69   locked */.#defi
4680: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44  ne SQLITE_LOCKED
4690: 20 20 20 20 20 20 20 36 20 20 20 2f 2a 20 41 20         6   /* A 
46a0: 74 61 62 6c 65 20 69 6e 20 74 68 65 20 64 61 74  table in the dat
46b0: 61 62 61 73 65 20 69 73 20 6c 6f 63 6b 65 64 20  abase is locked 
46c0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
46d0: 45 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 37  E_NOMEM        7
46e0: 20 20 20 2f 2a 20 41 20 6d 61 6c 6c 6f 63 28 29     /* A malloc()
46f0: 20 66 61 69 6c 65 64 20 2a 2f 0a 23 64 65 66 69   failed */.#defi
4700: 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e  ne SQLITE_READON
4710: 4c 59 20 20 20 20 20 38 20 20 20 2f 2a 20 41 74  LY     8   /* At
4720: 74 65 6d 70 74 20 74 6f 20 77 72 69 74 65 20 61  tempt to write a
4730: 20 72 65 61 64 6f 6e 6c 79 20 64 61 74 61 62 61   readonly databa
4740: 73 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  se */.#define SQ
4750: 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 20 20  LITE_INTERRUPT  
4760: 20 20 39 20 20 20 2f 2a 20 4f 70 65 72 61 74 69    9   /* Operati
4770: 6f 6e 20 74 65 72 6d 69 6e 61 74 65 64 20 62 79  on terminated by
4780: 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
4790: 70 74 28 29 2a 2f 0a 23 64 65 66 69 6e 65 20 53  pt()*/.#define S
47a0: 51 4c 49 54 45 5f 49 4f 45 52 52 20 20 20 20 20  QLITE_IOERR     
47b0: 20 20 31 30 20 20 20 2f 2a 20 53 6f 6d 65 20 6b    10   /* Some k
47c0: 69 6e 64 20 6f 66 20 64 69 73 6b 20 49 2f 4f 20  ind of disk I/O 
47d0: 65 72 72 6f 72 20 6f 63 63 75 72 72 65 64 20 2a  error occurred *
47e0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
47f0: 5f 43 4f 52 52 55 50 54 20 20 20 20 20 31 31 20  _CORRUPT     11 
4800: 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73    /* The databas
4810: 65 20 64 69 73 6b 20 69 6d 61 67 65 20 69 73 20  e disk image is 
4820: 6d 61 6c 66 6f 72 6d 65 64 20 2a 2f 0a 23 64 65  malformed */.#de
4830: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 46  fine SQLITE_NOTF
4840: 4f 55 4e 44 20 20 20 20 31 32 20 20 20 2f 2a 20  OUND    12   /* 
4850: 4e 4f 54 20 55 53 45 44 2e 20 54 61 62 6c 65 20  NOT USED. Table 
4860: 6f 72 20 72 65 63 6f 72 64 20 6e 6f 74 20 66 6f  or record not fo
4870: 75 6e 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  und */.#define S
4880: 51 4c 49 54 45 5f 46 55 4c 4c 20 20 20 20 20 20  QLITE_FULL      
4890: 20 20 31 33 20 20 20 2f 2a 20 49 6e 73 65 72 74    13   /* Insert
48a0: 69 6f 6e 20 66 61 69 6c 65 64 20 62 65 63 61 75  ion failed becau
48b0: 73 65 20 64 61 74 61 62 61 73 65 20 69 73 20 66  se database is f
48c0: 75 6c 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ull */.#define S
48d0: 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 20  QLITE_CANTOPEN  
48e0: 20 20 31 34 20 20 20 2f 2a 20 55 6e 61 62 6c 65    14   /* Unable
48f0: 20 74 6f 20 6f 70 65 6e 20 74 68 65 20 64 61 74   to open the dat
4900: 61 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64  abase file */.#d
4910: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 4f  efine SQLITE_PRO
4920: 54 4f 43 4f 4c 20 20 20 20 31 35 20 20 20 2f 2a  TOCOL    15   /*
4930: 20 4e 4f 54 20 55 53 45 44 2e 20 44 61 74 61 62   NOT USED. Datab
4940: 61 73 65 20 6c 6f 63 6b 20 70 72 6f 74 6f 63 6f  ase lock protoco
4950: 6c 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69  l error */.#defi
4960: 6e 65 20 53 51 4c 49 54 45 5f 45 4d 50 54 59 20  ne SQLITE_EMPTY 
4970: 20 20 20 20 20 20 31 36 20 20 20 2f 2a 20 44 61        16   /* Da
4980: 74 61 62 61 73 65 20 69 73 20 65 6d 70 74 79 20  tabase is empty 
4990: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
49a0: 45 5f 53 43 48 45 4d 41 20 20 20 20 20 20 31 37  E_SCHEMA      17
49b0: 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61     /* The databa
49c0: 73 65 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65  se schema change
49d0: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
49e0: 49 54 45 5f 54 4f 4f 42 49 47 20 20 20 20 20 20  ITE_TOOBIG      
49f0: 31 38 20 20 20 2f 2a 20 53 74 72 69 6e 67 20 6f  18   /* String o
4a00: 72 20 42 4c 4f 42 20 65 78 63 65 65 64 73 20 73  r BLOB exceeds s
4a10: 69 7a 65 20 6c 69 6d 69 74 20 2a 2f 0a 23 64 65  ize limit */.#de
4a20: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53  fine SQLITE_CONS
4a30: 54 52 41 49 4e 54 20 20 31 39 20 20 20 2f 2a 20  TRAINT  19   /* 
4a40: 41 62 6f 72 74 20 64 75 65 20 74 6f 20 63 6f 6e  Abort due to con
4a50: 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f  straint violatio
4a60: 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  n */.#define SQL
4a70: 49 54 45 5f 4d 49 53 4d 41 54 43 48 20 20 20 20  ITE_MISMATCH    
4a80: 32 30 20 20 20 2f 2a 20 44 61 74 61 20 74 79 70  20   /* Data typ
4a90: 65 20 6d 69 73 6d 61 74 63 68 20 2a 2f 0a 23 64  e mismatch */.#d
4aa0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53  efine SQLITE_MIS
4ab0: 55 53 45 20 20 20 20 20 20 32 31 20 20 20 2f 2a  USE      21   /*
4ac0: 20 4c 69 62 72 61 72 79 20 75 73 65 64 20 69 6e   Library used in
4ad0: 63 6f 72 72 65 63 74 6c 79 20 2a 2f 0a 23 64 65  correctly */.#de
4ae0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4c 46  fine SQLITE_NOLF
4af0: 53 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a 20  S       22   /* 
4b00: 55 73 65 73 20 4f 53 20 66 65 61 74 75 72 65 73  Uses OS features
4b10: 20 6e 6f 74 20 73 75 70 70 6f 72 74 65 64 20 6f   not supported o
4b20: 6e 20 68 6f 73 74 20 2a 2f 0a 23 64 65 66 69 6e  n host */.#defin
4b30: 65 20 53 51 4c 49 54 45 5f 41 55 54 48 20 20 20  e SQLITE_AUTH   
4b40: 20 20 20 20 20 32 33 20 20 20 2f 2a 20 41 75 74       23   /* Aut
4b50: 68 6f 72 69 7a 61 74 69 6f 6e 20 64 65 6e 69 65  horization denie
4b60: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
4b70: 49 54 45 5f 46 4f 52 4d 41 54 20 20 20 20 20 20  ITE_FORMAT      
4b80: 32 34 20 20 20 2f 2a 20 41 75 78 69 6c 69 61 72  24   /* Auxiliar
4b90: 79 20 64 61 74 61 62 61 73 65 20 66 6f 72 6d 61  y database forma
4ba0: 74 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69  t error */.#defi
4bb0: 6e 65 20 53 51 4c 49 54 45 5f 52 41 4e 47 45 20  ne SQLITE_RANGE 
4bc0: 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20 32 6e        25   /* 2n
4bd0: 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  d parameter to s
4be0: 71 6c 69 74 65 33 5f 62 69 6e 64 20 6f 75 74 20  qlite3_bind out 
4bf0: 6f 66 20 72 61 6e 67 65 20 2a 2f 0a 23 64 65 66  of range */.#def
4c00: 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 41 44  ine SQLITE_NOTAD
4c10: 42 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20 46  B      26   /* F
4c20: 69 6c 65 20 6f 70 65 6e 65 64 20 74 68 61 74 20  ile opened that 
4c30: 69 73 20 6e 6f 74 20 61 20 64 61 74 61 62 61 73  is not a databas
4c40: 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e  e file */.#defin
4c50: 65 20 53 51 4c 49 54 45 5f 52 4f 57 20 20 20 20  e SQLITE_ROW    
4c60: 20 20 20 20 20 31 30 30 20 20 2f 2a 20 73 71 6c       100  /* sql
4c70: 69 74 65 33 5f 73 74 65 70 28 29 20 68 61 73 20  ite3_step() has 
4c80: 61 6e 6f 74 68 65 72 20 72 6f 77 20 72 65 61 64  another row read
4c90: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
4ca0: 49 54 45 5f 44 4f 4e 45 20 20 20 20 20 20 20 20  ITE_DONE        
4cb0: 31 30 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f  101  /* sqlite3_
4cc0: 73 74 65 70 28 29 20 68 61 73 20 66 69 6e 69 73  step() has finis
4cd0: 68 65 64 20 65 78 65 63 75 74 69 6e 67 20 2a 2f  hed executing */
4ce0: 0a 2f 2a 20 65 6e 64 2d 6f 66 2d 65 72 72 6f 72  ./* end-of-error
4cf0: 2d 63 6f 64 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a  -codes */../*.**
4d00: 20 43 41 50 49 33 52 45 46 3a 20 45 78 74 65 6e   CAPI3REF: Exten
4d10: 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65 73  ded Result Codes
4d20: 20 7b 48 31 30 32 32 30 7d 20 3c 53 31 30 37 30   {H10220} <S1070
4d30: 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  0>.** KEYWORDS: 
4d40: 7b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20  {extended error 
4d50: 63 6f 64 65 7d 20 7b 65 78 74 65 6e 64 65 64 20  code} {extended 
4d60: 65 72 72 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a 20  error codes}.** 
4d70: 4b 45 59 57 4f 52 44 53 3a 20 7b 65 78 74 65 6e  KEYWORDS: {exten
4d80: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 7d  ded result code}
4d90: 20 7b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c   {extended resul
4da0: 74 20 63 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a 20 49  t codes}.**.** I
4db0: 6e 20 69 74 73 20 64 65 66 61 75 6c 74 20 63 6f  n its default co
4dc0: 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20 53 51 4c  nfiguration, SQL
4dd0: 69 74 65 20 41 50 49 20 72 6f 75 74 69 6e 65 73  ite API routines
4de0: 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 32   return one of 2
4df0: 36 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 53 51  6 integer.** [SQ
4e00: 4c 49 54 45 5f 4f 4b 20 7c 20 72 65 73 75 6c 74  LITE_OK | result
4e10: 20 63 6f 64 65 73 5d 2e 20 20 48 6f 77 65 76 65   codes].  Howeve
4e20: 72 2c 20 65 78 70 65 72 69 65 6e 63 65 20 68 61  r, experience ha
4e30: 73 20 73 68 6f 77 6e 20 74 68 61 74 20 6d 61 6e  s shown that man
4e40: 79 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20 72 65  y of.** these re
4e50: 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 20 74  sult codes are t
4e60: 6f 6f 20 63 6f 61 72 73 65 2d 67 72 61 69 6e 65  oo coarse-graine
4e70: 64 2e 20 20 54 68 65 79 20 64 6f 20 6e 6f 74 20  d.  They do not 
4e80: 70 72 6f 76 69 64 65 20 61 73 0a 2a 2a 20 6d 75  provide as.** mu
4e90: 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61  ch information a
4ea0: 62 6f 75 74 20 70 72 6f 62 6c 65 6d 73 20 61 73  bout problems as
4eb0: 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67   programmers mig
4ec0: 68 74 20 6c 69 6b 65 2e 20 20 49 6e 20 61 6e 20  ht like.  In an 
4ed0: 65 66 66 6f 72 74 20 74 6f 0a 2a 2a 20 61 64 64  effort to.** add
4ee0: 72 65 73 73 20 74 68 69 73 2c 20 6e 65 77 65 72  ress this, newer
4ef0: 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
4f00: 69 74 65 20 28 76 65 72 73 69 6f 6e 20 33 2e 33  ite (version 3.3
4f10: 2e 38 20 61 6e 64 20 6c 61 74 65 72 29 20 69 6e  .8 and later) in
4f20: 63 6c 75 64 65 0a 2a 2a 20 73 75 70 70 6f 72 74  clude.** support
4f30: 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20   for additional 
4f40: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 74 68 61  result codes tha
4f50: 74 20 70 72 6f 76 69 64 65 20 6d 6f 72 65 20 64  t provide more d
4f60: 65 74 61 69 6c 65 64 20 69 6e 66 6f 72 6d 61 74  etailed informat
4f70: 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20 65 72 72  ion.** about err
4f80: 6f 72 73 2e 20 54 68 65 20 65 78 74 65 6e 64 65  ors. The extende
4f90: 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61  d result codes a
4fa0: 72 65 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69  re enabled or di
4fb0: 73 61 62 6c 65 64 0a 2a 2a 20 6f 6e 20 61 20 70  sabled.** on a p
4fc0: 65 72 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  er database conn
4fd0: 65 63 74 69 6f 6e 20 62 61 73 69 73 20 75 73 69  ection basis usi
4fe0: 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ng the.** [sqlit
4ff0: 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75  e3_extended_resu
5000: 6c 74 5f 63 6f 64 65 73 28 29 5d 20 41 50 49 2e  lt_codes()] API.
5010: 0a 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 6f 66 20 74  .**.** Some of t
5020: 68 65 20 61 76 61 69 6c 61 62 6c 65 20 65 78 74  he available ext
5030: 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
5040: 65 73 20 61 72 65 20 6c 69 73 74 65 64 20 68 65  es are listed he
5050: 72 65 2e 0a 2a 2a 20 4f 6e 65 20 6d 61 79 20 65  re..** One may e
5060: 78 70 65 63 74 20 74 68 65 20 6e 75 6d 62 65 72  xpect the number
5070: 20 6f 66 20 65 78 74 65 6e 64 65 64 20 72 65 73   of extended res
5080: 75 6c 74 20 63 6f 64 65 73 20 77 69 6c 6c 20 62  ult codes will b
5090: 65 20 65 78 70 61 6e 64 0a 2a 2a 20 6f 76 65 72  e expand.** over
50a0: 20 74 69 6d 65 2e 20 20 53 6f 66 74 77 61 72 65   time.  Software
50b0: 20 74 68 61 74 20 75 73 65 73 20 65 78 74 65 6e   that uses exten
50c0: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
50d0: 20 73 68 6f 75 6c 64 20 65 78 70 65 63 74 0a 2a   should expect.*
50e0: 2a 20 74 6f 20 73 65 65 20 6e 65 77 20 72 65 73  * to see new res
50f0: 75 6c 74 20 63 6f 64 65 73 20 69 6e 20 66 75 74  ult codes in fut
5100: 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20  ure releases of 
5110: 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  SQLite..**.** Th
5120: 65 20 53 51 4c 49 54 45 5f 4f 4b 20 72 65 73 75  e SQLITE_OK resu
5130: 6c 74 20 63 6f 64 65 20 77 69 6c 6c 20 6e 65 76  lt code will nev
5140: 65 72 20 62 65 20 65 78 74 65 6e 64 65 64 2e 20  er be extended. 
5150: 20 49 74 20 77 69 6c 6c 20 61 6c 77 61 79 73 0a   It will always.
5160: 2a 2a 20 62 65 20 65 78 61 63 74 6c 79 20 7a 65  ** be exactly ze
5170: 72 6f 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  ro..**.** INVARI
5180: 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 30  ANTS:.**.** {H10
5190: 32 32 33 7d 20 54 68 65 20 73 79 6d 62 6f 6c 69  223} The symboli
51a0: 63 20 6e 61 6d 65 20 66 6f 72 20 61 6e 20 65 78  c name for an ex
51b0: 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
51c0: 64 65 20 73 68 61 6c 6c 20 63 6f 6e 74 61 69 6e  de shall contain
51d0: 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20  s.**          a 
51e0: 72 65 6c 61 74 65 64 20 70 72 69 6d 61 72 79 20  related primary 
51f0: 72 65 73 75 6c 74 20 63 6f 64 65 20 61 73 20 61  result code as a
5200: 20 70 72 65 66 69 78 2e 0a 2a 2a 0a 2a 2a 20 7b   prefix..**.** {
5210: 48 31 30 32 32 34 7d 20 50 72 69 6d 61 72 79 20  H10224} Primary 
5220: 72 65 73 75 6c 74 20 63 6f 64 65 20 6e 61 6d 65  result code name
5230: 73 20 73 68 61 6c 6c 20 63 6f 6e 74 61 69 6e 20  s shall contain 
5240: 61 20 73 69 6e 67 6c 65 20 22 5f 22 20 63 68 61  a single "_" cha
5250: 72 61 63 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48  racter..**.** {H
5260: 31 30 32 32 35 7d 20 45 78 74 65 6e 64 65 64 20  10225} Extended 
5270: 72 65 73 75 6c 74 20 63 6f 64 65 20 6e 61 6d 65  result code name
5280: 73 20 73 68 61 6c 6c 20 63 6f 6e 74 61 69 6e 20  s shall contain 
5290: 74 77 6f 20 6f 72 20 6d 6f 72 65 20 22 5f 22 20  two or more "_" 
52a0: 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a  characters..**.*
52b0: 2a 20 7b 48 31 30 32 32 36 7d 20 54 68 65 20 6e  * {H10226} The n
52c0: 75 6d 65 72 69 63 20 76 61 6c 75 65 20 6f 66 20  umeric value of 
52d0: 61 6e 20 65 78 74 65 6e 64 65 64 20 72 65 73 75  an extended resu
52e0: 6c 74 20 63 6f 64 65 20 73 68 61 6c 6c 20 63 6f  lt code shall co
52f0: 6e 74 61 69 6e 20 74 68 65 0a 2a 2a 20 20 20 20  ntain the.**    
5300: 20 20 20 20 20 20 6e 75 6d 65 72 69 63 20 76 61        numeric va
5310: 6c 75 65 20 6f 66 20 69 74 73 20 63 6f 72 72 65  lue of its corre
5320: 73 70 6f 6e 64 69 6e 67 20 70 72 69 6d 61 72 79  sponding primary
5330: 20 72 65 73 75 6c 74 20 63 6f 64 65 20 69 6e 0a   result code in.
5340: 2a 2a 20 20 20 20 20 20 20 20 20 20 69 74 73 20  **          its 
5350: 6c 65 61 73 74 20 73 69 67 6e 69 66 69 63 61 6e  least significan
5360: 74 20 38 20 62 69 74 73 2e 0a 2a 2f 0a 23 64 65  t 8 bits..*/.#de
5370: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
5380: 52 5f 52 45 41 44 20 20 20 20 20 20 20 20 20 20  R_READ          
5390: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
53a0: 52 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66  R | (1<<8)).#def
53b0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
53c0: 5f 53 48 4f 52 54 5f 52 45 41 44 20 20 20 20 20  _SHORT_READ     
53d0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
53e0: 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69   | (2<<8)).#defi
53f0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5400: 57 52 49 54 45 20 20 20 20 20 20 20 20 20 20 20  WRITE           
5410: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5420: 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (3<<8)).#defin
5430: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46  e SQLITE_IOERR_F
5440: 53 59 4e 43 20 20 20 20 20 20 20 20 20 20 20 20  SYNC            
5450: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
5460: 20 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (4<<8)).#define
5470: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49   SQLITE_IOERR_DI
5480: 52 5f 46 53 59 4e 43 20 20 20 20 20 20 20 20 20  R_FSYNC         
5490: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
54a0: 28 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (5<<8)).#define 
54b0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 54 52 55  SQLITE_IOERR_TRU
54c0: 4e 43 41 54 45 20 20 20 20 20 20 20 20 20 20 28  NCATE          (
54d0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
54e0: 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  6<<8)).#define S
54f0: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46 53 54 41  QLITE_IOERR_FSTA
5500: 54 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53  T             (S
5510: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 37  QLITE_IOERR | (7
5520: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5530: 4c 49 54 45 5f 49 4f 45 52 52 5f 55 4e 4c 4f 43  LITE_IOERR_UNLOC
5540: 4b 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51  K            (SQ
5550: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 38 3c  LITE_IOERR | (8<
5560: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5570: 49 54 45 5f 49 4f 45 52 52 5f 52 44 4c 4f 43 4b  ITE_IOERR_RDLOCK
5580: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
5590: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 39 3c 3c  ITE_IOERR | (9<<
55a0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
55b0: 54 45 5f 49 4f 45 52 52 5f 44 45 4c 45 54 45 20  TE_IOERR_DELETE 
55c0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
55d0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 30 3c 3c  TE_IOERR | (10<<
55e0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
55f0: 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44  TE_IOERR_BLOCKED
5600: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
5610: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 31 3c 3c  TE_IOERR | (11<<
5620: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5630: 54 45 5f 49 4f 45 52 52 5f 4e 4f 4d 45 4d 20 20  TE_IOERR_NOMEM  
5640: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
5650: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 32 3c 3c  TE_IOERR | (12<<
5660: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5670: 54 45 5f 49 4f 45 52 52 5f 41 43 43 45 53 53 20  TE_IOERR_ACCESS 
5680: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
5690: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 33 3c 3c  TE_IOERR | (13<<
56a0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
56b0: 54 45 5f 49 4f 45 52 52 5f 43 48 45 43 4b 52 45  TE_IOERR_CHECKRE
56c0: 53 45 52 56 45 44 4c 4f 43 4b 20 28 53 51 4c 49  SERVEDLOCK (SQLI
56d0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 34 3c 3c  TE_IOERR | (14<<
56e0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
56f0: 54 45 5f 49 4f 45 52 52 5f 4c 4f 43 4b 20 20 20  TE_IOERR_LOCK   
5700: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
5710: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 35 3c 3c  TE_IOERR | (15<<
5720: 38 29 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  8))../*.** CAPI3
5730: 52 45 46 3a 20 46 6c 61 67 73 20 46 6f 72 20 46  REF: Flags For F
5740: 69 6c 65 20 4f 70 65 6e 20 4f 70 65 72 61 74 69  ile Open Operati
5750: 6f 6e 73 20 7b 48 31 30 32 33 30 7d 20 3c 48 31  ons {H10230} <H1
5760: 31 31 32 30 3e 20 3c 48 31 32 37 30 30 3e 0a 2a  1120> <H12700>.*
5770: 2a 0a 2a 2a 20 54 68 65 73 65 20 62 69 74 20 76  *.** These bit v
5780: 61 6c 75 65 73 20 61 72 65 20 69 6e 74 65 6e 64  alues are intend
5790: 65 64 20 66 6f 72 20 75 73 65 20 69 6e 20 74 68  ed for use in th
57a0: 65 0a 2a 2a 20 33 72 64 20 70 61 72 61 6d 65 74  e.** 3rd paramet
57b0: 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  er to the [sqlit
57c0: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e  e3_open_v2()] in
57d0: 74 65 72 66 61 63 65 20 61 6e 64 0a 2a 2a 20 69  terface and.** i
57e0: 6e 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65  n the 4th parame
57f0: 74 65 72 20 74 6f 20 74 68 65 20 78 4f 70 65 6e  ter to the xOpen
5800: 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 0a 2a   method of the.*
5810: 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  * [sqlite3_vfs] 
5820: 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 23 64 65 66 69  object..*/.#defi
5830: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  ne SQLITE_OPEN_R
5840: 45 41 44 4f 4e 4c 59 20 20 20 20 20 20 20 20 20  EADONLY         
5850: 30 78 30 30 30 30 30 30 30 31 0a 23 64 65 66 69  0x00000001.#defi
5860: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  ne SQLITE_OPEN_R
5870: 45 41 44 57 52 49 54 45 20 20 20 20 20 20 20 20  EADWRITE        
5880: 30 78 30 30 30 30 30 30 30 32 0a 23 64 65 66 69  0x00000002.#defi
5890: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43  ne SQLITE_OPEN_C
58a0: 52 45 41 54 45 20 20 20 20 20 20 20 20 20 20 20  REATE           
58b0: 30 78 30 30 30 30 30 30 30 34 0a 23 64 65 66 69  0x00000004.#defi
58c0: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44  ne SQLITE_OPEN_D
58d0: 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 20 20 20 20  ELETEONCLOSE    
58e0: 30 78 30 30 30 30 30 30 30 38 0a 23 64 65 66 69  0x00000008.#defi
58f0: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45  ne SQLITE_OPEN_E
5900: 58 43 4c 55 53 49 56 45 20 20 20 20 20 20 20 20  XCLUSIVE        
5910: 30 78 30 30 30 30 30 30 31 30 0a 23 64 65 66 69  0x00000010.#defi
5920: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d  ne SQLITE_OPEN_M
5930: 41 49 4e 5f 44 42 20 20 20 20 20 20 20 20 20 20  AIN_DB          
5940: 30 78 30 30 30 30 30 31 30 30 0a 23 64 65 66 69  0x00000100.#defi
5950: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54  ne SQLITE_OPEN_T
5960: 45 4d 50 5f 44 42 20 20 20 20 20 20 20 20 20 20  EMP_DB          
5970: 30 78 30 30 30 30 30 32 30 30 0a 23 64 65 66 69  0x00000200.#defi
5980: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54  ne SQLITE_OPEN_T
5990: 52 41 4e 53 49 45 4e 54 5f 44 42 20 20 20 20 20  RANSIENT_DB     
59a0: 30 78 30 30 30 30 30 34 30 30 0a 23 64 65 66 69  0x00000400.#defi
59b0: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d  ne SQLITE_OPEN_M
59c0: 41 49 4e 5f 4a 4f 55 52 4e 41 4c 20 20 20 20 20  AIN_JOURNAL     
59d0: 30 78 30 30 30 30 30 38 30 30 0a 23 64 65 66 69  0x00000800.#defi
59e0: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54  ne SQLITE_OPEN_T
59f0: 45 4d 50 5f 4a 4f 55 52 4e 41 4c 20 20 20 20 20  EMP_JOURNAL     
5a00: 30 78 30 30 30 30 31 30 30 30 0a 23 64 65 66 69  0x00001000.#defi
5a10: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53  ne SQLITE_OPEN_S
5a20: 55 42 4a 4f 55 52 4e 41 4c 20 20 20 20 20 20 20  UBJOURNAL       
5a30: 30 78 30 30 30 30 32 30 30 30 0a 23 64 65 66 69  0x00002000.#defi
5a40: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d  ne SQLITE_OPEN_M
5a50: 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 20 20 20  ASTER_JOURNAL   
5a60: 30 78 30 30 30 30 34 30 30 30 0a 23 64 65 66 69  0x00004000.#defi
5a70: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e  ne SQLITE_OPEN_N
5a80: 4f 4d 55 54 45 58 20 20 20 20 20 20 20 20 20 20  OMUTEX          
5a90: 30 78 30 30 30 30 38 30 30 30 0a 23 64 65 66 69  0x00008000.#defi
5aa0: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46  ne SQLITE_OPEN_F
5ab0: 55 4c 4c 4d 55 54 45 58 20 20 20 20 20 20 20 20  ULLMUTEX        
5ac0: 30 78 30 30 30 31 30 30 30 30 0a 0a 2f 2a 0a 2a  0x00010000../*.*
5ad0: 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 76 69  * CAPI3REF: Devi
5ae0: 63 65 20 43 68 61 72 61 63 74 65 72 69 73 74 69  ce Characteristi
5af0: 63 73 20 7b 48 31 30 32 34 30 7d 20 3c 48 31 31  cs {H10240} <H11
5b00: 31 32 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  120>.**.** The x
5b10: 44 65 76 69 63 65 43 61 70 61 62 69 6c 69 74 69  DeviceCapabiliti
5b20: 65 73 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65  es method of the
5b30: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
5b40: 68 6f 64 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20  hods].** object 
5b50: 72 65 74 75 72 6e 73 20 61 6e 20 69 6e 74 65 67  returns an integ
5b60: 65 72 20 77 68 69 63 68 20 69 73 20 61 20 76 65  er which is a ve
5b70: 63 74 6f 72 20 6f 66 20 74 68 65 20 74 68 65 73  ctor of the thes
5b80: 65 0a 2a 2a 20 62 69 74 20 76 61 6c 75 65 73 20  e.** bit values 
5b90: 65 78 70 72 65 73 73 69 6e 67 20 49 2f 4f 20 63  expressing I/O c
5ba0: 68 61 72 61 63 74 65 72 69 73 74 69 63 73 20 6f  haracteristics o
5bb0: 66 20 74 68 65 20 6d 61 73 73 20 73 74 6f 72 61  f the mass stora
5bc0: 67 65 0a 2a 2a 20 64 65 76 69 63 65 20 74 68 61  ge.** device tha
5bd0: 74 20 68 6f 6c 64 73 20 74 68 65 20 66 69 6c 65  t holds the file
5be0: 20 74 68 61 74 20 74 68 65 20 5b 73 71 6c 69 74   that the [sqlit
5bf0: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a  e3_io_methods].*
5c00: 2a 20 72 65 66 65 72 73 20 74 6f 2e 0a 2a 2a 0a  * refers to..**.
5c10: 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  ** The SQLITE_IO
5c20: 43 41 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65  CAP_ATOMIC prope
5c30: 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 20 61  rty means that a
5c40: 6c 6c 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20  ll writes of.** 
5c50: 61 6e 79 20 73 69 7a 65 20 61 72 65 20 61 74 6f  any size are ato
5c60: 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45  mic.  The SQLITE
5c70: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e  _IOCAP_ATOMICnnn
5c80: 20 76 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20   values.** mean 
5c90: 74 68 61 74 20 77 72 69 74 65 73 20 6f 66 20 62  that writes of b
5ca0: 6c 6f 63 6b 73 20 74 68 61 74 20 61 72 65 20 6e  locks that are n
5cb0: 6e 6e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65  nn bytes in size
5cc0: 20 61 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67   and.** are alig
5cd0: 6e 65 64 20 74 6f 20 61 6e 20 61 64 64 72 65 73  ned to an addres
5ce0: 73 20 77 68 69 63 68 20 69 73 20 61 6e 20 69 6e  s which is an in
5cf0: 74 65 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f  teger multiple o
5d00: 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f  f.** nnn are ato
5d10: 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45  mic.  The SQLITE
5d20: 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45  _IOCAP_SAFE_APPE
5d30: 4e 44 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a  ND value means.*
5d40: 2a 20 74 68 61 74 20 77 68 65 6e 20 64 61 74 61  * that when data
5d50: 20 69 73 20 61 70 70 65 6e 64 65 64 20 74 6f 20   is appended to 
5d60: 61 20 66 69 6c 65 2c 20 74 68 65 20 64 61 74 61  a file, the data
5d70: 20 69 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20   is appended.** 
5d80: 66 69 72 73 74 20 74 68 65 6e 20 74 68 65 20 73  first then the s
5d90: 69 7a 65 20 6f 66 20 74 68 65 20 66 69 6c 65 20  ize of the file 
5da0: 69 73 20 65 78 74 65 6e 64 65 64 2c 20 6e 65 76  is extended, nev
5db0: 65 72 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20  er the other.** 
5dc0: 77 61 79 20 61 72 6f 75 6e 64 2e 20 20 54 68 65  way around.  The
5dd0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45   SQLITE_IOCAP_SE
5de0: 51 55 45 4e 54 49 41 4c 20 70 72 6f 70 65 72 74  QUENTIAL propert
5df0: 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20  y means that.** 
5e00: 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77  information is w
5e10: 72 69 74 74 65 6e 20 74 6f 20 64 69 73 6b 20 69  ritten to disk i
5e20: 6e 20 74 68 65 20 73 61 6d 65 20 6f 72 64 65 72  n the same order
5e30: 20 61 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20   as calls.** to 
5e40: 78 57 72 69 74 65 28 29 2e 0a 2a 2f 0a 23 64 65  xWrite()..*/.#de
5e50: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
5e60: 50 5f 41 54 4f 4d 49 43 20 20 20 20 20 20 20 20  P_ATOMIC        
5e70: 20 20 30 78 30 30 30 30 30 30 30 31 0a 23 64 65    0x00000001.#de
5e80: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
5e90: 50 5f 41 54 4f 4d 49 43 35 31 32 20 20 20 20 20  P_ATOMIC512     
5ea0: 20 20 30 78 30 30 30 30 30 30 30 32 0a 23 64 65    0x00000002.#de
5eb0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
5ec0: 50 5f 41 54 4f 4d 49 43 31 4b 20 20 20 20 20 20  P_ATOMIC1K      
5ed0: 20 20 30 78 30 30 30 30 30 30 30 34 0a 23 64 65    0x00000004.#de
5ee0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
5ef0: 50 5f 41 54 4f 4d 49 43 32 4b 20 20 20 20 20 20  P_ATOMIC2K      
5f00: 20 20 30 78 30 30 30 30 30 30 30 38 0a 23 64 65    0x00000008.#de
5f10: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
5f20: 50 5f 41 54 4f 4d 49 43 34 4b 20 20 20 20 20 20  P_ATOMIC4K      
5f30: 20 20 30 78 30 30 30 30 30 30 31 30 0a 23 64 65    0x00000010.#de
5f40: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
5f50: 50 5f 41 54 4f 4d 49 43 38 4b 20 20 20 20 20 20  P_ATOMIC8K      
5f60: 20 20 30 78 30 30 30 30 30 30 32 30 0a 23 64 65    0x00000020.#de
5f70: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
5f80: 50 5f 41 54 4f 4d 49 43 31 36 4b 20 20 20 20 20  P_ATOMIC16K     
5f90: 20 20 30 78 30 30 30 30 30 30 34 30 0a 23 64 65    0x00000040.#de
5fa0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
5fb0: 50 5f 41 54 4f 4d 49 43 33 32 4b 20 20 20 20 20  P_ATOMIC32K     
5fc0: 20 20 30 78 30 30 30 30 30 30 38 30 0a 23 64 65    0x00000080.#de
5fd0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
5fe0: 50 5f 41 54 4f 4d 49 43 36 34 4b 20 20 20 20 20  P_ATOMIC64K     
5ff0: 20 20 30 78 30 30 30 30 30 31 30 30 0a 23 64 65    0x00000100.#de
6000: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
6010: 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 20 20  P_SAFE_APPEND   
6020: 20 20 30 78 30 30 30 30 30 32 30 30 0a 23 64 65    0x00000200.#de
6030: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
6040: 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 20 20 20  P_SEQUENTIAL    
6050: 20 20 30 78 30 30 30 30 30 34 30 30 0a 0a 2f 2a    0x00000400../*
6060: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 69  .** CAPI3REF: Fi
6070: 6c 65 20 4c 6f 63 6b 69 6e 67 20 4c 65 76 65 6c  le Locking Level
6080: 73 20 7b 48 31 30 32 35 30 7d 20 3c 48 31 31 31  s {H10250} <H111
6090: 32 30 3e 20 3c 48 31 31 33 31 30 3e 0a 2a 2a 0a  20> <H11310>.**.
60a0: 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 6f  ** SQLite uses o
60b0: 6e 65 20 6f 66 20 74 68 65 73 65 20 69 6e 74 65  ne of these inte
60c0: 67 65 72 20 76 61 6c 75 65 73 20 61 73 20 74 68  ger values as th
60d0: 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 61 72 67 75  e second.** argu
60e0: 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 73 20 69 74  ment to calls it
60f0: 20 6d 61 6b 65 73 20 74 6f 20 74 68 65 20 78 4c   makes to the xL
6100: 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63  ock() and xUnloc
6110: 6b 28 29 20 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f  k() methods.** o
6120: 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f  f an [sqlite3_io
6130: 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74  _methods] object
6140: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
6150: 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20 20 20  ITE_LOCK_NONE   
6160: 20 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65         0.#define
6170: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41   SQLITE_LOCK_SHA
6180: 52 45 44 20 20 20 20 20 20 20 20 31 0a 23 64 65  RED        1.#de
6190: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
61a0: 5f 52 45 53 45 52 56 45 44 20 20 20 20 20 20 32  _RESERVED      2
61b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
61c0: 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 20 20 20 20  LOCK_PENDING    
61d0: 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c     3.#define SQL
61e0: 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49  ITE_LOCK_EXCLUSI
61f0: 56 45 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20  VE     4../*.** 
6200: 43 41 50 49 33 52 45 46 3a 20 53 79 6e 63 68 72  CAPI3REF: Synchr
6210: 6f 6e 69 7a 61 74 69 6f 6e 20 54 79 70 65 20 46  onization Type F
6220: 6c 61 67 73 20 7b 48 31 30 32 36 30 7d 20 3c 48  lags {H10260} <H
6230: 31 31 31 32 30 3e 0a 2a 2a 0a 2a 2a 20 57 68 65  11120>.**.** Whe
6240: 6e 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73  n SQLite invokes
6250: 20 74 68 65 20 78 53 79 6e 63 28 29 20 6d 65 74   the xSync() met
6260: 68 6f 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73 71  hod of an.** [sq
6270: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
6280: 5d 20 6f 62 6a 65 63 74 20 69 74 20 75 73 65 73  ] object it uses
6290: 20 61 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f   a combination o
62a0: 66 0a 2a 2a 20 74 68 65 73 65 20 69 6e 74 65 67  f.** these integ
62b0: 65 72 20 76 61 6c 75 65 73 20 61 73 20 74 68 65  er values as the
62c0: 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
62d0: 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65  ..**.** When the
62e0: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54   SQLITE_SYNC_DAT
62f0: 41 4f 4e 4c 59 20 66 6c 61 67 20 69 73 20 75 73  AONLY flag is us
6300: 65 64 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61  ed, it means tha
6310: 74 20 74 68 65 0a 2a 2a 20 73 79 6e 63 20 6f 70  t the.** sync op
6320: 65 72 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65 65  eration only nee
6330: 64 73 20 74 6f 20 66 6c 75 73 68 20 64 61 74 61  ds to flush data
6340: 20 74 6f 20 6d 61 73 73 20 73 74 6f 72 61 67 65   to mass storage
6350: 2e 20 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66 6f  .  Inode.** info
6360: 72 6d 61 74 69 6f 6e 20 6e 65 65 64 20 6e 6f 74  rmation need not
6370: 20 62 65 20 66 6c 75 73 68 65 64 2e 20 54 68 65   be flushed. The
6380: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52   SQLITE_SYNC_NOR
6390: 4d 41 4c 20 66 6c 61 67 20 6d 65 61 6e 73 0a 2a  MAL flag means.*
63a0: 2a 20 74 6f 20 75 73 65 20 6e 6f 72 6d 61 6c 20  * to use normal 
63b0: 66 73 79 6e 63 28 29 20 73 65 6d 61 6e 74 69 63  fsync() semantic
63c0: 73 2e 20 54 68 65 20 53 51 4c 49 54 45 5f 53 59  s. The SQLITE_SY
63d0: 4e 43 5f 46 55 4c 4c 20 66 6c 61 67 20 6d 65 61  NC_FULL flag mea
63e0: 6e 73 0a 2a 2a 20 74 6f 20 75 73 65 20 4d 61 63  ns.** to use Mac
63f0: 20 4f 53 2d 58 20 73 74 79 6c 65 20 66 75 6c 6c   OS-X style full
6400: 73 79 6e 63 20 69 6e 73 74 65 61 64 20 6f 66 20  sync instead of 
6410: 66 73 79 6e 63 28 29 2e 0a 2a 2f 0a 23 64 65 66  fsync()..*/.#def
6420: 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  ine SQLITE_SYNC_
6430: 4e 4f 52 4d 41 4c 20 20 20 20 20 20 20 20 30 78  NORMAL        0x
6440: 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51  00002.#define SQ
6450: 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 20  LITE_SYNC_FULL  
6460: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 33 0a          0x00003.
6470: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
6480: 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 20 20 20  YNC_DATAONLY    
6490: 20 20 30 78 30 30 30 31 30 0a 0a 2f 2a 0a 2a 2a    0x00010../*.**
64a0: 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e   CAPI3REF: OS In
64b0: 74 65 72 66 61 63 65 20 4f 70 65 6e 20 46 69 6c  terface Open Fil
64c0: 65 20 48 61 6e 64 6c 65 20 7b 48 31 31 31 31 30  e Handle {H11110
64d0: 7d 20 3c 53 32 30 31 31 30 3e 0a 2a 2a 0a 2a 2a  } <S20110>.**.**
64e0: 20 41 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c   An [sqlite3_fil
64f0: 65 5d 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73  e] object repres
6500: 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20 66 69 6c  ents an open fil
6510: 65 20 69 6e 20 74 68 65 20 4f 53 0a 2a 2a 20 69  e in the OS.** i
6520: 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72 2e 20  nterface layer. 
6530: 20 49 6e 64 69 76 69 64 75 61 6c 20 4f 53 20 69   Individual OS i
6540: 6e 74 65 72 66 61 63 65 20 69 6d 70 6c 65 6d 65  nterface impleme
6550: 6e 74 61 74 69 6f 6e 73 20 77 69 6c 6c 0a 2a 2a  ntations will.**
6560: 20 77 61 6e 74 20 74 6f 20 73 75 62 63 6c 61 73   want to subclas
6570: 73 20 74 68 69 73 20 6f 62 6a 65 63 74 20 62 79  s this object by
6580: 20 61 70 70 65 6e 64 69 6e 67 20 61 64 64 69 74   appending addit
6590: 69 6f 6e 61 6c 20 66 69 65 6c 64 73 0a 2a 2a 20  ional fields.** 
65a0: 66 6f 72 20 74 68 65 69 72 20 6f 77 6e 20 75 73  for their own us
65b0: 65 2e 20 20 54 68 65 20 70 4d 65 74 68 6f 64 73  e.  The pMethods
65c0: 20 65 6e 74 72 79 20 69 73 20 61 20 70 6f 69 6e   entry is a poin
65d0: 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71  ter to an.** [sq
65e0: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
65f0: 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 20 64 65  ] object that de
6600: 66 69 6e 65 73 20 6d 65 74 68 6f 64 73 20 66 6f  fines methods fo
6610: 72 20 70 65 72 66 6f 72 6d 69 6e 67 0a 2a 2a 20  r performing.** 
6620: 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73 20 6f  I/O operations o
6630: 6e 20 74 68 65 20 6f 70 65 6e 20 66 69 6c 65 2e  n the open file.
6640: 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
6650: 63 74 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20  ct sqlite3_file 
6660: 73 71 6c 69 74 65 33 5f 66 69 6c 65 3b 0a 73 74  sqlite3_file;.st
6670: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 66 69 6c  ruct sqlite3_fil
6680: 65 20 7b 0a 20 20 63 6f 6e 73 74 20 73 74 72 75  e {.  const stru
6690: 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  ct sqlite3_io_me
66a0: 74 68 6f 64 73 20 2a 70 4d 65 74 68 6f 64 73 3b  thods *pMethods;
66b0: 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 66 6f 72    /* Methods for
66c0: 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 2a 2f   an open file */
66d0: 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .};../*.** CAPI3
66e0: 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63  REF: OS Interfac
66f0: 65 20 46 69 6c 65 20 56 69 72 74 75 61 6c 20 4d  e File Virtual M
6700: 65 74 68 6f 64 73 20 4f 62 6a 65 63 74 20 7b 48  ethods Object {H
6710: 31 31 31 32 30 7d 20 3c 53 32 30 31 31 30 3e 0a  11120} <S20110>.
6720: 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 66 69 6c 65  **.** Every file
6730: 20 6f 70 65 6e 65 64 20 62 79 20 74 68 65 20 5b   opened by the [
6740: 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 78 4f 70  sqlite3_vfs] xOp
6750: 65 6e 20 6d 65 74 68 6f 64 20 70 6f 70 75 6c 61  en method popula
6760: 74 65 73 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74  tes an.** [sqlit
6770: 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20  e3_file] object 
6780: 28 6f 72 2c 20 6d 6f 72 65 20 63 6f 6d 6d 6f 6e  (or, more common
6790: 6c 79 2c 20 61 20 73 75 62 63 6c 61 73 73 20 6f  ly, a subclass o
67a0: 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  f the.** [sqlite
67b0: 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 29 20  3_file] object) 
67c0: 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72 20 74  with a pointer t
67d0: 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  o an instance of
67e0: 20 74 68 69 73 20 6f 62 6a 65 63 74 2e 0a 2a 2a   this object..**
67f0: 20 54 68 69 73 20 6f 62 6a 65 63 74 20 64 65 66   This object def
6800: 69 6e 65 73 20 74 68 65 20 6d 65 74 68 6f 64 73  ines the methods
6810: 20 75 73 65 64 20 74 6f 20 70 65 72 66 6f 72 6d   used to perform
6820: 20 76 61 72 69 6f 75 73 20 6f 70 65 72 61 74 69   various operati
6830: 6f 6e 73 0a 2a 2a 20 61 67 61 69 6e 73 74 20 74  ons.** against t
6840: 68 65 20 6f 70 65 6e 20 66 69 6c 65 20 72 65 70  he open file rep
6850: 72 65 73 65 6e 74 65 64 20 62 79 20 74 68 65 20  resented by the 
6860: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f  [sqlite3_file] o
6870: 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  bject..**.** The
6880: 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20   flags argument 
6890: 74 6f 20 78 53 79 6e 63 20 6d 61 79 20 62 65 20  to xSync may be 
68a0: 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 53  one of [SQLITE_S
68b0: 59 4e 43 5f 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a  YNC_NORMAL] or.*
68c0: 2a 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46  * [SQLITE_SYNC_F
68d0: 55 4c 4c 5d 2e 20 20 54 68 65 20 66 69 72 73 74  ULL].  The first
68e0: 20 63 68 6f 69 63 65 20 69 73 20 74 68 65 20 6e   choice is the n
68f0: 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 2e 0a 2a  ormal fsync()..*
6900: 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 63 68 6f  * The second cho
6910: 69 63 65 20 69 73 20 61 20 4d 61 63 20 4f 53 2d  ice is a Mac OS-
6920: 58 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63  X style fullsync
6930: 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 53  .  The [SQLITE_S
6940: 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 5d 0a 2a 2a  YNC_DATAONLY].**
6950: 20 66 6c 61 67 20 6d 61 79 20 62 65 20 4f 52 65   flag may be ORe
6960: 64 20 69 6e 20 74 6f 20 69 6e 64 69 63 61 74 65  d in to indicate
6970: 20 74 68 61 74 20 6f 6e 6c 79 20 74 68 65 20 64   that only the d
6980: 61 74 61 20 6f 66 20 74 68 65 20 66 69 6c 65 0a  ata of the file.
6990: 2a 2a 20 61 6e 64 20 6e 6f 74 20 69 74 73 20 69  ** and not its i
69a0: 6e 6f 64 65 20 6e 65 65 64 73 20 74 6f 20 62 65  node needs to be
69b0: 20 73 79 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a 20 54   synced..**.** T
69c0: 68 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65  he integer value
69d0: 73 20 74 6f 20 78 4c 6f 63 6b 28 29 20 61 6e 64  s to xLock() and
69e0: 20 78 55 6e 6c 6f 63 6b 28 29 20 61 72 65 20 6f   xUnlock() are o
69f0: 6e 65 20 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  ne of.** <ul>.**
6a00: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f   <li> [SQLITE_LO
6a10: 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69  CK_NONE],.** <li
6a20: 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53  > [SQLITE_LOCK_S
6a30: 48 41 52 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20  HARED],.** <li> 
6a40: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53  [SQLITE_LOCK_RES
6a50: 45 52 56 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20  ERVED],.** <li> 
6a60: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e  [SQLITE_LOCK_PEN
6a70: 44 49 4e 47 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69  DING], or.** <li
6a80: 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45  > [SQLITE_LOCK_E
6a90: 58 43 4c 55 53 49 56 45 5d 2e 0a 2a 2a 20 3c 2f  XCLUSIVE]..** </
6aa0: 75 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b 28 29 20 69  ul>.** xLock() i
6ab0: 6e 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63  ncreases the loc
6ac0: 6b 2e 20 78 55 6e 6c 6f 63 6b 28 29 20 64 65 63  k. xUnlock() dec
6ad0: 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e  reases the lock.
6ae0: 0a 2a 2a 20 54 68 65 20 78 43 68 65 63 6b 52 65  .** The xCheckRe
6af0: 73 65 72 76 65 64 4c 6f 63 6b 28 29 20 6d 65 74  servedLock() met
6b00: 68 6f 64 20 63 68 65 63 6b 73 20 77 68 65 74 68  hod checks wheth
6b10: 65 72 20 61 6e 79 20 64 61 74 61 62 61 73 65 20  er any database 
6b20: 63 6f 6e 6e 65 63 74 69 6f 6e 2c 0a 2a 2a 20 65  connection,.** e
6b30: 69 74 68 65 72 20 69 6e 20 74 68 69 73 20 70 72  ither in this pr
6b40: 6f 63 65 73 73 20 6f 72 20 69 6e 20 73 6f 6d 65  ocess or in some
6b50: 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73 2c 20   other process, 
6b60: 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 52 45 53  is holding a RES
6b70: 45 52 56 45 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e  ERVED,.** PENDIN
6b80: 47 2c 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20  G, or EXCLUSIVE 
6b90: 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 66 69 6c 65  lock on the file
6ba0: 2e 20 20 49 74 20 72 65 74 75 72 6e 73 20 74 72  .  It returns tr
6bb0: 75 65 0a 2a 2a 20 69 66 20 73 75 63 68 20 61 20  ue.** if such a 
6bc0: 6c 6f 63 6b 20 65 78 69 73 74 73 20 61 6e 64 20  lock exists and 
6bd0: 66 61 6c 73 65 20 6f 74 68 65 72 77 69 73 65 2e  false otherwise.
6be0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 69 6c 65  .**.** The xFile
6bf0: 43 6f 6e 74 72 6f 6c 28 29 20 6d 65 74 68 6f 64  Control() method
6c00: 20 69 73 20 61 20 67 65 6e 65 72 69 63 20 69 6e   is a generic in
6c10: 74 65 72 66 61 63 65 20 74 68 61 74 20 61 6c 6c  terface that all
6c20: 6f 77 73 20 63 75 73 74 6f 6d 0a 2a 2a 20 56 46  ows custom.** VF
6c30: 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  S implementation
6c40: 73 20 74 6f 20 64 69 72 65 63 74 6c 79 20 63 6f  s to directly co
6c50: 6e 74 72 6f 6c 20 61 6e 20 6f 70 65 6e 20 66 69  ntrol an open fi
6c60: 6c 65 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20  le using the.** 
6c70: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f  [sqlite3_file_co
6c80: 6e 74 72 6f 6c 28 29 5d 20 69 6e 74 65 72 66 61  ntrol()] interfa
6c90: 63 65 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20  ce.  The second 
6ca0: 22 6f 70 22 20 61 72 67 75 6d 65 6e 74 20 69 73  "op" argument is
6cb0: 20 61 6e 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6f   an.** integer o
6cc0: 70 63 6f 64 65 2e 20 20 54 68 65 20 74 68 69 72  pcode.  The thir
6cd0: 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20  d argument is a 
6ce0: 67 65 6e 65 72 69 63 20 70 6f 69 6e 74 65 72 20  generic pointer 
6cf0: 69 6e 74 65 6e 64 65 64 20 74 6f 0a 2a 2a 20 70  intended to.** p
6d00: 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 75 63 74  oint to a struct
6d10: 75 72 65 20 74 68 61 74 20 6d 61 79 20 63 6f 6e  ure that may con
6d20: 74 61 69 6e 20 61 72 67 75 6d 65 6e 74 73 20 6f  tain arguments o
6d30: 72 20 73 70 61 63 65 20 69 6e 20 77 68 69 63 68  r space in which
6d40: 20 74 6f 0a 2a 2a 20 77 72 69 74 65 20 72 65 74   to.** write ret
6d50: 75 72 6e 20 76 61 6c 75 65 73 2e 20 20 50 6f 74  urn values.  Pot
6d60: 65 6e 74 69 61 6c 20 75 73 65 73 20 66 6f 72 20  ential uses for 
6d70: 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d  xFileControl() m
6d80: 69 67 68 74 20 62 65 0a 2a 2a 20 66 75 6e 63 74  ight be.** funct
6d90: 69 6f 6e 73 20 74 6f 20 65 6e 61 62 6c 65 20 62  ions to enable b
6da0: 6c 6f 63 6b 69 6e 67 20 6c 6f 63 6b 73 20 77 69  locking locks wi
6db0: 74 68 20 74 69 6d 65 6f 75 74 73 2c 20 74 6f 20  th timeouts, to 
6dc0: 63 68 61 6e 67 65 20 74 68 65 0a 2a 2a 20 6c 6f  change the.** lo
6dd0: 63 6b 69 6e 67 20 73 74 72 61 74 65 67 79 20 28  cking strategy (
6de0: 66 6f 72 20 65 78 61 6d 70 6c 65 20 74 6f 20 75  for example to u
6df0: 73 65 20 64 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b  se dot-file lock
6e00: 73 29 2c 20 74 6f 20 69 6e 71 75 69 72 65 0a 2a  s), to inquire.*
6e10: 2a 20 61 62 6f 75 74 20 74 68 65 20 73 74 61 74  * about the stat
6e20: 75 73 20 6f 66 20 61 20 6c 6f 63 6b 2c 20 6f 72  us of a lock, or
6e30: 20 74 6f 20 62 72 65 61 6b 20 73 74 61 6c 65 20   to break stale 
6e40: 6c 6f 63 6b 73 2e 20 20 54 68 65 20 53 51 4c 69  locks.  The SQLi
6e50: 74 65 0a 2a 2a 20 63 6f 72 65 20 72 65 73 65 72  te.** core reser
6e60: 76 65 73 20 61 6c 6c 20 6f 70 63 6f 64 65 73 20  ves all opcodes 
6e70: 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20 66 6f  less than 100 fo
6e80: 72 20 69 74 73 20 6f 77 6e 20 75 73 65 2e 0a 2a  r its own use..*
6e90: 2a 20 41 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  * A [SQLITE_FCNT
6ea0: 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 7c 20 6c 69  L_LOCKSTATE | li
6eb0: 73 74 20 6f 66 20 6f 70 63 6f 64 65 73 5d 20 6c  st of opcodes] l
6ec0: 65 73 73 20 74 68 61 6e 20 31 30 30 20 69 73 20  ess than 100 is 
6ed0: 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 41 70  available..** Ap
6ee0: 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20  plications that 
6ef0: 64 65 66 69 6e 65 20 61 20 63 75 73 74 6f 6d 20  define a custom 
6f00: 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74  xFileControl met
6f10: 68 6f 64 20 73 68 6f 75 6c 64 20 75 73 65 20 6f  hod should use o
6f20: 70 63 6f 64 65 73 0a 2a 2a 20 67 72 65 61 74 65  pcodes.** greate
6f30: 72 20 74 68 61 6e 20 31 30 30 20 74 6f 20 61 76  r than 100 to av
6f40: 6f 69 64 20 63 6f 6e 66 6c 69 63 74 73 2e 0a 2a  oid conflicts..*
6f50: 2a 0a 2a 2a 20 54 68 65 20 78 53 65 63 74 6f 72  *.** The xSector
6f60: 53 69 7a 65 28 29 20 6d 65 74 68 6f 64 20 72 65  Size() method re
6f70: 74 75 72 6e 73 20 74 68 65 20 73 65 63 74 6f 72  turns the sector
6f80: 20 73 69 7a 65 20 6f 66 20 74 68 65 0a 2a 2a 20   size of the.** 
6f90: 64 65 76 69 63 65 20 74 68 61 74 20 75 6e 64 65  device that unde
6fa0: 72 6c 69 65 73 20 74 68 65 20 66 69 6c 65 2e 20  rlies the file. 
6fb0: 20 54 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65   The sector size
6fc0: 20 69 73 20 74 68 65 0a 2a 2a 20 6d 69 6e 69 6d   is the.** minim
6fd0: 75 6d 20 77 72 69 74 65 20 74 68 61 74 20 63 61  um write that ca
6fe0: 6e 20 62 65 20 70 65 72 66 6f 72 6d 65 64 20 77  n be performed w
6ff0: 69 74 68 6f 75 74 20 64 69 73 74 75 72 62 69 6e  ithout disturbin
7000: 67 0a 2a 2a 20 6f 74 68 65 72 20 62 79 74 65 73  g.** other bytes
7010: 20 69 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 54   in the file.  T
7020: 68 65 20 78 44 65 76 69 63 65 43 68 61 72 61 63  he xDeviceCharac
7030: 74 65 72 69 73 74 69 63 73 28 29 0a 2a 2a 20 6d  teristics().** m
7040: 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20  ethod returns a 
7050: 62 69 74 20 76 65 63 74 6f 72 20 64 65 73 63 72  bit vector descr
7060: 69 62 69 6e 67 20 62 65 68 61 76 69 6f 72 73 20  ibing behaviors 
7070: 6f 66 20 74 68 65 0a 2a 2a 20 75 6e 64 65 72 6c  of the.** underl
7080: 79 69 6e 67 20 64 65 76 69 63 65 3a 0a 2a 2a 0a  ying device:.**.
7090: 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
70a0: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
70b0: 4f 4d 49 43 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  OMIC].** <li> [S
70c0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
70d0: 49 43 35 31 32 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  IC512].** <li> [
70e0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
70f0: 4d 49 43 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  MIC1K].** <li> [
7100: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
7110: 4d 49 43 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  MIC2K].** <li> [
7120: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
7130: 4d 49 43 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  MIC4K].** <li> [
7140: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
7150: 4d 49 43 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  MIC8K].** <li> [
7160: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
7170: 4d 49 43 31 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20  MIC16K].** <li> 
7180: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
7190: 4f 4d 49 43 33 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e  OMIC32K].** <li>
71a0: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
71b0: 54 4f 4d 49 43 36 34 4b 5d 0a 2a 2a 20 3c 6c 69  TOMIC64K].** <li
71c0: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
71d0: 53 41 46 45 5f 41 50 50 45 4e 44 5d 0a 2a 2a 20  SAFE_APPEND].** 
71e0: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
71f0: 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 5d 0a 2a  AP_SEQUENTIAL].*
7200: 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68  * </ul>.**.** Th
7210: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
7220: 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d  TOMIC property m
7230: 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72  eans that all wr
7240: 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73  ites of.** any s
7250: 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20  ize are atomic. 
7260: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
7270: 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75  P_ATOMICnnn valu
7280: 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20  es.** mean that 
7290: 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73  writes of blocks
72a0: 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79   that are nnn by
72b0: 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a  tes in size and.
72c0: 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74  ** are aligned t
72d0: 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77 68 69  o an address whi
72e0: 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  ch is an integer
72f0: 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20   multiple of.** 
7300: 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20  nnn are atomic. 
7310: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
7320: 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61  P_SAFE_APPEND va
7330: 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61  lue means.** tha
7340: 74 20 77 68 65 6e 20 64 61 74 61 20 69 73 20 61  t when data is a
7350: 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c  ppended to a fil
7360: 65 2c 20 74 68 65 20 64 61 74 61 20 69 73 20 61  e, the data is a
7370: 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74  ppended.** first
7380: 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f   then the size o
7390: 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 65 78  f the file is ex
73a0: 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68  tended, never th
73b0: 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61  e other.** way a
73c0: 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49  round.  The SQLI
73d0: 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54  TE_IOCAP_SEQUENT
73e0: 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61  IAL property mea
73f0: 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72  ns that.** infor
7400: 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65  mation is writte
7410: 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65  n to disk in the
7420: 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63   same order as c
7430: 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74  alls.** to xWrit
7440: 65 28 29 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  e()..*/.typedef 
7450: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69  struct sqlite3_i
7460: 6f 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65  o_methods sqlite
7470: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 3b 0a 73 74  3_io_methods;.st
7480: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f  ruct sqlite3_io_
7490: 6d 65 74 68 6f 64 73 20 7b 0a 20 20 69 6e 74 20  methods {.  int 
74a0: 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69 6e 74 20  iVersion;.  int 
74b0: 28 2a 78 43 6c 6f 73 65 29 28 73 71 6c 69 74 65  (*xClose)(sqlite
74c0: 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20  3_file*);.  int 
74d0: 28 2a 78 52 65 61 64 29 28 73 71 6c 69 74 65 33  (*xRead)(sqlite3
74e0: 5f 66 69 6c 65 2a 2c 20 76 6f 69 64 2a 2c 20 69  _file*, void*, i
74f0: 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 33  nt iAmt, sqlite3
7500: 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 20  _int64 iOfst);. 
7510: 20 69 6e 74 20 28 2a 78 57 72 69 74 65 29 28 73   int (*xWrite)(s
7520: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 63 6f  qlite3_file*, co
7530: 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69  nst void*, int i
7540: 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  Amt, sqlite3_int
7550: 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74  64 iOfst);.  int
7560: 20 28 2a 78 54 72 75 6e 63 61 74 65 29 28 73 71   (*xTruncate)(sq
7570: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c  lite3_file*, sql
7580: 69 74 65 33 5f 69 6e 74 36 34 20 73 69 7a 65 29  ite3_int64 size)
7590: 3b 0a 20 20 69 6e 74 20 28 2a 78 53 79 6e 63 29  ;.  int (*xSync)
75a0: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
75b0: 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20 69 6e  int flags);.  in
75c0: 74 20 28 2a 78 46 69 6c 65 53 69 7a 65 29 28 73  t (*xFileSize)(s
75d0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71  qlite3_file*, sq
75e0: 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 70 53 69  lite3_int64 *pSi
75f0: 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4c 6f  ze);.  int (*xLo
7600: 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ck)(sqlite3_file
7610: 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28  *, int);.  int (
7620: 2a 78 55 6e 6c 6f 63 6b 29 28 73 71 6c 69 74 65  *xUnlock)(sqlite
7630: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20  3_file*, int);. 
7640: 20 69 6e 74 20 28 2a 78 43 68 65 63 6b 52 65 73   int (*xCheckRes
7650: 65 72 76 65 64 4c 6f 63 6b 29 28 73 71 6c 69 74  ervedLock)(sqlit
7660: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 2a 70  e3_file*, int *p
7670: 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28  ResOut);.  int (
7680: 2a 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 29 28 73  *xFileControl)(s
7690: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e  qlite3_file*, in
76a0: 74 20 6f 70 2c 20 76 6f 69 64 20 2a 70 41 72 67  t op, void *pArg
76b0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 65 63 74  );.  int (*xSect
76c0: 6f 72 53 69 7a 65 29 28 73 71 6c 69 74 65 33 5f  orSize)(sqlite3_
76d0: 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  file*);.  int (*
76e0: 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65 72  xDeviceCharacter
76f0: 69 73 74 69 63 73 29 28 73 71 6c 69 74 65 33 5f  istics)(sqlite3_
7700: 66 69 6c 65 2a 29 3b 0a 20 20 2f 2a 20 41 64 64  file*);.  /* Add
7710: 69 74 69 6f 6e 61 6c 20 6d 65 74 68 6f 64 73 20  itional methods 
7720: 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20  may be added in 
7730: 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20  future releases 
7740: 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.};../*.** CAP
7750: 49 33 52 45 46 3a 20 53 74 61 6e 64 61 72 64 20  I3REF: Standard 
7760: 46 69 6c 65 20 43 6f 6e 74 72 6f 6c 20 4f 70 63  File Control Opc
7770: 6f 64 65 73 20 7b 48 31 31 33 31 30 7d 20 3c 53  odes {H11310} <S
7780: 33 30 38 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  30800>.**.** The
7790: 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74  se integer const
77a0: 61 6e 74 73 20 61 72 65 20 6f 70 63 6f 64 65 73  ants are opcodes
77b0: 20 66 6f 72 20 74 68 65 20 78 46 69 6c 65 43 6f   for the xFileCo
77c0: 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 0a 2a 2a 20  ntrol method.** 
77d0: 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
77e0: 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65  io_methods] obje
77f0: 63 74 20 61 6e 64 20 66 6f 72 20 74 68 65 20 5b  ct and for the [
7800: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
7810: 74 72 6f 6c 28 29 5d 0a 2a 2a 20 69 6e 74 65 72  trol()].** inter
7820: 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  face..**.** The 
7830: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f  [SQLITE_FCNTL_LO
7840: 43 4b 53 54 41 54 45 5d 20 6f 70 63 6f 64 65 20  CKSTATE] opcode 
7850: 69 73 20 75 73 65 64 20 66 6f 72 20 64 65 62 75  is used for debu
7860: 67 67 69 6e 67 2e 20 20 54 68 69 73 0a 2a 2a 20  gging.  This.** 
7870: 6f 70 63 6f 64 65 20 63 61 75 73 65 73 20 74 68  opcode causes th
7880: 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d  e xFileControl m
7890: 65 74 68 6f 64 20 74 6f 20 77 72 69 74 65 20 74  ethod to write t
78a0: 68 65 20 63 75 72 72 65 6e 74 20 73 74 61 74 65  he current state
78b0: 20 6f 66 0a 2a 2a 20 74 68 65 20 6c 6f 63 6b 20   of.** the lock 
78c0: 28 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f  (one of [SQLITE_
78d0: 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b 53 51 4c  LOCK_NONE], [SQL
78e0: 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 5d  ITE_LOCK_SHARED]
78f0: 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  ,.** [SQLITE_LOC
7900: 4b 5f 52 45 53 45 52 56 45 44 5d 2c 20 5b 53 51  K_RESERVED], [SQ
7910: 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e  LITE_LOCK_PENDIN
7920: 47 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4c  G], or [SQLITE_L
7930: 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d 29 0a  OCK_EXCLUSIVE]).
7940: 2a 2a 20 69 6e 74 6f 20 61 6e 20 69 6e 74 65 67  ** into an integ
7950: 65 72 20 74 68 61 74 20 74 68 65 20 70 41 72 67  er that the pArg
7960: 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 73   argument points
7970: 20 74 6f 2e 20 54 68 69 73 20 63 61 70 61 62 69   to. This capabi
7980: 6c 69 74 79 0a 2a 2a 20 69 73 20 75 73 65 64 20  lity.** is used 
7990: 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67 20 61  during testing a
79a0: 6e 64 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f  nd only needs to
79b0: 20 62 65 20 73 75 70 70 6f 72 74 65 64 20 77 68   be supported wh
79c0: 65 6e 20 53 51 4c 49 54 45 5f 54 45 53 54 0a 2a  en SQLITE_TEST.*
79d0: 2a 20 69 73 20 64 65 66 69 6e 65 64 2e 0a 2a 2f  * is defined..*/
79e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
79f0: 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20  FCNTL_LOCKSTATE 
7a00: 20 20 20 20 20 20 20 31 0a 0a 2f 2a 0a 2a 2a 20         1../*.** 
7a10: 43 41 50 49 33 52 45 46 3a 20 4d 75 74 65 78 20  CAPI3REF: Mutex 
7a20: 48 61 6e 64 6c 65 20 7b 48 31 37 31 31 30 7d 20  Handle {H17110} 
7a30: 3c 53 32 30 31 33 30 3e 0a 2a 2a 0a 2a 2a 20 54  <S20130>.**.** T
7a40: 68 65 20 6d 75 74 65 78 20 6d 6f 64 75 6c 65 20  he mutex module 
7a50: 77 69 74 68 69 6e 20 53 51 4c 69 74 65 20 64 65  within SQLite de
7a60: 66 69 6e 65 73 20 5b 73 71 6c 69 74 65 33 5f 6d  fines [sqlite3_m
7a70: 75 74 65 78 5d 20 74 6f 20 62 65 20 61 6e 0a 2a  utex] to be an.*
7a80: 2a 20 61 62 73 74 72 61 63 74 20 74 79 70 65 20  * abstract type 
7a90: 66 6f 72 20 61 20 6d 75 74 65 78 20 6f 62 6a 65  for a mutex obje
7aa0: 63 74 2e 20 20 54 68 65 20 53 51 4c 69 74 65 20  ct.  The SQLite 
7ab0: 63 6f 72 65 20 6e 65 76 65 72 20 6c 6f 6f 6b 73  core never looks
7ac0: 0a 2a 2a 20 61 74 20 74 68 65 20 69 6e 74 65 72  .** at the inter
7ad0: 6e 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69  nal representati
7ae0: 6f 6e 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65  on of an [sqlite
7af0: 33 5f 6d 75 74 65 78 5d 2e 20 20 49 74 20 6f 6e  3_mutex].  It on
7b00: 6c 79 0a 2a 2a 20 64 65 61 6c 73 20 77 69 74 68  ly.** deals with
7b10: 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 74 68 65   pointers to the
7b20: 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d   [sqlite3_mutex]
7b30: 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d   object..**.** M
7b40: 75 74 65 78 65 73 20 61 72 65 20 63 72 65 61 74  utexes are creat
7b50: 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ed using [sqlite
7b60: 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 5d  3_mutex_alloc()]
7b70: 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
7b80: 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 65  uct sqlite3_mute
7b90: 78 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 3b  x sqlite3_mutex;
7ba0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
7bb0: 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 4f  : OS Interface O
7bc0: 62 6a 65 63 74 20 7b 48 31 31 31 34 30 7d 20 3c  bject {H11140} <
7bd0: 53 32 30 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 41 6e  S20100>.**.** An
7be0: 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65   instance of the
7bf0: 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a   sqlite3_vfs obj
7c00: 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20  ect defines the 
7c10: 69 6e 74 65 72 66 61 63 65 20 62 65 74 77 65 65  interface betwee
7c20: 6e 0a 2a 2a 20 74 68 65 20 53 51 4c 69 74 65 20  n.** the SQLite 
7c30: 63 6f 72 65 20 61 6e 64 20 74 68 65 20 75 6e 64  core and the und
7c40: 65 72 6c 79 69 6e 67 20 6f 70 65 72 61 74 69 6e  erlying operatin
7c50: 67 20 73 79 73 74 65 6d 2e 20 20 54 68 65 20 22  g system.  The "
7c60: 76 66 73 22 0a 2a 2a 20 69 6e 20 74 68 65 20 6e  vfs".** in the n
7c70: 61 6d 65 20 6f 66 20 74 68 65 20 6f 62 6a 65 63  ame of the objec
7c80: 74 20 73 74 61 6e 64 73 20 66 6f 72 20 22 76 69  t stands for "vi
7c90: 72 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65  rtual file syste
7ca0: 6d 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 76 61  m"..**.** The va
7cb0: 6c 75 65 20 6f 66 20 74 68 65 20 69 56 65 72 73  lue of the iVers
7cc0: 69 6f 6e 20 66 69 65 6c 64 20 69 73 20 69 6e 69  ion field is ini
7cd0: 74 69 61 6c 6c 79 20 31 20 62 75 74 20 6d 61 79  tially 1 but may
7ce0: 20 62 65 20 6c 61 72 67 65 72 20 69 6e 0a 2a 2a   be larger in.**
7cf0: 20 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73   future versions
7d00: 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 41 64 64   of SQLite.  Add
7d10: 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20 6d  itional fields m
7d20: 61 79 20 62 65 20 61 70 70 65 6e 64 65 64 20 74  ay be appended t
7d30: 6f 20 74 68 69 73 0a 2a 2a 20 6f 62 6a 65 63 74  o this.** object
7d40: 20 77 68 65 6e 20 74 68 65 20 69 56 65 72 73 69   when the iVersi
7d50: 6f 6e 20 76 61 6c 75 65 20 69 73 20 69 6e 63 72  on value is incr
7d60: 65 61 73 65 64 2e 20 20 4e 6f 74 65 20 74 68 61  eased.  Note tha
7d70: 74 20 74 68 65 20 73 74 72 75 63 74 75 72 65 0a  t the structure.
7d80: 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65  ** of the sqlite
7d90: 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 63 68 61  3_vfs object cha
7da0: 6e 67 65 73 20 69 6e 20 74 68 65 20 74 72 61 6e  nges in the tran
7db0: 73 61 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 0a  saction between.
7dc0: 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  ** SQLite versio
7dd0: 6e 20 33 2e 35 2e 39 20 61 6e 64 20 33 2e 36 2e  n 3.5.9 and 3.6.
7de0: 30 20 61 6e 64 20 79 65 74 20 74 68 65 20 69 56  0 and yet the iV
7df0: 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 77 61 73  ersion field was
7e00: 20 6e 6f 74 0a 2a 2a 20 6d 6f 64 69 66 69 65 64   not.** modified
7e10: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 7a 4f 73  ..**.** The szOs
7e20: 46 69 6c 65 20 66 69 65 6c 64 20 69 73 20 74 68  File field is th
7e30: 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 73 75  e size of the su
7e40: 62 63 6c 61 73 73 65 64 20 5b 73 71 6c 69 74 65  bclassed [sqlite
7e50: 33 5f 66 69 6c 65 5d 0a 2a 2a 20 73 74 72 75 63  3_file].** struc
7e60: 74 75 72 65 20 75 73 65 64 20 62 79 20 74 68 69  ture used by thi
7e70: 73 20 56 46 53 2e 20 20 6d 78 50 61 74 68 6e 61  s VFS.  mxPathna
7e80: 6d 65 20 69 73 20 74 68 65 20 6d 61 78 69 6d 75  me is the maximu
7e90: 6d 20 6c 65 6e 67 74 68 20 6f 66 0a 2a 2a 20 61  m length of.** a
7ea0: 20 70 61 74 68 6e 61 6d 65 20 69 6e 20 74 68 69   pathname in thi
7eb0: 73 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 52 65 67  s VFS..**.** Reg
7ec0: 69 73 74 65 72 65 64 20 73 71 6c 69 74 65 33 5f  istered sqlite3_
7ed0: 76 66 73 20 6f 62 6a 65 63 74 73 20 61 72 65 20  vfs objects are 
7ee0: 6b 65 70 74 20 6f 6e 20 61 20 6c 69 6e 6b 65 64  kept on a linked
7ef0: 20 6c 69 73 74 20 66 6f 72 6d 65 64 20 62 79 0a   list formed by.
7f00: 2a 2a 20 74 68 65 20 70 4e 65 78 74 20 70 6f 69  ** the pNext poi
7f10: 6e 74 65 72 2e 20 20 54 68 65 20 5b 73 71 6c 69  nter.  The [sqli
7f20: 74 65 33 5f 76 66 73 5f 72 65 67 69 73 74 65 72  te3_vfs_register
7f30: 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69  ()].** and [sqli
7f40: 74 65 33 5f 76 66 73 5f 75 6e 72 65 67 69 73 74  te3_vfs_unregist
7f50: 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73  er()] interfaces
7f60: 20 6d 61 6e 61 67 65 20 74 68 69 73 20 6c 69 73   manage this lis
7f70: 74 0a 2a 2a 20 69 6e 20 61 20 74 68 72 65 61 64  t.** in a thread
7f80: 2d 73 61 66 65 20 77 61 79 2e 20 20 54 68 65 20  -safe way.  The 
7f90: 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 66 69 6e  [sqlite3_vfs_fin
7fa0: 64 28 29 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a  d()] interface.*
7fb0: 2a 20 73 65 61 72 63 68 65 73 20 74 68 65 20 6c  * searches the l
7fc0: 69 73 74 2e 20 20 4e 65 69 74 68 65 72 20 74 68  ist.  Neither th
7fd0: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f  e application co
7fe0: 64 65 20 6e 6f 72 20 74 68 65 20 56 46 53 0a 2a  de nor the VFS.*
7ff0: 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
8000: 20 73 68 6f 75 6c 64 20 75 73 65 20 74 68 65 20   should use the 
8010: 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e 0a 2a  pNext pointer..*
8020: 2a 0a 2a 2a 20 54 68 65 20 70 4e 65 78 74 20 66  *.** The pNext f
8030: 69 65 6c 64 20 69 73 20 74 68 65 20 6f 6e 6c 79  ield is the only
8040: 20 66 69 65 6c 64 20 69 6e 20 74 68 65 20 73 71   field in the sq
8050: 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20 73 74 72  lite3_vfs.** str
8060: 75 63 74 75 72 65 20 74 68 61 74 20 53 51 4c 69  ucture that SQLi
8070: 74 65 20 77 69 6c 6c 20 65 76 65 72 20 6d 6f 64  te will ever mod
8080: 69 66 79 2e 20 20 53 51 4c 69 74 65 20 77 69 6c  ify.  SQLite wil
8090: 6c 20 6f 6e 6c 79 20 61 63 63 65 73 73 0a 2a 2a  l only access.**
80a0: 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20   or modify this 
80b0: 66 69 65 6c 64 20 77 68 69 6c 65 20 68 6f 6c 64  field while hold
80c0: 69 6e 67 20 61 20 70 61 72 74 69 63 75 6c 61 72  ing a particular
80d0: 20 73 74 61 74 69 63 20 6d 75 74 65 78 2e 0a 2a   static mutex..*
80e0: 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
80f0: 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 20 6d  n should never m
8100: 6f 64 69 66 79 20 61 6e 79 74 68 69 6e 67 20 77  odify anything w
8110: 69 74 68 69 6e 20 74 68 65 20 73 71 6c 69 74 65  ithin the sqlite
8120: 33 5f 76 66 73 0a 2a 2a 20 6f 62 6a 65 63 74 20  3_vfs.** object 
8130: 6f 6e 63 65 20 74 68 65 20 6f 62 6a 65 63 74 20  once the object 
8140: 68 61 73 20 62 65 65 6e 20 72 65 67 69 73 74 65  has been registe
8150: 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 7a  red..**.** The z
8160: 4e 61 6d 65 20 66 69 65 6c 64 20 68 6f 6c 64 73  Name field holds
8170: 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
8180: 20 56 46 53 20 6d 6f 64 75 6c 65 2e 20 20 54 68   VFS module.  Th
8190: 65 20 6e 61 6d 65 20 6d 75 73 74 0a 2a 2a 20 62  e name must.** b
81a0: 65 20 75 6e 69 71 75 65 20 61 63 72 6f 73 73 20  e unique across 
81b0: 61 6c 6c 20 56 46 53 20 6d 6f 64 75 6c 65 73 2e  all VFS modules.
81c0: 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 31 34 31 7d 20  .**.** {H11141} 
81d0: 53 51 4c 69 74 65 20 77 69 6c 6c 20 67 75 61 72  SQLite will guar
81e0: 61 6e 74 65 65 20 74 68 61 74 20 74 68 65 20 7a  antee that the z
81f0: 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74  Filename paramet
8200: 65 72 20 74 6f 20 78 4f 70 65 6e 0a 2a 2a 20 69  er to xOpen.** i
8210: 73 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 20  s either a NULL 
8220: 70 6f 69 6e 74 65 72 20 6f 72 20 73 74 72 69 6e  pointer or strin
8230: 67 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72  g obtained.** fr
8240: 6f 6d 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65  om xFullPathname
8250: 28 29 2e 20 20 53 51 4c 69 74 65 20 66 75 72 74  ().  SQLite furt
8260: 68 65 72 20 67 75 61 72 61 6e 74 65 65 73 20 74  her guarantees t
8270: 68 61 74 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e  hat.** the strin
8280: 67 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 64 20  g will be valid 
8290: 61 6e 64 20 75 6e 63 68 61 6e 67 65 64 20 75 6e  and unchanged un
82a0: 74 69 6c 20 78 43 6c 6f 73 65 28 29 20 69 73 0a  til xClose() is.
82b0: 2a 2a 20 63 61 6c 6c 65 64 2e 20 7b 45 4e 44 7d  ** called. {END}
82c0: 20 20 42 65 63 61 75 73 65 20 6f 66 20 74 68 65    Because of the
82d0: 20 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e   previous senten
82e0: 73 65 2c 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69  se,.** the [sqli
82f0: 74 65 33 5f 66 69 6c 65 5d 20 63 61 6e 20 73 61  te3_file] can sa
8300: 66 65 6c 79 20 73 74 6f 72 65 20 61 20 70 6f 69  fely store a poi
8310: 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 66  nter to the.** f
8320: 69 6c 65 6e 61 6d 65 20 69 66 20 69 74 20 6e 65  ilename if it ne
8330: 65 64 73 20 74 6f 20 72 65 6d 65 6d 62 65 72 20  eds to remember 
8340: 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 66 6f 72  the filename for
8350: 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2e 0a 2a 2a   some reason..**
8360: 20 49 66 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d   If the zFilenam
8370: 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 78  e parameter is x
8380: 4f 70 65 6e 20 69 73 20 61 20 4e 55 4c 4c 20 70  Open is a NULL p
8390: 6f 69 6e 74 65 72 20 74 68 65 6e 20 78 4f 70 65  ointer then xOpe
83a0: 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e 76 69 74 65  n.** must invite
83b0: 20 69 74 73 20 6f 77 6e 20 74 65 6d 70 6f 72 61   its own tempora
83c0: 72 79 20 6e 61 6d 65 20 66 6f 72 20 74 68 65 20  ry name for the 
83d0: 66 69 6c 65 2e 20 20 57 68 65 6e 65 76 65 72 20  file.  Whenever 
83e0: 74 68 65 20 0a 2a 2a 20 78 46 69 6c 65 6e 61 6d  the .** xFilenam
83f0: 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 4e  e parameter is N
8400: 55 4c 4c 20 69 74 20 77 69 6c 6c 20 61 6c 73 6f  ULL it will also
8410: 20 62 65 20 74 68 65 20 63 61 73 65 20 74 68 61   be the case tha
8420: 74 20 74 68 65 0a 2a 2a 20 66 6c 61 67 73 20 70  t the.** flags p
8430: 61 72 61 6d 65 74 65 72 20 77 69 6c 6c 20 69 6e  arameter will in
8440: 63 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50  clude [SQLITE_OP
8450: 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45  EN_DELETEONCLOSE
8460: 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 31 34 32  ]..**.** {H11142
8470: 7d 20 54 68 65 20 66 6c 61 67 73 20 61 72 67 75  } The flags argu
8480: 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 28 29 20  ment to xOpen() 
8490: 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20 62 69 74  includes all bit
84a0: 73 20 73 65 74 20 69 6e 0a 2a 2a 20 74 68 65 20  s set in.** the 
84b0: 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74  flags argument t
84c0: 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  o [sqlite3_open_
84d0: 76 32 28 29 5d 2e 20 20 4f 72 20 69 66 20 5b 73  v2()].  Or if [s
84e0: 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a  qlite3_open()].*
84f0: 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70  * or [sqlite3_op
8500: 65 6e 31 36 28 29 5d 20 69 73 20 75 73 65 64 2c  en16()] is used,
8510: 20 74 68 65 6e 20 66 6c 61 67 73 20 69 6e 63 6c   then flags incl
8520: 75 64 65 73 20 61 74 20 6c 65 61 73 74 0a 2a 2a  udes at least.**
8530: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45   [SQLITE_OPEN_RE
8540: 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49  ADWRITE] | [SQLI
8550: 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 2e  TE_OPEN_CREATE].
8560: 20 7b 45 4e 44 7d 0a 2a 2a 20 49 66 20 78 4f 70   {END}.** If xOp
8570: 65 6e 28 29 20 6f 70 65 6e 73 20 61 20 66 69 6c  en() opens a fil
8580: 65 20 72 65 61 64 2d 6f 6e 6c 79 20 74 68 65 6e  e read-only then
8590: 20 69 74 20 73 65 74 73 20 2a 70 4f 75 74 46 6c   it sets *pOutFl
85a0: 61 67 73 20 74 6f 0a 2a 2a 20 69 6e 63 6c 75 64  ags to.** includ
85b0: 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  e [SQLITE_OPEN_R
85c0: 45 41 44 4f 4e 4c 59 5d 2e 20 20 4f 74 68 65 72  EADONLY].  Other
85d0: 20 62 69 74 73 20 69 6e 20 2a 70 4f 75 74 46 6c   bits in *pOutFl
85e0: 61 67 73 20 6d 61 79 20 62 65 20 73 65 74 2e 0a  ags may be set..
85f0: 2a 2a 0a 2a 2a 20 7b 48 31 31 31 34 33 7d 20 53  **.** {H11143} S
8600: 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 73 6f 20  QLite will also 
8610: 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 66  add one of the f
8620: 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20 74  ollowing flags t
8630: 6f 20 74 68 65 20 78 4f 70 65 6e 28 29 0a 2a 2a  o the xOpen().**
8640: 20 63 61 6c 6c 2c 20 64 65 70 65 6e 64 69 6e 67   call, depending
8650: 20 6f 6e 20 74 68 65 20 6f 62 6a 65 63 74 20 62   on the object b
8660: 65 69 6e 67 20 6f 70 65 6e 65 64 3a 0a 2a 2a 0a  eing opened:.**.
8670: 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
8680: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41   [SQLITE_OPEN_MA
8690: 49 4e 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20  IN_DB].** <li>  
86a0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49  [SQLITE_OPEN_MAI
86b0: 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c  N_JOURNAL].** <l
86c0: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
86d0: 5f 54 45 4d 50 5f 44 42 5d 0a 2a 2a 20 3c 6c 69  _TEMP_DB].** <li
86e0: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
86f0: 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a  TEMP_JOURNAL].**
8700: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
8710: 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42  PEN_TRANSIENT_DB
8720: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  ].** <li>  [SQLI
8730: 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e  TE_OPEN_SUBJOURN
8740: 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  AL].** <li>  [SQ
8750: 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52  LITE_OPEN_MASTER
8760: 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 2f 75  _JOURNAL].** </u
8770: 6c 3e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54  l> {END}.**.** T
8780: 68 65 20 66 69 6c 65 20 49 2f 4f 20 69 6d 70 6c  he file I/O impl
8790: 65 6d 65 6e 74 61 74 69 6f 6e 20 63 61 6e 20 75  ementation can u
87a0: 73 65 20 74 68 65 20 6f 62 6a 65 63 74 20 74 79  se the object ty
87b0: 70 65 20 66 6c 61 67 73 20 74 6f 0a 2a 2a 20 63  pe flags to.** c
87c0: 68 61 6e 67 65 20 74 68 65 20 77 61 79 20 69 74  hange the way it
87d0: 20 64 65 61 6c 73 20 77 69 74 68 20 66 69 6c 65   deals with file
87e0: 73 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c  s.  For example,
87f0: 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a   an application.
8800: 2a 2a 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74  ** that does not
8810: 20 63 61 72 65 20 61 62 6f 75 74 20 63 72 61 73   care about cras
8820: 68 20 72 65 63 6f 76 65 72 79 20 6f 72 20 72 6f  h recovery or ro
8830: 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 6d 61 6b  llback might mak
8840: 65 0a 2a 2a 20 74 68 65 20 6f 70 65 6e 20 6f 66  e.** the open of
8850: 20 61 20 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20   a journal file 
8860: 61 20 6e 6f 2d 6f 70 2e 20 20 57 72 69 74 65 73  a no-op.  Writes
8870: 20 74 6f 20 74 68 69 73 20 6a 6f 75 72 6e 61 6c   to this journal
8880: 20 77 6f 75 6c 64 0a 2a 2a 20 61 6c 73 6f 20 62   would.** also b
8890: 65 20 6e 6f 2d 6f 70 73 2c 20 61 6e 64 20 61 6e  e no-ops, and an
88a0: 79 20 61 74 74 65 6d 70 74 20 74 6f 20 72 65 61  y attempt to rea
88b0: 64 20 74 68 65 20 6a 6f 75 72 6e 61 6c 20 77 6f  d the journal wo
88c0: 75 6c 64 20 72 65 74 75 72 6e 0a 2a 2a 20 53 51  uld return.** SQ
88d0: 4c 49 54 45 5f 49 4f 45 52 52 2e 20 20 4f 72 20  LITE_IOERR.  Or 
88e0: 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  the implementati
88f0: 6f 6e 20 6d 69 67 68 74 20 72 65 63 6f 67 6e 69  on might recogni
8900: 7a 65 20 74 68 61 74 20 61 20 64 61 74 61 62 61  ze that a databa
8910: 73 65 0a 2a 2a 20 66 69 6c 65 20 77 69 6c 6c 20  se.** file will 
8920: 62 65 20 64 6f 69 6e 67 20 70 61 67 65 2d 61 6c  be doing page-al
8930: 69 67 6e 65 64 20 73 65 63 74 6f 72 20 72 65 61  igned sector rea
8940: 64 73 20 61 6e 64 20 77 72 69 74 65 73 20 69 6e  ds and writes in
8950: 20 61 20 72 61 6e 64 6f 6d 0a 2a 2a 20 6f 72 64   a random.** ord
8960: 65 72 20 61 6e 64 20 73 65 74 20 75 70 20 69 74  er and set up it
8970: 73 20 49 2f 4f 20 73 75 62 73 79 73 74 65 6d 20  s I/O subsystem 
8980: 61 63 63 6f 72 64 69 6e 67 6c 79 2e 0a 2a 2a 0a  accordingly..**.
8990: 2a 2a 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20  ** SQLite might 
89a0: 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20  also add one of 
89b0: 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c  the following fl
89c0: 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e  ags to the xOpen
89d0: 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c   method:.**.** <
89e0: 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  ul>.** <li> [SQL
89f0: 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f  ITE_OPEN_DELETEO
8a00: 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e 20  NCLOSE].** <li> 
8a10: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43  [SQLITE_OPEN_EXC
8a20: 4c 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e  LUSIVE].** </ul>
8a30: 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 31 34 35 7d 20  .**.** {H11145} 
8a40: 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  The [SQLITE_OPEN
8a50: 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 20  _DELETEONCLOSE] 
8a60: 66 6c 61 67 20 6d 65 61 6e 73 20 74 68 65 20 66  flag means the f
8a70: 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a  ile should be.**
8a80: 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20 69 74   deleted when it
8a90: 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 7b 48 31   is closed.  {H1
8aa0: 31 31 34 36 7d 20 54 68 65 20 5b 53 51 4c 49 54  1146} The [SQLIT
8ab0: 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43  E_OPEN_DELETEONC
8ac0: 4c 4f 53 45 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65  LOSE].** will be
8ad0: 20 73 65 74 20 66 6f 72 20 54 45 4d 50 20 20 64   set for TEMP  d
8ae0: 61 74 61 62 61 73 65 73 2c 20 6a 6f 75 72 6e 61  atabases, journa
8af0: 6c 73 20 61 6e 64 20 66 6f 72 20 73 75 62 6a 6f  ls and for subjo
8b00: 75 72 6e 61 6c 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48  urnals..**.** {H
8b10: 31 31 31 34 37 7d 20 54 68 65 20 5b 53 51 4c 49  11147} The [SQLI
8b20: 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56  TE_OPEN_EXCLUSIV
8b30: 45 5d 20 66 6c 61 67 20 6d 65 61 6e 73 20 74 68  E] flag means th
8b40: 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65  e file should be
8b50: 20 6f 70 65 6e 65 64 0a 2a 2a 20 66 6f 72 20 65   opened.** for e
8b60: 78 63 6c 75 73 69 76 65 20 61 63 63 65 73 73 2e  xclusive access.
8b70: 20 20 54 68 69 73 20 66 6c 61 67 20 69 73 20 73    This flag is s
8b80: 65 74 20 66 6f 72 20 61 6c 6c 20 66 69 6c 65 73  et for all files
8b90: 20 65 78 63 65 70 74 0a 2a 2a 20 66 6f 72 20 74   except.** for t
8ba0: 68 65 20 6d 61 69 6e 20 64 61 74 61 62 61 73 65  he main database
8bb0: 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31   file..**.** {H1
8bc0: 31 31 34 38 7d 20 41 74 20 6c 65 61 73 74 20 73  1148} At least s
8bd0: 7a 4f 73 46 69 6c 65 20 62 79 74 65 73 20 6f 66  zOsFile bytes of
8be0: 20 6d 65 6d 6f 72 79 20 61 72 65 20 61 6c 6c 6f   memory are allo
8bf0: 63 61 74 65 64 20 62 79 20 53 51 4c 69 74 65 0a  cated by SQLite.
8c00: 2a 2a 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 20  ** to hold the  
8c10: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 73  [sqlite3_file] s
8c20: 74 72 75 63 74 75 72 65 20 70 61 73 73 65 64 20  tructure passed 
8c30: 61 73 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20  as the third.** 
8c40: 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65  argument to xOpe
8c50: 6e 2e 20 7b 45 4e 44 7d 20 20 54 68 65 20 78 4f  n. {END}  The xO
8c60: 70 65 6e 20 6d 65 74 68 6f 64 20 64 6f 65 73 20  pen method does 
8c70: 6e 6f 74 20 68 61 76 65 20 74 6f 0a 2a 2a 20 61  not have to.** a
8c80: 6c 6c 6f 63 61 74 65 20 74 68 65 20 73 74 72 75  llocate the stru
8c90: 63 74 75 72 65 3b 20 69 74 20 73 68 6f 75 6c 64  cture; it should
8ca0: 20 6a 75 73 74 20 66 69 6c 6c 20 69 74 20 69 6e   just fill it in
8cb0: 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 31 34 39 7d  ..**.** {H11149}
8cc0: 20 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d   The flags argum
8cd0: 65 6e 74 20 74 6f 20 78 41 63 63 65 73 73 28 29  ent to xAccess()
8ce0: 20 6d 61 79 20 62 65 20 5b 53 51 4c 49 54 45 5f   may be [SQLITE_
8cf0: 41 43 43 45 53 53 5f 45 58 49 53 54 53 5d 0a 2a  ACCESS_EXISTS].*
8d00: 2a 20 74 6f 20 74 65 73 74 20 66 6f 72 20 74 68  * to test for th
8d10: 65 20 65 78 69 73 74 65 6e 63 65 20 6f 66 20 61  e existence of a
8d20: 20 66 69 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54   file, or [SQLIT
8d30: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49  E_ACCESS_READWRI
8d40: 54 45 5d 20 74 6f 0a 2a 2a 20 74 65 73 74 20 77  TE] to.** test w
8d50: 68 65 74 68 65 72 20 61 20 66 69 6c 65 20 69 73  hether a file is
8d60: 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72   readable and wr
8d70: 69 74 61 62 6c 65 2c 20 6f 72 20 5b 53 51 4c 49  itable, or [SQLI
8d80: 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 5d 0a  TE_ACCESS_READ].
8d90: 2a 2a 20 74 6f 20 74 65 73 74 20 77 68 65 74 68  ** to test wheth
8da0: 65 72 20 61 20 66 69 6c 65 20 69 73 20 61 74 20  er a file is at 
8db0: 6c 65 61 73 74 20 72 65 61 64 61 62 6c 65 2e 20  least readable. 
8dc0: 7b 45 4e 44 7d 20 20 54 68 65 20 66 69 6c 65 20  {END}  The file 
8dd0: 63 61 6e 20 62 65 20 61 0a 2a 2a 20 64 69 72 65  can be a.** dire
8de0: 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  ctory..**.** {H1
8df0: 31 31 35 30 7d 20 53 51 4c 69 74 65 20 77 69 6c  1150} SQLite wil
8e00: 6c 20 61 6c 77 61 79 73 20 61 6c 6c 6f 63 61 74  l always allocat
8e10: 65 20 61 74 20 6c 65 61 73 74 20 6d 78 50 61 74  e at least mxPat
8e20: 68 6e 61 6d 65 2b 31 20 62 79 74 65 73 20 66 6f  hname+1 bytes fo
8e30: 72 20 74 68 65 0a 2a 2a 20 6f 75 74 70 75 74 20  r the.** output 
8e40: 62 75 66 66 65 72 20 78 46 75 6c 6c 50 61 74 68  buffer xFullPath
8e50: 6e 61 6d 65 2e 20 7b 48 31 31 31 35 31 7d 20 54  name. {H11151} T
8e60: 68 65 20 65 78 61 63 74 20 73 69 7a 65 20 6f 66  he exact size of
8e70: 20 74 68 65 20 6f 75 74 70 75 74 20 62 75 66 66   the output buff
8e80: 65 72 0a 2a 2a 20 69 73 20 61 6c 73 6f 20 70 61  er.** is also pa
8e90: 73 73 65 64 20 61 73 20 61 20 70 61 72 61 6d 65  ssed as a parame
8ea0: 74 65 72 20 74 6f 20 62 6f 74 68 20 20 6d 65 74  ter to both  met
8eb0: 68 6f 64 73 2e 20 7b 45 4e 44 7d 20 20 49 66 20  hods. {END}  If 
8ec0: 74 68 65 20 6f 75 74 70 75 74 20 62 75 66 66 65  the output buffe
8ed0: 72 0a 2a 2a 20 69 73 20 6e 6f 74 20 6c 61 72 67  r.** is not larg
8ee0: 65 20 65 6e 6f 75 67 68 2c 20 5b 53 51 4c 49 54  e enough, [SQLIT
8ef0: 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 73 68 6f 75  E_CANTOPEN] shou
8f00: 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20  ld be returned. 
8f10: 53 69 6e 63 65 20 74 68 69 73 20 69 73 0a 2a 2a  Since this is.**
8f20: 20 68 61 6e 64 6c 65 64 20 61 73 20 61 20 66 61   handled as a fa
8f30: 74 61 6c 20 65 72 72 6f 72 20 62 79 20 53 51 4c  tal error by SQL
8f40: 69 74 65 2c 20 76 66 73 20 69 6d 70 6c 65 6d 65  ite, vfs impleme
8f50: 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20  ntations should 
8f60: 65 6e 64 65 61 76 6f 72 0a 2a 2a 20 74 6f 20 70  endeavor.** to p
8f70: 72 65 76 65 6e 74 20 74 68 69 73 20 62 79 20 73  revent this by s
8f80: 65 74 74 69 6e 67 20 6d 78 50 61 74 68 6e 61 6d  etting mxPathnam
8f90: 65 20 74 6f 20 61 20 73 75 66 66 69 63 69 65 6e  e to a sufficien
8fa0: 74 6c 79 20 6c 61 72 67 65 20 76 61 6c 75 65 2e  tly large value.
8fb0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64  .**.** The xRand
8fc0: 6f 6d 6e 65 73 73 28 29 2c 20 78 53 6c 65 65 70  omness(), xSleep
8fd0: 28 29 2c 20 61 6e 64 20 78 43 75 72 72 65 6e 74  (), and xCurrent
8fe0: 54 69 6d 65 28 29 20 69 6e 74 65 72 66 61 63 65  Time() interface
8ff0: 73 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 73 74 72  s.** are not str
9000: 69 63 74 6c 79 20 61 20 70 61 72 74 20 6f 66 20  ictly a part of 
9010: 74 68 65 20 66 69 6c 65 73 79 73 74 65 6d 2c 20  the filesystem, 
9020: 62 75 74 20 74 68 65 79 20 61 72 65 0a 2a 2a 20  but they are.** 
9030: 69 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 65 20  included in the 
9040: 56 46 53 20 73 74 72 75 63 74 75 72 65 20 66 6f  VFS structure fo
9050: 72 20 63 6f 6d 70 6c 65 74 65 6e 65 73 73 2e 0a  r completeness..
9060: 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65  ** The xRandomne
9070: 73 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 61 74  ss() function at
9080: 74 65 6d 70 74 73 20 74 6f 20 72 65 74 75 72 6e  tempts to return
9090: 20 6e 42 79 74 65 73 20 62 79 74 65 73 0a 2a 2a   nBytes bytes.**
90a0: 20 6f 66 20 67 6f 6f 64 2d 71 75 61 6c 69 74 79   of good-quality
90b0: 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f   randomness into
90c0: 20 7a 4f 75 74 2e 20 20 54 68 65 20 72 65 74 75   zOut.  The retu
90d0: 72 6e 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20 74  rn value is.** t
90e0: 68 65 20 61 63 74 75 61 6c 20 6e 75 6d 62 65 72  he actual number
90f0: 20 6f 66 20 62 79 74 65 73 20 6f 66 20 72 61 6e   of bytes of ran
9100: 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 64  domness obtained
9110: 2e 0a 2a 2a 20 54 68 65 20 78 53 6c 65 65 70 28  ..** The xSleep(
9120: 29 20 6d 65 74 68 6f 64 20 63 61 75 73 65 73 20  ) method causes 
9130: 74 68 65 20 63 61 6c 6c 69 6e 67 20 74 68 72 65  the calling thre
9140: 61 64 20 74 6f 20 73 6c 65 65 70 20 66 6f 72 20  ad to sleep for 
9150: 61 74 0a 2a 2a 20 6c 65 61 73 74 20 74 68 65 20  at.** least the 
9160: 6e 75 6d 62 65 72 20 6f 66 20 6d 69 63 72 6f 73  number of micros
9170: 65 63 6f 6e 64 73 20 67 69 76 65 6e 2e 20 20 54  econds given.  T
9180: 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28  he xCurrentTime(
9190: 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74 75  ).** method retu
91a0: 72 6e 73 20 61 20 4a 75 6c 69 61 6e 20 44 61 79  rns a Julian Day
91b0: 20 4e 75 6d 62 65 72 20 66 6f 72 20 74 68 65 20   Number for the 
91c0: 63 75 72 72 65 6e 74 20 64 61 74 65 20 61 6e 64  current date and
91d0: 20 74 69 6d 65 2e 0a 2a 2f 0a 74 79 70 65 64 65   time..*/.typede
91e0: 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
91f0: 5f 76 66 73 20 73 71 6c 69 74 65 33 5f 76 66 73  _vfs sqlite3_vfs
9200: 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  ;.struct sqlite3
9210: 5f 76 66 73 20 7b 0a 20 20 69 6e 74 20 69 56 65  _vfs {.  int iVe
9220: 72 73 69 6f 6e 3b 20 20 20 20 20 20 20 20 20 20  rsion;          
9230: 20 20 2f 2a 20 53 74 72 75 63 74 75 72 65 20 76    /* Structure v
9240: 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 2a 2f  ersion number */
9250: 0a 20 20 69 6e 74 20 73 7a 4f 73 46 69 6c 65 3b  .  int szOsFile;
9260: 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53              /* S
9270: 69 7a 65 20 6f 66 20 73 75 62 63 6c 61 73 73 65  ize of subclasse
9280: 64 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 2a  d sqlite3_file *
9290: 2f 0a 20 20 69 6e 74 20 6d 78 50 61 74 68 6e 61  /.  int mxPathna
92a0: 6d 65 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20  me;          /* 
92b0: 4d 61 78 69 6d 75 6d 20 66 69 6c 65 20 70 61 74  Maximum file pat
92c0: 68 6e 61 6d 65 20 6c 65 6e 67 74 68 20 2a 2f 0a  hname length */.
92d0: 20 20 73 71 6c 69 74 65 33 5f 76 66 73 20 2a 70    sqlite3_vfs *p
92e0: 4e 65 78 74 3b 20 20 20 20 20 20 2f 2a 20 4e 65  Next;      /* Ne
92f0: 78 74 20 72 65 67 69 73 74 65 72 65 64 20 56 46  xt registered VF
9300: 53 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  S */.  const cha
9310: 72 20 2a 7a 4e 61 6d 65 3b 20 20 20 20 20 20 20  r *zName;       
9320: 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 69 73 20  /* Name of this 
9330: 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73 79 73  virtual file sys
9340: 74 65 6d 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70  tem */.  void *p
9350: 41 70 70 44 61 74 61 3b 20 20 20 20 20 20 20 20  AppData;        
9360: 20 20 2f 2a 20 50 6f 69 6e 74 65 72 20 74 6f 20    /* Pointer to 
9370: 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73 70 65 63  application-spec
9380: 69 66 69 63 20 64 61 74 61 20 2a 2f 0a 20 20 69  ific data */.  i
9390: 6e 74 20 28 2a 78 4f 70 65 6e 29 28 73 71 6c 69  nt (*xOpen)(sqli
93a0: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
93b0: 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c  char *zName, sql
93c0: 69 74 65 33 5f 66 69 6c 65 2a 2c 0a 20 20 20 20  ite3_file*,.    
93d0: 20 20 20 20 20 20 20 20 20 20 20 69 6e 74 20 66             int f
93e0: 6c 61 67 73 2c 20 69 6e 74 20 2a 70 4f 75 74 46  lags, int *pOutF
93f0: 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78  lags);.  int (*x
9400: 44 65 6c 65 74 65 29 28 73 71 6c 69 74 65 33 5f  Delete)(sqlite3_
9410: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
9420: 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 73 79 6e   *zName, int syn
9430: 63 44 69 72 29 3b 0a 20 20 69 6e 74 20 28 2a 78  cDir);.  int (*x
9440: 41 63 63 65 73 73 29 28 73 71 6c 69 74 65 33 5f  Access)(sqlite3_
9450: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
9460: 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 66 6c 61   *zName, int fla
9470: 67 73 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 74  gs, int *pResOut
9480: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 75 6c 6c  );.  int (*xFull
9490: 50 61 74 68 6e 61 6d 65 29 28 73 71 6c 69 74 65  Pathname)(sqlite
94a0: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
94b0: 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 6e  ar *zName, int n
94c0: 4f 75 74 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29  Out, char *zOut)
94d0: 3b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 44 6c 4f  ;.  void *(*xDlO
94e0: 70 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 66 73  pen)(sqlite3_vfs
94f0: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
9500: 46 69 6c 65 6e 61 6d 65 29 3b 0a 20 20 76 6f 69  Filename);.  voi
9510: 64 20 28 2a 78 44 6c 45 72 72 6f 72 29 28 73 71  d (*xDlError)(sq
9520: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20  lite3_vfs*, int 
9530: 6e 42 79 74 65 2c 20 63 68 61 72 20 2a 7a 45 72  nByte, char *zEr
9540: 72 4d 73 67 29 3b 0a 20 20 76 6f 69 64 20 2a 28  rMsg);.  void *(
9550: 2a 78 44 6c 53 79 6d 29 28 73 71 6c 69 74 65 33  *xDlSym)(sqlite3
9560: 5f 76 66 73 2a 2c 76 6f 69 64 2a 2c 20 63 6f 6e  _vfs*,void*, con
9570: 73 74 20 63 68 61 72 20 2a 7a 53 79 6d 62 6f 6c  st char *zSymbol
9580: 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 43  );.  void (*xDlC
9590: 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 76 66  lose)(sqlite3_vf
95a0: 73 2a 2c 20 76 6f 69 64 2a 29 3b 0a 20 20 69 6e  s*, void*);.  in
95b0: 74 20 28 2a 78 52 61 6e 64 6f 6d 6e 65 73 73 29  t (*xRandomness)
95c0: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69  (sqlite3_vfs*, i
95d0: 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20 2a  nt nByte, char *
95e0: 7a 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78  zOut);.  int (*x
95f0: 53 6c 65 65 70 29 28 73 71 6c 69 74 65 33 5f 76  Sleep)(sqlite3_v
9600: 66 73 2a 2c 20 69 6e 74 20 6d 69 63 72 6f 73 65  fs*, int microse
9610: 63 6f 6e 64 73 29 3b 0a 20 20 69 6e 74 20 28 2a  conds);.  int (*
9620: 78 43 75 72 72 65 6e 74 54 69 6d 65 29 28 73 71  xCurrentTime)(sq
9630: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 64 6f 75 62  lite3_vfs*, doub
9640: 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 47  le*);.  int (*xG
9650: 65 74 4c 61 73 74 45 72 72 6f 72 29 28 73 71 6c  etLastError)(sql
9660: 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 2c 20  ite3_vfs*, int, 
9670: 63 68 61 72 20 2a 29 3b 0a 20 20 2f 2a 20 4e 65  char *);.  /* Ne
9680: 77 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20  w fields may be 
9690: 61 70 70 65 6e 64 65 64 20 69 6e 20 66 69 67 75  appended in figu
96a0: 72 65 20 76 65 72 73 69 6f 6e 73 2e 20 20 54 68  re versions.  Th
96b0: 65 20 69 56 65 72 73 69 6f 6e 0a 20 20 2a 2a 20  e iVersion.  ** 
96c0: 76 61 6c 75 65 20 77 69 6c 6c 20 69 6e 63 72 65  value will incre
96d0: 6d 65 6e 74 20 77 68 65 6e 65 76 65 72 20 74 68  ment whenever th
96e0: 69 73 20 68 61 70 70 65 6e 73 2e 20 2a 2f 0a 7d  is happens. */.}
96f0: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
9700: 46 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68 65  F: Flags for the
9710: 20 78 41 63 63 65 73 73 20 56 46 53 20 6d 65 74   xAccess VFS met
9720: 68 6f 64 20 7b 48 31 31 31 39 30 7d 20 3c 48 31  hod {H11190} <H1
9730: 31 31 34 30 3e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31  1140>.**.** {H11
9740: 31 39 31 7d 20 54 68 65 73 65 20 69 6e 74 65 67  191} These integ
9750: 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 63 61 6e  er constants can
9760: 20 62 65 20 75 73 65 64 20 61 73 20 74 68 65 20   be used as the 
9770: 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
9780: 74 6f 0a 2a 2a 20 74 68 65 20 78 41 63 63 65 73  to.** the xAcces
9790: 73 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 20 5b  s method of an [
97a0: 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a  sqlite3_vfs] obj
97b0: 65 63 74 2e 20 7b 45 4e 44 7d 20 20 54 68 65 79  ect. {END}  They
97c0: 20 64 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 77 68   determine.** wh
97d0: 61 74 20 6b 69 6e 64 20 6f 66 20 70 65 72 6d 69  at kind of permi
97e0: 73 73 69 6f 6e 73 20 74 68 65 20 78 41 63 63 65  ssions the xAcce
97f0: 73 73 20 6d 65 74 68 6f 64 20 69 73 20 6c 6f 6f  ss method is loo
9800: 6b 69 6e 67 20 66 6f 72 2e 0a 2a 2a 20 7b 48 31  king for..** {H1
9810: 31 31 39 32 7d 20 57 69 74 68 20 53 51 4c 49 54  1192} With SQLIT
9820: 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 2c  E_ACCESS_EXISTS,
9830: 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74   the xAccess met
9840: 68 6f 64 0a 2a 2a 20 73 69 6d 70 6c 79 20 63 68  hod.** simply ch
9850: 65 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65  ecks whether the
9860: 20 66 69 6c 65 20 65 78 69 73 74 73 2e 0a 2a 2a   file exists..**
9870: 20 7b 48 31 31 31 39 33 7d 20 57 69 74 68 20 53   {H11193} With S
9880: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
9890: 44 57 52 49 54 45 2c 20 74 68 65 20 78 41 63 63  DWRITE, the xAcc
98a0: 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68  ess method.** ch
98b0: 65 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65  ecks whether the
98c0: 20 66 69 6c 65 20 69 73 20 62 6f 74 68 20 72 65   file is both re
98d0: 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74 61  adable and writa
98e0: 62 6c 65 2e 0a 2a 2a 20 7b 48 31 31 31 39 34 7d  ble..** {H11194}
98f0: 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43   With SQLITE_ACC
9900: 45 53 53 5f 52 45 41 44 2c 20 74 68 65 20 78 41  ESS_READ, the xA
9910: 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20  ccess method.** 
9920: 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 74  checks whether t
9930: 68 65 20 66 69 6c 65 20 69 73 20 72 65 61 64 61  he file is reada
9940: 62 6c 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ble..*/.#define 
9950: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58  SQLITE_ACCESS_EX
9960: 49 53 54 53 20 20 20 20 30 0a 23 64 65 66 69 6e  ISTS    0.#defin
9970: 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  e SQLITE_ACCESS_
9980: 52 45 41 44 57 52 49 54 45 20 31 0a 23 64 65 66  READWRITE 1.#def
9990: 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53  ine SQLITE_ACCES
99a0: 53 5f 52 45 41 44 20 20 20 20 20 20 32 0a 0a 2f  S_READ      2../
99b0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49  *.** CAPI3REF: I
99c0: 6e 69 74 69 61 6c 69 7a 65 20 54 68 65 20 53 51  nitialize The SQ
99d0: 4c 69 74 65 20 4c 69 62 72 61 72 79 20 7b 48 31  Lite Library {H1
99e0: 30 31 33 30 7d 20 3c 53 32 30 30 30 30 3e 3c 53  0130} <S20000><S
99f0: 33 30 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  30100>.**.** The
9a00: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
9a10: 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69 6e  ize() routine in
9a20: 69 74 69 61 6c 69 7a 65 73 20 74 68 65 0a 2a 2a  itializes the.**
9a30: 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e   SQLite library.
9a40: 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 73 68    The sqlite3_sh
9a50: 75 74 64 6f 77 6e 28 29 20 72 6f 75 74 69 6e 65  utdown() routine
9a60: 0a 2a 2a 20 64 65 61 6c 6c 6f 63 61 74 65 73 20  .** deallocates 
9a70: 61 6e 79 20 72 65 73 6f 75 72 63 65 73 20 74 68  any resources th
9a80: 61 74 20 77 65 72 65 20 61 6c 6c 6f 63 61 74 65  at were allocate
9a90: 64 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69  d by sqlite3_ini
9aa0: 74 69 61 6c 69 7a 65 28 29 2e 0a 2a 2a 0a 2a 2a  tialize()..**.**
9ab0: 20 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74   A call to sqlit
9ac0: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
9ad0: 69 73 20 61 6e 20 22 65 66 66 65 63 74 69 76 65  is an "effective
9ae0: 22 20 63 61 6c 6c 20 69 66 20 69 74 20 69 73 0a  " call if it is.
9af0: 2a 2a 20 74 68 65 20 66 69 72 73 74 20 74 69 6d  ** the first tim
9b00: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
9b10: 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65  lize() is invoke
9b20: 64 20 64 75 72 69 6e 67 20 74 68 65 20 6c 69 66  d during the lif
9b30: 65 74 69 6d 65 20 6f 66 0a 2a 2a 20 74 68 65 20  etime of.** the 
9b40: 70 72 6f 63 65 73 73 2c 20 6f 72 20 69 66 20 69  process, or if i
9b50: 74 20 69 73 20 74 68 65 20 66 69 72 73 74 20 74  t is the first t
9b60: 69 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  ime sqlite3_init
9b70: 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f  ialize() is invo
9b80: 6b 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67  ked.** following
9b90: 20 61 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74   a call to sqlit
9ba0: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20  e3_shutdown().  
9bb0: 4f 6e 6c 79 20 61 6e 20 65 66 66 65 63 74 69 76  Only an effectiv
9bc0: 65 20 63 61 6c 6c 0a 2a 2a 20 6f 66 20 73 71 6c  e call.** of sql
9bd0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
9be0: 29 20 64 6f 65 73 20 61 6e 79 20 69 6e 69 74 69  ) does any initi
9bf0: 61 6c 69 7a 61 74 69 6f 6e 2e 20 20 41 6c 6c 20  alization.  All 
9c00: 6f 74 68 65 72 20 63 61 6c 6c 73 0a 2a 2a 20 61  other calls.** a
9c10: 72 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f  re harmless no-o
9c20: 70 73 2e 0a 2a 2a 0a 2a 2a 20 41 6d 6f 6e 67 20  ps..**.** Among 
9c30: 6f 74 68 65 72 20 74 68 69 6e 67 73 2c 20 73 71  other things, sq
9c40: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
9c50: 28 29 20 73 68 61 6c 6c 20 69 6e 76 6f 6b 65 0a  () shall invoke.
9c60: 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  ** sqlite3_os_in
9c70: 69 74 28 29 2e 20 20 53 69 6d 69 6c 61 72 6c 79  it().  Similarly
9c80: 2c 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  , sqlite3_shutdo
9c90: 77 6e 28 29 0a 2a 2a 20 73 68 61 6c 6c 20 69 6e  wn().** shall in
9ca0: 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f  voke sqlite3_os_
9cb0: 65 6e 64 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  end()..**.** The
9cc0: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
9cd0: 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65  ize() routine re
9ce0: 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 4f 4b 20  turns SQLITE_OK 
9cf0: 6f 6e 20 73 75 63 63 65 73 73 2e 0a 2a 2a 20 49  on success..** I
9d00: 66 20 66 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f  f for some reaso
9d10: 6e 2c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  n, sqlite3_initi
9d20: 61 6c 69 7a 65 28 29 20 69 73 20 75 6e 61 62 6c  alize() is unabl
9d30: 65 20 74 6f 20 69 6e 69 74 69 61 6c 69 7a 65 0a  e to initialize.
9d40: 2a 2a 20 74 68 65 20 6c 69 62 72 61 72 79 20 28  ** the library (
9d50: 70 65 72 68 61 70 73 20 69 74 20 69 73 20 75 6e  perhaps it is un
9d60: 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65  able to allocate
9d70: 20 61 20 6e 65 65 64 65 64 20 72 65 73 6f 75 72   a needed resour
9d80: 63 65 20 73 75 63 68 0a 2a 2a 20 61 73 20 61 20  ce such.** as a 
9d90: 6d 75 74 65 78 29 20 69 74 20 72 65 74 75 72 6e  mutex) it return
9da0: 73 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65  s an [error code
9db0: 5d 20 6f 74 68 65 72 20 74 68 61 6e 20 53 51 4c  ] other than SQL
9dc0: 49 54 45 5f 4f 4b 2e 0a 2a 2a 0a 2a 2a 20 54 68  ITE_OK..**.** Th
9dd0: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
9de0: 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69  lize() routine i
9df0: 73 20 63 61 6c 6c 65 64 20 69 6e 74 65 72 6e 61  s called interna
9e00: 6c 6c 79 20 62 79 20 6d 61 6e 79 20 6f 74 68 65  lly by many othe
9e10: 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65  r.** SQLite inte
9e20: 72 66 61 63 65 73 20 73 6f 20 74 68 61 74 20 61  rfaces so that a
9e30: 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 75 73  n application us
9e40: 75 61 6c 6c 79 20 64 6f 65 73 20 6e 6f 74 20 6e  ually does not n
9e50: 65 65 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65  eed to.** invoke
9e60: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
9e70: 69 7a 65 28 29 20 64 69 72 65 63 74 6c 79 2e 20  ize() directly. 
9e80: 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 5b 73   For example, [s
9e90: 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a  qlite3_open()].*
9ea0: 2a 20 63 61 6c 6c 73 20 73 71 6c 69 74 65 33 5f  * calls sqlite3_
9eb0: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 73 6f 20  initialize() so 
9ec0: 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61  the SQLite libra
9ed0: 72 79 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d  ry will be autom
9ee0: 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 69 6e 69 74  atically.** init
9ef0: 69 61 6c 69 7a 65 64 20 77 68 65 6e 20 5b 73 71  ialized when [sq
9f00: 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 69 73  lite3_open()] is
9f10: 20 63 61 6c 6c 65 64 20 69 66 20 69 74 20 68 61   called if it ha
9f20: 73 20 6e 6f 74 20 62 65 20 69 6e 69 74 69 61 6c  s not be initial
9f30: 69 7a 65 64 0a 2a 2a 20 61 6c 72 65 61 64 79 2e  ized.** already.
9f40: 20 20 48 6f 77 65 76 65 72 2c 20 69 66 20 53 51    However, if SQ
9f50: 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
9f60: 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45   with the SQLITE
9f70: 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 0a 2a  _OMIT_AUTOINIT.*
9f80: 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  * compile-time o
9f90: 70 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20  ption, then the 
9fa0: 61 75 74 6f 6d 61 74 69 63 20 63 61 6c 6c 73 20  automatic calls 
9fb0: 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  to sqlite3_initi
9fc0: 61 6c 69 7a 65 28 29 0a 2a 2a 20 61 72 65 20 6f  alize().** are o
9fd0: 6d 69 74 74 65 64 20 61 6e 64 20 74 68 65 20 61  mitted and the a
9fe0: 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
9ff0: 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 69 6e 69  call sqlite3_ini
a000: 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63 74  tialize() direct
a010: 6c 79 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 75  ly.** prior to u
a020: 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53  sing any other S
a030: 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e  QLite interface.
a040: 20 20 46 6f 72 20 6d 61 78 69 6d 75 6d 20 70 6f    For maximum po
a050: 72 74 61 62 69 6c 69 74 79 2c 0a 2a 2a 20 69 74  rtability,.** it
a060: 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20   is recommended 
a070: 74 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e  that application
a080: 73 20 61 6c 77 61 79 73 20 69 6e 76 6f 6b 65 20  s always invoke 
a090: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
a0a0: 7a 65 28 29 0a 2a 2a 20 64 69 72 65 63 74 6c 79  ze().** directly
a0b0: 20 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20   prior to using 
a0c0: 61 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65  any other SQLite
a0d0: 20 69 6e 74 65 72 66 61 63 65 2e 20 20 46 75 74   interface.  Fut
a0e0: 75 72 65 20 72 65 6c 65 61 73 65 73 0a 2a 2a 20  ure releases.** 
a0f0: 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20 72 65  of SQLite may re
a100: 71 75 69 72 65 20 74 68 69 73 2e 20 20 49 6e 20  quire this.  In 
a110: 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65  other words, the
a120: 20 62 65 68 61 76 69 6f 72 20 65 78 68 69 62 69   behavior exhibi
a130: 74 65 64 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69  ted.** when SQLi
a140: 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
a150: 69 74 68 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  ith SQLITE_OMIT_
a160: 41 55 54 4f 49 4e 49 54 20 6d 69 67 68 74 20 62  AUTOINIT might b
a170: 65 63 6f 6d 65 20 74 68 65 0a 2a 2a 20 64 65 66  ecome the.** def
a180: 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20 69 6e  ault behavior in
a190: 20 73 6f 6d 65 20 66 75 74 75 72 65 20 72 65 6c   some future rel
a1a0: 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 2e 0a  ease of SQLite..
a1b0: 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
a1c0: 33 5f 6f 73 5f 69 6e 69 74 28 29 20 72 6f 75 74  3_os_init() rout
a1d0: 69 6e 65 20 64 6f 65 73 20 6f 70 65 72 61 74 69  ine does operati
a1e0: 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69 66  ng-system specif
a1f0: 69 63 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a 61  ic.** initializa
a200: 74 69 6f 6e 20 6f 66 20 74 68 65 20 53 51 4c 69  tion of the SQLi
a210: 74 65 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65  te library.  The
a220: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28   sqlite3_os_end(
a230: 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 75 6e 64  ).** routine und
a240: 6f 65 73 20 74 68 65 20 65 66 66 65 63 74 20 6f  oes the effect o
a250: 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  f sqlite3_os_ini
a260: 74 28 29 2e 20 20 54 79 70 69 63 61 6c 20 74 61  t().  Typical ta
a270: 73 6b 73 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64  sks.** performed
a280: 20 62 79 20 74 68 65 73 65 20 72 6f 75 74 69 6e   by these routin
a290: 65 73 20 69 6e 63 6c 75 64 65 20 61 6c 6c 6f 63  es include alloc
a2a0: 61 74 69 6f 6e 20 6f 72 20 64 65 61 6c 6c 6f 63  ation or dealloc
a2b0: 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 73 74 61 74  ation.** of stat
a2c0: 69 63 20 72 65 73 6f 75 72 63 65 73 2c 20 69 6e  ic resources, in
a2d0: 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20  itialization of 
a2e0: 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c 65 73  global variables
a2f0: 2c 0a 2a 2a 20 73 65 74 74 69 6e 67 20 75 70 20  ,.** setting up 
a300: 61 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74  a default [sqlit
a310: 65 33 5f 76 66 73 5d 20 6d 6f 64 75 6c 65 2c 20  e3_vfs] module, 
a320: 6f 72 20 73 65 74 74 69 6e 67 20 75 70 0a 2a 2a  or setting up.**
a330: 20 61 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69   a default confi
a340: 67 75 72 61 74 69 6f 6e 20 75 73 69 6e 67 20 5b  guration using [
a350: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
a360: 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70  ]..**.** The app
a370: 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20  lication should 
a380: 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 65 69 74  never invoke eit
a390: 68 65 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69  her sqlite3_os_i
a3a0: 6e 69 74 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69  nit().** or sqli
a3b0: 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 64 69 72  te3_os_end() dir
a3c0: 65 63 74 6c 79 2e 20 20 54 68 65 20 61 70 70 6c  ectly.  The appl
a3d0: 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6f  ication should o
a3e0: 6e 6c 79 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71  nly invoke.** sq
a3f0: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
a400: 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 73  () and sqlite3_s
a410: 68 75 74 64 6f 77 6e 28 29 2e 20 20 54 68 65 20  hutdown().  The 
a420: 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
a430: 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69  ).** interface i
a440: 73 20 63 61 6c 6c 65 64 20 61 75 74 6f 6d 61 74  s called automat
a450: 69 63 61 6c 6c 79 20 62 79 20 73 71 6c 69 74 65  ically by sqlite
a460: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 61  3_initialize() a
a470: 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73  nd.** sqlite3_os
a480: 5f 65 6e 64 28 29 20 69 73 20 63 61 6c 6c 65 64  _end() is called
a490: 20 62 79 20 73 71 6c 69 74 65 33 5f 73 68 75 74   by sqlite3_shut
a4a0: 64 6f 77 6e 28 29 2e 20 20 41 70 70 72 6f 70 72  down().  Appropr
a4b0: 69 61 74 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e  iate.** implemen
a4c0: 74 61 74 69 6f 6e 73 20 66 6f 72 20 73 71 6c 69  tations for sqli
a4d0: 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e  te3_os_init() an
a4e0: 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  d sqlite3_os_end
a4f0: 28 29 0a 2a 2a 20 61 72 65 20 62 75 69 6c 74 20  ().** are built 
a500: 69 6e 74 6f 20 53 51 4c 69 74 65 20 77 68 65 6e  into SQLite when
a510: 20 69 74 20 69 73 20 63 6f 6d 70 69 6c 65 64 20   it is compiled 
a520: 66 6f 72 20 75 6e 69 78 2c 20 77 69 6e 64 6f 77  for unix, window
a530: 73 2c 20 6f 72 20 6f 73 2f 32 2e 0a 2a 2a 20 57  s, or os/2..** W
a540: 68 65 6e 20 62 75 69 6c 74 20 66 6f 72 20 6f 74  hen built for ot
a550: 68 65 72 20 70 6c 61 74 66 6f 72 6d 73 20 28 75  her platforms (u
a560: 73 69 6e 67 20 74 68 65 20 53 51 4c 49 54 45 5f  sing the SQLITE_
a570: 4f 53 5f 4f 54 48 45 52 3d 31 20 63 6f 6d 70 69  OS_OTHER=1 compi
a580: 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f  le-time.** optio
a590: 6e 29 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  n) the applicati
a5a0: 6f 6e 20 6d 75 73 74 20 73 75 70 70 6c 79 20 61  on must supply a
a5b0: 20 73 75 69 74 61 62 6c 65 20 69 6d 70 6c 65 6d   suitable implem
a5c0: 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20  entation for.** 
a5d0: 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
a5e0: 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73  ) and sqlite3_os
a5f0: 5f 65 6e 64 28 29 2e 20 20 41 6e 20 61 70 70 6c  _end().  An appl
a600: 69 63 61 74 69 6f 6e 2d 73 75 70 70 6c 69 65 64  ication-supplied
a610: 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
a620: 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73  on of sqlite3_os
a630: 5f 69 6e 69 74 28 29 20 6f 72 20 73 71 6c 69 74  _init() or sqlit
a640: 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 6d  e3_os_end().** m
a650: 75 73 74 20 72 65 74 75 72 6e 20 53 51 4c 49 54  ust return SQLIT
a660: 45 5f 4f 4b 20 6f 6e 20 73 75 63 63 65 73 73 20  E_OK on success 
a670: 61 6e 64 20 73 6f 6d 65 20 6f 74 68 65 72 20 5b  and some other [
a680: 65 72 72 6f 72 20 63 6f 64 65 5d 20 75 70 6f 6e  error code] upon
a690: 0a 2a 2a 20 66 61 69 6c 75 72 65 2e 0a 2a 2f 0a  .** failure..*/.
a6a0: 69 6e 74 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  int sqlite3_init
a6b0: 69 61 6c 69 7a 65 28 76 6f 69 64 29 3b 0a 69 6e  ialize(void);.in
a6c0: 74 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  t sqlite3_shutdo
a6d0: 77 6e 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71  wn(void);.int sq
a6e0: 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 76 6f  lite3_os_init(vo
a6f0: 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  id);.int sqlite3
a700: 5f 6f 73 5f 65 6e 64 28 76 6f 69 64 29 3b 0a 0a  _os_end(void);..
a710: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
a720: 43 6f 6e 66 69 67 75 72 69 6e 67 20 54 68 65 20  Configuring The 
a730: 53 51 4c 69 74 65 20 4c 69 62 72 61 72 79 20 7b  SQLite Library {
a740: 48 31 30 31 34 35 7d 20 3c 53 32 30 30 30 30 3e  H10145} <S20000>
a750: 3c 53 33 30 32 30 30 3e 0a 2a 2a 20 45 58 50 45  <S30200>.** EXPE
a760: 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54  RIMENTAL.**.** T
a770: 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  he sqlite3_confi
a780: 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73  g() interface is
a790: 20 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 67 6c   used to make gl
a7a0: 6f 62 61 6c 20 63 6f 6e 66 69 67 75 72 61 74 69  obal configurati
a7b0: 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f  on.** changes to
a7c0: 20 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72   SQLite in order
a7d0: 20 74 6f 20 74 75 6e 65 20 53 51 4c 69 74 65 20   to tune SQLite 
a7e0: 74 6f 20 74 68 65 20 73 70 65 63 69 66 69 63 20  to the specific 
a7f0: 6e 65 65 64 73 20 6f 66 0a 2a 2a 20 74 68 65 20  needs of.** the 
a800: 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 54 68  application.  Th
a810: 65 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67  e default config
a820: 75 72 61 74 69 6f 6e 20 69 73 20 72 65 63 6f 6d  uration is recom
a830: 6d 65 6e 64 65 64 20 66 6f 72 20 6d 6f 73 74 0a  mended for most.
a840: 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  ** applications 
a850: 61 6e 64 20 73 6f 20 74 68 69 73 20 72 6f 75 74  and so this rout
a860: 69 6e 65 20 69 73 20 75 73 75 61 6c 6c 79 20 6e  ine is usually n
a870: 6f 74 20 6e 65 63 65 73 73 61 72 79 2e 20 20 49  ot necessary.  I
a880: 74 20 69 73 0a 2a 2a 20 70 72 6f 76 69 64 65 64  t is.** provided
a890: 20 74 6f 20 73 75 70 70 6f 72 74 20 72 61 72 65   to support rare
a8a0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 77 69   applications wi
a8b0: 74 68 20 75 6e 75 73 75 61 6c 20 6e 65 65 64 73  th unusual needs
a8c0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
a8d0: 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74  te3_config() int
a8e0: 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20 74 68  erface is not th
a8f0: 72 65 61 64 73 61 66 65 2e 20 20 54 68 65 20 61  readsafe.  The a
a900: 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 6d 75  pplication.** mu
a910: 73 74 20 69 6e 73 75 72 65 20 74 68 61 74 20 6e  st insure that n
a920: 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69  o other SQLite i
a930: 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 69 6e  nterfaces are in
a940: 76 6f 6b 65 64 20 62 79 20 6f 74 68 65 72 0a 2a  voked by other.*
a950: 2a 20 74 68 72 65 61 64 73 20 77 68 69 6c 65 20  * threads while 
a960: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
a970: 20 69 73 20 72 75 6e 6e 69 6e 67 2e 20 20 46 75   is running.  Fu
a980: 72 74 68 65 72 6d 6f 72 65 2c 20 73 71 6c 69 74  rthermore, sqlit
a990: 65 33 5f 63 6f 6e 66 69 67 28 29 0a 2a 2a 20 6d  e3_config().** m
a9a0: 61 79 20 6f 6e 6c 79 20 62 65 20 69 6e 76 6f 6b  ay only be invok
a9b0: 65 64 20 70 72 69 6f 72 20 74 6f 20 6c 69 62 72  ed prior to libr
a9c0: 61 72 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  ary initializati
a9d0: 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c  on using.** [sql
a9e0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
a9f0: 29 5d 20 6f 72 20 61 66 74 65 72 20 73 68 75 74  )] or after shut
aa00: 64 6f 77 6e 20 62 79 20 5b 73 71 6c 69 74 65 33  down by [sqlite3
aa10: 5f 73 68 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a  _shutdown()]..**
aa20: 20 4e 6f 74 65 2c 20 68 6f 77 65 76 65 72 2c 20   Note, however, 
aa30: 74 68 61 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e  that sqlite3_con
aa40: 66 69 67 28 29 20 63 61 6e 20 62 65 20 63 61 6c  fig() can be cal
aa50: 6c 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 74  led as part of t
aa60: 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  he.** implementa
aa70: 74 69 6f 6e 20 6f 66 20 61 6e 20 61 70 70 6c 69  tion of an appli
aa80: 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 5b  cation-defined [
aa90: 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
aaa0: 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  )]..**.** The fi
aab0: 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
aac0: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
aad0: 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a   is an integer.*
aae0: 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  * [SQLITE_CONFIG
aaf0: 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 20 7c 20  _SINGLETHREAD | 
ab00: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
ab10: 74 69 6f 6e 5d 20 74 68 61 74 20 64 65 74 65 72  tion] that deter
ab20: 6d 69 6e 65 73 0a 2a 2a 20 77 68 61 74 20 70 72  mines.** what pr
ab30: 6f 70 65 72 74 79 20 6f 66 20 53 51 4c 69 74 65  operty of SQLite
ab40: 20 69 73 20 74 6f 20 62 65 20 63 6f 6e 66 69 67   is to be config
ab50: 75 72 65 64 2e 20 20 53 75 62 73 65 71 75 65 6e  ured.  Subsequen
ab60: 74 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 76  t arguments.** v
ab70: 61 72 79 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e  ary depending on
ab80: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e   the [SQLITE_CON
ab90: 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44  FIG_SINGLETHREAD
aba0: 20 7c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e   | configuration
abb0: 20 6f 70 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74   option].** in t
abc0: 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
abd0: 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 61 20  t..**.** When a 
abe0: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
abf0: 74 69 6f 6e 20 69 73 20 73 65 74 2c 20 73 71 6c  tion is set, sql
ac00: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 72 65  ite3_config() re
ac10: 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 4f 4b 2e  turns SQLITE_OK.
ac20: 0a 2a 2a 20 49 66 20 74 68 65 20 6f 70 74 69 6f  .** If the optio
ac30: 6e 20 69 73 20 75 6e 6b 6e 6f 77 6e 20 6f 72 20  n is unknown or 
ac40: 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65  SQLite is unable
ac50: 20 74 6f 20 73 65 74 20 74 68 65 20 6f 70 74 69   to set the opti
ac60: 6f 6e 0a 2a 2a 20 74 68 65 6e 20 74 68 69 73 20  on.** then this 
ac70: 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
ac80: 61 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f  a non-zero [erro
ac90: 72 20 63 6f 64 65 5d 2e 0a 2a 2f 0a 53 51 4c 49  r code]..*/.SQLI
aca0: 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 20  TE_EXPERIMENTAL 
acb0: 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66  int sqlite3_conf
acc0: 69 67 28 69 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f  ig(int, ...);../
acd0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
ace0: 6f 6e 66 69 67 75 72 65 20 64 61 74 61 62 61 73  onfigure databas
acf0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 20 7b  e connections  {
ad00: 48 31 30 31 38 30 7d 20 3c 53 32 30 30 30 30 3e  H10180} <S20000>
ad10: 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c  .** EXPERIMENTAL
ad20: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
ad30: 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 69  e3_db_config() i
ad40: 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64  nterface is used
ad50: 20 74 6f 20 6d 61 6b 65 20 63 6f 6e 66 69 67 75   to make configu
ad60: 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65  ration.** change
ad70: 73 20 74 6f 20 61 20 5b 64 61 74 61 62 61 73 65  s to a [database
ad80: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54   connection].  T
ad90: 68 65 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  he interface is 
ada0: 73 69 6d 69 6c 61 72 20 74 6f 0a 2a 2a 20 5b 73  similar to.** [s
adb0: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
adc0: 20 65 78 63 65 70 74 20 74 68 61 74 20 74 68 65   except that the
add0: 20 63 68 61 6e 67 65 73 20 61 70 70 6c 79 20 74   changes apply t
ade0: 6f 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b 64  o a single.** [d
adf0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
ae00: 6f 6e 5d 20 28 73 70 65 63 69 66 69 65 64 20 69  on] (specified i
ae10: 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  n the first argu
ae20: 6d 65 6e 74 29 2e 20 20 54 68 65 0a 2a 2a 20 73  ment).  The.** s
ae30: 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
ae40: 28 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e  () interface can
ae50: 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 69 6d   only be used im
ae60: 6d 65 64 69 61 74 65 6c 79 20 61 66 74 65 72 0a  mediately after.
ae70: 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ** the database 
ae80: 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 72  connection is cr
ae90: 65 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c  eated using [sql
aea0: 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 0a 2a 2a  ite3_open()],.**
aeb0: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36   [sqlite3_open16
aec0: 28 29 5d 2c 20 6f 72 20 5b 73 71 6c 69 74 65 33  ()], or [sqlite3
aed0: 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 20 20 0a 2a  _open_v2()].  .*
aee0: 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  *.** The second 
aef0: 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69  argument to sqli
af00: 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 44 2c  te3_db_config(D,
af10: 56 2c 2e 2e 2e 29 20 20 69 73 20 74 68 65 0a 2a  V,...)  is the.*
af20: 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  * configuration 
af30: 76 65 72 62 20 2d 20 61 6e 20 69 6e 74 65 67 65  verb - an intege
af40: 72 20 63 6f 64 65 20 74 68 61 74 20 69 6e 64 69  r code that indi
af50: 63 61 74 65 73 20 77 68 61 74 0a 2a 2a 20 61 73  cates what.** as
af60: 70 65 63 74 20 6f 66 20 74 68 65 20 5b 64 61 74  pect of the [dat
af70: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
af80: 5d 20 69 73 20 62 65 69 6e 67 20 63 6f 6e 66 69  ] is being confi
af90: 67 75 72 65 64 2e 0a 2a 2a 20 54 68 65 20 6f 6e  gured..** The on
afa0: 6c 79 20 63 68 6f 69 63 65 20 66 6f 72 20 74 68  ly choice for th
afb0: 69 73 20 76 61 6c 75 65 20 69 73 20 5b 53 51 4c  is value is [SQL
afc0: 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f  ITE_DBCONFIG_LOO
afd0: 4b 41 53 49 44 45 5d 2e 0a 2a 2a 20 4e 65 77 20  KASIDE]..** New 
afe0: 76 65 72 62 73 20 61 72 65 20 6c 69 6b 65 6c 79  verbs are likely
aff0: 20 74 6f 20 62 65 20 61 64 64 65 64 20 69 6e 20   to be added in 
b000: 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20  future releases 
b010: 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 41 64  of SQLite..** Ad
b020: 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e  ditional argumen
b030: 74 73 20 64 65 70 65 6e 64 20 6f 6e 20 74 68 65  ts depend on the
b040: 20 76 65 72 62 2e 0a 2a 2f 0a 53 51 4c 49 54 45   verb..*/.SQLITE
b050: 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 69 6e  _EXPERIMENTAL in
b060: 74 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e  t sqlite3_db_con
b070: 66 69 67 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e  fig(sqlite3*, in
b080: 74 20 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a  t op, ...);../*.
b090: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d  ** CAPI3REF: Mem
b0a0: 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 52  ory Allocation R
b0b0: 6f 75 74 69 6e 65 73 20 7b 48 31 30 31 35 35 7d  outines {H10155}
b0c0: 20 3c 53 32 30 31 32 30 3e 0a 2a 2a 20 45 58 50   <S20120>.** EXP
b0d0: 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20  ERIMENTAL.**.** 
b0e0: 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  An instance of t
b0f0: 68 69 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e  his object defin
b100: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
b110: 20 62 65 74 77 65 65 6e 20 53 51 4c 69 74 65 0a   between SQLite.
b120: 2a 2a 20 61 6e 64 20 6c 6f 77 2d 6c 65 76 65 6c  ** and low-level
b130: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
b140: 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a  on routines..**.
b150: 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69  ** This object i
b160: 73 20 75 73 65 64 20 69 6e 20 6f 6e 6c 79 20 6f  s used in only o
b170: 6e 65 20 70 6c 61 63 65 20 69 6e 20 74 68 65 20  ne place in the 
b180: 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
b190: 2e 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20 74  ..** A pointer t
b1a0: 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  o an instance of
b1b0: 20 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20   this object is 
b1c0: 74 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a  the argument to.
b1d0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ** [sqlite3_conf
b1e0: 69 67 28 29 5d 20 77 68 65 6e 20 74 68 65 20 63  ig()] when the c
b1f0: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
b200: 69 6f 6e 20 69 73 0a 2a 2a 20 5b 53 51 4c 49 54  ion is.** [SQLIT
b210: 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d  E_CONFIG_MALLOC]
b220: 2e 20 20 42 79 20 63 72 65 61 74 69 6e 67 20 61  .  By creating a
b230: 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
b240: 69 73 20 6f 62 6a 65 63 74 0a 2a 2a 20 61 6e 64  is object.** and
b250: 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b   passing it to [
b260: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
b270: 5d 20 64 75 72 69 6e 67 20 63 6f 6e 66 69 67 75  ] during configu
b280: 72 61 74 69 6f 6e 2c 20 61 6e 0a 2a 2a 20 61 70  ration, an.** ap
b290: 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e 20 73 70  plication can sp
b2a0: 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e 61  ecify an alterna
b2b0: 74 69 76 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  tive memory allo
b2c0: 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d  cation subsystem
b2d0: 0a 2a 2a 20 66 6f 72 20 53 51 4c 69 74 65 20 74  .** for SQLite t
b2e0: 6f 20 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66  o use for all of
b2f0: 20 69 74 73 20 64 79 6e 61 6d 69 63 20 6d 65 6d   its dynamic mem
b300: 6f 72 79 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a  ory needs..**.**
b310: 20 4e 6f 74 65 20 74 68 61 74 20 53 51 4c 69 74   Note that SQLit
b320: 65 20 63 6f 6d 65 73 20 77 69 74 68 20 61 20 62  e comes with a b
b330: 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61  uilt-in memory a
b340: 6c 6c 6f 63 61 74 6f 72 20 74 68 61 74 20 69 73  llocator that is
b350: 0a 2a 2a 20 70 65 72 66 65 63 74 6c 79 20 61 64  .** perfectly ad
b360: 65 71 75 61 74 65 20 66 6f 72 20 74 68 65 20 6f  equate for the o
b370: 76 65 72 77 68 65 6c 6d 69 6e 67 20 6d 61 6a 6f  verwhelming majo
b380: 72 69 74 79 20 6f 66 20 61 70 70 6c 69 63 61 74  rity of applicat
b390: 69 6f 6e 73 0a 2a 2a 20 61 6e 64 20 74 68 61 74  ions.** and that
b3a0: 20 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20   this object is 
b3b0: 6f 6e 6c 79 20 75 73 65 66 75 6c 20 74 6f 20 61  only useful to a
b3c0: 20 74 69 6e 79 20 6d 69 6e 6f 72 69 74 79 20 6f   tiny minority o
b3d0: 66 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a  f applications.*
b3e0: 2a 20 77 69 74 68 20 73 70 65 63 69 61 6c 69 7a  * with specializ
b3f0: 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ed memory alloca
b400: 74 69 6f 6e 20 72 65 71 75 69 72 65 6d 65 6e 74  tion requirement
b410: 73 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20  s.  This object 
b420: 69 73 0a 2a 2a 20 61 6c 73 6f 20 75 73 65 64 20  is.** also used 
b430: 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67 20 6f  during testing o
b440: 66 20 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 65  f SQLite in orde
b450: 72 20 74 6f 20 73 70 65 63 69 66 79 20 61 6e 20  r to specify an 
b460: 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d  alternative.** m
b470: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20  emory allocator 
b480: 74 68 61 74 20 73 69 6d 75 6c 61 74 65 73 20 6d  that simulates m
b490: 65 6d 6f 72 79 20 6f 75 74 2d 6f 66 2d 6d 65 6d  emory out-of-mem
b4a0: 6f 72 79 20 63 6f 6e 64 69 74 69 6f 6e 73 20 69  ory conditions i
b4b0: 6e 0a 2a 2a 20 6f 72 64 65 72 20 74 6f 20 76 65  n.** order to ve
b4c0: 72 69 66 79 20 74 68 61 74 20 53 51 4c 69 74 65  rify that SQLite
b4d0: 20 72 65 63 6f 76 65 72 73 20 67 72 61 63 65 66   recovers gracef
b4e0: 75 6c 6c 79 20 66 72 6f 6d 20 73 75 63 68 0a 2a  ully from such.*
b4f0: 2a 20 63 6f 6e 64 69 74 69 6f 6e 73 2e 0a 2a 2a  * conditions..**
b500: 0a 2a 2a 20 54 68 65 20 78 4d 61 6c 6c 6f 63 2c  .** The xMalloc,
b510: 20 78 46 72 65 65 2c 20 61 6e 64 20 78 52 65 61   xFree, and xRea
b520: 6c 6c 6f 63 20 6d 65 74 68 6f 64 73 20 6d 75 73  lloc methods mus
b530: 74 20 77 6f 72 6b 20 6c 69 6b 65 20 74 68 65 0a  t work like the.
b540: 2a 2a 20 6d 61 6c 6c 6f 63 28 29 2c 20 66 72 65  ** malloc(), fre
b550: 65 28 29 2c 20 61 6e 64 20 72 65 61 6c 6c 6f 63  e(), and realloc
b560: 28 29 20 66 75 6e 63 74 69 6f 6e 73 20 66 72 6f  () functions fro
b570: 6d 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 6c  m the standard l
b580: 69 62 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 78 53  ibrary..**.** xS
b590: 69 7a 65 20 73 68 6f 75 6c 64 20 72 65 74 75 72  ize should retur
b5a0: 6e 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 20  n the allocated 
b5b0: 73 69 7a 65 20 6f 66 20 61 20 6d 65 6d 6f 72 79  size of a memory
b5c0: 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 70   allocation.** p
b5d0: 72 65 76 69 6f 75 73 6c 79 20 6f 62 74 61 69 6e  reviously obtain
b5e0: 65 64 20 66 72 6f 6d 20 78 4d 61 6c 6c 6f 63 20  ed from xMalloc 
b5f0: 6f 72 20 78 52 65 61 6c 6c 6f 63 2e 20 20 54 68  or xRealloc.  Th
b600: 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65  e allocated size
b610: 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61 74  .** is always at
b620: 20 6c 65 61 73 74 20 61 73 20 62 69 67 20 61 73   least as big as
b630: 20 74 68 65 20 72 65 71 75 65 73 74 65 64 20 73   the requested s
b640: 69 7a 65 20 62 75 74 20 6d 61 79 20 62 65 20 6c  ize but may be l
b650: 61 72 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  arger..**.** The
b660: 20 78 52 6f 75 6e 64 75 70 20 6d 65 74 68 6f 64   xRoundup method
b670: 20 72 65 74 75 72 6e 73 20 77 68 61 74 20 77 6f   returns what wo
b680: 75 6c 64 20 62 65 20 74 68 65 20 61 6c 6c 6f 63  uld be the alloc
b690: 61 74 65 64 20 73 69 7a 65 20 6f 66 0a 2a 2a 20  ated size of.** 
b6a0: 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  a memory allocat
b6b0: 69 6f 6e 20 67 69 76 65 6e 20 61 20 70 61 72 74  ion given a part
b6c0: 69 63 75 6c 61 72 20 72 65 71 75 65 73 74 65 64  icular requested
b6d0: 20 73 69 7a 65 2e 20 20 4d 6f 73 74 20 6d 65 6d   size.  Most mem
b6e0: 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72  ory.** allocator
b6f0: 73 20 72 6f 75 6e 64 20 75 70 20 6d 65 6d 6f 72  s round up memor
b700: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 61 74  y allocations at
b710: 20 6c 65 61 73 74 20 74 6f 20 74 68 65 20 6e 65   least to the ne
b720: 78 74 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 6f  xt multiple.** o
b730: 66 20 38 2e 20 20 53 6f 6d 65 20 61 6c 6c 6f 63  f 8.  Some alloc
b740: 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20 74  ators round up t
b750: 6f 20 61 20 6c 61 72 67 65 72 20 6d 75 6c 74 69  o a larger multi
b760: 70 6c 65 20 6f 72 20 74 6f 20 61 20 70 6f 77 65  ple or to a powe
b770: 72 20 6f 66 20 32 2e 0a 2a 2a 0a 2a 2a 20 54 68  r of 2..**.** Th
b780: 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 69  e xInit method i
b790: 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65 20 6d  nitializes the m
b7a0: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 2e  emory allocator.
b7b0: 20 20 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 0a    (For example,.
b7c0: 2a 2a 20 69 74 20 6d 69 67 68 74 20 61 6c 6c 6f  ** it might allo
b7d0: 63 61 74 65 20 61 6e 79 20 72 65 71 75 69 72 65  cate any require
b7e0: 20 6d 75 74 65 78 65 73 20 6f 72 20 69 6e 69 74   mutexes or init
b7f0: 69 61 6c 69 7a 65 20 69 6e 74 65 72 6e 61 6c 20  ialize internal 
b800: 64 61 74 61 0a 2a 2a 20 73 74 72 75 63 74 75 72  data.** structur
b810: 65 73 2e 20 20 54 68 65 20 78 53 68 75 74 64 6f  es.  The xShutdo
b820: 77 6e 20 6d 65 74 68 6f 64 20 69 73 20 69 6e 76  wn method is inv
b830: 6f 6b 65 64 20 28 69 6e 64 69 72 65 63 74 6c 79  oked (indirectly
b840: 29 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ) by.** [sqlite3
b850: 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 61 6e 64  _shutdown()] and
b860: 20 73 68 6f 75 6c 64 20 64 65 61 6c 6c 6f 63 61   should dealloca
b870: 74 65 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73  te any resources
b880: 20 61 63 71 75 69 72 65 64 0a 2a 2a 20 62 79 20   acquired.** by 
b890: 78 49 6e 69 74 2e 20 20 54 68 65 20 70 41 70 70  xInit.  The pApp
b8a0: 44 61 74 61 20 70 6f 69 6e 74 65 72 20 69 73 20  Data pointer is 
b8b0: 75 73 65 64 20 61 73 20 74 68 65 20 6f 6e 6c 79  used as the only
b8c0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
b8d0: 20 78 49 6e 69 74 20 61 6e 64 20 78 53 68 75 74   xInit and xShut
b8e0: 64 6f 77 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  down..*/.typedef
b8f0: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
b900: 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69  mem_methods sqli
b910: 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 3b  te3_mem_methods;
b920: 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f  .struct sqlite3_
b930: 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20  mem_methods {.  
b940: 76 6f 69 64 20 2a 28 2a 78 4d 61 6c 6c 6f 63 29  void *(*xMalloc)
b950: 28 69 6e 74 29 3b 20 20 20 20 20 20 20 20 20 2f  (int);         /
b960: 2a 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  * Memory allocat
b970: 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a  ion function */.
b980: 20 20 76 6f 69 64 20 28 2a 78 46 72 65 65 29 28    void (*xFree)(
b990: 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20  void*);         
b9a0: 20 2f 2a 20 46 72 65 65 20 61 20 70 72 69 6f 72   /* Free a prior
b9b0: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20   allocation */. 
b9c0: 20 76 6f 69 64 20 2a 28 2a 78 52 65 61 6c 6c 6f   void *(*xReallo
b9d0: 63 29 28 76 6f 69 64 2a 2c 69 6e 74 29 3b 20 20  c)(void*,int);  
b9e0: 2f 2a 20 52 65 73 69 7a 65 20 61 6e 20 61 6c 6c  /* Resize an all
b9f0: 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74  ocation */.  int
ba00: 20 28 2a 78 53 69 7a 65 29 28 76 6f 69 64 2a 29   (*xSize)(void*)
ba10: 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 52  ;           /* R
ba20: 65 74 75 72 6e 20 74 68 65 20 73 69 7a 65 20 6f  eturn the size o
ba30: 66 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  f an allocation 
ba40: 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 52 6f 75 6e  */.  int (*xRoun
ba50: 64 75 70 29 28 69 6e 74 29 3b 20 20 20 20 20 20  dup)(int);      
ba60: 20 20 20 20 2f 2a 20 52 6f 75 6e 64 20 75 70 20      /* Round up 
ba70: 72 65 71 75 65 73 74 20 73 69 7a 65 20 74 6f 20  request size to 
ba80: 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20  allocation size 
ba90: 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 49 6e 69 74  */.  int (*xInit
baa0: 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20  )(void*);       
bab0: 20 20 20 20 2f 2a 20 49 6e 69 74 69 61 6c 69 7a      /* Initializ
bac0: 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  e the memory all
bad0: 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64  ocator */.  void
bae0: 20 28 2a 78 53 68 75 74 64 6f 77 6e 29 28 76 6f   (*xShutdown)(vo
baf0: 69 64 2a 29 3b 20 20 20 20 20 20 2f 2a 20 44 65  id*);      /* De
bb00: 69 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20 6d  initialize the m
bb10: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20  emory allocator 
bb20: 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 44  */.  void *pAppD
bb30: 61 74 61 3b 20 20 20 20 20 20 20 20 20 20 20 20  ata;            
bb40: 20 20 20 20 2f 2a 20 41 72 67 75 6d 65 6e 74 20      /* Argument 
bb50: 74 6f 20 78 49 6e 69 74 28 29 20 61 6e 64 20 78  to xInit() and x
bb60: 53 68 75 74 64 6f 77 6e 28 29 20 2a 2f 0a 7d 3b  Shutdown() */.};
bb70: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
bb80: 3a 20 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  : Configuration 
bb90: 4f 70 74 69 6f 6e 73 20 7b 48 31 30 31 36 30 7d  Options {H10160}
bba0: 20 3c 53 32 30 30 30 30 3e 0a 2a 2a 20 45 58 50   <S20000>.** EXP
bbb0: 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20  ERIMENTAL.**.** 
bbc0: 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20  These constants 
bbd0: 61 72 65 20 74 68 65 20 61 76 61 69 6c 61 62 6c  are the availabl
bbe0: 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 67  e integer config
bbf0: 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20  uration options 
bc00: 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70  that.** can be p
bc10: 61 73 73 65 64 20 61 73 20 74 68 65 20 66 69 72  assed as the fir
bc20: 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  st argument to t
bc30: 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  he [sqlite3_conf
bc40: 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e  ig()] interface.
bc50: 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69  .**.** New confi
bc60: 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73  guration options
bc70: 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e   may be added in
bc80: 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   future releases
bc90: 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45   of SQLite..** E
bca0: 78 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 72  xisting configur
bcb0: 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69  ation options mi
bcc0: 67 68 74 20 62 65 20 64 69 73 63 6f 6e 74 69 6e  ght be discontin
bcd0: 75 65 64 2e 20 20 41 70 70 6c 69 63 61 74 69 6f  ued.  Applicatio
bce0: 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65  ns.** should che
bcf0: 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f  ck the return co
bd00: 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  de from [sqlite3
bd10: 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61  _config()] to ma
bd20: 6b 65 20 73 75 72 65 20 74 68 61 74 0a 2a 2a 20  ke sure that.** 
bd30: 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e  the call worked.
bd40: 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63    The [sqlite3_c
bd50: 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61  onfig()] interfa
bd60: 63 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61  ce will return a
bd70: 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72  .** non-zero [er
bd80: 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20 64  ror code] if a d
bd90: 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75  iscontinued or u
bda0: 6e 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 69  nsupported confi
bdb0: 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a  guration option.
bdc0: 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a  ** is invoked..*
bdd0: 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74  *.** <dl>.** <dt
bde0: 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  >SQLITE_CONFIG_S
bdf0: 49 4e 47 4c 45 54 48 52 45 41 44 3c 2f 64 74 3e  INGLETHREAD</dt>
be00: 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72  .** <dd>There ar
be10: 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74  e no arguments t
be20: 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20  o this option.  
be30: 54 68 69 73 20 6f 70 74 69 6f 6e 20 64 69 73 61  This option disa
be40: 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65  bles.** all mute
be50: 78 69 6e 67 20 61 6e 64 20 70 75 74 73 20 53 51  xing and puts SQ
be60: 4c 69 74 65 20 69 6e 74 6f 20 61 20 6d 6f 64 65  Lite into a mode
be70: 20 77 68 65 72 65 20 69 74 20 63 61 6e 20 6f 6e   where it can on
be80: 6c 79 20 62 65 20 75 73 65 64 0a 2a 2a 20 62 79  ly be used.** by
be90: 20 61 20 73 69 6e 67 6c 65 20 74 68 72 65 61 64   a single thread
bea0: 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74  .</dd>.**.** <dt
beb0: 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  >SQLITE_CONFIG_M
bec0: 55 4c 54 49 54 48 52 45 41 44 3c 2f 64 74 3e 0a  ULTITHREAD</dt>.
bed0: 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65  ** <dd>There are
bee0: 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f   no arguments to
bef0: 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 54   this option.  T
bf00: 68 69 73 20 6f 70 74 69 6f 6e 20 64 69 73 61 62  his option disab
bf10: 6c 65 73 0a 2a 2a 20 6d 75 74 65 78 69 6e 67 20  les.** mutexing 
bf20: 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  on [database con
bf30: 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72  nection] and [pr
bf40: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
bf50: 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 54 68  ] objects..** Th
bf60: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73  e application is
bf70: 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72   responsible for
bf80: 20 73 65 72 69 61 6c 69 7a 69 6e 67 20 61 63 63   serializing acc
bf90: 65 73 73 20 74 6f 0a 2a 2a 20 5b 64 61 74 61 62  ess to.** [datab
bfa0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d  ase connections]
bfb0: 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73   and [prepared s
bfc0: 74 61 74 65 6d 65 6e 74 73 5d 2e 20 20 42 75 74  tatements].  But
bfd0: 20 6f 74 68 65 72 20 6d 75 74 65 78 65 73 0a 2a   other mutexes.*
bfe0: 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20 73 6f  * are enabled so
bff0: 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c   that SQLite wil
c000: 6c 20 62 65 20 73 61 66 65 20 74 6f 20 75 73 65  l be safe to use
c010: 20 69 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72 65   in a multi-thre
c020: 61 64 65 64 0a 2a 2a 20 65 6e 76 69 72 6f 6e 6d  aded.** environm
c030: 65 6e 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ent.</dd>.**.** 
c040: 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
c050: 47 5f 53 45 52 49 41 4c 49 5a 45 44 3c 2f 64 74  G_SERIALIZED</dt
c060: 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61  >.** <dd>There a
c070: 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20  re no arguments 
c080: 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20  to this option. 
c090: 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 65 6e 61   This option ena
c0a0: 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65  bles.** all mute
c0b0: 78 65 73 20 69 6e 63 6c 75 64 69 6e 67 20 74 68  xes including th
c0c0: 65 20 72 65 63 75 72 73 69 76 65 0a 2a 2a 20 6d  e recursive.** m
c0d0: 75 74 65 78 65 73 20 6f 6e 20 5b 64 61 74 61 62  utexes on [datab
c0e0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
c0f0: 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74  and [prepared st
c100: 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73  atement] objects
c110: 2e 0a 2a 2a 20 49 6e 20 74 68 69 73 20 6d 6f 64  ..** In this mod
c120: 65 20 28 77 68 69 63 68 20 69 73 20 74 68 65 20  e (which is the 
c130: 64 65 66 61 75 6c 74 20 77 68 65 6e 20 53 51 4c  default when SQL
c140: 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
c150: 77 69 74 68 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  with.** [SQLITE_
c160: 54 48 52 45 41 44 53 41 46 45 3d 31 5d 29 20 74  THREADSAFE=1]) t
c170: 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72  he SQLite librar
c180: 79 20 77 69 6c 6c 20 69 74 73 65 6c 66 20 73 65  y will itself se
c190: 72 69 61 6c 69 7a 65 20 61 63 63 65 73 73 0a 2a  rialize access.*
c1a0: 2a 20 74 6f 20 5b 64 61 74 61 62 61 73 65 20 63  * to [database c
c1b0: 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20  onnections] and 
c1c0: 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
c1d0: 65 6e 74 73 5d 20 73 6f 20 74 68 61 74 20 74 68  ents] so that th
c1e0: 65 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e  e.** application
c1f0: 20 69 73 20 66 72 65 65 20 74 6f 20 75 73 65 20   is free to use 
c200: 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61  the same [databa
c210: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f  se connection] o
c220: 72 20 74 68 65 0a 2a 2a 20 73 61 6d 65 20 5b 70  r the.** same [p
c230: 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
c240: 74 5d 20 69 6e 20 64 69 66 66 65 72 65 6e 74 20  t] in different 
c250: 74 68 72 65 61 64 73 20 61 74 20 74 68 65 20 73  threads at the s
c260: 61 6d 65 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20  ame time..**.** 
c270: 3c 70 3e 54 68 69 73 20 63 6f 6e 66 69 67 75 72  <p>This configur
c280: 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 6d 65 72  ation option mer
c290: 65 6c 79 20 73 65 74 73 20 74 68 65 20 64 65 66  ely sets the def
c2a0: 61 75 6c 74 20 6d 75 74 65 78 20 0a 2a 2a 20 62  ault mutex .** b
c2b0: 65 68 61 76 69 6f 72 20 74 6f 20 73 65 72 69 61  ehavior to seria
c2c0: 6c 69 7a 65 20 61 63 63 65 73 73 20 74 6f 20 5b  lize access to [
c2d0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
c2e0: 69 6f 6e 73 5d 2e 20 20 49 6e 64 69 76 69 64 75  ions].  Individu
c2f0: 61 6c 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  al.** [database 
c300: 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 63 61 6e  connections] can
c310: 20 6f 76 65 72 72 69 64 65 20 74 68 69 73 20 73   override this s
c320: 65 74 74 69 6e 67 0a 2a 2a 20 75 73 69 6e 67 20  etting.** using 
c330: 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  the [SQLITE_OPEN
c340: 5f 4e 4f 4d 55 54 45 58 5d 20 66 6c 61 67 20 74  _NOMUTEX] flag t
c350: 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  o [sqlite3_open_
c360: 76 32 28 29 5d 2e 3c 2f 70 3e 3c 2f 64 64 3e 0a  v2()].</p></dd>.
c370: 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
c380: 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 3c 2f  _CONFIG_MALLOC</
c390: 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20  dt>.** <dd>This 
c3a0: 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73  option takes a s
c3b0: 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77  ingle argument w
c3c0: 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65  hich is a pointe
c3d0: 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61  r to an.** insta
c3e0: 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  nce of the [sqli
c3f0: 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d  te3_mem_methods]
c400: 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 65   structure.  The
c410: 20 61 72 67 75 6d 65 6e 74 20 73 70 65 63 69 66   argument specif
c420: 69 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69  ies.** alternati
c430: 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d  ve low-level mem
c440: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72  ory allocation r
c450: 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73  outines to be us
c460: 65 64 20 69 6e 20 70 6c 61 63 65 20 6f 66 0a 2a  ed in place of.*
c470: 2a 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  * the memory all
c480: 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73  ocation routines
c490: 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69   built into SQLi
c4a0: 74 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  te.</dd>.**.** <
c4b0: 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
c4c0: 5f 47 45 54 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a  _GETMALLOC</dt>.
c4d0: 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69  ** <dd>This opti
c4e0: 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
c4f0: 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  e argument which
c500: 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
c510: 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20   an.** instance 
c520: 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
c530: 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72  mem_methods] str
c540: 75 63 74 75 72 65 2e 20 20 54 68 65 20 5b 73 71  ucture.  The [sq
c550: 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
c560: 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20  s].** structure 
c570: 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74  is filled with t
c580: 68 65 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66  he currently def
c590: 69 6e 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ined memory allo
c5a0: 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e  cation routines.
c5b0: 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20  .** This option 
c5c0: 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f  can be used to o
c5d0: 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61  verload the defa
c5e0: 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ult memory alloc
c5f0: 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65  ation.** routine
c600: 73 20 77 69 74 68 20 61 20 77 72 61 70 70 65 72  s with a wrapper
c610: 20 74 68 61 74 20 73 69 6d 75 6c 61 74 69 6f 6e   that simulation
c620: 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  s memory allocat
c630: 69 6f 6e 20 66 61 69 6c 75 72 65 20 6f 72 0a 2a  ion failure or.*
c640: 2a 20 74 72 61 63 6b 73 20 6d 65 6d 6f 72 79 20  * tracks memory 
c650: 75 73 61 67 65 2c 20 66 6f 72 20 65 78 61 6d 70  usage, for examp
c660: 6c 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  le.</dd>.**.** <
c670: 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
c680: 5f 4d 45 4d 53 54 41 54 55 53 3c 2f 64 74 3e 0a  _MEMSTATUS</dt>.
c690: 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69  ** <dd>This opti
c6a0: 6f 6e 20 74 61 6b 65 73 20 73 69 6e 67 6c 65 20  on takes single 
c6b0: 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 79 70 65  argument of type
c6c0: 20 69 6e 74 2c 20 69 6e 74 65 72 70 72 65 74 65   int, interprete
c6d0: 64 20 61 73 20 61 20 0a 2a 2a 20 62 6f 6f 6c 65  d as a .** boole
c6e0: 61 6e 2c 20 77 68 69 63 68 20 65 6e 61 62 6c 65  an, which enable
c6f0: 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68  s or disables th
c700: 65 20 63 6f 6c 6c 65 63 74 69 6f 6e 20 6f 66 20  e collection of 
c710: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
c720: 6e 20 0a 2a 2a 20 73 74 61 74 69 73 74 69 63 73  n .** statistics
c730: 2e 20 57 68 65 6e 20 64 69 73 61 62 6c 65 64 2c  . When disabled,
c740: 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 53   the following S
c750: 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73  QLite interfaces
c760: 20 62 65 63 6f 6d 65 20 0a 2a 2a 20 6e 6f 6e 2d   become .** non-
c770: 6f 70 65 72 61 74 69 6f 6e 61 6c 3a 0a 2a 2a 20  operational:.** 
c780: 20 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e    <ul>.**   <li>
c790: 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
c7a0: 5f 75 73 65 64 28 29 5d 0a 2a 2a 20 20 20 3c 6c  _used()].**   <l
c7b0: 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  i> [sqlite3_memo
c7c0: 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 0a  ry_highwater()].
c7d0: 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74  **   <li> [sqlit
c7e0: 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d  e3_soft_heap_lim
c7f0: 69 74 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20  it()].**   <li> 
c800: 5b 73 71 6c 69 74 65 33 5f 73 74 61 74 75 73 28  [sqlite3_status(
c810: 29 5d 0a 2a 2a 20 20 20 3c 2f 75 6c 3e 0a 2a 2a  )].**   </ul>.**
c820: 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74   </dd>.**.** <dt
c830: 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  >SQLITE_CONFIG_S
c840: 43 52 41 54 43 48 3c 2f 64 74 3e 0a 2a 2a 20 3c  CRATCH</dt>.** <
c850: 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73  dd>This option s
c860: 70 65 63 69 66 69 65 73 20 61 20 73 74 61 74 69  pecifies a stati
c870: 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20  c memory buffer 
c880: 74 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20  that SQLite can 
c890: 75 73 65 20 66 6f 72 0a 2a 2a 20 73 63 72 61 74  use for.** scrat
c8a0: 63 68 20 6d 65 6d 6f 72 79 2e 20 20 54 68 65 72  ch memory.  Ther
c8b0: 65 20 61 72 65 20 74 68 72 65 65 20 61 72 67 75  e are three argu
c8c0: 6d 65 6e 74 73 3a 20 20 41 20 70 6f 69 6e 74 65  ments:  A pointe
c8d0: 72 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79 2c  r to the memory,
c8e0: 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20   the.** size of 
c8f0: 65 61 63 68 20 73 63 72 61 74 63 68 20 62 75 66  each scratch buf
c900: 66 65 72 20 28 73 7a 29 2c 20 61 6e 64 20 74 68  fer (sz), and th
c910: 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 75 66 66  e number of buff
c920: 65 72 73 20 28 4e 29 2e 20 20 54 68 65 20 73 7a  ers (N).  The sz
c930: 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6d 75 73  .** argument mus
c940: 74 20 62 65 20 61 20 6d 75 6c 74 69 70 6c 65 20  t be a multiple 
c950: 6f 66 20 31 36 2e 20 54 68 65 20 73 7a 20 70 61  of 16. The sz pa
c960: 72 61 6d 65 74 65 72 20 73 68 6f 75 6c 64 20 62  rameter should b
c970: 65 20 61 20 66 65 77 20 62 79 74 65 73 0a 2a 2a  e a few bytes.**
c980: 20 6c 61 72 67 65 72 20 74 68 61 6e 20 74 68 65   larger than the
c990: 20 61 63 74 75 61 6c 20 73 63 72 61 74 63 68 20   actual scratch 
c9a0: 73 70 61 63 65 20 72 65 71 75 69 72 65 64 20 64  space required d
c9b0: 75 65 20 69 6e 74 65 72 6e 61 6c 20 6f 76 65 72  ue internal over
c9c0: 68 65 61 64 2e 0a 2a 2a 20 54 68 65 20 66 69 72  head..** The fir
c9d0: 73 74 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 73  st.** argument s
c9e0: 68 6f 75 6c 64 20 70 6f 69 6e 74 20 74 6f 20 61  hould point to a
c9f0: 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 66 20  n allocation of 
ca00: 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79  at least sz*N by
ca10: 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a  tes of memory..*
ca20: 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73  * SQLite will us
ca30: 65 20 6e 6f 20 6d 6f 72 65 20 74 68 61 6e 20 6f  e no more than o
ca40: 6e 65 20 73 63 72 61 74 63 68 20 62 75 66 66 65  ne scratch buffe
ca50: 72 20 61 74 20 6f 6e 63 65 20 70 65 72 20 74 68  r at once per th
ca60: 72 65 61 64 2c 20 73 6f 0a 2a 2a 20 4e 20 73 68  read, so.** N sh
ca70: 6f 75 6c 64 20 62 65 20 73 65 74 20 74 6f 20 74  ould be set to t
ca80: 68 65 20 65 78 70 65 63 74 65 64 20 6d 61 78 69  he expected maxi
ca90: 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74 68  mum number of th
caa0: 72 65 61 64 73 2e 20 20 54 68 65 20 73 7a 0a 2a  reads.  The sz.*
cab0: 2a 20 70 61 72 61 6d 65 74 65 72 20 73 68 6f 75  * parameter shou
cac0: 6c 64 20 62 65 20 36 20 74 69 6d 65 73 20 74 68  ld be 6 times th
cad0: 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6c 61  e size of the la
cae0: 72 67 65 73 74 20 64 61 74 61 62 61 73 65 20 70  rgest database p
caf0: 61 67 65 20 73 69 7a 65 2e 0a 2a 2a 20 53 63 72  age size..** Scr
cb00: 61 74 63 68 20 62 75 66 66 65 72 73 20 61 72 65  atch buffers are
cb10: 20 75 73 65 64 20 61 73 20 70 61 72 74 20 6f 66   used as part of
cb20: 20 74 68 65 20 62 74 72 65 65 20 62 61 6c 61 6e   the btree balan
cb30: 63 65 20 6f 70 65 72 61 74 69 6f 6e 2e 20 20 49  ce operation.  I
cb40: 66 0a 2a 2a 20 54 68 65 20 62 74 72 65 65 20 62  f.** The btree b
cb50: 61 6c 61 6e 63 65 72 20 6e 65 65 64 73 20 61 64  alancer needs ad
cb60: 64 69 74 69 6f 6e 61 6c 20 6d 65 6d 6f 72 79 20  ditional memory 
cb70: 62 65 79 6f 6e 64 20 77 68 61 74 20 69 73 20 70  beyond what is p
cb80: 72 6f 76 69 64 65 64 20 62 79 0a 2a 2a 20 73 63  rovided by.** sc
cb90: 72 61 74 63 68 20 62 75 66 66 65 72 73 20 6f 72  ratch buffers or
cba0: 20 69 66 20 6e 6f 20 73 63 72 61 74 63 68 20 62   if no scratch b
cbb0: 75 66 66 65 72 20 73 70 61 63 65 20 69 73 20 73  uffer space is s
cbc0: 70 65 63 69 66 69 65 64 2c 20 74 68 65 6e 20 53  pecified, then S
cbd0: 51 4c 69 74 65 0a 2a 2a 20 67 6f 65 73 20 74 6f  QLite.** goes to
cbe0: 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
cbf0: 28 29 5d 20 74 6f 20 6f 62 74 61 69 6e 20 74 68  ()] to obtain th
cc00: 65 20 6d 65 6d 6f 72 79 20 69 74 20 6e 65 65 64  e memory it need
cc10: 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  s.</dd>.**.** <d
cc20: 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
cc30: 50 41 47 45 43 41 43 48 45 3c 2f 64 74 3e 0a 2a  PAGECACHE</dt>.*
cc40: 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f  * <dd>This optio
cc50: 6e 20 73 70 65 63 69 66 69 65 73 20 61 20 73 74  n specifies a st
cc60: 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66  atic memory buff
cc70: 65 72 20 74 68 61 74 20 53 51 4c 69 74 65 20 63  er that SQLite c
cc80: 61 6e 20 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68  an use for.** th
cc90: 65 20 64 61 74 61 62 61 73 65 20 70 61 67 65 20  e database page 
cca0: 63 61 63 68 65 2e 20 20 54 68 65 72 65 20 61 72  cache.  There ar
ccb0: 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74  e three argument
ccc0: 73 3a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20  s: A pointer to 
ccd0: 74 68 65 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 74  the.** memory, t
cce0: 68 65 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20  he size of each 
ccf0: 70 61 67 65 20 62 75 66 66 65 72 20 28 73 7a 29  page buffer (sz)
cd00: 2c 20 61 6e 64 20 74 68 65 20 6e 75 6d 62 65 72  , and the number
cd10: 20 6f 66 20 70 61 67 65 73 20 28 4e 29 2e 0a 2a   of pages (N)..*
cd20: 2a 20 54 68 65 20 73 7a 20 61 72 67 75 6d 65 6e  * The sz argumen
cd30: 74 20 6d 75 73 74 20 62 65 20 61 20 70 6f 77 65  t must be a powe
cd40: 72 20 6f 66 20 74 77 6f 20 62 65 74 77 65 65 6e  r of two between
cd50: 20 35 31 32 20 61 6e 64 20 33 32 37 36 38 2e 20   512 and 32768. 
cd60: 20 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 61 72   The first.** ar
cd70: 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 70 6f  gument should po
cd80: 69 6e 74 20 74 6f 20 61 6e 20 61 6c 6c 6f 63 61  int to an alloca
cd90: 74 69 6f 6e 20 6f 66 20 61 74 20 6c 65 61 73 74  tion of at least
cda0: 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d   sz*N bytes of m
cdb0: 65 6d 6f 72 79 2e 0a 2a 2a 20 53 51 4c 69 74 65  emory..** SQLite
cdc0: 20 77 69 6c 6c 20 75 73 65 20 74 68 65 20 6d 65   will use the me
cdd0: 6d 6f 72 79 20 70 72 6f 76 69 64 65 64 20 62 79  mory provided by
cde0: 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
cdf0: 65 6e 74 20 74 6f 20 73 61 74 69 73 66 79 20 69  ent to satisfy i
ce00: 74 73 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6e 65 65  ts.** memory nee
ce10: 64 73 20 66 6f 72 20 74 68 65 20 66 69 72 73 74  ds for the first
ce20: 20 4e 20 70 61 67 65 73 20 74 68 61 74 20 69 74   N pages that it
ce30: 20 61 64 64 73 20 74 6f 20 63 61 63 68 65 2e 20   adds to cache. 
ce40: 20 49 66 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a   If additional.*
ce50: 2a 20 70 61 67 65 20 63 61 63 68 65 20 6d 65 6d  * page cache mem
ce60: 6f 72 79 20 69 73 20 6e 65 65 64 65 64 20 62 65  ory is needed be
ce70: 79 6f 6e 64 20 77 68 61 74 20 69 73 20 70 72 6f  yond what is pro
ce80: 76 69 64 65 64 20 62 79 20 74 68 69 73 20 6f 70  vided by this op
ce90: 74 69 6f 6e 2c 20 74 68 65 6e 0a 2a 2a 20 53 51  tion, then.** SQ
cea0: 4c 69 74 65 20 67 6f 65 73 20 74 6f 20 5b 73 71  Lite goes to [sq
ceb0: 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
cec0: 66 6f 72 20 74 68 65 20 61 64 64 69 74 69 6f 6e  for the addition
ced0: 61 6c 20 73 74 6f 72 61 67 65 20 73 70 61 63 65  al storage space
cee0: 2e 0a 2a 2a 20 54 68 65 20 69 6d 70 6c 65 6d 65  ..** The impleme
cef0: 6e 74 61 74 69 6f 6e 20 6d 69 67 68 74 20 75 73  ntation might us
cf00: 65 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66  e one or more of
cf10: 20 74 68 65 20 4e 20 62 75 66 66 65 72 73 20 74   the N buffers t
cf20: 6f 20 68 6f 6c 64 20 0a 2a 2a 20 6d 65 6d 6f 72  o hold .** memor
cf30: 79 20 61 63 63 6f 75 6e 74 69 6e 67 20 69 6e 66  y accounting inf
cf40: 6f 72 6d 61 74 69 6f 6e 2e 20 3c 2f 64 64 3e 0a  ormation. </dd>.
cf50: 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
cf60: 5f 43 4f 4e 46 49 47 5f 48 45 41 50 3c 2f 64 74  _CONFIG_HEAP</dt
cf70: 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70  >.** <dd>This op
cf80: 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61  tion specifies a
cf90: 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62   static memory b
cfa0: 75 66 66 65 72 20 74 68 61 74 20 53 51 4c 69 74  uffer that SQLit
cfb0: 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 66 6f  e will use.** fo
cfc0: 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 64 79 6e  r all of its dyn
cfd0: 61 6d 69 63 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  amic memory allo
cfe0: 63 61 74 69 6f 6e 20 6e 65 65 64 73 20 62 65 79  cation needs bey
cff0: 6f 6e 64 20 74 68 6f 73 65 20 70 72 6f 76 69 64  ond those provid
d000: 65 64 0a 2a 2a 20 66 6f 72 20 62 79 20 5b 53 51  ed.** for by [SQ
d010: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41  LITE_CONFIG_SCRA
d020: 54 43 48 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45  TCH] and [SQLITE
d030: 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48  _CONFIG_PAGECACH
d040: 45 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65  E]..** There are
d050: 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73   three arguments
d060: 3a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  : A pointer to t
d070: 68 65 20 6d 65 6d 6f 72 79 2c 20 74 68 65 20 6e  he memory, the n
d080: 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 62 79 74 65  umber of.** byte
d090: 73 20 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20  s in the memory 
d0a0: 62 75 66 66 65 72 2c 20 61 6e 64 20 74 68 65 20  buffer, and the 
d0b0: 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69  minimum allocati
d0c0: 6f 6e 20 73 69 7a 65 2e 20 20 49 66 0a 2a 2a 20  on size.  If.** 
d0d0: 74 68 65 20 66 69 72 73 74 20 70 6f 69 6e 74 65  the first pointe
d0e0: 72 20 28 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f  r (the memory po
d0f0: 69 6e 74 65 72 29 20 69 73 20 4e 55 4c 4c 2c 20  inter) is NULL, 
d100: 74 68 65 6e 20 53 51 4c 69 74 65 20 72 65 76 65  then SQLite reve
d110: 72 74 73 0a 2a 2a 20 74 6f 20 75 73 69 6e 67 20  rts.** to using 
d120: 69 74 73 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f  its default memo
d130: 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 28 74 68  ry allocator (th
d140: 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28  e system malloc(
d150: 29 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  ) implementation
d160: 29 2c 0a 2a 2a 20 75 6e 64 6f 69 6e 67 20 61 6e  ),.** undoing an
d170: 79 20 70 72 69 6f 72 20 69 6e 76 6f 63 61 74 69  y prior invocati
d180: 6f 6e 20 6f 66 20 5b 53 51 4c 49 54 45 5f 43 4f  on of [SQLITE_CO
d190: 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 2e 20 20 49  NFIG_MALLOC].  I
d1a0: 66 20 74 68 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20  f the.** memory 
d1b0: 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e  pointer is not N
d1c0: 55 4c 4c 20 61 6e 64 20 65 69 74 68 65 72 20 5b  ULL and either [
d1d0: 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45  SQLITE_ENABLE_ME
d1e0: 4d 53 59 53 33 5d 20 6f 72 0a 2a 2a 20 5b 53 51  MSYS3] or.** [SQ
d1f0: 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53  LITE_ENABLE_MEMS
d200: 59 53 35 5d 20 61 72 65 20 64 65 66 69 6e 65 64  YS5] are defined
d210: 2c 20 74 68 65 6e 20 74 68 65 20 61 6c 74 65 72  , then the alter
d220: 6e 61 74 69 76 65 20 6d 65 6d 6f 72 79 0a 2a 2a  native memory.**
d230: 20 61 6c 6c 6f 63 61 74 6f 72 20 69 73 20 65 6e   allocator is en
d240: 67 61 67 65 64 20 74 6f 20 68 61 6e 64 6c 65 20  gaged to handle 
d250: 61 6c 6c 20 6f 66 20 53 51 4c 69 74 65 73 20 6d  all of SQLites m
d260: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
d270: 20 6e 65 65 64 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a   needs.</dd>.**.
d280: 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ** <dt>SQLITE_CO
d290: 4e 46 49 47 5f 4d 55 54 45 58 3c 2f 64 74 3e 0a  NFIG_MUTEX</dt>.
d2a0: 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69  ** <dd>This opti
d2b0: 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
d2c0: 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  e argument which
d2d0: 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
d2e0: 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20   an.** instance 
d2f0: 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
d300: 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73  mutex_methods] s
d310: 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 20 61  tructure.  The a
d320: 72 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65  rgument specifie
d330: 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76 65  s.** alternative
d340: 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 75 74 65 78   low-level mutex
d350: 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20   routines to be 
d360: 75 73 65 64 20 69 6e 20 70 6c 61 63 65 0a 2a 2a  used in place.**
d370: 20 74 68 65 20 6d 75 74 65 78 20 72 6f 75 74 69   the mutex routi
d380: 6e 65 73 20 62 75 69 6c 74 20 69 6e 74 6f 20 53  nes built into S
d390: 51 4c 69 74 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  QLite.</dd>.**.*
d3a0: 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
d3b0: 46 49 47 5f 47 45 54 4d 55 54 45 58 3c 2f 64 74  FIG_GETMUTEX</dt
d3c0: 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70  >.** <dd>This op
d3d0: 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e  tion takes a sin
d3e0: 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69  gle argument whi
d3f0: 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  ch is a pointer 
d400: 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63  to an.** instanc
d410: 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  e of the [sqlite
d420: 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d  3_mutex_methods]
d430: 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 65   structure.  The
d440: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  .** [sqlite3_mut
d450: 65 78 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73  ex_methods].** s
d460: 74 72 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c  tructure is fill
d470: 65 64 20 77 69 74 68 20 74 68 65 20 63 75 72 72  ed with the curr
d480: 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 75  ently defined mu
d490: 74 65 78 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a  tex routines..**
d4a0: 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e   This option can
d4b0: 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72   be used to over
d4c0: 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c 74  load the default
d4d0: 20 6d 75 74 65 78 20 61 6c 6c 6f 63 61 74 69 6f   mutex allocatio
d4e0: 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 69  n.** routines wi
d4f0: 74 68 20 61 20 77 72 61 70 70 65 72 20 75 73 65  th a wrapper use
d500: 64 20 74 6f 20 74 72 61 63 6b 20 6d 75 74 65 78  d to track mutex
d510: 20 75 73 61 67 65 20 66 6f 72 20 70 65 72 66 6f   usage for perfo
d520: 72 6d 61 6e 63 65 0a 2a 2a 20 70 72 6f 66 69 6c  rmance.** profil
d530: 69 6e 67 20 6f 72 20 74 65 73 74 69 6e 67 2c 20  ing or testing, 
d540: 66 6f 72 20 65 78 61 6d 70 6c 65 2e 3c 2f 64 64  for example.</dd
d550: 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
d560: 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  TE_CONFIG_LOOKAS
d570: 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  IDE</dt>.** <dd>
d580: 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65  This option take
d590: 73 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 20  s two arguments 
d5a0: 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65 20 74  that determine t
d5b0: 68 65 20 64 65 66 61 75 6c 74 0a 2a 2a 20 6d 65  he default.** me
d5c0: 6d 6f 72 79 20 61 6c 6c 63 61 74 69 6f 6e 20 6c  mory allcation l
d5d0: 6f 6f 6b 61 73 69 64 65 20 6f 70 74 69 6d 69 7a  ookaside optimiz
d5e0: 61 74 69 6f 6e 2e 20 20 54 68 65 20 66 69 72 73  ation.  The firs
d5f0: 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68  t argument is th
d600: 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61 63  e.** size of eac
d610: 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66  h lookaside buff
d620: 65 72 20 73 6c 6f 74 20 61 6e 64 20 74 68 65 20  er slot and the 
d630: 73 65 63 6f 6e 64 20 69 73 20 74 68 65 20 6e 75  second is the nu
d640: 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73  mber of.** slots
d650: 20 61 6c 6c 6f 63 61 74 65 64 20 74 6f 20 65 61   allocated to ea
d660: 63 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ch database conn
d670: 65 63 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a  ection.</dd>.**.
d680: 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66  ** </dl>.*/.#def
d690: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
d6a0: 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 20 20  G_SINGLETHREAD  
d6b0: 31 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65  1  /* nil */.#de
d6c0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
d6d0: 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 20 20  IG_MULTITHREAD  
d6e0: 20 32 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64   2  /* nil */.#d
d6f0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
d700: 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 20 20  FIG_SERIALIZED  
d710: 20 20 33 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23    3  /* nil */.#
d720: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
d730: 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20 20 20 20 20  NFIG_MALLOC     
d740: 20 20 20 34 20 20 2f 2a 20 73 71 6c 69 74 65 33     4  /* sqlite3
d750: 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f  _mem_methods* */
d760: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
d770: 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43  CONFIG_GETMALLOC
d780: 20 20 20 20 20 35 20 20 2f 2a 20 73 71 6c 69 74       5  /* sqlit
d790: 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20  e3_mem_methods* 
d7a0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
d7b0: 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48  E_CONFIG_SCRATCH
d7c0: 20 20 20 20 20 20 20 36 20 20 2f 2a 20 76 6f 69         6  /* voi
d7d0: 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20  d*, int sz, int 
d7e0: 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  N */.#define SQL
d7f0: 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43  ITE_CONFIG_PAGEC
d800: 41 43 48 45 20 20 20 20 20 37 20 20 2f 2a 20 76  ACHE     7  /* v
d810: 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e  oid*, int sz, in
d820: 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  t N */.#define S
d830: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41  QLITE_CONFIG_HEA
d840: 50 20 20 20 20 20 20 20 20 20 20 38 20 20 2f 2a  P          8  /*
d850: 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 42 79 74   void*, int nByt
d860: 65 2c 20 69 6e 74 20 6d 69 6e 20 2a 2f 0a 23 64  e, int min */.#d
d870: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
d880: 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 20 20 20  FIG_MEMSTATUS   
d890: 20 20 39 20 20 2f 2a 20 62 6f 6f 6c 65 61 6e 20    9  /* boolean 
d8a0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
d8b0: 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 20  E_CONFIG_MUTEX  
d8c0: 20 20 20 20 20 20 31 30 20 20 2f 2a 20 73 71 6c        10  /* sql
d8d0: 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f  ite3_mutex_metho
d8e0: 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ds* */.#define S
d8f0: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
d900: 4d 55 54 45 58 20 20 20 20 20 31 31 20 20 2f 2a  MUTEX     11  /*
d910: 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d   sqlite3_mutex_m
d920: 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69  ethods* */.#defi
d930: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
d940: 5f 43 48 55 4e 4b 41 4c 4c 4f 43 20 20 20 31 32  _CHUNKALLOC   12
d950: 20 20 2f 2a 20 69 6e 74 20 74 68 72 65 73 68 6f    /* int thresho
d960: 6c 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ld */.#define SQ
d970: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  LITE_CONFIG_LOOK
d980: 41 53 49 44 45 20 20 20 20 31 33 20 20 2f 2a 20  ASIDE    13  /* 
d990: 69 6e 74 20 69 6e 74 20 2a 2f 0a 0a 2f 2a 0a 2a  int int */../*.*
d9a0: 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66  * CAPI3REF: Conf
d9b0: 69 67 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e  iguration Option
d9c0: 73 20 7b 48 31 30 31 37 30 7d 20 3c 53 32 30 30  s {H10170} <S200
d9d0: 30 30 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e  00>.** EXPERIMEN
d9e0: 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  TAL.**.** These 
d9f0: 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 74 68  constants are th
da00: 65 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 74 65  e available inte
da10: 67 65 72 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ger configuratio
da20: 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a  n options that.*
da30: 2a 20 63 61 6e 20 62 65 20 70 61 73 73 65 64 20  * can be passed 
da40: 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72  as the second ar
da50: 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 73  gument to the [s
da60: 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
da70: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  ()] interface..*
da80: 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75  *.** New configu
da90: 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d  ration options m
daa0: 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66  ay be added in f
dab0: 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f  uture releases o
dac0: 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69  f SQLite..** Exi
dad0: 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74  sting configurat
dae0: 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68  ion options migh
daf0: 74 20 62 65 20 64 69 73 63 6f 6e 74 69 6e 75 65  t be discontinue
db00: 64 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  d.  Applications
db10: 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65 63 6b  .** should check
db20: 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65   the return code
db30: 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 64   from [sqlite3_d
db40: 62 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d  b_config()] to m
db50: 61 6b 65 20 73 75 72 65 20 74 68 61 74 0a 2a 2a  ake sure that.**
db60: 20 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64   the call worked
db70: 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  .  The [sqlite3_
db80: 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74  db_config()] int
db90: 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65 74 75  erface will retu
dba0: 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f  rn a.** non-zero
dbb0: 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66   [error code] if
dbc0: 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 20   a discontinued 
dbd0: 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64 20 63  or unsupported c
dbe0: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
dbf0: 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65  ion.** is invoke
dc00: 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a  d..**.** <dl>.**
dc10: 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f   <dt>SQLITE_DBCO
dc20: 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f  NFIG_LOOKASIDE</
dc30: 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20  dt>.** <dd>This 
dc40: 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 68 72  option takes thr
dc50: 65 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72  ee additional ar
dc60: 67 75 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74  guments that det
dc70: 65 72 6d 69 6e 65 20 74 68 65 20 0a 2a 2a 20 5b  ermine the .** [
dc80: 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79  lookaside memory
dc90: 20 61 6c 6c 6f 63 61 74 6f 72 5d 20 63 6f 6e 66   allocator] conf
dca0: 69 67 75 72 61 74 69 6f 6e 20 66 6f 72 20 74 68  iguration for th
dcb0: 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
dcc0: 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 54 68 65 20  ection]..** The 
dcd0: 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 28  first argument (
dce0: 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
dcf0: 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ter to [sqlite3_
dd00: 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 73 20  db_config()] is 
dd10: 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20  a.** pointer to 
dd20: 61 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20  a memory buffer 
dd30: 74 6f 20 75 73 65 20 66 6f 72 20 6c 6f 6f 6b 61  to use for looka
dd40: 73 69 64 65 20 6d 65 6d 6f 72 79 2e 20 20 54 68  side memory.  Th
dd50: 65 20 66 69 72 73 74 0a 2a 2a 20 61 72 67 75 6d  e first.** argum
dd60: 65 6e 74 20 6d 61 79 20 62 65 20 4e 55 4c 4c 20  ent may be NULL 
dd70: 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 53 51  in which case SQ
dd80: 4c 69 74 65 20 77 69 6c 6c 20 61 6c 6c 6f 63 61  Lite will alloca
dd90: 74 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65  te the lookaside
dda0: 0a 2a 2a 20 62 75 66 66 65 72 20 69 74 73 65 6c  .** buffer itsel
ddb0: 66 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  f using [sqlite3
ddc0: 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 20 54 68 65  _malloc()].  The
ddd0: 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
dde0: 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20   is the.** size 
ddf0: 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64  of each lookasid
de00: 65 20 62 75 66 66 65 72 20 73 6c 6f 74 20 61 6e  e buffer slot an
de10: 64 20 74 68 65 20 74 68 69 72 64 20 61 72 67 75  d the third argu
de20: 6d 65 6e 74 20 69 73 20 74 68 65 20 6e 75 6d 62  ment is the numb
de30: 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 2e 20  er of.** slots. 
de40: 20 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   The size of the
de50: 20 62 75 66 66 65 72 20 69 6e 20 74 68 65 20 66   buffer in the f
de60: 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75  irst argument mu
de70: 73 74 20 62 65 20 67 72 65 61 74 65 72 20 74 68  st be greater th
de80: 61 6e 0a 2a 2a 20 6f 72 20 65 71 75 61 6c 20 74  an.** or equal t
de90: 6f 20 74 68 65 20 70 72 6f 64 75 63 74 20 6f 66  o the product of
dea0: 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20   the second and 
deb0: 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 73 2e  third arguments.
dec0: 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c  </dd>.**.** </dl
ded0: 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  >.*/.#define SQL
dee0: 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f  ITE_DBCONFIG_LOO
def0: 4b 41 53 49 44 45 20 20 20 20 31 30 30 31 20 20  KASIDE    1001  
df00: 2f 2a 20 76 6f 69 64 2a 20 69 6e 74 20 69 6e 74  /* void* int int
df10: 20 2a 2f 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49   */.../*.** CAPI
df20: 33 52 45 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20  3REF: Enable Or 
df30: 44 69 73 61 62 6c 65 20 45 78 74 65 6e 64 65 64  Disable Extended
df40: 20 52 65 73 75 6c 74 20 43 6f 64 65 73 20 7b 48   Result Codes {H
df50: 31 32 32 30 30 7d 20 3c 53 31 30 37 30 30 3e 0a  12200} <S10700>.
df60: 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
df70: 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c  3_extended_resul
df80: 74 5f 63 6f 64 65 73 28 29 20 72 6f 75 74 69 6e  t_codes() routin
df90: 65 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73  e enables or dis
dfa0: 61 62 6c 65 73 20 74 68 65 0a 2a 2a 20 5b 65 78  ables the.** [ex
dfb0: 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
dfc0: 64 65 73 5d 20 66 65 61 74 75 72 65 20 6f 66 20  des] feature of 
dfd0: 53 51 4c 69 74 65 2e 20 54 68 65 20 65 78 74 65  SQLite. The exte
dfe0: 6e 64 65 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63  nded result.** c
dff0: 6f 64 65 73 20 61 72 65 20 64 69 73 61 62 6c 65  odes are disable
e000: 64 20 62 79 20 64 65 66 61 75 6c 74 20 66 6f 72  d by default for
e010: 20 68 69 73 74 6f 72 69 63 61 6c 20 63 6f 6d 70   historical comp
e020: 61 74 69 62 69 6c 69 74 79 20 63 6f 6e 73 69 64  atibility consid
e030: 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20  erations..**.** 
e040: 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
e050: 2a 20 7b 48 31 32 32 30 31 7d 20 45 61 63 68 20  * {H12201} Each 
e060: 6e 65 77 20 5b 64 61 74 61 62 61 73 65 20 63 6f  new [database co
e070: 6e 6e 65 63 74 69 6f 6e 5d 20 73 68 61 6c 6c 20  nnection] shall 
e080: 68 61 76 65 20 74 68 65 0a 2a 2a 20 20 20 20 20  have the.**     
e090: 20 20 20 20 20 5b 65 78 74 65 6e 64 65 64 20 72       [extended r
e0a0: 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 66 65 61  esult codes] fea
e0b0: 74 75 72 65 20 64 69 73 61 62 6c 65 64 20 62 79  ture disabled by
e0c0: 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20   default..**.** 
e0d0: 7b 48 31 32 32 30 32 7d 20 54 68 65 20 5b 73 71  {H12202} The [sq
e0e0: 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72  lite3_extended_r
e0f0: 65 73 75 6c 74 5f 63 6f 64 65 73 28 44 2c 46 29  esult_codes(D,F)
e100: 5d 20 69 6e 74 65 72 66 61 63 65 20 73 68 61 6c  ] interface shal
e110: 6c 20 65 6e 61 62 6c 65 0a 2a 2a 20 20 20 20 20  l enable.**     
e120: 20 20 20 20 20 5b 65 78 74 65 6e 64 65 64 20 72       [extended r
e130: 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 66 6f 72  esult codes] for
e140: 20 74 68 65 20 20 5b 64 61 74 61 62 61 73 65 20   the  [database 
e150: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a 2a  connection] D.**
e160: 20 20 20 20 20 20 20 20 20 20 69 66 20 74 68 65            if the
e170: 20 46 20 70 61 72 61 6d 65 74 65 72 20 69 73 20   F parameter is 
e180: 74 72 75 65 2c 20 6f 72 20 64 69 73 61 62 6c 65  true, or disable
e190: 20 74 68 65 6d 20 69 66 20 46 20 69 73 20 66 61   them if F is fa
e1a0: 6c 73 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  lse..*/.int sqli
e1b0: 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73  te3_extended_res
e1c0: 75 6c 74 5f 63 6f 64 65 73 28 73 71 6c 69 74 65  ult_codes(sqlite
e1d0: 33 2a 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a  3*, int onoff);.
e1e0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
e1f0: 20 4c 61 73 74 20 49 6e 73 65 72 74 20 52 6f 77   Last Insert Row
e200: 69 64 20 7b 48 31 32 32 32 30 7d 20 3c 53 31 30  id {H12220} <S10
e210: 37 30 30 3e 0a 2a 2a 0a 2a 2a 20 45 61 63 68 20  700>.**.** Each 
e220: 65 6e 74 72 79 20 69 6e 20 61 6e 20 53 51 4c 69  entry in an SQLi
e230: 74 65 20 74 61 62 6c 65 20 68 61 73 20 61 20 75  te table has a u
e240: 6e 69 71 75 65 20 36 34 2d 62 69 74 20 73 69 67  nique 64-bit sig
e250: 6e 65 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6b  ned.** integer k
e260: 65 79 20 63 61 6c 6c 65 64 20 74 68 65 20 22 72  ey called the "r
e270: 6f 77 69 64 22 2e 20 54 68 65 20 72 6f 77 69 64  owid". The rowid
e280: 20 69 73 20 61 6c 77 61 79 73 20 61 76 61 69 6c   is always avail
e290: 61 62 6c 65 0a 2a 2a 20 61 73 20 61 6e 20 75 6e  able.** as an un
e2a0: 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 20  declared column 
e2b0: 6e 61 6d 65 64 20 52 4f 57 49 44 2c 20 4f 49 44  named ROWID, OID
e2c0: 2c 20 6f 72 20 5f 52 4f 57 49 44 5f 20 61 73 20  , or _ROWID_ as 
e2d0: 6c 6f 6e 67 20 61 73 20 74 68 6f 73 65 0a 2a 2a  long as those.**
e2e0: 20 6e 61 6d 65 73 20 61 72 65 20 6e 6f 74 20 61   names are not a
e2f0: 6c 73 6f 20 75 73 65 64 20 62 79 20 65 78 70 6c  lso used by expl
e300: 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64 20  icitly declared 
e310: 63 6f 6c 75 6d 6e 73 2e 20 49 66 0a 2a 2a 20 74  columns. If.** t
e320: 68 65 20 74 61 62 6c 65 20 68 61 73 20 61 20 63  he table has a c
e330: 6f 6c 75 6d 6e 20 6f 66 20 74 79 70 65 20 49 4e  olumn of type IN
e340: 54 45 47 45 52 20 50 52 49 4d 41 52 59 20 4b 45  TEGER PRIMARY KE
e350: 59 20 74 68 65 6e 20 74 68 61 74 20 63 6f 6c 75  Y then that colu
e360: 6d 6e 0a 2a 2a 20 69 73 20 61 6e 6f 74 68 65 72  mn.** is another
e370: 20 61 6c 69 61 73 20 66 6f 72 20 74 68 65 20 72   alias for the r
e380: 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  owid..**.** This
e390: 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
e3a0: 20 74 68 65 20 72 6f 77 69 64 20 6f 66 20 74 68   the rowid of th
e3b0: 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 0a 2a 2a  e most recent.**
e3c0: 20 73 75 63 63 65 73 73 66 75 6c 20 49 4e 53 45   successful INSE
e3d0: 52 54 20 69 6e 74 6f 20 74 68 65 20 64 61 74 61  RT into the data
e3e0: 62 61 73 65 20 66 72 6f 6d 20 74 68 65 20 5b 64  base from the [d
e3f0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
e400: 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65 20 66 69  on].** in the fi
e410: 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 20 20 49  rst argument.  I
e420: 66 20 6e 6f 20 73 75 63 63 65 73 73 66 75 6c 20  f no successful 
e430: 49 4e 53 45 52 54 73 0a 2a 2a 20 68 61 76 65 20  INSERTs.** have 
e440: 65 76 65 72 20 6f 63 63 75 72 72 65 64 20 6f 6e  ever occurred on
e450: 20 74 68 61 74 20 64 61 74 61 62 61 73 65 20 63   that database c
e460: 6f 6e 6e 65 63 74 69 6f 6e 2c 20 7a 65 72 6f 20  onnection, zero 
e470: 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  is returned..**.
e480: 2a 2a 20 49 66 20 61 6e 20 49 4e 53 45 52 54 20  ** If an INSERT 
e490: 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20 61 20  occurs within a 
e4a0: 74 72 69 67 67 65 72 2c 20 74 68 65 6e 20 74 68  trigger, then th
e4b0: 65 20 72 6f 77 69 64 20 6f 66 20 74 68 65 20 69  e rowid of the i
e4c0: 6e 73 65 72 74 65 64 0a 2a 2a 20 72 6f 77 20 69  nserted.** row i
e4d0: 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  s returned by th
e4e0: 69 73 20 72 6f 75 74 69 6e 65 20 61 73 20 6c 6f  is routine as lo
e4f0: 6e 67 20 61 73 20 74 68 65 20 74 72 69 67 67 65  ng as the trigge
e500: 72 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a  r is running..**
e510: 20 42 75 74 20 6f 6e 63 65 20 74 68 65 20 74 72   But once the tr
e520: 69 67 67 65 72 20 74 65 72 6d 69 6e 61 74 65 73  igger terminates
e530: 2c 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  , the value retu
e540: 72 6e 65 64 20 62 79 20 74 68 69 73 20 72 6f 75  rned by this rou
e550: 74 69 6e 65 0a 2a 2a 20 72 65 76 65 72 74 73 20  tine.** reverts 
e560: 74 6f 20 74 68 65 20 6c 61 73 74 20 76 61 6c 75  to the last valu
e570: 65 20 69 6e 73 65 72 74 65 64 20 62 65 66 6f 72  e inserted befor
e580: 65 20 74 68 65 20 74 72 69 67 67 65 72 20 66 69  e the trigger fi
e590: 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 49 4e  red..**.** An IN
e5a0: 53 45 52 54 20 74 68 61 74 20 66 61 69 6c 73 20  SERT that fails 
e5b0: 64 75 65 20 74 6f 20 61 20 63 6f 6e 73 74 72 61  due to a constra
e5c0: 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 69 73  int violation is
e5d0: 20 6e 6f 74 20 61 0a 2a 2a 20 73 75 63 63 65 73   not a.** succes
e5e0: 73 66 75 6c 20 49 4e 53 45 52 54 20 61 6e 64 20  sful INSERT and 
e5f0: 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20  does not change 
e600: 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
e610: 65 64 20 62 79 20 74 68 69 73 0a 2a 2a 20 72 6f  ed by this.** ro
e620: 75 74 69 6e 65 2e 20 20 54 68 75 73 20 49 4e 53  utine.  Thus INS
e630: 45 52 54 20 4f 52 20 46 41 49 4c 2c 20 49 4e 53  ERT OR FAIL, INS
e640: 45 52 54 20 4f 52 20 49 47 4e 4f 52 45 2c 20 49  ERT OR IGNORE, I
e650: 4e 53 45 52 54 20 4f 52 20 52 4f 4c 4c 42 41 43  NSERT OR ROLLBAC
e660: 4b 2c 0a 2a 2a 20 61 6e 64 20 49 4e 53 45 52 54  K,.** and INSERT
e670: 20 4f 52 20 41 42 4f 52 54 20 6d 61 6b 65 20 6e   OR ABORT make n
e680: 6f 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65  o changes to the
e690: 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66   return value of
e6a0: 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65   this.** routine
e6b0: 20 77 68 65 6e 20 74 68 65 69 72 20 69 6e 73 65   when their inse
e6c0: 72 74 69 6f 6e 20 66 61 69 6c 73 2e 20 20 57 68  rtion fails.  Wh
e6d0: 65 6e 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50  en INSERT OR REP
e6e0: 4c 41 43 45 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65  LACE.** encounte
e6f0: 72 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20  rs a constraint 
e700: 76 69 6f 6c 61 74 69 6f 6e 2c 20 69 74 20 64 6f  violation, it do
e710: 65 73 20 6e 6f 74 20 66 61 69 6c 2e 20 20 54 68  es not fail.  Th
e720: 65 0a 2a 2a 20 49 4e 53 45 52 54 20 63 6f 6e 74  e.** INSERT cont
e730: 69 6e 75 65 73 20 74 6f 20 63 6f 6d 70 6c 65 74  inues to complet
e740: 69 6f 6e 20 61 66 74 65 72 20 64 65 6c 65 74 69  ion after deleti
e750: 6e 67 20 72 6f 77 73 20 74 68 61 74 20 63 61 75  ng rows that cau
e760: 73 65 64 0a 2a 2a 20 74 68 65 20 63 6f 6e 73 74  sed.** the const
e770: 72 61 69 6e 74 20 70 72 6f 62 6c 65 6d 20 73 6f  raint problem so
e780: 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41   INSERT OR REPLA
e790: 43 45 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 63  CE will always c
e7a0: 68 61 6e 67 65 0a 2a 2a 20 74 68 65 20 72 65 74  hange.** the ret
e7b0: 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69  urn value of thi
e7c0: 73 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a  s interface..**.
e7d0: 2a 2a 20 46 6f 72 20 74 68 65 20 70 75 72 70 6f  ** For the purpo
e7e0: 73 65 73 20 6f 66 20 74 68 69 73 20 72 6f 75 74  ses of this rout
e7f0: 69 6e 65 2c 20 61 6e 20 49 4e 53 45 52 54 20 69  ine, an INSERT i
e800: 73 20 63 6f 6e 73 69 64 65 72 65 64 20 74 6f 0a  s considered to.
e810: 2a 2a 20 62 65 20 73 75 63 63 65 73 73 66 75 6c  ** be successful
e820: 20 65 76 65 6e 20 69 66 20 69 74 20 69 73 20 73   even if it is s
e830: 75 62 73 65 71 75 65 6e 74 6c 79 20 72 6f 6c 6c  ubsequently roll
e840: 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 49  ed back..**.** I
e850: 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
e860: 20 7b 48 31 32 32 32 31 7d 20 54 68 65 20 5b 73   {H12221} The [s
e870: 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65  qlite3_last_inse
e880: 72 74 5f 72 6f 77 69 64 28 29 5d 20 66 75 6e 63  rt_rowid()] func
e890: 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65  tion returns the
e8a0: 20 72 6f 77 69 64 0a 2a 2a 20 20 20 20 20 20 20   rowid.**       
e8b0: 20 20 20 6f 66 20 74 68 65 20 6d 6f 73 74 20 72     of the most r
e8c0: 65 63 65 6e 74 20 73 75 63 63 65 73 73 66 75 6c  ecent successful
e8d0: 20 49 4e 53 45 52 54 20 70 65 72 66 6f 72 6d 65   INSERT performe
e8e0: 64 20 6f 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a  d on the same.**
e8f0: 20 20 20 20 20 20 20 20 20 20 5b 64 61 74 61 62            [datab
e900: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
e910: 61 6e 64 20 77 69 74 68 69 6e 20 74 68 65 20 73  and within the s
e920: 61 6d 65 20 6f 72 20 68 69 67 68 65 72 20 6c 65  ame or higher le
e930: 76 65 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  vel.**          
e940: 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2c  trigger context,
e950: 20 6f 72 20 7a 65 72 6f 20 69 66 20 74 68 65 72   or zero if ther
e960: 65 20 68 61 76 65 20 62 65 65 6e 20 6e 6f 20 71  e have been no q
e970: 75 61 6c 69 66 79 69 6e 67 20 69 6e 73 65 72 74  ualifying insert
e980: 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 32 33  s..**.** {H12223
e990: 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c  } The [sqlite3_l
e9a0: 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64  ast_insert_rowid
e9b0: 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20 72 65 74  ()] function ret
e9c0: 75 72 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20 20  urns the.**     
e9d0: 20 20 20 20 20 73 61 6d 65 20 76 61 6c 75 65 20       same value 
e9e0: 77 68 65 6e 20 63 61 6c 6c 65 64 20 66 72 6f 6d  when called from
e9f0: 20 74 68 65 20 73 61 6d 65 20 74 72 69 67 67 65   the same trigge
ea00: 72 20 63 6f 6e 74 65 78 74 0a 2a 2a 20 20 20 20  r context.**    
ea10: 20 20 20 20 20 20 69 6d 6d 65 64 69 61 74 65 6c        immediatel
ea20: 79 20 62 65 66 6f 72 65 20 61 6e 64 20 61 66 74  y before and aft
ea30: 65 72 20 61 20 52 4f 4c 4c 42 41 43 4b 2e 0a 2a  er a ROLLBACK..*
ea40: 2a 0a 2a 2a 20 41 53 53 55 4d 50 54 49 4f 4e 53  *.** ASSUMPTIONS
ea50: 3a 0a 2a 2a 0a 2a 2a 20 7b 41 31 32 32 33 32 7d  :.**.** {A12232}
ea60: 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74   If a separate t
ea70: 68 72 65 61 64 20 70 65 72 66 6f 72 6d 73 20 61  hread performs a
ea80: 20 6e 65 77 20 49 4e 53 45 52 54 20 6f 6e 20 74   new INSERT on t
ea90: 68 65 20 73 61 6d 65 0a 2a 2a 20 20 20 20 20 20  he same.**      
eaa0: 20 20 20 20 64 61 74 61 62 61 73 65 20 63 6f 6e      database con
eab0: 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65 20 74 68  nection while th
eac0: 65 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f  e [sqlite3_last_
ead0: 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 0a  insert_rowid()].
eae0: 2a 2a 20 20 20 20 20 20 20 20 20 20 66 75 6e 63  **          func
eaf0: 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 20  tion is running 
eb00: 61 6e 64 20 74 68 75 73 20 63 68 61 6e 67 65 73  and thus changes
eb10: 20 74 68 65 20 6c 61 73 74 20 69 6e 73 65 72 74   the last insert
eb20: 20 72 6f 77 69 64 2c 0a 2a 2a 20 20 20 20 20 20   rowid,.**      
eb30: 20 20 20 20 74 68 65 6e 20 74 68 65 20 76 61 6c      then the val
eb40: 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b  ue returned by [
eb50: 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73  sqlite3_last_ins
eb60: 65 72 74 5f 72 6f 77 69 64 28 29 5d 20 69 73 0a  ert_rowid()] is.
eb70: 2a 2a 20 20 20 20 20 20 20 20 20 20 75 6e 70 72  **          unpr
eb80: 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6d 69  edictable and mi
eb90: 67 68 74 20 6e 6f 74 20 65 71 75 61 6c 20 65 69  ght not equal ei
eba0: 74 68 65 72 20 74 68 65 20 6f 6c 64 20 6f 72 20  ther the old or 
ebb0: 74 68 65 20 6e 65 77 0a 2a 2a 20 20 20 20 20 20  the new.**      
ebc0: 20 20 20 20 6c 61 73 74 20 69 6e 73 65 72 74 20      last insert 
ebd0: 72 6f 77 69 64 2e 0a 2a 2f 0a 73 71 6c 69 74 65  rowid..*/.sqlite
ebe0: 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f  3_int64 sqlite3_
ebf0: 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69  last_insert_rowi
ec00: 64 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a  d(sqlite3*);../*
ec10: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
ec20: 75 6e 74 20 54 68 65 20 4e 75 6d 62 65 72 20 4f  unt The Number O
ec30: 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 20  f Rows Modified 
ec40: 7b 48 31 32 32 34 30 7d 20 3c 53 31 30 36 30 30  {H12240} <S10600
ec50: 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e  >.**.** This fun
ec60: 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68  ction returns th
ec70: 65 20 6e 75 6d 62 65 72 20 6f 66 20 64 61 74 61  e number of data
ec80: 62 61 73 65 20 72 6f 77 73 20 74 68 61 74 20 77  base rows that w
ec90: 65 72 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20 6f  ere changed.** o
eca0: 72 20 69 6e 73 65 72 74 65 64 20 6f 72 20 64 65  r inserted or de
ecb0: 6c 65 74 65 64 20 62 79 20 74 68 65 20 6d 6f 73  leted by the mos
ecc0: 74 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c  t recently compl
ecd0: 65 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65  eted SQL stateme
ece0: 6e 74 0a 2a 2a 20 6f 6e 20 74 68 65 20 5b 64 61  nt.** on the [da
ecf0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
ed00: 6e 5d 20 73 70 65 63 69 66 69 65 64 20 62 79 20  n] specified by 
ed10: 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  the first parame
ed20: 74 65 72 2e 0a 2a 2a 20 4f 6e 6c 79 20 63 68 61  ter..** Only cha
ed30: 6e 67 65 73 20 74 68 61 74 20 61 72 65 20 64 69  nges that are di
ed40: 72 65 63 74 6c 79 20 73 70 65 63 69 66 69 65 64  rectly specified
ed50: 20 62 79 20 74 68 65 20 49 4e 53 45 52 54 2c 20   by the INSERT, 
ed60: 55 50 44 41 54 45 2c 0a 2a 2a 20 6f 72 20 44 45  UPDATE,.** or DE
ed70: 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20 61  LETE statement a
ed80: 72 65 20 63 6f 75 6e 74 65 64 2e 20 20 41 75 78  re counted.  Aux
ed90: 69 6c 69 61 72 79 20 63 68 61 6e 67 65 73 20 63  iliary changes c
eda0: 61 75 73 65 64 20 62 79 0a 2a 2a 20 74 72 69 67  aused by.** trig
edb0: 67 65 72 73 20 61 72 65 20 6e 6f 74 20 63 6f 75  gers are not cou
edc0: 6e 74 65 64 2e 20 55 73 65 20 74 68 65 20 5b 73  nted. Use the [s
edd0: 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61  qlite3_total_cha
ede0: 6e 67 65 73 28 29 5d 20 66 75 6e 63 74 69 6f 6e  nges()] function
edf0: 0a 2a 2a 20 74 6f 20 66 69 6e 64 20 74 68 65 20  .** to find the 
ee00: 74 6f 74 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20  total number of 
ee10: 63 68 61 6e 67 65 73 20 69 6e 63 6c 75 64 69 6e  changes includin
ee20: 67 20 63 68 61 6e 67 65 73 20 63 61 75 73 65 64  g changes caused
ee30: 20 62 79 20 74 72 69 67 67 65 72 73 2e 0a 2a 2a   by triggers..**
ee40: 0a 2a 2a 20 41 20 22 72 6f 77 20 63 68 61 6e 67  .** A "row chang
ee50: 65 22 20 69 73 20 61 20 63 68 61 6e 67 65 20 74  e" is a change t
ee60: 6f 20 61 20 73 69 6e 67 6c 65 20 72 6f 77 20 6f  o a single row o
ee70: 66 20 61 20 73 69 6e 67 6c 65 20 74 61 62 6c 65  f a single table
ee80: 0a 2a 2a 20 63 61 75 73 65 64 20 62 79 20 61 6e  .** caused by an
ee90: 20 49 4e 53 45 52 54 2c 20 44 45 4c 45 54 45 2c   INSERT, DELETE,
eea0: 20 6f 72 20 55 50 44 41 54 45 20 73 74 61 74 65   or UPDATE state
eeb0: 6d 65 6e 74 2e 20 20 52 6f 77 73 20 74 68 61 74  ment.  Rows that
eec0: 0a 2a 2a 20 61 72 65 20 63 68 61 6e 67 65 64 20  .** are changed 
eed0: 61 73 20 73 69 64 65 20 65 66 66 65 63 74 73 20  as side effects 
eee0: 6f 66 20 52 45 50 4c 41 43 45 20 63 6f 6e 73 74  of REPLACE const
eef0: 72 61 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e  raint resolution
ef00: 2c 0a 2a 2a 20 72 6f 6c 6c 62 61 63 6b 2c 20 41  ,.** rollback, A
ef10: 42 4f 52 54 20 70 72 6f 63 65 73 73 69 6e 67 2c  BORT processing,
ef20: 20 44 52 4f 50 20 54 41 42 4c 45 2c 20 6f 72 20   DROP TABLE, or 
ef30: 62 79 20 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20  by any other.** 
ef40: 6d 65 63 68 61 6e 69 73 6d 73 20 64 6f 20 6e 6f  mechanisms do no
ef50: 74 20 63 6f 75 6e 74 20 61 73 20 64 69 72 65 63  t count as direc
ef60: 74 20 72 6f 77 20 63 68 61 6e 67 65 73 2e 0a 2a  t row changes..*
ef70: 2a 0a 2a 2a 20 41 20 22 74 72 69 67 67 65 72 20  *.** A "trigger 
ef80: 63 6f 6e 74 65 78 74 22 20 69 73 20 61 20 73 63  context" is a sc
ef90: 6f 70 65 20 6f 66 20 65 78 65 63 75 74 69 6f 6e  ope of execution
efa0: 20 74 68 61 74 20 62 65 67 69 6e 73 20 61 6e 64   that begins and
efb0: 0a 2a 2a 20 65 6e 64 73 20 77 69 74 68 20 74 68  .** ends with th
efc0: 65 20 73 63 72 69 70 74 20 6f 66 20 61 20 74 72  e script of a tr
efd0: 69 67 67 65 72 2e 20 20 4d 6f 73 74 20 53 51 4c  igger.  Most SQL
efe0: 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 0a   statements are.
eff0: 2a 2a 20 65 76 61 6c 75 61 74 65 64 20 6f 75 74  ** evaluated out
f000: 73 69 64 65 20 6f 66 20 61 6e 79 20 74 72 69 67  side of any trig
f010: 67 65 72 2e 20 20 54 68 69 73 20 69 73 20 74 68  ger.  This is th
f020: 65 20 22 74 6f 70 20 6c 65 76 65 6c 22 0a 2a 2a  e "top level".**
f030: 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74   trigger context
f040: 2e 20 20 49 66 20 61 20 74 72 69 67 67 65 72 20  .  If a trigger 
f050: 66 69 72 65 73 20 66 72 6f 6d 20 74 68 65 20 74  fires from the t
f060: 6f 70 20 6c 65 76 65 6c 2c 20 61 0a 2a 2a 20 6e  op level, a.** n
f070: 65 77 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65  ew trigger conte
f080: 78 74 20 69 73 20 65 6e 74 65 72 65 64 20 66 6f  xt is entered fo
f090: 72 20 74 68 65 20 64 75 72 61 74 69 6f 6e 20 6f  r the duration o
f0a0: 66 20 74 68 61 74 20 6f 6e 65 0a 2a 2a 20 74 72  f that one.** tr
f0b0: 69 67 67 65 72 2e 20 20 53 75 62 74 72 69 67 67  igger.  Subtrigg
f0c0: 65 72 73 20 63 72 65 61 74 65 20 73 75 62 63 6f  ers create subco
f0d0: 6e 74 65 78 74 73 20 66 6f 72 20 74 68 65 69 72  ntexts for their
f0e0: 20 64 75 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a   duration..**.**
f0f0: 20 43 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   Calling [sqlite
f100: 33 5f 65 78 65 63 28 29 5d 20 6f 72 20 5b 73 71  3_exec()] or [sq
f110: 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 72 65  lite3_step()] re
f120: 63 75 72 73 69 76 65 6c 79 20 64 6f 65 73 0a 2a  cursively does.*
f130: 2a 20 6e 6f 74 20 63 72 65 61 74 65 20 61 20 6e  * not create a n
f140: 65 77 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65  ew trigger conte
f150: 78 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66  xt..**.** This f
f160: 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
f170: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 64 69  the number of di
f180: 72 65 63 74 20 72 6f 77 20 63 68 61 6e 67 65 73  rect row changes
f190: 20 69 6e 20 74 68 65 0a 2a 2a 20 6d 6f 73 74 20   in the.** most 
f1a0: 72 65 63 65 6e 74 20 49 4e 53 45 52 54 2c 20 55  recent INSERT, U
f1b0: 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45  PDATE, or DELETE
f1c0: 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69   statement withi
f1d0: 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 74 72  n the same.** tr
f1e0: 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 0a 2a  igger context..*
f1f0: 2a 0a 2a 2a 20 54 68 75 73 2c 20 77 68 65 6e 20  *.** Thus, when 
f200: 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20  called from the 
f210: 74 6f 70 20 6c 65 76 65 6c 2c 20 74 68 69 73 20  top level, this 
f220: 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
f230: 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f   the.** number o
f240: 66 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65  f changes in the
f250: 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 49 4e 53   most recent INS
f260: 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20  ERT, UPDATE, or 
f270: 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20 61  DELETE.** that a
f280: 6c 73 6f 20 6f 63 63 75 72 72 65 64 20 61 74 20  lso occurred at 
f290: 74 68 65 20 74 6f 70 20 6c 65 76 65 6c 2e 20 20  the top level.  
f2a0: 57 69 74 68 69 6e 20 74 68 65 20 62 6f 64 79 20  Within the body 
f2b0: 6f 66 20 61 20 74 72 69 67 67 65 72 2c 0a 2a 2a  of a trigger,.**
f2c0: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 68 61   the sqlite3_cha
f2d0: 6e 67 65 73 28 29 20 69 6e 74 65 72 66 61 63 65  nges() interface
f2e0: 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 74   can be called t
f2f0: 6f 20 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 65  o find the numbe
f300: 72 20 6f 66 0a 2a 2a 20 63 68 61 6e 67 65 73 20  r of.** changes 
f310: 69 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  in the most rece
f320: 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20 49  ntly completed I
f330: 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f  NSERT, UPDATE, o
f340: 72 20 44 45 4c 45 54 45 0a 2a 2a 20 73 74 61 74  r DELETE.** stat
f350: 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 74 68 65  ement within the
f360: 20 62 6f 64 79 20 6f 66 20 74 68 65 20 73 61 6d   body of the sam
f370: 65 20 74 72 69 67 67 65 72 2e 0a 2a 2a 20 48 6f  e trigger..** Ho
f380: 77 65 76 65 72 2c 20 74 68 65 20 6e 75 6d 62 65  wever, the numbe
f390: 72 20 72 65 74 75 72 6e 65 64 20 64 6f 65 73 20  r returned does 
f3a0: 6e 6f 74 20 69 6e 63 6c 75 64 65 20 63 68 61 6e  not include chan
f3b0: 67 65 73 0a 2a 2a 20 63 61 75 73 65 64 20 62 79  ges.** caused by
f3c0: 20 73 75 62 74 72 69 67 67 65 72 73 20 73 69 6e   subtriggers sin
f3d0: 63 65 20 74 68 6f 73 65 20 68 61 76 65 20 74 68  ce those have th
f3e0: 65 69 72 20 6f 77 6e 20 63 6f 6e 74 65 78 74 2e  eir own context.
f3f0: 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6d  .**.** SQLite im
f400: 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 63 6f 6d  plements the com
f410: 6d 61 6e 64 20 22 44 45 4c 45 54 45 20 46 52 4f  mand "DELETE FRO
f420: 4d 20 74 61 62 6c 65 22 20 77 69 74 68 6f 75 74  M table" without
f430: 20 61 20 57 48 45 52 45 20 63 6c 61 75 73 65 0a   a WHERE clause.
f440: 2a 2a 20 62 79 20 64 72 6f 70 70 69 6e 67 20 61  ** by dropping a
f450: 6e 64 20 72 65 63 72 65 61 74 69 6e 67 20 74 68  nd recreating th
f460: 65 20 74 61 62 6c 65 2e 20 20 28 54 68 69 73 20  e table.  (This 
f470: 69 73 20 6d 75 63 68 20 66 61 73 74 65 72 20 74  is much faster t
f480: 68 61 6e 20 67 6f 69 6e 67 0a 2a 2a 20 74 68 72  han going.** thr
f490: 6f 75 67 68 20 61 6e 64 20 64 65 6c 65 74 69 6e  ough and deletin
f4a0: 67 20 69 6e 64 69 76 69 64 75 61 6c 20 65 6c 65  g individual ele
f4b0: 6d 65 6e 74 73 20 66 72 6f 6d 20 74 68 65 20 74  ments from the t
f4c0: 61 62 6c 65 2e 29 20 20 42 65 63 61 75 73 65 20  able.)  Because 
f4d0: 6f 66 20 74 68 69 73 0a 2a 2a 20 6f 70 74 69 6d  of this.** optim
f4e0: 69 7a 61 74 69 6f 6e 2c 20 74 68 65 20 64 65 6c  ization, the del
f4f0: 65 74 69 6f 6e 73 20 69 6e 20 22 44 45 4c 45 54  etions in "DELET
f500: 45 20 46 52 4f 4d 20 74 61 62 6c 65 22 20 61 72  E FROM table" ar
f510: 65 20 6e 6f 74 20 72 6f 77 20 63 68 61 6e 67 65  e not row change
f520: 73 20 61 6e 64 0a 2a 2a 20 77 69 6c 6c 20 6e 6f  s and.** will no
f530: 74 20 62 65 20 63 6f 75 6e 74 65 64 20 62 79 20  t be counted by 
f540: 74 68 65 20 73 71 6c 69 74 65 33 5f 63 68 61 6e  the sqlite3_chan
f550: 67 65 73 28 29 20 6f 72 20 5b 73 71 6c 69 74 65  ges() or [sqlite
f560: 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28  3_total_changes(
f570: 29 5d 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 2c  )].** functions,
f580: 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 74   regardless of t
f590: 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 65 6c 65  he number of ele
f5a0: 6d 65 6e 74 73 20 74 68 61 74 20 77 65 72 65 20  ments that were 
f5b0: 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 69 6e  originally.** in
f5c0: 20 74 68 65 20 74 61 62 6c 65 2e 20 20 54 6f 20   the table.  To 
f5d0: 67 65 74 20 61 6e 20 61 63 63 75 72 61 74 65 20  get an accurate 
f5e0: 63 6f 75 6e 74 20 6f 66 20 74 68 65 20 6e 75 6d  count of the num
f5f0: 62 65 72 20 6f 66 20 72 6f 77 73 20 64 65 6c 65  ber of rows dele
f600: 74 65 64 2c 20 75 73 65 0a 2a 2a 20 22 44 45 4c  ted, use.** "DEL
f610: 45 54 45 20 46 52 4f 4d 20 74 61 62 6c 65 20 57  ETE FROM table W
f620: 48 45 52 45 20 31 22 20 69 6e 73 74 65 61 64 2e  HERE 1" instead.
f630: 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
f640: 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 34 31  S:.**.** {H12241
f650: 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  } The [sqlite3_c
f660: 68 61 6e 67 65 73 28 29 5d 20 66 75 6e 63 74 69  hanges()] functi
f670: 6f 6e 20 73 68 61 6c 6c 20 72 65 74 75 72 6e 20  on shall return 
f680: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a  the number of.**
f690: 20 20 20 20 20 20 20 20 20 20 72 6f 77 20 63 68            row ch
f6a0: 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 20  anges caused by 
f6b0: 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
f6c0: 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 0a  INSERT, UPDATE,.
f6d0: 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 44  **          or D
f6e0: 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20  ELETE statement 
f6f0: 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74 61  on the same data
f700: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
f710: 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  and.**          
f720: 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20  within the same 
f730: 6f 72 20 68 69 67 68 65 72 20 74 72 69 67 67 65  or higher trigge
f740: 72 20 63 6f 6e 74 65 78 74 2c 20 6f 72 20 7a 65  r context, or ze
f750: 72 6f 20 69 66 20 74 68 65 72 65 20 68 61 76 65  ro if there have
f760: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 6f 74  .**          not
f770: 20 62 65 65 6e 20 61 6e 79 20 71 75 61 6c 69 66   been any qualif
f780: 79 69 6e 67 20 72 6f 77 20 63 68 61 6e 67 65 73  ying row changes
f790: 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 34 33 7d  ..**.** {H12243}
f7a0: 20 53 74 61 74 65 6d 65 6e 74 73 20 6f 66 20 74   Statements of t
f7b0: 68 65 20 66 6f 72 6d 20 22 44 45 4c 45 54 45 20  he form "DELETE 
f7c0: 46 52 4f 4d 20 74 61 62 6c 65 6e 61 6d 65 22 20  FROM tablename" 
f7d0: 77 69 74 68 20 6e 6f 0a 2a 2a 20 20 20 20 20 20  with no.**      
f7e0: 20 20 20 20 57 48 45 52 45 20 63 6c 61 75 73 65      WHERE clause
f7f0: 20 73 68 61 6c 6c 20 63 61 75 73 65 20 73 75 62   shall cause sub
f800: 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f  sequent calls to
f810: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
f820: 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d  lite3_changes()]
f830: 20 74 6f 20 72 65 74 75 72 6e 20 7a 65 72 6f 2c   to return zero,
f840: 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 74   regardless of t
f850: 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e  he.**          n
f860: 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 6f 72  umber of rows or
f870: 69 67 69 6e 61 6c 6c 79 20 69 6e 20 74 68 65 20  iginally in the 
f880: 74 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 41 53 53  table..**.** ASS
f890: 55 4d 50 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20  UMPTIONS:.**.** 
f8a0: 7b 41 31 32 32 35 32 7d 20 49 66 20 61 20 73 65  {A12252} If a se
f8b0: 70 61 72 61 74 65 20 74 68 72 65 61 64 20 6d 61  parate thread ma
f8c0: 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 74  kes changes on t
f8d0: 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65  he same database
f8e0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 20   connection.**  
f8f0: 20 20 20 20 20 20 20 20 77 68 69 6c 65 20 5b 73          while [s
f900: 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29  qlite3_changes()
f910: 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65  ] is running the
f920: 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  n the value retu
f930: 72 6e 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20  rned.**         
f940: 20 69 73 20 75 6e 70 72 65 64 69 63 74 61 62 6c   is unpredictabl
f950: 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e  e and not meanin
f960: 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  gful..*/.int sql
f970: 69 74 65 33 5f 63 68 61 6e 67 65 73 28 73 71 6c  ite3_changes(sql
f980: 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ite3*);../*.** C
f990: 41 50 49 33 52 45 46 3a 20 54 6f 74 61 6c 20 4e  API3REF: Total N
f9a0: 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f  umber Of Rows Mo
f9b0: 64 69 66 69 65 64 20 7b 48 31 32 32 36 30 7d 20  dified {H12260} 
f9c0: 3c 53 31 30 36 30 30 3e 0a 2a 2a 0a 2a 2a 20 54  <S10600>.**.** T
f9d0: 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74  his function ret
f9e0: 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
f9f0: 6f 66 20 72 6f 77 20 63 68 61 6e 67 65 73 20 63  of row changes c
fa00: 61 75 73 65 64 20 62 79 20 49 4e 53 45 52 54 2c  aused by INSERT,
fa10: 0a 2a 2a 20 55 50 44 41 54 45 20 6f 72 20 44 45  .** UPDATE or DE
fa20: 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 73 20  LETE statements 
fa30: 73 69 6e 63 65 20 74 68 65 20 5b 64 61 74 61 62  since the [datab
fa40: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
fa50: 77 61 73 20 6f 70 65 6e 65 64 2e 0a 2a 2a 20 54  was opened..** T
fa60: 68 65 20 63 6f 75 6e 74 20 69 6e 63 6c 75 64 65  he count include
fa70: 73 20 61 6c 6c 20 63 68 61 6e 67 65 73 20 66 72  s all changes fr
fa80: 6f 6d 20 61 6c 6c 20 74 72 69 67 67 65 72 20 63  om all trigger c
fa90: 6f 6e 74 65 78 74 73 2e 20 20 48 6f 77 65 76 65  ontexts.  Howeve
faa0: 72 2c 0a 2a 2a 20 74 68 65 20 63 6f 75 6e 74 20  r,.** the count 
fab0: 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65  does not include
fac0: 20 63 68 61 6e 67 65 73 20 75 73 65 64 20 74 6f   changes used to
fad0: 20 69 6d 70 6c 65 6d 65 6e 74 20 52 45 50 4c 41   implement REPLA
fae0: 43 45 20 63 6f 6e 73 74 72 61 69 6e 74 73 2c 0a  CE constraints,.
faf0: 2a 2a 20 64 6f 20 72 6f 6c 6c 62 61 63 6b 73 20  ** do rollbacks 
fb00: 6f 72 20 41 42 4f 52 54 20 70 72 6f 63 65 73 73  or ABORT process
fb10: 69 6e 67 2c 20 6f 72 20 44 52 4f 50 20 74 61 62  ing, or DROP tab
fb20: 6c 65 20 70 72 6f 63 65 73 73 69 6e 67 2e 0a 2a  le processing..*
fb30: 2a 20 54 68 65 20 63 68 61 6e 67 65 73 20 61 72  * The changes ar
fb40: 65 20 63 6f 75 6e 74 65 64 20 61 73 20 73 6f 6f  e counted as soo
fb50: 6e 20 61 73 20 74 68 65 20 73 74 61 74 65 6d 65  n as the stateme
fb60: 6e 74 20 74 68 61 74 20 6d 61 6b 65 73 20 74 68  nt that makes th
fb70: 65 6d 20 69 73 0a 2a 2a 20 63 6f 6d 70 6c 65 74  em is.** complet
fb80: 65 64 20 28 77 68 65 6e 20 74 68 65 20 73 74 61  ed (when the sta
fb90: 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 69 73  tement handle is
fba0: 20 70 61 73 73 65 64 20 74 6f 20 5b 73 71 6c 69   passed to [sqli
fbb0: 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a  te3_reset()] or.
fbc0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  ** [sqlite3_fina
fbd0: 6c 69 7a 65 28 29 5d 29 2e 0a 2a 2a 0a 2a 2a 20  lize()])..**.** 
fbe0: 53 51 4c 69 74 65 20 69 6d 70 6c 65 6d 65 6e 74  SQLite implement
fbf0: 73 20 74 68 65 20 63 6f 6d 6d 61 6e 64 20 22 44  s the command "D
fc00: 45 4c 45 54 45 20 46 52 4f 4d 20 74 61 62 6c 65  ELETE FROM table
fc10: 22 20 77 69 74 68 6f 75 74 20 61 20 57 48 45 52  " without a WHER
fc20: 45 20 63 6c 61 75 73 65 0a 2a 2a 20 62 79 20 64  E clause.** by d
fc30: 72 6f 70 70 69 6e 67 20 61 6e 64 20 72 65 63 72  ropping and recr
fc40: 65 61 74 69 6e 67 20 74 68 65 20 74 61 62 6c 65  eating the table
fc50: 2e 20 20 28 54 68 69 73 20 69 73 20 6d 75 63 68  .  (This is much
fc60: 20 66 61 73 74 65 72 20 74 68 61 6e 20 67 6f 69   faster than goi
fc70: 6e 67 0a 2a 2a 20 74 68 72 6f 75 67 68 20 61 6e  ng.** through an
fc80: 64 20 64 65 6c 65 74 69 6e 67 20 69 6e 64 69 76  d deleting indiv
fc90: 69 64 75 61 6c 20 65 6c 65 6d 65 6e 74 73 20 66  idual elements f
fca0: 72 6f 6d 20 74 68 65 20 74 61 62 6c 65 2e 29 20  rom the table.) 
fcb0: 20 42 65 63 61 75 73 65 20 6f 66 20 74 68 69 73   Because of this
fcc0: 0a 2a 2a 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e  .** optimization
fcd0: 2c 20 74 68 65 20 64 65 6c 65 74 69 6f 6e 73 20  , the deletions 
fce0: 69 6e 20 22 44 45 4c 45 54 45 20 46 52 4f 4d 20  in "DELETE FROM 
fcf0: 74 61 62 6c 65 22 20 61 72 65 20 6e 6f 74 20 72  table" are not r
fd00: 6f 77 20 63 68 61 6e 67 65 73 20 61 6e 64 0a 2a  ow changes and.*
fd10: 2a 20 77 69 6c 6c 20 6e 6f 74 20 62 65 20 63 6f  * will not be co
fd20: 75 6e 74 65 64 20 62 79 20 74 68 65 20 73 71 6c  unted by the sql
fd30: 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 6f  ite3_changes() o
fd40: 72 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c  r [sqlite3_total
fd50: 5f 63 68 61 6e 67 65 73 28 29 5d 0a 2a 2a 20 66  _changes()].** f
fd60: 75 6e 63 74 69 6f 6e 73 2c 20 72 65 67 61 72 64  unctions, regard
fd70: 6c 65 73 73 20 6f 66 20 74 68 65 20 6e 75 6d 62  less of the numb
fd80: 65 72 20 6f 66 20 65 6c 65 6d 65 6e 74 73 20 74  er of elements t
fd90: 68 61 74 20 77 65 72 65 20 6f 72 69 67 69 6e 61  hat were origina
fda0: 6c 6c 79 0a 2a 2a 20 69 6e 20 74 68 65 20 74 61  lly.** in the ta
fdb0: 62 6c 65 2e 20 20 54 6f 20 67 65 74 20 61 6e 20  ble.  To get an 
fdc0: 61 63 63 75 72 61 74 65 20 63 6f 75 6e 74 20 6f  accurate count o
fdd0: 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  f the number of 
fde0: 72 6f 77 73 20 64 65 6c 65 74 65 64 2c 20 75 73  rows deleted, us
fdf0: 65 0a 2a 2a 20 22 44 45 4c 45 54 45 20 46 52 4f  e.** "DELETE FRO
fe00: 4d 20 74 61 62 6c 65 20 57 48 45 52 45 20 31 22  M table WHERE 1"
fe10: 20 69 6e 73 74 65 61 64 2e 0a 2a 2a 0a 2a 2a 20   instead..**.** 
fe20: 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71  See also the [sq
fe30: 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d  lite3_changes()]
fe40: 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a   interface..**.*
fe50: 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
fe60: 0a 2a 2a 20 7b 48 31 32 32 36 31 7d 20 54 68 65  .** {H12261} The
fe70: 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f   [sqlite3_total_
fe80: 63 68 61 6e 67 65 73 28 29 5d 20 72 65 74 75 72  changes()] retur
fe90: 6e 73 20 74 68 65 20 74 6f 74 61 6c 20 6e 75 6d  ns the total num
fea0: 62 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ber.**          
feb0: 6f 66 20 72 6f 77 20 63 68 61 6e 67 65 73 20 63  of row changes c
fec0: 61 75 73 65 64 20 62 79 20 49 4e 53 45 52 54 2c  aused by INSERT,
fed0: 20 55 50 44 41 54 45 2c 20 61 6e 64 2f 6f 72 20   UPDATE, and/or 
fee0: 44 45 4c 45 54 45 0a 2a 2a 20 20 20 20 20 20 20  DELETE.**       
fef0: 20 20 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 6e     statements on
ff00: 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62   the same [datab
ff10: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c  ase connection],
ff20: 20 69 6e 20 61 6e 79 0a 2a 2a 20 20 20 20 20 20   in any.**      
ff30: 20 20 20 20 74 72 69 67 67 65 72 20 63 6f 6e 74      trigger cont
ff40: 65 78 74 2c 20 73 69 6e 63 65 20 74 68 65 20 64  ext, since the d
ff50: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
ff60: 6f 6e 20 77 61 73 20 63 72 65 61 74 65 64 2e 0a  on was created..
ff70: 2a 2a 0a 2a 2a 20 7b 48 31 32 32 36 33 7d 20 53  **.** {H12263} S
ff80: 74 61 74 65 6d 65 6e 74 73 20 6f 66 20 74 68 65  tatements of the
ff90: 20 66 6f 72 6d 20 22 44 45 4c 45 54 45 20 46 52   form "DELETE FR
ffa0: 4f 4d 20 74 61 62 6c 65 6e 61 6d 65 22 20 77 69  OM tablename" wi
ffb0: 74 68 20 6e 6f 0a 2a 2a 20 20 20 20 20 20 20 20  th no.**        
ffc0: 20 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 73    WHERE clause s
ffd0: 68 61 6c 6c 20 6e 6f 74 20 63 68 61 6e 67 65 20  hall not change 
ffe0: 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
fff0: 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62  ed.**          b
10000 79 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c  y [sqlite3_total
10010 5f 63 68 61 6e 67 65 73 28 29 5d 2e 0a 2a 2a 0a  _changes()]..**.
10020 2a 2a 20 41 53 53 55 4d 50 54 49 4f 4e 53 3a 0a  ** ASSUMPTIONS:.
10030 2a 2a 0a 2a 2a 20 7b 41 31 32 32 36 34 7d 20 49  **.** {A12264} I
10040 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72  f a separate thr
10050 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65  ead makes change
10060 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61  s on the same da
10070 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
10080 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 68  n.**          wh
10090 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74  ile [sqlite3_tot
100a0 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 73  al_changes()] is
100b0 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68   running then th
100c0 65 20 76 61 6c 75 65 0a 2a 2a 20 20 20 20 20 20  e value.**      
100d0 20 20 20 20 72 65 74 75 72 6e 65 64 20 69 73 20      returned is 
100e0 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e  unpredictable an
100f0 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c  d not meaningful
10100 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
10110 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 73  _total_changes(s
10120 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  qlite3*);../*.**
10130 20 43 41 50 49 33 52 45 46 3a 20 49 6e 74 65 72   CAPI3REF: Inter
10140 72 75 70 74 20 41 20 4c 6f 6e 67 2d 52 75 6e 6e  rupt A Long-Runn
10150 69 6e 67 20 51 75 65 72 79 20 7b 48 31 32 32 37  ing Query {H1227
10160 30 7d 20 3c 53 33 30 35 30 30 3e 0a 2a 2a 0a 2a  0} <S30500>.**.*
10170 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20  * This function 
10180 63 61 75 73 65 73 20 61 6e 79 20 70 65 6e 64 69  causes any pendi
10190 6e 67 20 64 61 74 61 62 61 73 65 20 6f 70 65 72  ng database oper
101a0 61 74 69 6f 6e 20 74 6f 20 61 62 6f 72 74 20 61  ation to abort a
101b0 6e 64 0a 2a 2a 20 72 65 74 75 72 6e 20 61 74 20  nd.** return at 
101c0 69 74 73 20 65 61 72 6c 69 65 73 74 20 6f 70 70  its earliest opp
101d0 6f 72 74 75 6e 69 74 79 2e 20 54 68 69 73 20 72  ortunity. This r
101e0 6f 75 74 69 6e 65 20 69 73 20 74 79 70 69 63 61  outine is typica
101f0 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 69 6e  lly.** called in
10200 20 72 65 73 70 6f 6e 73 65 20 74 6f 20 61 20 75   response to a u
10210 73 65 72 20 61 63 74 69 6f 6e 20 73 75 63 68 20  ser action such 
10220 61 73 20 70 72 65 73 73 69 6e 67 20 22 43 61 6e  as pressing "Can
10230 63 65 6c 22 0a 2a 2a 20 6f 72 20 43 74 72 6c 2d  cel".** or Ctrl-
10240 43 20 77 68 65 72 65 20 74 68 65 20 75 73 65 72  C where the user
10250 20 77 61 6e 74 73 20 61 20 6c 6f 6e 67 20 71 75   wants a long qu
10260 65 72 79 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f  ery operation to
10270 20 68 61 6c 74 0a 2a 2a 20 69 6d 6d 65 64 69 61   halt.** immedia
10280 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69  tely..**.** It i
10290 73 20 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74  s safe to call t
102a0 68 69 73 20 72 6f 75 74 69 6e 65 20 66 72 6f 6d  his routine from
102b0 20 61 20 74 68 72 65 61 64 20 64 69 66 66 65 72   a thread differ
102c0 65 6e 74 20 66 72 6f 6d 20 74 68 65 0a 2a 2a 20  ent from the.** 
102d0 74 68 72 65 61 64 20 74 68 61 74 20 69 73 20 63  thread that is c
102e0 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67  urrently running
102f0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6f 70   the database op
10300 65 72 61 74 69 6f 6e 2e 20 20 42 75 74 20 69 74  eration.  But it
10310 0a 2a 2a 20 69 73 20 6e 6f 74 20 73 61 66 65 20  .** is not safe 
10320 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75  to call this rou
10330 74 69 6e 65 20 77 69 74 68 20 61 20 5b 64 61 74  tine with a [dat
10340 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
10350 5d 20 74 68 61 74 0a 2a 2a 20 69 73 20 63 6c 6f  ] that.** is clo
10360 73 65 64 20 6f 72 20 6d 69 67 68 74 20 63 6c 6f  sed or might clo
10370 73 65 20 62 65 66 6f 72 65 20 73 71 6c 69 74 65  se before sqlite
10380 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 72 65  3_interrupt() re
10390 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  turns..**.** If 
103a0 61 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e  an SQL operation
103b0 20 69 73 20 76 65 72 79 20 6e 65 61 72 6c 79 20   is very nearly 
103c0 66 69 6e 69 73 68 65 64 20 61 74 20 74 68 65 20  finished at the 
103d0 74 69 6d 65 20 77 68 65 6e 0a 2a 2a 20 73 71 6c  time when.** sql
103e0 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
103f0 20 69 73 20 63 61 6c 6c 65 64 2c 20 74 68 65 6e   is called, then
10400 20 69 74 20 6d 69 67 68 74 20 6e 6f 74 20 68 61   it might not ha
10410 76 65 20 61 6e 20 6f 70 70 6f 72 74 75 6e 69 74  ve an opportunit
10420 79 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 74 65 72  y.** to be inter
10430 72 75 70 74 65 64 20 61 6e 64 20 6d 69 67 68 74  rupted and might
10440 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 63 6f 6d   continue to com
10450 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 41  pletion..**.** A
10460 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20  n SQL operation 
10470 74 68 61 74 20 69 73 20 69 6e 74 65 72 72 75 70  that is interrup
10480 74 65 64 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  ted will return 
10490 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50  [SQLITE_INTERRUP
104a0 54 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20 69 6e  T]..** If the in
104b0 74 65 72 72 75 70 74 65 64 20 53 51 4c 20 6f 70  terrupted SQL op
104c0 65 72 61 74 69 6f 6e 20 69 73 20 61 6e 20 49 4e  eration is an IN
104d0 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72  SERT, UPDATE, or
104e0 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20   DELETE.** that 
104f0 69 73 20 69 6e 73 69 64 65 20 61 6e 20 65 78 70  is inside an exp
10500 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f  licit transactio
10510 6e 2c 20 74 68 65 6e 20 74 68 65 20 65 6e 74 69  n, then the enti
10520 72 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 0a 2a  re transaction.*
10530 2a 20 77 69 6c 6c 20 62 65 20 72 6f 6c 6c 65 64  * will be rolled
10540 20 62 61 63 6b 20 61 75 74 6f 6d 61 74 69 63 61   back automatica
10550 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c  lly..**.** A cal
10560 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 74  l to sqlite3_int
10570 65 72 72 75 70 74 28 29 20 68 61 73 20 6e 6f 20  errupt() has no 
10580 65 66 66 65 63 74 20 6f 6e 20 53 51 4c 20 73 74  effect on SQL st
10590 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74  atements.** that
105a0 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66 74   are started aft
105b0 65 72 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  er sqlite3_inter
105c0 72 75 70 74 28 29 20 72 65 74 75 72 6e 73 2e 0a  rupt() returns..
105d0 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
105e0 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 37 31 7d  :.**.** {H12271}
105f0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6e   The [sqlite3_in
10600 74 65 72 72 75 70 74 28 29 5d 20 69 6e 74 65 72  terrupt()] inter
10610 66 61 63 65 20 77 69 6c 6c 20 66 6f 72 63 65 20  face will force 
10620 61 6c 6c 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 20  all running.**  
10630 20 20 20 20 20 20 20 20 53 51 4c 20 73 74 61 74          SQL stat
10640 65 6d 65 6e 74 73 20 61 73 73 6f 63 69 61 74 65  ements associate
10650 64 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20  d with the same 
10660 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
10670 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ion.**          
10680 74 6f 20 68 61 6c 74 20 61 66 74 65 72 20 70 72  to halt after pr
10690 6f 63 65 73 73 69 6e 67 20 61 74 20 6d 6f 73 74  ocessing at most
106a0 20 6f 6e 65 20 61 64 64 69 74 69 6f 6e 61 6c 20   one additional 
106b0 72 6f 77 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a  row of data..**.
106c0 2a 2a 20 7b 48 31 32 32 37 32 7d 20 41 6e 79 20  ** {H12272} Any 
106d0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 68  SQL statement th
106e0 61 74 20 69 73 20 69 6e 74 65 72 72 75 70 74 65  at is interrupte
106f0 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 69 6e  d by [sqlite3_in
10700 74 65 72 72 75 70 74 28 29 5d 0a 2a 2a 20 20 20  terrupt()].**   
10710 20 20 20 20 20 20 20 77 69 6c 6c 20 72 65 74 75         will retu
10720 72 6e 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52  rn [SQLITE_INTER
10730 52 55 50 54 5d 2e 0a 2a 2a 0a 2a 2a 20 41 53 53  RUPT]..**.** ASS
10740 55 4d 50 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20  UMPTIONS:.**.** 
10750 7b 41 31 32 32 37 39 7d 20 49 66 20 74 68 65 20  {A12279} If the 
10760 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
10770 69 6f 6e 20 63 6c 6f 73 65 73 20 77 68 69 6c 65  ion closes while
10780 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72   [sqlite3_interr
10790 75 70 74 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20  upt()].**       
107a0 20 20 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68     is running th
107b0 65 6e 20 62 61 64 20 74 68 69 6e 67 73 20 77 69  en bad things wi
107c0 6c 6c 20 6c 69 6b 65 6c 79 20 68 61 70 70 65 6e  ll likely happen
107d0 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65  ..*/.void sqlite
107e0 33 5f 69 6e 74 65 72 72 75 70 74 28 73 71 6c 69  3_interrupt(sqli
107f0 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  te3*);../*.** CA
10800 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e  PI3REF: Determin
10810 65 20 49 66 20 41 6e 20 53 51 4c 20 53 74 61 74  e If An SQL Stat
10820 65 6d 65 6e 74 20 49 73 20 43 6f 6d 70 6c 65 74  ement Is Complet
10830 65 20 7b 48 31 30 35 31 30 7d 20 3c 53 37 30 32  e {H10510} <S702
10840 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  00>.**.** These 
10850 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65  routines are use
10860 66 75 6c 20 66 6f 72 20 63 6f 6d 6d 61 6e 64 2d  ful for command-
10870 6c 69 6e 65 20 69 6e 70 75 74 20 74 6f 20 64 65  line input to de
10880 74 65 72 6d 69 6e 65 20 69 66 20 74 68 65 0a 2a  termine if the.*
10890 2a 20 63 75 72 72 65 6e 74 6c 79 20 65 6e 74 65  * currently ente
108a0 72 65 64 20 74 65 78 74 20 73 65 65 6d 73 20 74  red text seems t
108b0 6f 20 66 6f 72 6d 20 63 6f 6d 70 6c 65 74 65 20  o form complete 
108c0 61 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  a SQL statement 
108d0 6f 72 0a 2a 2a 20 69 66 20 61 64 64 69 74 69 6f  or.** if additio
108e0 6e 61 6c 20 69 6e 70 75 74 20 69 73 20 6e 65 65  nal input is nee
108f0 64 65 64 20 62 65 66 6f 72 65 20 73 65 6e 64 69  ded before sendi
10900 6e 67 20 74 68 65 20 74 65 78 74 20 69 6e 74 6f  ng the text into
10910 0a 2a 2a 20 53 51 4c 69 74 65 20 66 6f 72 20 70  .** SQLite for p
10920 61 72 73 69 6e 67 2e 20 20 54 68 65 73 65 20 72  arsing.  These r
10930 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74  outines return t
10940 72 75 65 20 69 66 20 74 68 65 20 69 6e 70 75 74  rue if the input
10950 20 73 74 72 69 6e 67 0a 2a 2a 20 61 70 70 65 61   string.** appea
10960 72 73 20 74 6f 20 62 65 20 61 20 63 6f 6d 70 6c  rs to be a compl
10970 65 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ete SQL statemen
10980 74 2e 20 20 41 20 73 74 61 74 65 6d 65 6e 74 20  t.  A statement 
10990 69 73 20 6a 75 64 67 65 64 20 74 6f 20 62 65 0a  is judged to be.
109a0 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 69 66 20 69  ** complete if i
109b0 74 20 65 6e 64 73 20 77 69 74 68 20 61 20 73 65  t ends with a se
109c0 6d 69 63 6f 6c 6f 6e 20 74 6f 6b 65 6e 20 61 6e  micolon token an
109d0 64 20 69 73 20 6e 6f 74 20 61 20 66 72 61 67 6d  d is not a fragm
109e0 65 6e 74 20 6f 66 20 61 0a 2a 2a 20 43 52 45 41  ent of a.** CREA
109f0 54 45 20 54 52 49 47 47 45 52 20 73 74 61 74 65  TE TRIGGER state
10a00 6d 65 6e 74 2e 20 20 53 65 6d 69 63 6f 6c 6f 6e  ment.  Semicolon
10a10 73 20 74 68 61 74 20 61 72 65 20 65 6d 62 65 64  s that are embed
10a20 64 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 73 74  ded within.** st
10a30 72 69 6e 67 20 6c 69 74 65 72 61 6c 73 20 6f 72  ring literals or
10a40 20 71 75 6f 74 65 64 20 69 64 65 6e 74 69 66 69   quoted identifi
10a50 65 72 20 6e 61 6d 65 73 20 6f 72 20 63 6f 6d 6d  er names or comm
10a60 65 6e 74 73 20 61 72 65 20 6e 6f 74 0a 2a 2a 20  ents are not.** 
10a70 69 6e 64 65 70 65 6e 64 65 6e 74 20 74 6f 6b 65  independent toke
10a80 6e 73 20 28 74 68 65 79 20 61 72 65 20 70 61 72  ns (they are par
10a90 74 20 6f 66 20 74 68 65 20 74 6f 6b 65 6e 20 69  t of the token i
10aa0 6e 20 77 68 69 63 68 20 74 68 65 79 20 61 72 65  n which they are
10ab0 0a 2a 2a 20 65 6d 62 65 64 64 65 64 29 20 61 6e  .** embedded) an
10ac0 64 20 74 68 75 73 20 64 6f 20 6e 6f 74 20 63 6f  d thus do not co
10ad0 75 6e 74 20 61 73 20 61 20 73 74 61 74 65 6d 65  unt as a stateme
10ae0 6e 74 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a  nt terminator..*
10af0 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
10b00 6e 65 73 20 64 6f 20 6e 6f 74 20 70 61 72 73 65  nes do not parse
10b10 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
10b20 6e 74 73 20 74 68 75 73 0a 2a 2a 20 77 69 6c 6c  nts thus.** will
10b30 20 6e 6f 74 20 64 65 74 65 63 74 20 73 79 6e 74   not detect synt
10b40 61 63 74 69 63 61 6c 6c 79 20 69 6e 63 6f 72 72  actically incorr
10b50 65 63 74 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20 49  ect SQL..**.** I
10b60 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
10b70 20 7b 48 31 30 35 31 31 7d 20 41 20 73 75 63 63   {H10511} A succ
10b80 65 73 73 66 75 6c 20 65 76 61 6c 75 61 74 69 6f  essful evaluatio
10b90 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 63 6f  n of [sqlite3_co
10ba0 6d 70 6c 65 74 65 28 29 5d 20 6f 72 0a 2a 2a 20  mplete()] or.** 
10bb0 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
10bc0 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 5d 20  3_complete16()] 
10bd0 66 75 6e 63 74 69 6f 6e 73 20 73 68 61 6c 6c 0a  functions shall.
10be0 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75  **          retu
10bf0 72 6e 20 61 20 6e 75 6d 65 72 69 63 20 31 20 69  rn a numeric 1 i
10c00 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68  f and only if th
10c10 65 20 6c 61 73 74 20 6e 6f 6e 2d 77 68 69 74 65  e last non-white
10c20 73 70 61 63 65 0a 2a 2a 20 20 20 20 20 20 20 20  space.**        
10c30 20 20 74 6f 6b 65 6e 20 69 6e 20 74 68 65 69 72    token in their
10c40 20 69 6e 70 75 74 20 69 73 20 61 20 73 65 6d 69   input is a semi
10c50 63 6f 6c 6f 6e 20 74 68 61 74 20 69 73 20 6e 6f  colon that is no
10c60 74 20 69 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20  t in between.** 
10c70 20 20 20 20 20 20 20 20 20 74 68 65 20 42 45 47           the BEG
10c80 49 4e 20 61 6e 64 20 45 4e 44 20 6f 66 20 61 20  IN and END of a 
10c90 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20 73  CREATE TRIGGER s
10ca0 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  tatement..**.** 
10cb0 7b 48 31 30 35 31 32 7d 20 49 66 20 61 20 6d 65  {H10512} If a me
10cc0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
10cd0 65 72 72 6f 72 20 6f 63 63 75 72 73 20 64 75 72  error occurs dur
10ce0 69 6e 67 20 61 6e 20 69 6e 76 6f 63 61 74 69 6f  ing an invocatio
10cf0 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66  n.**          of
10d00 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65   [sqlite3_comple
10d10 74 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  te()] or [sqlite
10d20 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 5d 20  3_complete16()] 
10d30 74 68 65 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20  then the.**     
10d40 20 20 20 20 20 72 6f 75 74 69 6e 65 20 73 68 61       routine sha
10d50 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  ll return [SQLIT
10d60 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20  E_NOMEM]..**.** 
10d70 41 53 53 55 4d 50 54 49 4f 4e 53 3a 0a 2a 2a 0a  ASSUMPTIONS:.**.
10d80 2a 2a 20 7b 41 31 30 35 31 32 7d 20 54 68 65 20  ** {A10512} The 
10d90 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65  input to [sqlite
10da0 33 5f 63 6f 6d 70 6c 65 74 65 28 29 5d 20 6d 75  3_complete()] mu
10db0 73 74 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 72  st be a zero-ter
10dc0 6d 69 6e 61 74 65 64 0a 2a 2a 20 20 20 20 20 20  minated.**      
10dd0 20 20 20 20 55 54 46 2d 38 20 73 74 72 69 6e 67      UTF-8 string
10de0 2e 0a 2a 2a 0a 2a 2a 20 7b 41 31 30 35 31 33 7d  ..**.** {A10513}
10df0 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20 5b 73   The input to [s
10e00 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31  qlite3_complete1
10e10 36 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a  6()] must be a z
10e20 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a  ero-terminated.*
10e30 2a 20 20 20 20 20 20 20 20 20 20 55 54 46 2d 31  *          UTF-1
10e40 36 20 73 74 72 69 6e 67 20 69 6e 20 6e 61 74 69  6 string in nati
10e50 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a  ve byte order..*
10e60 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  /.int sqlite3_co
10e70 6d 70 6c 65 74 65 28 63 6f 6e 73 74 20 63 68 61  mplete(const cha
10e80 72 20 2a 73 71 6c 29 3b 0a 69 6e 74 20 73 71 6c  r *sql);.int sql
10e90 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28  ite3_complete16(
10ea0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 29  const void *sql)
10eb0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
10ec0 46 3a 20 52 65 67 69 73 74 65 72 20 41 20 43 61  F: Register A Ca
10ed0 6c 6c 62 61 63 6b 20 54 6f 20 48 61 6e 64 6c 65  llback To Handle
10ee0 20 53 51 4c 49 54 45 5f 42 55 53 59 20 45 72 72   SQLITE_BUSY Err
10ef0 6f 72 73 20 7b 48 31 32 33 31 30 7d 20 3c 53 34  ors {H12310} <S4
10f00 30 34 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  0400>.**.** This
10f10 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20   routine sets a 
10f20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
10f30 6e 20 74 68 61 74 20 6d 69 67 68 74 20 62 65 20  n that might be 
10f40 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72  invoked whenever
10f50 0a 2a 2a 20 61 6e 20 61 74 74 65 6d 70 74 20 69  .** an attempt i
10f60 73 20 6d 61 64 65 20 74 6f 20 6f 70 65 6e 20 61  s made to open a
10f70 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 20   database table 
10f80 74 68 61 74 20 61 6e 6f 74 68 65 72 20 74 68 72  that another thr
10f90 65 61 64 0a 2a 2a 20 6f 72 20 70 72 6f 63 65 73  ead.** or proces
10fa0 73 20 68 61 73 20 6c 6f 63 6b 65 64 2e 0a 2a 2a  s has locked..**
10fb0 0a 2a 2a 20 49 66 20 74 68 65 20 62 75 73 79 20  .** If the busy 
10fc0 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c  callback is NULL
10fd0 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 42  , then [SQLITE_B
10fe0 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  USY] or [SQLITE_
10ff0 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a  IOERR_BLOCKED].*
11000 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 6d  * is returned im
11010 6d 65 64 69 61 74 65 6c 79 20 75 70 6f 6e 20 65  mediately upon e
11020 6e 63 6f 75 6e 74 65 72 69 6e 67 20 74 68 65 20  ncountering the 
11030 6c 6f 63 6b 2e 20 49 66 20 74 68 65 20 62 75 73  lock. If the bus
11040 79 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73  y callback.** is
11050 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20   not NULL, then 
11060 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 77 69 6c  the callback wil
11070 6c 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74  l be invoked wit
11080 68 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 2e  h two arguments.
11090 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  .**.** The first
110a0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
110b0 20 68 61 6e 64 6c 65 72 20 69 73 20 61 20 63 6f   handler is a co
110c0 70 79 20 6f 66 20 74 68 65 20 76 6f 69 64 2a 20  py of the void* 
110d0 70 6f 69 6e 74 65 72 20 77 68 69 63 68 0a 2a 2a  pointer which.**
110e0 20 69 73 20 74 68 65 20 74 68 69 72 64 20 61 72   is the third ar
110f0 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65  gument to sqlite
11100 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29  3_busy_handler()
11110 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72  .  The second ar
11120 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74 68 65  gument to.** the
11130 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63   handler callbac
11140 6b 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20  k is the number 
11150 6f 66 20 74 69 6d 65 73 20 74 68 61 74 20 74 68  of times that th
11160 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 68  e busy handler h
11170 61 73 0a 2a 2a 20 62 65 65 6e 20 69 6e 76 6f 6b  as.** been invok
11180 65 64 20 66 6f 72 20 74 68 69 73 20 6c 6f 63 6b  ed for this lock
11190 69 6e 67 20 65 76 65 6e 74 2e 20 20 49 66 20 74  ing event.  If t
111a0 68 65 0a 2a 2a 20 62 75 73 79 20 63 61 6c 6c 62  he.** busy callb
111b0 61 63 6b 20 72 65 74 75 72 6e 73 20 30 2c 20 74  ack returns 0, t
111c0 68 65 6e 20 6e 6f 20 61 64 64 69 74 69 6f 6e 61  hen no additiona
111d0 6c 20 61 74 74 65 6d 70 74 73 20 61 72 65 20 6d  l attempts are m
111e0 61 64 65 20 74 6f 0a 2a 2a 20 61 63 63 65 73 73  ade to.** access
111f0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 61 6e   the database an
11200 64 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20  d [SQLITE_BUSY] 
11210 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  or [SQLITE_IOERR
11220 5f 42 4c 4f 43 4b 45 44 5d 20 69 73 20 72 65 74  _BLOCKED] is ret
11230 75 72 6e 65 64 2e 0a 2a 2a 20 49 66 20 74 68 65  urned..** If the
11240 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
11250 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e  s non-zero, then
11260 20 61 6e 6f 74 68 65 72 20 61 74 74 65 6d 70 74   another attempt
11270 0a 2a 2a 20 69 73 20 6d 61 64 65 20 74 6f 20 6f  .** is made to o
11280 70 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  pen the database
11290 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64   for reading and
112a0 20 74 68 65 20 63 79 63 6c 65 20 72 65 70 65 61   the cycle repea
112b0 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72  ts..**.** The pr
112c0 65 73 65 6e 63 65 20 6f 66 20 61 20 62 75 73 79  esence of a busy
112d0 20 68 61 6e 64 6c 65 72 20 64 6f 65 73 20 6e 6f   handler does no
112e0 74 20 67 75 61 72 61 6e 74 65 65 20 74 68 61 74  t guarantee that
112f0 20 69 74 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f   it will be invo
11300 6b 65 64 0a 2a 2a 20 77 68 65 6e 20 74 68 65 72  ked.** when ther
11310 65 20 69 73 20 6c 6f 63 6b 20 63 6f 6e 74 65 6e  e is lock conten
11320 74 69 6f 6e 2e 20 49 66 20 53 51 4c 69 74 65 20  tion. If SQLite 
11330 64 65 74 65 72 6d 69 6e 65 73 20 74 68 61 74 20  determines that 
11340 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62 75 73  invoking the bus
11350 79 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 63 6f 75  y.** handler cou
11360 6c 64 20 72 65 73 75 6c 74 20 69 6e 20 61 20 64  ld result in a d
11370 65 61 64 6c 6f 63 6b 2c 20 69 74 20 77 69 6c 6c  eadlock, it will
11380 20 67 6f 20 61 68 65 61 64 20 61 6e 64 20 72 65   go ahead and re
11390 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53  turn [SQLITE_BUS
113a0 59 5d 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45  Y].** or [SQLITE
113b0 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 20  _IOERR_BLOCKED] 
113c0 69 6e 73 74 65 61 64 20 6f 66 20 69 6e 76 6f 6b  instead of invok
113d0 69 6e 67 20 74 68 65 20 62 75 73 79 20 68 61 6e  ing the busy han
113e0 64 6c 65 72 2e 0a 2a 2a 20 43 6f 6e 73 69 64 65  dler..** Conside
113f0 72 20 61 20 73 63 65 6e 61 72 69 6f 20 77 68 65  r a scenario whe
11400 72 65 20 6f 6e 65 20 70 72 6f 63 65 73 73 20 69  re one process i
11410 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 61 64  s holding a read
11420 20 6c 6f 63 6b 20 74 68 61 74 0a 2a 2a 20 69 74   lock that.** it
11430 20 69 73 20 74 72 79 69 6e 67 20 74 6f 20 70 72   is trying to pr
11440 6f 6d 6f 74 65 20 74 6f 20 61 20 72 65 73 65 72  omote to a reser
11450 76 65 64 20 6c 6f 63 6b 20 61 6e 64 0a 2a 2a 20  ved lock and.** 
11460 61 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73  a second process
11470 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65   is holding a re
11480 73 65 72 76 65 64 20 6c 6f 63 6b 20 74 68 61 74  served lock that
11490 20 69 74 20 69 73 20 74 72 79 69 6e 67 0a 2a 2a   it is trying.**
114a0 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61   to promote to a
114b0 6e 20 65 78 63 6c 75 73 69 76 65 20 6c 6f 63 6b  n exclusive lock
114c0 2e 20 20 54 68 65 20 66 69 72 73 74 20 70 72 6f  .  The first pro
114d0 63 65 73 73 20 63 61 6e 6e 6f 74 20 70 72 6f 63  cess cannot proc
114e0 65 65 64 0a 2a 2a 20 62 65 63 61 75 73 65 20 69  eed.** because i
114f0 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20  t is blocked by 
11500 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74  the second and t
11510 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73  he second proces
11520 73 20 63 61 6e 6e 6f 74 0a 2a 2a 20 70 72 6f 63  s cannot.** proc
11530 65 65 64 20 62 65 63 61 75 73 65 20 69 74 20 69  eed because it i
11540 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65  s blocked by the
11550 20 66 69 72 73 74 2e 20 20 49 66 20 62 6f 74 68   first.  If both
11560 20 70 72 6f 63 65 73 73 65 73 0a 2a 2a 20 69 6e   processes.** in
11570 76 6f 6b 65 20 74 68 65 20 62 75 73 79 20 68 61  voke the busy ha
11580 6e 64 6c 65 72 73 2c 20 6e 65 69 74 68 65 72 20  ndlers, neither 
11590 77 69 6c 6c 20 6d 61 6b 65 20 61 6e 79 20 70 72  will make any pr
115a0 6f 67 72 65 73 73 2e 20 20 54 68 65 72 65 66 6f  ogress.  Therefo
115b0 72 65 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 72 65  re,.** SQLite re
115c0 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 42 55  turns [SQLITE_BU
115d0 53 59 5d 20 66 6f 72 20 74 68 65 20 66 69 72 73  SY] for the firs
115e0 74 20 70 72 6f 63 65 73 73 2c 20 68 6f 70 69 6e  t process, hopin
115f0 67 20 74 68 61 74 20 74 68 69 73 0a 2a 2a 20 77  g that this.** w
11600 69 6c 6c 20 69 6e 64 75 63 65 20 74 68 65 20 66  ill induce the f
11610 69 72 73 74 20 70 72 6f 63 65 73 73 20 74 6f 20  irst process to 
11620 72 65 6c 65 61 73 65 20 69 74 73 20 72 65 61 64  release its read
11630 20 6c 6f 63 6b 20 61 6e 64 20 61 6c 6c 6f 77 0a   lock and allow.
11640 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72  ** the second pr
11650 6f 63 65 73 73 20 74 6f 20 70 72 6f 63 65 65 64  ocess to proceed
11660 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 66 61  ..**.** The defa
11670 75 6c 74 20 62 75 73 79 20 63 61 6c 6c 62 61 63  ult busy callbac
11680 6b 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  k is NULL..**.**
11690 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 42 55 53   The [SQLITE_BUS
116a0 59 5d 20 65 72 72 6f 72 20 69 73 20 63 6f 6e 76  Y] error is conv
116b0 65 72 74 65 64 20 74 6f 20 5b 53 51 4c 49 54 45  erted to [SQLITE
116c0 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a  _IOERR_BLOCKED].
116d0 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69  ** when SQLite i
116e0 73 20 69 6e 20 74 68 65 20 6d 69 64 64 6c 65 20  s in the middle 
116f0 6f 66 20 61 20 6c 61 72 67 65 20 74 72 61 6e 73  of a large trans
11700 61 63 74 69 6f 6e 20 77 68 65 72 65 20 61 6c 6c  action where all
11710 20 74 68 65 0a 2a 2a 20 63 68 61 6e 67 65 73 20   the.** changes 
11720 77 69 6c 6c 20 6e 6f 74 20 66 69 74 20 69 6e 74  will not fit int
11730 6f 20 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79 20  o the in-memory 
11740 63 61 63 68 65 2e 20 20 53 51 4c 69 74 65 20 77  cache.  SQLite w
11750 69 6c 6c 0a 2a 2a 20 61 6c 72 65 61 64 79 20 68  ill.** already h
11760 6f 6c 64 20 61 20 52 45 53 45 52 56 45 44 20 6c  old a RESERVED l
11770 6f 63 6b 20 6f 6e 20 74 68 65 20 64 61 74 61 62  ock on the datab
11780 61 73 65 20 66 69 6c 65 2c 20 62 75 74 20 69 74  ase file, but it
11790 20 6e 65 65 64 73 0a 2a 2a 20 74 6f 20 70 72 6f   needs.** to pro
117a0 6d 6f 74 65 20 74 68 69 73 20 6c 6f 63 6b 20 74  mote this lock t
117b0 6f 20 45 58 43 4c 55 53 49 56 45 20 73 6f 20 74  o EXCLUSIVE so t
117c0 68 61 74 20 69 74 20 63 61 6e 20 73 70 69 6c 6c  hat it can spill
117d0 20 63 61 63 68 65 0a 2a 2a 20 70 61 67 65 73 20   cache.** pages 
117e0 69 6e 74 6f 20 74 68 65 20 64 61 74 61 62 61 73  into the databas
117f0 65 20 66 69 6c 65 20 77 69 74 68 6f 75 74 20 68  e file without h
11800 61 72 6d 20 74 6f 20 63 6f 6e 63 75 72 72 65 6e  arm to concurren
11810 74 0a 2a 2a 20 72 65 61 64 65 72 73 2e 20 20 49  t.** readers.  I
11820 66 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20 74  f it is unable t
11830 6f 20 70 72 6f 6d 6f 74 65 20 74 68 65 20 6c 6f  o promote the lo
11840 63 6b 2c 20 74 68 65 6e 20 74 68 65 20 69 6e 2d  ck, then the in-
11850 6d 65 6d 6f 72 79 0a 2a 2a 20 63 61 63 68 65 20  memory.** cache 
11860 77 69 6c 6c 20 62 65 20 6c 65 66 74 20 69 6e 20  will be left in 
11870 61 6e 20 69 6e 63 6f 6e 73 69 73 74 65 6e 74 20  an inconsistent 
11880 73 74 61 74 65 20 61 6e 64 20 73 6f 20 74 68 65  state and so the
11890 20 65 72 72 6f 72 0a 2a 2a 20 63 6f 64 65 20 69   error.** code i
118a0 73 20 70 72 6f 6d 6f 74 65 64 20 66 72 6f 6d 20  s promoted from 
118b0 74 68 65 20 72 65 6c 61 74 69 76 65 6c 79 20 62  the relatively b
118c0 65 6e 69 67 6e 20 5b 53 51 4c 49 54 45 5f 42 55  enign [SQLITE_BU
118d0 53 59 5d 20 74 6f 0a 2a 2a 20 74 68 65 20 6d 6f  SY] to.** the mo
118e0 72 65 20 73 65 76 65 72 65 20 5b 53 51 4c 49 54  re severe [SQLIT
118f0 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d  E_IOERR_BLOCKED]
11900 2e 20 20 54 68 69 73 20 65 72 72 6f 72 20 63 6f  .  This error co
11910 64 65 20 70 72 6f 6d 6f 74 69 6f 6e 0a 2a 2a 20  de promotion.** 
11920 66 6f 72 63 65 73 20 61 6e 20 61 75 74 6f 6d 61  forces an automa
11930 74 69 63 20 72 6f 6c 6c 62 61 63 6b 20 6f 66 20  tic rollback of 
11940 74 68 65 20 63 68 61 6e 67 65 73 2e 20 20 53 65  the changes.  Se
11950 65 20 74 68 65 0a 2a 2a 20 3c 61 20 68 72 65 66  e the.** <a href
11960 3d 22 2f 63 76 73 74 72 61 63 2f 77 69 6b 69 3f  ="/cvstrac/wiki?
11970 70 3d 43 6f 72 72 75 70 74 69 6f 6e 46 6f 6c 6c  p=CorruptionFoll
11980 6f 77 69 6e 67 42 75 73 79 45 72 72 6f 72 22 3e  owingBusyError">
11990 0a 2a 2a 20 43 6f 72 72 75 70 74 69 6f 6e 46 6f  .** CorruptionFo
119a0 6c 6c 6f 77 69 6e 67 42 75 73 79 45 72 72 6f 72  llowingBusyError
119b0 3c 2f 61 3e 20 77 69 6b 69 20 70 61 67 65 20 66  </a> wiki page f
119c0 6f 72 20 61 20 64 69 73 63 75 73 73 69 6f 6e 20  or a discussion 
119d0 6f 66 20 77 68 79 0a 2a 2a 20 74 68 69 73 20 69  of why.** this i
119e0 73 20 69 6d 70 6f 72 74 61 6e 74 2e 0a 2a 2a 0a  s important..**.
119f0 2a 2a 20 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c  ** There can onl
11a00 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75  y be a single bu
11a10 73 79 20 68 61 6e 64 6c 65 72 20 64 65 66 69 6e  sy handler defin
11a20 65 64 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 5b  ed for each.** [
11a30 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
11a40 69 6f 6e 5d 2e 20 20 53 65 74 74 69 6e 67 20 61  ion].  Setting a
11a50 20 6e 65 77 20 62 75 73 79 20 68 61 6e 64 6c 65   new busy handle
11a60 72 20 63 6c 65 61 72 73 20 61 6e 79 0a 2a 2a 20  r clears any.** 
11a70 70 72 65 76 69 6f 75 73 6c 79 20 73 65 74 20 68  previously set h
11a80 61 6e 64 6c 65 72 2e 20 20 4e 6f 74 65 20 74 68  andler.  Note th
11a90 61 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  at calling [sqli
11aa0 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74  te3_busy_timeout
11ab0 28 29 5d 0a 2a 2a 20 77 69 6c 6c 20 61 6c 73 6f  ()].** will also
11ac0 20 73 65 74 20 6f 72 20 63 6c 65 61 72 20 74 68   set or clear th
11ad0 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a  e busy handler..
11ae0 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
11af0 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33 31 31 7d  :.**.** {H12311}
11b00 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 75   The [sqlite3_bu
11b10 73 79 5f 68 61 6e 64 6c 65 72 28 44 2c 43 2c 41  sy_handler(D,C,A
11b20 29 5d 20 66 75 6e 63 74 69 6f 6e 20 73 68 61 6c  )] function shal
11b30 6c 20 72 65 70 6c 61 63 65 0a 2a 2a 20 20 20 20  l replace.**    
11b40 20 20 20 20 20 20 62 75 73 79 20 63 61 6c 6c 62        busy callb
11b50 61 63 6b 20 69 6e 20 74 68 65 20 5b 64 61 74 61  ack in the [data
11b60 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
11b70 20 44 20 77 69 74 68 20 61 20 6e 65 77 0a 2a 2a   D with a new.**
11b80 20 20 20 20 20 20 20 20 20 20 61 20 6e 65 77 20            a new 
11b90 62 75 73 79 20 68 61 6e 64 6c 65 72 20 43 20 61  busy handler C a
11ba0 6e 64 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  nd application d
11bb0 61 74 61 20 70 6f 69 6e 74 65 72 20 41 2e 0a 2a  ata pointer A..*
11bc0 2a 0a 2a 2a 20 7b 48 31 32 33 31 32 7d 20 4e 65  *.** {H12312} Ne
11bd0 77 6c 79 20 63 72 65 61 74 65 64 20 5b 64 61 74  wly created [dat
11be0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
11bf0 73 5d 20 73 68 61 6c 6c 20 68 61 76 65 20 61 20  s] shall have a 
11c00 62 75 73 79 0a 2a 2a 20 20 20 20 20 20 20 20 20  busy.**         
11c10 20 68 61 6e 64 6c 65 72 20 6f 66 20 4e 55 4c 4c   handler of NULL
11c20 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33 31 34 7d  ..**.** {H12314}
11c30 20 57 68 65 6e 20 74 77 6f 20 6f 72 20 6d 6f 72   When two or mor
11c40 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
11c50 65 63 74 69 6f 6e 73 5d 20 73 68 61 72 65 20 61  ections] share a
11c60 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
11c70 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61  lite3_enable_sha
11c80 72 65 64 5f 63 61 63 68 65 20 7c 20 63 6f 6d 6d  red_cache | comm
11c90 6f 6e 20 63 61 63 68 65 5d 2c 0a 2a 2a 20 20 20  on cache],.**   
11ca0 20 20 20 20 20 20 20 74 68 65 20 62 75 73 79 20         the busy 
11cb0 68 61 6e 64 6c 65 72 20 66 6f 72 20 74 68 65 20  handler for the 
11cc0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
11cd0 69 6f 6e 20 63 75 72 72 65 6e 74 6c 79 20 75 73  ion currently us
11ce0 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ing.**          
11cf0 74 68 65 20 63 61 63 68 65 20 73 68 61 6c 6c 20  the cache shall 
11d00 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20  be invoked when 
11d10 74 68 65 20 63 61 63 68 65 20 65 6e 63 6f 75 6e  the cache encoun
11d20 74 65 72 73 20 61 20 6c 6f 63 6b 2e 0a 2a 2a 0a  ters a lock..**.
11d30 2a 2a 20 7b 48 31 32 33 31 36 7d 20 49 66 20 61  ** {H12316} If a
11d40 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 63 61   busy handler ca
11d50 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 7a  llback returns z
11d60 65 72 6f 2c 20 74 68 65 6e 20 74 68 65 20 53 51  ero, then the SQ
11d70 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 0a 2a  Lite interface.*
11d80 2a 20 20 20 20 20 20 20 20 20 20 74 68 61 74 20  *          that 
11d90 70 72 6f 76 6f 6b 65 64 20 74 68 65 20 6c 6f 63  provoked the loc
11da0 6b 69 6e 67 20 65 76 65 6e 74 20 73 68 61 6c 6c  king event shall
11db0 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
11dc0 42 55 53 59 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  BUSY]..**.** {H1
11dd0 32 33 31 38 7d 20 53 51 4c 69 74 65 20 73 68 61  2318} SQLite sha
11de0 6c 6c 20 69 6e 76 6f 6b 65 73 20 74 68 65 20 62  ll invokes the b
11df0 75 73 79 20 68 61 6e 64 6c 65 72 20 77 69 74 68  usy handler with
11e00 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 20 77   two arguments w
11e10 68 69 63 68 0a 2a 2a 20 20 20 20 20 20 20 20 20  hich.**         
11e20 20 61 72 65 20 61 20 63 6f 70 79 20 6f 66 20 74   are a copy of t
11e30 68 65 20 70 6f 69 6e 74 65 72 20 73 75 70 70 6c  he pointer suppl
11e40 69 65 64 20 62 79 20 74 68 65 20 33 72 64 20 70  ied by the 3rd p
11e50 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 20  arameter to.**  
11e60 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
11e70 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 5d  _busy_handler()]
11e80 20 61 6e 64 20 61 20 63 6f 75 6e 74 20 6f 66 20   and a count of 
11e90 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 70 72  the number of pr
11ea0 69 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ior.**          
11eb0 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74  invocations of t
11ec0 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  he busy handler 
11ed0 66 6f 72 20 74 68 65 20 73 61 6d 65 20 6c 6f 63  for the same loc
11ee0 6b 69 6e 67 20 65 76 65 6e 74 2e 0a 2a 2a 0a 2a  king event..**.*
11ef0 2a 20 41 53 53 55 4d 50 54 49 4f 4e 53 3a 0a 2a  * ASSUMPTIONS:.*
11f00 2a 0a 2a 2a 20 7b 41 31 32 33 31 39 7d 20 41 20  *.** {A12319} A 
11f10 62 75 73 79 20 68 61 6e 64 6c 65 72 20 6d 75 73  busy handler mus
11f20 74 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65 20  t not close the 
11f30 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
11f40 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ion.**          
11f50 6f 72 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  or [prepared sta
11f60 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 6e 76  tement] that inv
11f70 6f 6b 65 64 20 74 68 65 20 62 75 73 79 20 68 61  oked the busy ha
11f80 6e 64 6c 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ndler..*/.int sq
11f90 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c  lite3_busy_handl
11fa0 65 72 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74  er(sqlite3*, int
11fb0 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 29 2c 20  (*)(void*,int), 
11fc0 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  void*);../*.** C
11fd0 41 50 49 33 52 45 46 3a 20 53 65 74 20 41 20 42  API3REF: Set A B
11fe0 75 73 79 20 54 69 6d 65 6f 75 74 20 7b 48 31 32  usy Timeout {H12
11ff0 33 34 30 7d 20 3c 53 34 30 34 31 30 3e 0a 2a 2a  340} <S40410>.**
12000 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65  .** This routine
12010 20 73 65 74 73 20 61 20 5b 73 71 6c 69 74 65 33   sets a [sqlite3
12020 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 20 7c 20  _busy_handler | 
12030 62 75 73 79 20 68 61 6e 64 6c 65 72 5d 20 74 68  busy handler] th
12040 61 74 20 73 6c 65 65 70 73 0a 2a 2a 20 66 6f 72  at sleeps.** for
12050 20 61 20 73 70 65 63 69 66 69 65 64 20 61 6d 6f   a specified amo
12060 75 6e 74 20 6f 66 20 74 69 6d 65 20 77 68 65 6e  unt of time when
12070 20 61 20 74 61 62 6c 65 20 69 73 20 6c 6f 63 6b   a table is lock
12080 65 64 2e 20 20 54 68 65 20 68 61 6e 64 6c 65 72  ed.  The handler
12090 0a 2a 2a 20 77 69 6c 6c 20 73 6c 65 65 70 20 6d  .** will sleep m
120a0 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 75 6e  ultiple times un
120b0 74 69 6c 20 61 74 20 6c 65 61 73 74 20 22 6d 73  til at least "ms
120c0 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f  " milliseconds o
120d0 66 20 73 6c 65 65 70 69 6e 67 0a 2a 2a 20 68 61  f sleeping.** ha
120e0 76 65 20 61 63 63 75 6d 75 6c 61 74 65 64 2e 20  ve accumulated. 
120f0 7b 48 31 32 33 34 33 7d 20 41 66 74 65 72 20 22  {H12343} After "
12100 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73  ms" milliseconds
12110 20 6f 66 20 73 6c 65 65 70 69 6e 67 2c 0a 2a 2a   of sleeping,.**
12120 20 74 68 65 20 68 61 6e 64 6c 65 72 20 72 65 74   the handler ret
12130 75 72 6e 73 20 30 20 77 68 69 63 68 20 63 61 75  urns 0 which cau
12140 73 65 73 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  ses [sqlite3_ste
12150 70 28 29 5d 20 74 6f 20 72 65 74 75 72 6e 0a 2a  p()] to return.*
12160 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20  * [SQLITE_BUSY] 
12170 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  or [SQLITE_IOERR
12180 5f 42 4c 4f 43 4b 45 44 5d 2e 0a 2a 2a 0a 2a 2a  _BLOCKED]..**.**
12190 20 43 61 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f   Calling this ro
121a0 75 74 69 6e 65 20 77 69 74 68 20 61 6e 20 61 72  utine with an ar
121b0 67 75 6d 65 6e 74 20 6c 65 73 73 20 74 68 61 6e  gument less than
121c0 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72   or equal to zer
121d0 6f 0a 2a 2a 20 74 75 72 6e 73 20 6f 66 66 20 61  o.** turns off a
121e0 6c 6c 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73  ll busy handlers
121f0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 63 61  ..**.** There ca
12200 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67  n only be a sing
12210 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  le busy handler 
12220 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72  for a particular
12230 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
12240 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 79 20 61 6e  nnection] any an
12250 79 20 67 69 76 65 6e 20 6d 6f 6d 65 6e 74 2e 20  y given moment. 
12260 20 49 66 20 61 6e 6f 74 68 65 72 20 62 75 73 79   If another busy
12270 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 61 73 20   handler.** was 
12280 64 65 66 69 6e 65 64 20 20 28 75 73 69 6e 67 20  defined  (using 
12290 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61  [sqlite3_busy_ha
122a0 6e 64 6c 65 72 28 29 5d 29 20 70 72 69 6f 72 20  ndler()]) prior 
122b0 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 74 68  to calling.** th
122c0 69 73 20 72 6f 75 74 69 6e 65 2c 20 74 68 61 74  is routine, that
122d0 20 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e 64   other busy hand
122e0 6c 65 72 20 69 73 20 63 6c 65 61 72 65 64 2e 0a  ler is cleared..
122f0 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
12300 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33 34 31 7d  :.**.** {H12341}
12310 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 75   The [sqlite3_bu
12320 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 66 75  sy_timeout()] fu
12330 6e 63 74 69 6f 6e 20 73 68 61 6c 6c 20 6f 76 65  nction shall ove
12340 72 72 69 64 65 20 61 6e 79 20 70 72 69 6f 72 0a  rride any prior.
12350 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
12360 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75  ite3_busy_timeou
12370 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  t()] or [sqlite3
12380 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 5d  _busy_handler()]
12390 20 73 65 74 74 69 6e 67 0a 2a 2a 20 20 20 20 20   setting.**     
123a0 20 20 20 20 20 6f 6e 20 74 68 65 20 73 61 6d 65       on the same
123b0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
123c0 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48  ction]..**.** {H
123d0 31 32 33 34 33 7d 20 49 66 20 74 68 65 20 32 6e  12343} If the 2n
123e0 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  d parameter to [
123f0 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d  sqlite3_busy_tim
12400 65 6f 75 74 28 29 5d 20 69 73 20 6c 65 73 73 20  eout()] is less 
12410 74 68 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  than.**         
12420 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72   or equal to zer
12430 6f 2c 20 74 68 65 6e 20 74 68 65 20 62 75 73 79  o, then the busy
12440 20 68 61 6e 64 6c 65 72 20 73 68 61 6c 6c 20 62   handler shall b
12450 65 20 63 6c 65 61 72 65 64 20 73 6f 20 74 68 61  e cleared so tha
12460 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6c  t.**          al
12470 6c 20 73 75 62 73 65 71 75 65 6e 74 20 6c 6f 63  l subsequent loc
12480 6b 69 6e 67 20 65 76 65 6e 74 73 20 69 6d 6d 65  king events imme
12490 64 69 61 74 65 6c 79 20 72 65 74 75 72 6e 20 5b  diately return [
124a0 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a  SQLITE_BUSY]..**
124b0 0a 2a 2a 20 7b 48 31 32 33 34 34 7d 20 49 66 20  .** {H12344} If 
124c0 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65  the 2nd paramete
124d0 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 75  r to [sqlite3_bu
124e0 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 69 73  sy_timeout()] is
124f0 20 61 20 70 6f 73 69 74 69 76 65 0a 2a 2a 20 20   a positive.**  
12500 20 20 20 20 20 20 20 20 6e 75 6d 62 65 72 20 4e          number N
12510 2c 20 74 68 65 6e 20 61 20 62 75 73 79 20 68 61  , then a busy ha
12520 6e 64 6c 65 72 20 73 68 61 6c 6c 20 62 65 20 73  ndler shall be s
12530 65 74 20 74 68 61 74 20 72 65 70 65 61 74 65 64  et that repeated
12540 6c 79 20 63 61 6c 6c 73 0a 2a 2a 20 20 20 20 20  ly calls.**     
12550 20 20 20 20 20 74 68 65 20 78 53 6c 65 65 70 28       the xSleep(
12560 29 20 6d 65 74 68 6f 64 20 69 6e 20 74 68 65 20  ) method in the 
12570 5b 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 56  [sqlite3_vfs | V
12580 46 53 20 69 6e 74 65 72 66 61 63 65 5d 20 75 6e  FS interface] un
12590 74 69 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  til.**          
125a0 65 69 74 68 65 72 20 74 68 65 20 6c 6f 63 6b 20  either the lock 
125b0 63 6c 65 61 72 73 20 6f 72 20 75 6e 74 69 6c 20  clears or until 
125c0 74 68 65 20 63 75 6d 75 6c 61 74 69 76 65 20 73  the cumulative s
125d0 6c 65 65 70 20 74 69 6d 65 0a 2a 2a 20 20 20 20  leep time.**    
125e0 20 20 20 20 20 20 72 65 70 6f 72 74 65 64 20 62        reported b
125f0 61 63 6b 20 62 79 20 78 53 6c 65 65 70 28 29 20  ack by xSleep() 
12600 65 78 63 65 65 64 73 20 4e 20 6d 69 6c 6c 69 73  exceeds N millis
12610 65 63 6f 6e 64 73 2e 0a 2a 2f 0a 69 6e 74 20 73  econds..*/.int s
12620 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65  qlite3_busy_time
12630 6f 75 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e  out(sqlite3*, in
12640 74 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  t ms);../*.** CA
12650 50 49 33 52 45 46 3a 20 43 6f 6e 76 65 6e 69 65  PI3REF: Convenie
12660 6e 63 65 20 52 6f 75 74 69 6e 65 73 20 46 6f 72  nce Routines For
12670 20 52 75 6e 6e 69 6e 67 20 51 75 65 72 69 65 73   Running Queries
12680 20 7b 48 31 32 33 37 30 7d 20 3c 53 31 30 30 30   {H12370} <S1000
12690 30 3e 0a 2a 2a 0a 2a 2a 20 44 65 66 69 6e 69 74  0>.**.** Definit
126a0 69 6f 6e 3a 20 41 20 3c 62 3e 72 65 73 75 6c 74  ion: A <b>result
126b0 20 74 61 62 6c 65 3c 2f 62 3e 20 69 73 20 6d 65   table</b> is me
126c0 6d 6f 72 79 20 64 61 74 61 20 73 74 72 75 63 74  mory data struct
126d0 75 72 65 20 63 72 65 61 74 65 64 20 62 79 20 74  ure created by t
126e0 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 67  he.** [sqlite3_g
126f0 65 74 5f 74 61 62 6c 65 28 29 5d 20 69 6e 74 65  et_table()] inte
12700 72 66 61 63 65 2e 20 20 41 20 72 65 73 75 6c 74  rface.  A result
12710 20 74 61 62 6c 65 20 72 65 63 6f 72 64 73 20 74   table records t
12720 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 71  he.** complete q
12730 75 65 72 79 20 72 65 73 75 6c 74 73 20 66 72 6f  uery results fro
12740 6d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 71 75  m one or more qu
12750 65 72 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  eries..**.** The
12760 20 74 61 62 6c 65 20 63 6f 6e 63 65 70 74 75 61   table conceptua
12770 6c 6c 79 20 68 61 73 20 61 20 6e 75 6d 62 65 72  lly has a number
12780 20 6f 66 20 72 6f 77 73 20 61 6e 64 20 63 6f 6c   of rows and col
12790 75 6d 6e 73 2e 20 20 42 75 74 0a 2a 2a 20 74 68  umns.  But.** th
127a0 65 73 65 20 6e 75 6d 62 65 72 73 20 61 72 65 20  ese numbers are 
127b0 6e 6f 74 20 70 61 72 74 20 6f 66 20 74 68 65 20  not part of the 
127c0 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 74 73  result table its
127d0 65 6c 66 2e 20 20 54 68 65 73 65 0a 2a 2a 20 6e  elf.  These.** n
127e0 75 6d 62 65 72 73 20 61 72 65 20 6f 62 74 61 69  umbers are obtai
127f0 6e 65 64 20 73 65 70 61 72 61 74 65 6c 79 2e 20  ned separately. 
12800 20 4c 65 74 20 4e 20 62 65 20 74 68 65 20 6e 75   Let N be the nu
12810 6d 62 65 72 20 6f 66 20 72 6f 77 73 0a 2a 2a 20  mber of rows.** 
12820 61 6e 64 20 4d 20 62 65 20 74 68 65 20 6e 75 6d  and M be the num
12830 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 2e 0a  ber of columns..
12840 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74  **.** A result t
12850 61 62 6c 65 20 69 73 20 61 6e 20 61 72 72 61 79  able is an array
12860 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20   of pointers to 
12870 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
12880 55 54 46 2d 38 20 73 74 72 69 6e 67 73 2e 0a 2a  UTF-8 strings..*
12890 2a 20 54 68 65 72 65 20 61 72 65 20 28 4e 2b 31  * There are (N+1
128a0 29 2a 4d 20 65 6c 65 6d 65 6e 74 73 20 69 6e 20  )*M elements in 
128b0 74 68 65 20 61 72 72 61 79 2e 20 20 54 68 65 20  the array.  The 
128c0 66 69 72 73 74 20 4d 20 70 6f 69 6e 74 65 72 73  first M pointers
128d0 20 70 6f 69 6e 74 0a 2a 2a 20 74 6f 20 7a 65 72   point.** to zer
128e0 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72  o-terminated str
128f0 69 6e 67 73 20 74 68 61 74 20 20 63 6f 6e 74 61  ings that  conta
12900 69 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20  in the names of 
12910 74 68 65 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20  the columns..** 
12920 54 68 65 20 72 65 6d 61 69 6e 69 6e 67 20 65 6e  The remaining en
12930 74 72 69 65 73 20 61 6c 6c 20 70 6f 69 6e 74 20  tries all point 
12940 74 6f 20 71 75 65 72 79 20 72 65 73 75 6c 74 73  to query results
12950 2e 20 20 4e 55 4c 4c 20 76 61 6c 75 65 73 20 72  .  NULL values r
12960 65 73 75 6c 74 0a 2a 2a 20 69 6e 20 4e 55 4c 4c  esult.** in NULL
12970 20 70 6f 69 6e 74 65 72 73 2e 20 20 41 6c 6c 20   pointers.  All 
12980 6f 74 68 65 72 20 76 61 6c 75 65 73 20 61 72 65  other values are
12990 20 69 6e 20 74 68 65 69 72 20 55 54 46 2d 38 20   in their UTF-8 
129a0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a  zero-terminated.
129b0 2a 2a 20 73 74 72 69 6e 67 20 72 65 70 72 65 73  ** string repres
129c0 65 6e 74 61 74 69 6f 6e 20 61 73 20 72 65 74 75  entation as retu
129d0 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  rned by [sqlite3
129e0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2e  _column_text()].
129f0 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20  .**.** A result 
12a00 74 61 62 6c 65 20 6d 69 67 68 74 20 63 6f 6e 73  table might cons
12a10 69 73 74 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f  ist of one or mo
12a20 72 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  re memory alloca
12a30 74 69 6f 6e 73 2e 0a 2a 2a 20 49 74 20 69 73 20  tions..** It is 
12a40 6e 6f 74 20 73 61 66 65 20 74 6f 20 70 61 73 73  not safe to pass
12a50 20 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20   a result table 
12a60 64 69 72 65 63 74 6c 79 20 74 6f 20 5b 73 71 6c  directly to [sql
12a70 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a  ite3_free()]..**
12a80 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20   A result table 
12a90 73 68 6f 75 6c 64 20 62 65 20 64 65 61 6c 6c 6f  should be deallo
12aa0 63 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c  cated using [sql
12ab0 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28  ite3_free_table(
12ac0 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 73 20 61 6e 20  )]..**.** As an 
12ad0 65 78 61 6d 70 6c 65 20 6f 66 20 74 68 65 20 72  example of the r
12ae0 65 73 75 6c 74 20 74 61 62 6c 65 20 66 6f 72 6d  esult table form
12af0 61 74 2c 20 73 75 70 70 6f 73 65 20 61 20 71 75  at, suppose a qu
12b00 65 72 79 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73  ery result.** is
12b10 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a   as follows:.**.
12b20 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
12b30 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20 4e  pre>.**        N
12b40 61 6d 65 20 20 20 20 20 20 20 20 7c 20 41 67 65  ame        | Age
12b50 0a 2a 2a 20 20 20 20 20 20 20 20 2d 2d 2d 2d 2d  .**        -----
12b60 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
12b70 2d 2d 0a 2a 2a 20 20 20 20 20 20 20 20 41 6c 69  --.**        Ali
12b80 63 65 20 20 20 20 20 20 20 7c 20 34 33 0a 2a 2a  ce       | 43.**
12b90 20 20 20 20 20 20 20 20 42 6f 62 20 20 20 20 20          Bob     
12ba0 20 20 20 20 7c 20 32 38 0a 2a 2a 20 20 20 20 20      | 28.**     
12bb0 20 20 20 43 69 6e 64 79 20 20 20 20 20 20 20 7c     Cindy       |
12bc0 20 32 31 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62   21.** </pre></b
12bd0 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
12be0 20 54 68 65 72 65 20 61 72 65 20 74 77 6f 20 63   There are two c
12bf0 6f 6c 75 6d 6e 20 28 4d 3d 3d 32 29 20 61 6e 64  olumn (M==2) and
12c00 20 74 68 72 65 65 20 72 6f 77 73 20 28 4e 3d 3d   three rows (N==
12c10 33 29 2e 20 20 54 68 75 73 20 74 68 65 0a 2a 2a  3).  Thus the.**
12c20 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 68 61   result table ha
12c30 73 20 38 20 65 6e 74 72 69 65 73 2e 20 20 53 75  s 8 entries.  Su
12c40 70 70 6f 73 65 20 74 68 65 20 72 65 73 75 6c 74  ppose the result
12c50 20 74 61 62 6c 65 20 69 73 20 73 74 6f 72 65 64   table is stored
12c60 0a 2a 2a 20 69 6e 20 61 6e 20 61 72 72 61 79 20  .** in an array 
12c70 6e 61 6d 65 73 20 61 7a 52 65 73 75 6c 74 2e 20  names azResult. 
12c80 20 54 68 65 6e 20 61 7a 52 65 73 75 6c 74 20 68   Then azResult h
12c90 6f 6c 64 73 20 74 68 69 73 20 63 6f 6e 74 65 6e  olds this conten
12ca0 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  t:.**.** <blockq
12cb0 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20  uote><pre>.**   
12cc0 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
12cd0 31 3b 30 5d 20 3d 20 22 4e 61 6d 65 22 3b 0a 2a  1;0] = "Name";.*
12ce0 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
12cf0 74 26 23 39 31 3b 31 5d 20 3d 20 22 41 67 65 22  t&#91;1] = "Age"
12d00 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
12d10 73 75 6c 74 26 23 39 31 3b 32 5d 20 3d 20 22 41  sult&#91;2] = "A
12d20 6c 69 63 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20  lice";.**       
12d30 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 33 5d   azResult&#91;3]
12d40 20 3d 20 22 34 33 22 3b 0a 2a 2a 20 20 20 20 20   = "43";.**     
12d50 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
12d60 34 5d 20 3d 20 22 42 6f 62 22 3b 0a 2a 2a 20 20  4] = "Bob";.**  
12d70 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
12d80 39 31 3b 35 5d 20 3d 20 22 32 38 22 3b 0a 2a 2a  91;5] = "28";.**
12d90 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
12da0 26 23 39 31 3b 36 5d 20 3d 20 22 43 69 6e 64 79  &#91;6] = "Cindy
12db0 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
12dc0 65 73 75 6c 74 26 23 39 31 3b 37 5d 20 3d 20 22  esult&#91;7] = "
12dd0 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  21";.** </pre></
12de0 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
12df0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65  * The sqlite3_ge
12e00 74 5f 74 61 62 6c 65 28 29 20 66 75 6e 63 74 69  t_table() functi
12e10 6f 6e 20 65 76 61 6c 75 61 74 65 73 20 6f 6e 65  on evaluates one
12e20 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 73 65 6d 69   or more.** semi
12e30 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 65 64 20  colon-separated 
12e40 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69  SQL statements i
12e50 6e 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69  n the zero-termi
12e60 6e 61 74 65 64 20 55 54 46 2d 38 0a 2a 2a 20 73  nated UTF-8.** s
12e70 74 72 69 6e 67 20 6f 66 20 69 74 73 20 32 6e 64  tring of its 2nd
12e80 20 70 61 72 61 6d 65 74 65 72 2e 20 20 49 74 20   parameter.  It 
12e90 72 65 74 75 72 6e 73 20 61 20 72 65 73 75 6c 74  returns a result
12ea0 20 74 61 62 6c 65 20 74 6f 20 74 68 65 0a 2a 2a   table to the.**
12eb0 20 70 6f 69 6e 74 65 72 20 67 69 76 65 6e 20 69   pointer given i
12ec0 6e 20 69 74 73 20 33 72 64 20 70 61 72 61 6d 65  n its 3rd parame
12ed0 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72  ter..**.** After
12ee0 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e   the calling fun
12ef0 63 74 69 6f 6e 20 68 61 73 20 66 69 6e 69 73 68  ction has finish
12f00 65 64 20 75 73 69 6e 67 20 74 68 65 20 72 65 73  ed using the res
12f10 75 6c 74 2c 20 69 74 20 73 68 6f 75 6c 64 0a 2a  ult, it should.*
12f20 2a 20 70 61 73 73 20 74 68 65 20 70 6f 69 6e 74  * pass the point
12f30 65 72 20 74 6f 20 74 68 65 20 72 65 73 75 6c 74  er to the result
12f40 20 74 61 62 6c 65 20 74 6f 20 73 71 6c 69 74 65   table to sqlite
12f50 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 20 69  3_free_table() i
12f60 6e 20 6f 72 64 65 72 20 74 6f 0a 2a 2a 20 72 65  n order to.** re
12f70 6c 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79  lease the memory
12f80 20 74 68 61 74 20 77 61 73 20 6d 61 6c 6c 6f 63   that was malloc
12f90 65 64 2e 20 20 42 65 63 61 75 73 65 20 6f 66 20  ed.  Because of 
12fa0 74 68 65 20 77 61 79 20 74 68 65 0a 2a 2a 20 5b  the way the.** [
12fb0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
12fc0 5d 20 68 61 70 70 65 6e 73 20 77 69 74 68 69 6e  ] happens within
12fd0 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62   sqlite3_get_tab
12fe0 6c 65 28 29 2c 20 74 68 65 20 63 61 6c 6c 69 6e  le(), the callin
12ff0 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75  g.** function mu
13000 73 74 20 6e 6f 74 20 74 72 79 20 74 6f 20 63 61  st not try to ca
13010 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ll [sqlite3_free
13020 28 29 5d 20 64 69 72 65 63 74 6c 79 2e 20 20 4f  ()] directly.  O
13030 6e 6c 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  nly.** [sqlite3_
13040 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 20 69 73  free_table()] is
13050 20 61 62 6c 65 20 74 6f 20 72 65 6c 65 61 73 65   able to release
13060 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 70   the memory prop
13070 65 72 6c 79 20 61 6e 64 20 73 61 66 65 6c 79 2e  erly and safely.
13080 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
13090 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 69  e3_get_table() i
130a0 6e 74 65 72 66 61 63 65 20 69 73 20 69 6d 70 6c  nterface is impl
130b0 65 6d 65 6e 74 65 64 20 61 73 20 61 20 77 72 61  emented as a wra
130c0 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b  pper around.** [
130d0 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2e  sqlite3_exec()].
130e0 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65    The sqlite3_ge
130f0 74 5f 74 61 62 6c 65 28 29 20 72 6f 75 74 69 6e  t_table() routin
13100 65 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20  e does not have 
13110 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 61 6e 79  access.** to any
13120 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 20 73   internal data s
13130 74 72 75 63 74 75 72 65 73 20 6f 66 20 53 51 4c  tructures of SQL
13140 69 74 65 2e 20 20 49 74 20 75 73 65 73 20 6f 6e  ite.  It uses on
13150 6c 79 20 74 68 65 20 70 75 62 6c 69 63 0a 2a 2a  ly the public.**
13160 20 69 6e 74 65 72 66 61 63 65 20 64 65 66 69 6e   interface defin
13170 65 64 20 68 65 72 65 2e 20 20 41 73 20 61 20 63  ed here.  As a c
13180 6f 6e 73 65 71 75 65 6e 63 65 2c 20 65 72 72 6f  onsequence, erro
13190 72 73 20 74 68 61 74 20 6f 63 63 75 72 20 69 6e  rs that occur in
131a0 20 74 68 65 0a 2a 2a 20 77 72 61 70 70 65 72 20   the.** wrapper 
131b0 6c 61 79 65 72 20 6f 75 74 73 69 64 65 20 6f 66  layer outside of
131c0 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 5b 73   the internal [s
131d0 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 63  qlite3_exec()] c
131e0 61 6c 6c 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72  all are not.** r
131f0 65 66 6c 65 63 74 65 64 20 69 6e 20 73 75 62 73  eflected in subs
13200 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20  equent calls to 
13210 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65  [sqlite3_errcode
13220 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
13230 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a  errmsg()]..**.**
13240 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
13250 2a 2a 20 7b 48 31 32 33 37 31 7d 20 49 66 20 61  ** {H12371} If a
13260 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61   [sqlite3_get_ta
13270 62 6c 65 28 29 5d 20 66 61 69 6c 73 20 61 20 6d  ble()] fails a m
13280 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
13290 2c 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20  , then.**       
132a0 20 20 20 69 74 20 73 68 61 6c 6c 20 66 72 65 65     it shall free
132b0 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c   the result tabl
132c0 65 20 75 6e 64 65 72 20 63 6f 6e 73 74 72 75 63  e under construc
132d0 74 69 6f 6e 2c 20 61 62 6f 72 74 20 74 68 65 0a  tion, abort the.
132e0 2a 2a 20 20 20 20 20 20 20 20 20 20 71 75 65 72  **          quer
132f0 79 20 69 6e 20 70 72 6f 63 65 73 73 2c 20 73 6b  y in process, sk
13300 69 70 20 61 6e 79 20 73 75 62 73 65 71 75 65 6e  ip any subsequen
13310 74 20 71 75 65 72 69 65 73 2c 20 73 65 74 20 74  t queries, set t
13320 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 2a  he.**          *
13330 70 61 7a 52 65 73 75 6c 74 20 6f 75 74 70 75 74  pazResult output
13340 20 70 6f 69 6e 74 65 72 20 74 6f 20 4e 55 4c 4c   pointer to NULL
13350 20 61 6e 64 20 72 65 74 75 72 6e 20 5b 53 51 4c   and return [SQL
13360 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a  ITE_NOMEM]..**.*
13370 2a 20 7b 48 31 32 33 37 33 7d 20 49 66 20 74 68  * {H12373} If th
13380 65 20 70 6e 43 6f 6c 75 6d 6e 20 70 61 72 61 6d  e pnColumn param
13390 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33  eter to [sqlite3
133a0 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 69 73  _get_table()] is
133b0 20 6e 6f 74 20 4e 55 4c 4c 0a 2a 2a 20 20 20 20   not NULL.**    
133c0 20 20 20 20 20 20 74 68 65 6e 20 61 20 73 75 63        then a suc
133d0 63 65 73 73 66 75 6c 20 69 6e 76 6f 63 61 74 69  cessful invocati
133e0 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 67  on of [sqlite3_g
133f0 65 74 5f 74 61 62 6c 65 28 29 5d 20 73 68 61 6c  et_table()] shal
13400 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 72  l.**          wr
13410 69 74 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  ite the number o
13420 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65  f columns in the
13430 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 73  .**          res
13440 75 6c 74 20 73 65 74 20 6f 66 20 74 68 65 20 71  ult set of the q
13450 75 65 72 79 20 69 6e 74 6f 20 2a 70 6e 43 6f 6c  uery into *pnCol
13460 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33  umn..**.** {H123
13470 37 34 7d 20 49 66 20 74 68 65 20 70 6e 52 6f 77  74} If the pnRow
13480 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73   parameter to [s
13490 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
134a0 28 29 5d 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 0a  ()] is not NULL.
134b0 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 6e  **          then
134c0 20 61 20 73 75 63 63 65 73 73 66 75 6c 20 69 6e   a successful in
134d0 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c  vocation of [sql
134e0 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
134f0 5d 20 73 68 61 6c 6c 0a 2a 2a 20 20 20 20 20 20  ] shall.**      
13500 20 20 20 20 77 72 69 74 65 73 20 74 68 65 20 6e      writes the n
13510 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 69 6e  umber of rows in
13520 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
13530 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 74   result set of t
13540 68 65 20 71 75 65 72 79 20 69 6e 74 6f 20 2a 70  he query into *p
13550 6e 52 6f 77 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  nRow..**.** {H12
13560 33 37 36 7d 20 41 20 73 75 63 63 65 73 73 66 75  376} A successfu
13570 6c 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20  l invocation of 
13580 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62  [sqlite3_get_tab
13590 6c 65 28 29 5d 20 74 68 61 74 20 63 6f 6d 70 75  le()] that compu
135a0 74 65 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  tes.**          
135b0 4e 20 72 6f 77 73 20 6f 66 20 72 65 73 75 6c 74  N rows of result
135c0 20 77 69 74 68 20 43 20 63 6f 6c 75 6d 6e 73 20   with C columns 
135d0 70 65 72 20 72 6f 77 20 73 68 61 6c 6c 20 6d 61  per row shall ma
135e0 6b 65 20 2a 70 61 7a 52 65 73 75 6c 74 0a 2a 2a  ke *pazResult.**
135f0 20 20 20 20 20 20 20 20 20 20 70 6f 69 6e 74 20            point 
13600 74 6f 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70  to an array of p
13610 6f 69 6e 74 65 72 73 20 74 6f 20 28 4e 2b 31 29  ointers to (N+1)
13620 2a 43 20 73 74 72 69 6e 67 73 20 77 68 65 72 65  *C strings where
13630 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 20 20   the first.**   
13640 20 20 20 20 20 20 20 43 20 73 74 72 69 6e 67 73         C strings
13650 20 61 72 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65   are column name
13660 73 20 61 73 20 6f 62 74 61 69 6e 65 64 20 66 72  s as obtained fr
13670 6f 6d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  om.**          [
13680 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
13690 61 6d 65 28 29 5d 20 61 6e 64 20 74 68 65 20 72  ame()] and the r
136a0 65 73 74 20 61 72 65 20 63 6f 6c 75 6d 6e 20 72  est are column r
136b0 65 73 75 6c 74 20 76 61 6c 75 65 73 0a 2a 2a 20  esult values.** 
136c0 20 20 20 20 20 20 20 20 20 6f 62 74 61 69 6e 65           obtaine
136d0 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
136e0 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a  column_text()]..
136f0 2a 2a 0a 2a 2a 20 7b 48 31 32 33 37 39 7d 20 54  **.** {H12379} T
13700 68 65 20 76 61 6c 75 65 73 20 69 6e 20 74 68 65  he values in the
13710 20 70 61 7a 52 65 73 75 6c 74 20 61 72 72 61 79   pazResult array
13720 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71   returned by [sq
13730 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
13740 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73  )].**          s
13750 68 61 6c 6c 20 72 65 6d 61 69 6e 20 76 61 6c 69  hall remain vali
13760 64 20 75 6e 74 69 6c 20 63 6c 65 61 72 65 64 20  d until cleared 
13770 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  by [sqlite3_free
13780 5f 74 61 62 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a  _table()]..**.**
13790 20 7b 48 31 32 33 38 32 7d 20 57 68 65 6e 20 61   {H12382} When a
137a0 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 64  n error occurs d
137b0 75 72 69 6e 67 20 65 76 61 6c 75 61 74 69 6f 6e  uring evaluation
137c0 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 67 65 74   of [sqlite3_get
137d0 5f 74 61 62 6c 65 28 29 5d 0a 2a 2a 20 20 20 20  _table()].**    
137e0 20 20 20 20 20 20 74 68 65 20 66 75 6e 63 74 69        the functi
137f0 6f 6e 20 73 68 61 6c 6c 20 73 65 74 20 2a 70 61  on shall set *pa
13800 7a 52 65 73 75 6c 74 20 74 6f 20 4e 55 4c 4c 2c  zResult to NULL,
13810 20 77 72 69 74 65 20 61 6e 20 65 72 72 6f 72 20   write an error 
13820 6d 65 73 73 61 67 65 0a 2a 2a 20 20 20 20 20 20  message.**      
13830 20 20 20 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20      into memory 
13840 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73  obtained from [s
13850 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
13860 2c 20 6d 61 6b 65 0a 2a 2a 20 20 20 20 20 20 20  , make.**       
13870 20 20 20 2a 2a 70 7a 45 72 72 6d 73 67 20 70 6f     **pzErrmsg po
13880 69 6e 74 20 74 6f 20 74 68 61 74 20 65 72 72 6f  int to that erro
13890 72 20 6d 65 73 73 61 67 65 2c 20 61 6e 64 20 72  r message, and r
138a0 65 74 75 72 6e 20 61 0a 2a 2a 20 20 20 20 20 20  eturn a.**      
138b0 20 20 20 20 61 70 70 72 6f 70 72 69 61 74 65 20      appropriate 
138c0 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2f  [error code]..*/
138d0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 65 74  .int sqlite3_get
138e0 5f 74 61 62 6c 65 28 0a 20 20 73 71 6c 69 74 65  _table(.  sqlite
138f0 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
13900 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62  /* An open datab
13910 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  ase */.  const c
13920 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 2f  har *zSql,     /
13930 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 76 61 6c  * SQL to be eval
13940 75 61 74 65 64 20 2a 2f 0a 20 20 63 68 61 72 20  uated */.  char 
13950 2a 2a 2a 70 61 7a 52 65 73 75 6c 74 2c 20 20 20  ***pazResult,   
13960 20 2f 2a 20 52 65 73 75 6c 74 73 20 6f 66 20 74   /* Results of t
13970 68 65 20 71 75 65 72 79 20 2a 2f 0a 20 20 69 6e  he query */.  in
13980 74 20 2a 70 6e 52 6f 77 2c 20 20 20 20 20 20 20  t *pnRow,       
13990 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66      /* Number of
139a0 20 72 65 73 75 6c 74 20 72 6f 77 73 20 77 72 69   result rows wri
139b0 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 69  tten here */.  i
139c0 6e 74 20 2a 70 6e 43 6f 6c 75 6d 6e 2c 20 20 20  nt *pnColumn,   
139d0 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f       /* Number o
139e0 66 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 73  f result columns
139f0 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f   written here */
13a00 0a 20 20 63 68 61 72 20 2a 2a 70 7a 45 72 72 6d  .  char **pzErrm
13a10 73 67 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f  sg       /* Erro
13a20 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68 65  r msg written he
13a30 72 65 20 2a 2f 0a 29 3b 0a 76 6f 69 64 20 73 71  re */.);.void sq
13a40 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65  lite3_free_table
13a50 28 63 68 61 72 20 2a 2a 72 65 73 75 6c 74 29 3b  (char **result);
13a60 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
13a70 3a 20 46 6f 72 6d 61 74 74 65 64 20 53 74 72 69  : Formatted Stri
13a80 6e 67 20 50 72 69 6e 74 69 6e 67 20 46 75 6e 63  ng Printing Func
13a90 74 69 6f 6e 73 20 7b 48 31 37 34 30 30 7d 20 3c  tions {H17400} <
13aa0 53 37 30 30 30 30 3e 3c 53 32 30 30 30 30 3e 0a  S70000><S20000>.
13ab0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
13ac0 69 6e 65 73 20 61 72 65 20 77 6f 72 6b 61 6c 69  ines are workali
13ad0 6b 65 73 20 6f 66 20 74 68 65 20 22 70 72 69 6e  kes of the "prin
13ae0 74 66 28 29 22 20 66 61 6d 69 6c 79 20 6f 66 20  tf()" family of 
13af0 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 66 72 6f  functions.** fro
13b00 6d 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43  m the standard C
13b10 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20   library..**.** 
13b20 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 70 72 69  The sqlite3_mpri
13b30 6e 74 66 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ntf() and sqlite
13b40 33 5f 76 6d 70 72 69 6e 74 66 28 29 20 72 6f 75  3_vmprintf() rou
13b50 74 69 6e 65 73 20 77 72 69 74 65 20 74 68 65 69  tines write thei
13b60 72 0a 2a 2a 20 72 65 73 75 6c 74 73 20 69 6e 74  r.** results int
13b70 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65  o memory obtaine
13b80 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
13b90 6d 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a 20 54 68  malloc()]..** Th
13ba0 65 20 73 74 72 69 6e 67 73 20 72 65 74 75 72 6e  e strings return
13bb0 65 64 20 62 79 20 74 68 65 73 65 20 74 77 6f 20  ed by these two 
13bc0 72 6f 75 74 69 6e 65 73 20 73 68 6f 75 6c 64 20  routines should 
13bd0 62 65 0a 2a 2a 20 72 65 6c 65 61 73 65 64 20 62  be.** released b
13be0 79 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  y [sqlite3_free(
13bf0 29 5d 2e 20 20 42 6f 74 68 20 72 6f 75 74 69 6e  )].  Both routin
13c00 65 73 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 4e  es return a.** N
13c10 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 20 5b  ULL pointer if [
13c20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
13c30 5d 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61  ] is unable to a
13c40 6c 6c 6f 63 61 74 65 20 65 6e 6f 75 67 68 0a 2a  llocate enough.*
13c50 2a 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64  * memory to hold
13c60 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73   the resulting s
13c70 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20  tring..**.** In 
13c80 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
13c90 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 73 69  () routine is si
13ca0 6d 69 6c 61 72 20 74 6f 20 22 73 6e 70 72 69 6e  milar to "snprin
13cb0 74 66 28 29 22 20 66 72 6f 6d 0a 2a 2a 20 74 68  tf()" from.** th
13cc0 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62  e standard C lib
13cd0 72 61 72 79 2e 20 20 54 68 65 20 72 65 73 75 6c  rary.  The resul
13ce0 74 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e 74  t is written int
13cf0 6f 20 74 68 65 0a 2a 2a 20 62 75 66 66 65 72 20  o the.** buffer 
13d00 73 75 70 70 6c 69 65 64 20 61 73 20 74 68 65 20  supplied as the 
13d10 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
13d20 20 77 68 6f 73 65 20 73 69 7a 65 20 69 73 20 67   whose size is g
13d30 69 76 65 6e 20 62 79 0a 2a 2a 20 74 68 65 20 66  iven by.** the f
13d40 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e 20  irst parameter. 
13d50 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 6f 72  Note that the or
13d60 64 65 72 20 6f 66 20 74 68 65 0a 2a 2a 20 66 69  der of the.** fi
13d70 72 73 74 20 74 77 6f 20 70 61 72 61 6d 65 74 65  rst two paramete
13d80 72 73 20 69 73 20 72 65 76 65 72 73 65 64 20 66  rs is reversed f
13d90 72 6f 6d 20 73 6e 70 72 69 6e 74 66 28 29 2e 20  rom snprintf(). 
13da0 20 54 68 69 73 20 69 73 20 61 6e 0a 2a 2a 20 68   This is an.** h
13db0 69 73 74 6f 72 69 63 61 6c 20 61 63 63 69 64 65  istorical accide
13dc0 6e 74 20 74 68 61 74 20 63 61 6e 6e 6f 74 20 62  nt that cannot b
13dd0 65 20 66 69 78 65 64 20 77 69 74 68 6f 75 74 20  e fixed without 
13de0 62 72 65 61 6b 69 6e 67 0a 2a 2a 20 62 61 63 6b  breaking.** back
13df0 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c  wards compatibil
13e00 69 74 79 2e 20 20 4e 6f 74 65 20 61 6c 73 6f 20  ity.  Note also 
13e10 74 68 61 74 20 73 71 6c 69 74 65 33 5f 73 6e 70  that sqlite3_snp
13e20 72 69 6e 74 66 28 29 0a 2a 2a 20 72 65 74 75 72  rintf().** retur
13e30 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
13e40 69 74 73 20 62 75 66 66 65 72 20 69 6e 73 74 65  its buffer inste
13e50 61 64 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72  ad of the number
13e60 20 6f 66 0a 2a 2a 20 63 68 61 72 61 63 74 65 72   of.** character
13e70 73 20 61 63 74 75 61 6c 6c 79 20 77 72 69 74 74  s actually writt
13e80 65 6e 20 69 6e 74 6f 20 74 68 65 20 62 75 66 66  en into the buff
13e90 65 72 2e 20 20 57 65 20 61 64 6d 69 74 20 74 68  er.  We admit th
13ea0 61 74 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72  at.** the number
13eb0 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 20 77   of characters w
13ec0 72 69 74 74 65 6e 20 77 6f 75 6c 64 20 62 65 20  ritten would be 
13ed0 61 20 6d 6f 72 65 20 75 73 65 66 75 6c 20 72 65  a more useful re
13ee0 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 62 75  turn.** value bu
13ef0 74 20 77 65 20 63 61 6e 6e 6f 74 20 63 68 61 6e  t we cannot chan
13f00 67 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74  ge the implement
13f10 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33  ation of sqlite3
13f20 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 6e  _snprintf().** n
13f30 6f 77 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b  ow without break
13f40 69 6e 67 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  ing compatibilit
13f50 79 2e 0a 2a 2a 0a 2a 2a 20 41 73 20 6c 6f 6e 67  y..**.** As long
13f60 20 61 73 20 74 68 65 20 62 75 66 66 65 72 20 73   as the buffer s
13f70 69 7a 65 20 69 73 20 67 72 65 61 74 65 72 20 74  ize is greater t
13f80 68 61 6e 20 7a 65 72 6f 2c 20 73 71 6c 69 74 65  han zero, sqlite
13f90 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20  3_snprintf().** 
13fa0 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 20  guarantees that 
13fb0 74 68 65 20 62 75 66 66 65 72 20 69 73 20 61 6c  the buffer is al
13fc0 77 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  ways zero-termin
13fd0 61 74 65 64 2e 20 20 54 68 65 20 66 69 72 73 74  ated.  The first
13fe0 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 22 6e  .** parameter "n
13ff0 22 20 69 73 20 74 68 65 20 74 6f 74 61 6c 20 73  " is the total s
14000 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66 65  ize of the buffe
14010 72 2c 20 69 6e 63 6c 75 64 69 6e 67 20 73 70 61  r, including spa
14020 63 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 7a 65  ce for.** the ze
14030 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20  ro terminator.  
14040 53 6f 20 74 68 65 20 6c 6f 6e 67 65 73 74 20 73  So the longest s
14050 74 72 69 6e 67 20 74 68 61 74 20 63 61 6e 20 62  tring that can b
14060 65 20 63 6f 6d 70 6c 65 74 65 6c 79 0a 2a 2a 20  e completely.** 
14070 77 72 69 74 74 65 6e 20 77 69 6c 6c 20 62 65 20  written will be 
14080 6e 2d 31 20 63 68 61 72 61 63 74 65 72 73 2e 0a  n-1 characters..
14090 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
140a0 69 6e 65 73 20 61 6c 6c 20 69 6d 70 6c 65 6d 65  ines all impleme
140b0 6e 74 20 73 6f 6d 65 20 61 64 64 69 74 69 6f 6e  nt some addition
140c0 61 6c 20 66 6f 72 6d 61 74 74 69 6e 67 0a 2a 2a  al formatting.**
140d0 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 20 61 72   options that ar
140e0 65 20 75 73 65 66 75 6c 20 66 6f 72 20 63 6f 6e  e useful for con
140f0 73 74 72 75 63 74 69 6e 67 20 53 51 4c 20 73 74  structing SQL st
14100 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 41 6c 6c  atements..** All
14110 20 6f 66 20 74 68 65 20 75 73 75 61 6c 20 70 72   of the usual pr
14120 69 6e 74 66 28 29 20 66 6f 72 6d 61 74 74 69 6e  intf() formattin
14130 67 20 6f 70 74 69 6f 6e 73 20 61 70 70 6c 79 2e  g options apply.
14140 20 20 49 6e 20 61 64 64 69 74 69 6f 6e 2c 20 74    In addition, t
14150 68 65 72 65 0a 2a 2a 20 69 73 20 61 72 65 20 22  here.** is are "
14160 25 71 22 2c 20 22 25 51 22 2c 20 61 6e 64 20 22  %q", "%Q", and "
14170 25 7a 22 20 6f 70 74 69 6f 6e 73 2e 0a 2a 2a 0a  %z" options..**.
14180 2a 2a 20 54 68 65 20 25 71 20 6f 70 74 69 6f 6e  ** The %q option
14190 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 73 20 69   works like %s i
141a0 6e 20 74 68 61 74 20 69 74 20 73 75 62 73 74 69  n that it substi
141b0 74 75 74 65 73 20 61 20 6e 75 6c 6c 2d 74 65 72  tutes a null-ter
141c0 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e  minated.** strin
141d0 67 20 66 72 6f 6d 20 74 68 65 20 61 72 67 75 6d  g from the argum
141e0 65 6e 74 20 6c 69 73 74 2e 20 20 42 75 74 20 25  ent list.  But %
141f0 71 20 61 6c 73 6f 20 64 6f 75 62 6c 65 73 20 65  q also doubles e
14200 76 65 72 79 20 27 5c 27 27 20 63 68 61 72 61 63  very '\'' charac
14210 74 65 72 2e 0a 2a 2a 20 25 71 20 69 73 20 64 65  ter..** %q is de
14220 73 69 67 6e 65 64 20 66 6f 72 20 75 73 65 20 69  signed for use i
14230 6e 73 69 64 65 20 61 20 73 74 72 69 6e 67 20 6c  nside a string l
14240 69 74 65 72 61 6c 2e 20 20 42 79 20 64 6f 75 62  iteral.  By doub
14250 6c 69 6e 67 20 65 61 63 68 20 27 5c 27 27 0a 2a  ling each '\''.*
14260 2a 20 63 68 61 72 61 63 74 65 72 20 69 74 20 65  * character it e
14270 73 63 61 70 65 73 20 74 68 61 74 20 63 68 61 72  scapes that char
14280 61 63 74 65 72 20 61 6e 64 20 61 6c 6c 6f 77 73  acter and allows
14290 20 69 74 20 74 6f 20 62 65 20 69 6e 73 65 72 74   it to be insert
142a0 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 73  ed into.** the s
142b0 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72  tring..**.** For
142c0 20 65 78 61 6d 70 6c 65 2c 20 61 73 73 75 6d 65   example, assume
142d0 20 74 68 65 20 73 74 72 69 6e 67 20 76 61 72 69   the string vari
142e0 61 62 6c 65 20 7a 54 65 78 74 20 63 6f 6e 74 61  able zText conta
142f0 69 6e 73 20 74 65 78 74 20 61 73 20 66 6f 6c 6c  ins text as foll
14300 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  ows:.**.** <bloc
14310 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
14320 20 63 68 61 72 20 2a 7a 54 65 78 74 20 3d 20 22   char *zText = "
14330 49 74 27 73 20 61 20 68 61 70 70 79 20 64 61 79  It's a happy day
14340 21 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62  !";.** </pre></b
14350 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
14360 20 4f 6e 65 20 63 61 6e 20 75 73 65 20 74 68 69   One can use thi
14370 73 20 74 65 78 74 20 69 6e 20 61 6e 20 53 51 4c  s text in an SQL
14380 20 73 74 61 74 65 6d 65 6e 74 20 61 73 20 66 6f   statement as fo
14390 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  llows:.**.** <bl
143a0 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
143b0 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20  *  char *zSQL = 
143c0 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28  sqlite3_mprintf(
143d0 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62  "INSERT INTO tab
143e0 6c 65 20 56 41 4c 55 45 53 28 27 25 71 27 29 22  le VALUES('%q')"
143f0 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71  , zText);.**  sq
14400 6c 69 74 65 33 5f 65 78 65 63 28 64 62 2c 20 7a  lite3_exec(db, z
14410 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a  SQL, 0, 0, 0);.*
14420 2a 20 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  *  sqlite3_free(
14430 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e  zSQL);.** </pre>
14440 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
14450 0a 2a 2a 20 42 65 63 61 75 73 65 20 74 68 65 20  .** Because the 
14460 25 71 20 66 6f 72 6d 61 74 20 73 74 72 69 6e 67  %q format string
14470 20 69 73 20 75 73 65 64 2c 20 74 68 65 20 27 5c   is used, the '\
14480 27 27 20 63 68 61 72 61 63 74 65 72 20 69 6e 20  '' character in 
14490 7a 54 65 78 74 0a 2a 2a 20 69 73 20 65 73 63 61  zText.** is esca
144a0 70 65 64 20 61 6e 64 20 74 68 65 20 53 51 4c 20  ped and the SQL 
144b0 67 65 6e 65 72 61 74 65 64 20 69 73 20 61 73 20  generated is as 
144c0 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c  follows:.**.** <
144d0 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
144e0 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f  .**  INSERT INTO
144f0 20 74 61 62 6c 65 31 20 56 41 4c 55 45 53 28 27   table1 VALUES('
14500 49 74 27 27 73 20 61 20 68 61 70 70 79 20 64 61  It''s a happy da
14510 79 21 27 29 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  y!').** </pre></
14520 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
14530 2a 20 54 68 69 73 20 69 73 20 63 6f 72 72 65 63  * This is correc
14540 74 2e 20 20 48 61 64 20 77 65 20 75 73 65 64 20  t.  Had we used 
14550 25 73 20 69 6e 73 74 65 61 64 20 6f 66 20 25 71  %s instead of %q
14560 2c 20 74 68 65 20 67 65 6e 65 72 61 74 65 64 20  , the generated 
14570 53 51 4c 0a 2a 2a 20 77 6f 75 6c 64 20 68 61 76  SQL.** would hav
14580 65 20 6c 6f 6f 6b 65 64 20 6c 69 6b 65 20 74 68  e looked like th
14590 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  is:.**.** <block
145a0 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
145b0 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c  INSERT INTO tabl
145c0 65 31 20 56 41 4c 55 45 53 28 27 49 74 27 73 20  e1 VALUES('It's 
145d0 61 20 68 61 70 70 79 20 64 61 79 21 27 29 3b 0a  a happy day!');.
145e0 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
145f0 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69  quote>.**.** Thi
14600 73 20 73 65 63 6f 6e 64 20 65 78 61 6d 70 6c 65  s second example
14610 20 69 73 20 61 6e 20 53 51 4c 20 73 79 6e 74 61   is an SQL synta
14620 78 20 65 72 72 6f 72 2e 20 20 41 73 20 61 20 67  x error.  As a g
14630 65 6e 65 72 61 6c 20 72 75 6c 65 20 79 6f 75 20  eneral rule you 
14640 73 68 6f 75 6c 64 0a 2a 2a 20 61 6c 77 61 79 73  should.** always
14650 20 75 73 65 20 25 71 20 69 6e 73 74 65 61 64 20   use %q instead 
14660 6f 66 20 25 73 20 77 68 65 6e 20 69 6e 73 65 72  of %s when inser
14670 74 69 6e 67 20 74 65 78 74 20 69 6e 74 6f 20 61  ting text into a
14680 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e   string literal.
14690 0a 2a 2a 0a 2a 2a 20 54 68 65 20 25 51 20 6f 70  .**.** The %Q op
146a0 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20  tion works like 
146b0 25 71 20 65 78 63 65 70 74 20 69 74 20 61 6c 73  %q except it als
146c0 6f 20 61 64 64 73 20 73 69 6e 67 6c 65 20 71 75  o adds single qu
146d0 6f 74 65 73 20 61 72 6f 75 6e 64 0a 2a 2a 20 74  otes around.** t
146e0 68 65 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68  he outside of th
146f0 65 20 74 6f 74 61 6c 20 73 74 72 69 6e 67 2e 20  e total string. 
14700 20 41 64 64 69 74 69 6f 6e 61 6c 6c 79 2c 20 69   Additionally, i
14710 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  f the parameter 
14720 69 6e 20 74 68 65 0a 2a 2a 20 61 72 67 75 6d 65  in the.** argume
14730 6e 74 20 6c 69 73 74 20 69 73 20 61 20 4e 55 4c  nt list is a NUL
14740 4c 20 70 6f 69 6e 74 65 72 2c 20 25 51 20 73 75  L pointer, %Q su
14750 62 73 74 69 74 75 74 65 73 20 74 68 65 20 74 65  bstitutes the te
14760 78 74 20 22 4e 55 4c 4c 22 20 28 77 69 74 68 6f  xt "NULL" (witho
14770 75 74 0a 2a 2a 20 73 69 6e 67 6c 65 20 71 75 6f  ut.** single quo
14780 74 65 73 29 20 69 6e 20 70 6c 61 63 65 20 6f 66  tes) in place of
14790 20 74 68 65 20 25 51 20 6f 70 74 69 6f 6e 2e 20   the %Q option. 
147a0 20 53 6f 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65   So, for example
147b0 2c 20 6f 6e 65 20 63 6f 75 6c 64 20 73 61 79 3a  , one could say:
147c0 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
147d0 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61  te><pre>.**  cha
147e0 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65  r *zSQL = sqlite
147f0 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 45 52  3_mprintf("INSER
14800 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c  T INTO table VAL
14810 55 45 53 28 25 51 29 22 2c 20 7a 54 65 78 74 29  UES(%Q)", zText)
14820 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 78  ;.**  sqlite3_ex
14830 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20  ec(db, zSQL, 0, 
14840 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74  0, 0);.**  sqlit
14850 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a  e3_free(zSQL);.*
14860 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
14870 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  uote>.**.** The 
14880 63 6f 64 65 20 61 62 6f 76 65 20 77 69 6c 6c 20  code above will 
14890 72 65 6e 64 65 72 20 61 20 63 6f 72 72 65 63 74  render a correct
148a0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69   SQL statement i
148b0 6e 20 74 68 65 20 7a 53 51 4c 0a 2a 2a 20 76 61  n the zSQL.** va
148c0 72 69 61 62 6c 65 20 65 76 65 6e 20 69 66 20 74  riable even if t
148d0 68 65 20 7a 54 65 78 74 20 76 61 72 69 61 62 6c  he zText variabl
148e0 65 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  e is a NULL poin
148f0 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 22  ter..**.** The "
14900 25 7a 22 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f  %z" formatting o
14910 70 74 69 6f 6e 20 77 6f 72 6b 73 20 65 78 61 63  ption works exac
14920 74 6c 79 20 6c 69 6b 65 20 22 25 73 22 20 77 69  tly like "%s" wi
14930 74 68 20 74 68 65 0a 2a 2a 20 61 64 64 69 74 69  th the.** additi
14940 6f 6e 20 74 68 61 74 20 61 66 74 65 72 20 74 68  on that after th
14950 65 20 73 74 72 69 6e 67 20 68 61 73 20 62 65 65  e string has bee
14960 6e 20 72 65 61 64 20 61 6e 64 20 63 6f 70 69 65  n read and copie
14970 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 72 65  d into.** the re
14980 73 75 6c 74 2c 20 5b 73 71 6c 69 74 65 33 5f 66  sult, [sqlite3_f
14990 72 65 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64  ree()] is called
149a0 20 6f 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74   on the input st
149b0 72 69 6e 67 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a  ring. {END}.**.*
149c0 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
149d0 0a 2a 2a 20 7b 48 31 37 34 30 33 7d 20 20 54 68  .** {H17403}  Th
149e0 65 20 5b 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e  e [sqlite3_mprin
149f0 74 66 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  tf()] and [sqlit
14a00 65 33 5f 76 6d 70 72 69 6e 74 66 28 29 5d 20 69  e3_vmprintf()] i
14a10 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 20 20 20  nterfaces.**    
14a20 20 20 20 20 20 20 20 72 65 74 75 72 6e 20 65 69         return ei
14a30 74 68 65 72 20 70 6f 69 6e 74 65 72 73 20 74 6f  ther pointers to
14a40 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
14a50 20 55 54 46 2d 38 20 73 74 72 69 6e 67 73 20 68   UTF-8 strings h
14a60 65 6c 64 20 69 6e 0a 2a 2a 20 20 20 20 20 20 20  eld in.**       
14a70 20 20 20 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69      memory obtai
14a80 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ned from [sqlite
14a90 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 4e  3_malloc()] or N
14aa0 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20 69 66 0a  ULL pointers if.
14ab0 2a 2a 20 20 20 20 20 20 20 20 20 20 20 61 20 63  **           a c
14ac0 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
14ad0 6d 61 6c 6c 6f 63 28 29 5d 20 66 61 69 6c 73 2e  malloc()] fails.
14ae0 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 34 30 36 7d 20  .**.** {H17406} 
14af0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 6e   The [sqlite3_sn
14b00 70 72 69 6e 74 66 28 29 5d 20 69 6e 74 65 72 66  printf()] interf
14b10 61 63 65 20 77 72 69 74 65 73 20 61 20 7a 65 72  ace writes a zer
14b20 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20  o-terminated.** 
14b30 20 20 20 20 20 20 20 20 20 20 55 54 46 2d 38 20            UTF-8 
14b40 73 74 72 69 6e 67 20 69 6e 74 6f 20 74 68 65 20  string into the 
14b50 62 75 66 66 65 72 20 70 6f 69 6e 74 65 64 20 74  buffer pointed t
14b60 6f 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20  o by the second 
14b70 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 20 20 20  parameter.**    
14b80 20 20 20 20 20 20 20 70 72 6f 76 69 64 65 64 20         provided 
14b90 74 68 61 74 20 74 68 65 20 66 69 72 73 74 20 70  that the first p
14ba0 61 72 61 6d 65 74 65 72 20 69 73 20 67 72 65 61  arameter is grea
14bb0 74 65 72 20 74 68 61 6e 20 7a 65 72 6f 2e 0a 2a  ter than zero..*
14bc0 2a 0a 2a 2a 20 7b 48 31 37 34 30 37 7d 20 20 54  *.** {H17407}  T
14bd0 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72  he [sqlite3_snpr
14be0 69 6e 74 66 28 29 5d 20 69 6e 74 65 72 66 61 63  intf()] interfac
14bf0 65 20 64 6f 65 73 20 6e 6f 74 20 77 72 69 74 65  e does not write
14c00 20 73 6c 6f 74 73 20 6f 66 0a 2a 2a 20 20 20 20   slots of.**    
14c10 20 20 20 20 20 20 20 69 74 73 20 6f 75 74 70 75         its outpu
14c20 74 20 62 75 66 66 65 72 20 28 74 68 65 20 73 65  t buffer (the se
14c30 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 29 20  cond parameter) 
14c40 6f 75 74 73 69 64 65 20 74 68 65 20 72 61 6e 67  outside the rang
14c50 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 6f  e.**           o
14c60 66 20 30 20 74 68 72 6f 75 67 68 20 4e 2d 31 20  f 0 through N-1 
14c70 28 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20  (where N is the 
14c80 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 29  first parameter)
14c90 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 72 65  .**           re
14ca0 67 61 72 64 6c 65 73 73 20 6f 66 20 74 68 65 20  gardless of the 
14cb0 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 73 74  length of the st
14cc0 72 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20  ring.**         
14cd0 20 20 72 65 71 75 65 73 74 65 64 20 62 79 20 74    requested by t
14ce0 68 65 20 66 6f 72 6d 61 74 20 73 70 65 63 69 66  he format specif
14cf0 69 63 61 74 69 6f 6e 2e 0a 2a 2f 0a 63 68 61 72  ication..*/.char
14d00 20 2a 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74   *sqlite3_mprint
14d10 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 2e 2e  f(const char*,..
14d20 2e 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65  .);.char *sqlite
14d30 33 5f 76 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74  3_vmprintf(const
14d40 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29   char*, va_list)
14d50 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  ;.char *sqlite3_
14d60 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 61  snprintf(int,cha
14d70 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20  r*,const char*, 
14d80 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ...);../*.** CAP
14d90 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c  I3REF: Memory Al
14da0 6c 6f 63 61 74 69 6f 6e 20 53 75 62 73 79 73 74  location Subsyst
14db0 65 6d 20 7b 48 31 37 33 30 30 7d 20 3c 53 32 30  em {H17300} <S20
14dc0 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53  000>.**.** The S
14dd0 51 4c 69 74 65 20 63 6f 72 65 20 20 75 73 65 73  QLite core  uses
14de0 20 74 68 65 73 65 20 74 68 72 65 65 20 72 6f 75   these three rou
14df0 74 69 6e 65 73 20 66 6f 72 20 61 6c 6c 20 6f 66  tines for all of
14e00 20 69 74 73 20 6f 77 6e 0a 2a 2a 20 69 6e 74 65   its own.** inte
14e10 72 6e 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  rnal memory allo
14e20 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 20 22 43  cation needs. "C
14e30 6f 72 65 22 20 69 6e 20 74 68 65 20 70 72 65 76  ore" in the prev
14e40 69 6f 75 73 20 73 65 6e 74 65 6e 63 65 0a 2a 2a  ious sentence.**
14e50 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64   does not includ
14e60 65 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 74  e operating-syst
14e70 65 6d 20 73 70 65 63 69 66 69 63 20 56 46 53 20  em specific VFS 
14e80 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20  implementation. 
14e90 20 54 68 65 0a 2a 2a 20 57 69 6e 64 6f 77 73 20   The.** Windows 
14ea0 56 46 53 20 75 73 65 73 20 6e 61 74 69 76 65 20  VFS uses native 
14eb0 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65  malloc() and fre
14ec0 65 28 29 20 66 6f 72 20 73 6f 6d 65 20 6f 70 65  e() for some ope
14ed0 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54  rations..**.** T
14ee0 68 65 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  he sqlite3_mallo
14ef0 63 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75  c() routine retu
14f00 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
14f10 20 61 20 62 6c 6f 63 6b 0a 2a 2a 20 6f 66 20 6d   a block.** of m
14f20 65 6d 6f 72 79 20 61 74 20 6c 65 61 73 74 20 4e  emory at least N
14f30 20 62 79 74 65 73 20 69 6e 20 6c 65 6e 67 74 68   bytes in length
14f40 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65  , where N is the
14f50 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 49   parameter..** I
14f60 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  f sqlite3_malloc
14f70 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  () is unable to 
14f80 6f 62 74 61 69 6e 20 73 75 66 66 69 63 69 65 6e  obtain sufficien
14f90 74 20 66 72 65 65 0a 2a 2a 20 6d 65 6d 6f 72 79  t free.** memory
14fa0 2c 20 69 74 20 72 65 74 75 72 6e 73 20 61 20 4e  , it returns a N
14fb0 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 49 66  ULL pointer.  If
14fc0 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 4e   the parameter N
14fd0 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d   to.** sqlite3_m
14fe0 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f 20  alloc() is zero 
14ff0 6f 72 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e  or negative then
15000 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
15010 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20 4e  ) returns.** a N
15020 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a  ULL pointer..**.
15030 2a 2a 20 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74  ** Calling sqlit
15040 65 33 5f 66 72 65 65 28 29 20 77 69 74 68 20 61  e3_free() with a
15050 20 70 6f 69 6e 74 65 72 20 70 72 65 76 69 6f 75   pointer previou
15060 73 6c 79 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  sly returned.** 
15070 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  by sqlite3_mallo
15080 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72  c() or sqlite3_r
15090 65 61 6c 6c 6f 63 28 29 20 72 65 6c 65 61 73 65  ealloc() release
150a0 73 20 74 68 61 74 20 6d 65 6d 6f 72 79 20 73 6f  s that memory so
150b0 0a 2a 2a 20 74 68 61 74 20 69 74 20 6d 69 67 68  .** that it migh
150c0 74 20 62 65 20 72 65 75 73 65 64 2e 20 20 54 68  t be reused.  Th
150d0 65 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29  e sqlite3_free()
150e0 20 72 6f 75 74 69 6e 65 20 69 73 0a 2a 2a 20 61   routine is.** a
150f0 20 6e 6f 2d 6f 70 20 69 66 20 69 73 20 63 61 6c   no-op if is cal
15100 6c 65 64 20 77 69 74 68 20 61 20 4e 55 4c 4c 20  led with a NULL 
15110 70 6f 69 6e 74 65 72 2e 20 20 50 61 73 73 69 6e  pointer.  Passin
15120 67 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  g a NULL pointer
15130 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 66  .** to sqlite3_f
15140 72 65 65 28 29 20 69 73 20 68 61 72 6d 6c 65 73  ree() is harmles
15150 73 2e 20 20 41 66 74 65 72 20 62 65 69 6e 67 20  s.  After being 
15160 66 72 65 65 64 2c 20 6d 65 6d 6f 72 79 0a 2a 2a  freed, memory.**
15170 20 73 68 6f 75 6c 64 20 6e 65 69 74 68 65 72 20   should neither 
15180 62 65 20 72 65 61 64 20 6e 6f 72 20 77 72 69 74  be read nor writ
15190 74 65 6e 2e 20 20 45 76 65 6e 20 72 65 61 64 69  ten.  Even readi
151a0 6e 67 20 70 72 65 76 69 6f 75 73 6c 79 20 66 72  ng previously fr
151b0 65 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6d 69  eed.** memory mi
151c0 67 68 74 20 72 65 73 75 6c 74 20 69 6e 20 61 20  ght result in a 
151d0 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75  segmentation fau
151e0 6c 74 20 6f 72 20 6f 74 68 65 72 20 73 65 76 65  lt or other seve
151f0 72 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 4d 65 6d  re error..** Mem
15200 6f 72 79 20 63 6f 72 72 75 70 74 69 6f 6e 2c 20  ory corruption, 
15210 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66  a segmentation f
15220 61 75 6c 74 2c 20 6f 72 20 6f 74 68 65 72 20 73  ault, or other s
15230 65 76 65 72 65 20 65 72 72 6f 72 0a 2a 2a 20 6d  evere error.** m
15240 69 67 68 74 20 72 65 73 75 6c 74 20 69 66 20 73  ight result if s
15250 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69 73  qlite3_free() is
15260 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20 6e   called with a n
15270 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20  on-NULL pointer 
15280 74 68 61 74 0a 2a 2a 20 77 61 73 20 6e 6f 74 20  that.** was not 
15290 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 73 71  obtained from sq
152a0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f  lite3_malloc() o
152b0 72 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29  r sqlite3_free()
152c0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
152d0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 69 6e  te3_realloc() in
152e0 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 73  terface attempts
152f0 20 74 6f 20 72 65 73 69 7a 65 20 61 0a 2a 2a 20   to resize a.** 
15300 70 72 69 6f 72 20 6d 65 6d 6f 72 79 20 61 6c 6c  prior memory all
15310 6f 63 61 74 69 6f 6e 20 74 6f 20 62 65 20 61 74  ocation to be at
15320 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 2c 20   least N bytes, 
15330 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 0a 2a  where N is the.*
15340 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  * second paramet
15350 65 72 2e 20 20 54 68 65 20 6d 65 6d 6f 72 79 20  er.  The memory 
15360 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 62 65  allocation to be
15370 20 72 65 73 69 7a 65 64 20 69 73 20 74 68 65 20   resized is the 
15380 66 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74  first.** paramet
15390 65 72 2e 20 20 49 66 20 74 68 65 20 66 69 72 73  er.  If the firs
153a0 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  t parameter to s
153b0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
153c0 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  .** is a NULL po
153d0 69 6e 74 65 72 20 74 68 65 6e 20 69 74 73 20 62  inter then its b
153e0 65 68 61 76 69 6f 72 20 69 73 20 69 64 65 6e 74  ehavior is ident
153f0 69 63 61 6c 20 74 6f 20 63 61 6c 6c 69 6e 67 0a  ical to calling.
15400 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  ** sqlite3_mallo
15410 63 28 4e 29 20 77 68 65 72 65 20 4e 20 69 73 20  c(N) where N is 
15420 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  the second param
15430 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
15440 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 49 66  realloc()..** If
15450 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   the second para
15460 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
15470 5f 72 65 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65  _realloc() is ze
15480 72 6f 20 6f 72 0a 2a 2a 20 6e 65 67 61 74 69 76  ro or.** negativ
15490 65 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76  e then the behav
154a0 69 6f 72 20 69 73 20 65 78 61 63 74 6c 79 20 74  ior is exactly t
154b0 68 65 20 73 61 6d 65 20 61 73 20 63 61 6c 6c 69  he same as calli
154c0 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66 72  ng.** sqlite3_fr
154d0 65 65 28 50 29 20 77 68 65 72 65 20 50 20 69 73  ee(P) where P is
154e0 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   the first param
154f0 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
15500 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 73 71  realloc()..** sq
15510 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20  lite3_realloc() 
15520 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
15530 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20 61 6c  r to a memory al
15540 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 61  location.** of a
15550 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20  t least N bytes 
15560 69 6e 20 73 69 7a 65 20 6f 72 20 4e 55 4c 4c 20  in size or NULL 
15570 69 66 20 73 75 66 66 69 63 69 65 6e 74 20 6d 65  if sufficient me
15580 6d 6f 72 79 20 69 73 20 75 6e 61 76 61 69 6c 61  mory is unavaila
15590 62 6c 65 2e 0a 2a 2a 20 49 66 20 4d 20 69 73 20  ble..** If M is 
155a0 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  the size of the 
155b0 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e  prior allocation
155c0 2c 20 74 68 65 6e 20 6d 69 6e 28 4e 2c 4d 29 20  , then min(N,M) 
155d0 62 79 74 65 73 0a 2a 2a 20 6f 66 20 74 68 65 20  bytes.** of the 
155e0 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e  prior allocation
155f0 20 61 72 65 20 63 6f 70 69 65 64 20 69 6e 74 6f   are copied into
15600 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f   the beginning o
15610 66 20 62 75 66 66 65 72 20 72 65 74 75 72 6e 65  f buffer returne
15620 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f  d.** by sqlite3_
15630 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64 20 74 68  realloc() and th
15640 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69  e prior allocati
15650 6f 6e 20 69 73 20 66 72 65 65 64 2e 0a 2a 2a 20  on is freed..** 
15660 49 66 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  If sqlite3_reall
15670 6f 63 28 29 20 72 65 74 75 72 6e 73 20 4e 55 4c  oc() returns NUL
15680 4c 2c 20 74 68 65 6e 20 74 68 65 20 70 72 69 6f  L, then the prio
15690 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20  r allocation.** 
156a0 69 73 20 6e 6f 74 20 66 72 65 65 64 2e 0a 2a 2a  is not freed..**
156b0 0a 2a 2a 20 54 68 65 20 6d 65 6d 6f 72 79 20 72  .** The memory r
156c0 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
156d0 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20  e3_malloc() and 
156e0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
156f0 29 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61  ).** is always a
15700 6c 69 67 6e 65 64 20 74 6f 20 61 74 20 6c 65 61  ligned to at lea
15710 73 74 20 61 6e 20 38 20 62 79 74 65 20 62 6f 75  st an 8 byte bou
15720 6e 64 61 72 79 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a  ndary. {END}.**.
15730 2a 2a 20 54 68 65 20 64 65 66 61 75 6c 74 20 69  ** The default i
15740 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
15750 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f   the memory allo
15760 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d  cation subsystem
15770 20 75 73 65 73 0a 2a 2a 20 74 68 65 20 6d 61 6c   uses.** the mal
15780 6c 6f 63 28 29 2c 20 72 65 61 6c 6c 6f 63 28 29  loc(), realloc()
15790 20 61 6e 64 20 66 72 65 65 28 29 20 70 72 6f 76   and free() prov
157a0 69 64 65 64 20 62 79 20 74 68 65 20 73 74 61 6e  ided by the stan
157b0 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a  dard C library..
157c0 2a 2a 20 7b 48 31 37 33 38 32 7d 20 48 6f 77 65  ** {H17382} Howe
157d0 76 65 72 2c 20 69 66 20 53 51 4c 69 74 65 20 69  ver, if SQLite i
157e0 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20  s compiled with 
157f0 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 4d 45  the.** SQLITE_ME
15800 4d 4f 52 59 5f 53 49 5a 45 3d 3c 69 3e 4e 4e 4e  MORY_SIZE=<i>NNN
15810 3c 2f 69 3e 20 43 20 70 72 65 70 72 6f 63 65 73  </i> C preproces
15820 73 6f 72 20 6d 61 63 72 6f 20 28 77 68 65 72 65  sor macro (where
15830 20 3c 69 3e 4e 4e 4e 3c 2f 69 3e 0a 2a 2a 20 69   <i>NNN</i>.** i
15840 73 20 61 6e 20 69 6e 74 65 67 65 72 29 2c 20 74  s an integer), t
15850 68 65 6e 20 53 51 4c 69 74 65 20 63 72 65 61 74  hen SQLite creat
15860 65 20 61 20 73 74 61 74 69 63 20 61 72 72 61 79  e a static array
15870 20 6f 66 20 61 74 20 6c 65 61 73 74 0a 2a 2a 20   of at least.** 
15880 3c 69 3e 4e 4e 4e 3c 2f 69 3e 20 62 79 74 65 73  <i>NNN</i> bytes
15890 20 69 6e 20 73 69 7a 65 20 61 6e 64 20 75 73 65   in size and use
158a0 73 20 74 68 61 74 20 61 72 72 61 79 20 66 6f 72  s that array for
158b0 20 61 6c 6c 20 6f 66 20 69 74 73 20 64 79 6e 61   all of its dyna
158c0 6d 69 63 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c  mic.** memory al
158d0 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 20  location needs. 
158e0 7b 45 4e 44 7d 20 20 41 64 64 69 74 69 6f 6e 61  {END}  Additiona
158f0 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  l memory allocat
15900 6f 72 20 6f 70 74 69 6f 6e 73 0a 2a 2a 20 6d 61  or options.** ma
15910 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75  y be added in fu
15920 74 75 72 65 20 72 65 6c 65 61 73 65 73 2e 0a 2a  ture releases..*
15930 2a 0a 2a 2a 20 49 6e 20 53 51 4c 69 74 65 20 76  *.** In SQLite v
15940 65 72 73 69 6f 6e 20 33 2e 35 2e 30 20 61 6e 64  ersion 3.5.0 and
15950 20 33 2e 35 2e 31 2c 20 69 74 20 77 61 73 20 70   3.5.1, it was p
15960 6f 73 73 69 62 6c 65 20 74 6f 20 64 65 66 69 6e  ossible to defin
15970 65 0a 2a 2a 20 74 68 65 20 53 51 4c 49 54 45 5f  e.** the SQLITE_
15980 4f 4d 49 54 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f  OMIT_MEMORY_ALLO
15990 43 41 54 49 4f 4e 20 77 68 69 63 68 20 77 6f 75  CATION which wou
159a0 6c 64 20 63 61 75 73 65 20 74 68 65 20 62 75 69  ld cause the bui
159b0 6c 74 2d 69 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65  lt-in.** impleme
159c0 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 73 65  ntation of these
159d0 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20   routines to be 
159e0 6f 6d 69 74 74 65 64 2e 20 20 54 68 61 74 20 63  omitted.  That c
159f0 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20  apability.** is 
15a00 6e 6f 20 6c 6f 6e 67 65 72 20 70 72 6f 76 69 64  no longer provid
15a10 65 64 2e 20 20 4f 6e 6c 79 20 62 75 69 6c 74 2d  ed.  Only built-
15a20 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  in memory alloca
15a30 74 6f 72 73 20 63 61 6e 20 62 65 20 75 73 65 64  tors can be used
15a40 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 57 69 6e 64  ..**.** The Wind
15a50 6f 77 73 20 4f 53 20 69 6e 74 65 72 66 61 63 65  ows OS interface
15a60 20 6c 61 79 65 72 20 63 61 6c 6c 73 0a 2a 2a 20   layer calls.** 
15a70 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f  the system mallo
15a80 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 64  c() and free() d
15a90 69 72 65 63 74 6c 79 20 77 68 65 6e 20 63 6f 6e  irectly when con
15aa0 76 65 72 74 69 6e 67 0a 2a 2a 20 66 69 6c 65 6e  verting.** filen
15ab0 61 6d 65 73 20 62 65 74 77 65 65 6e 20 74 68 65  ames between the
15ac0 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20   UTF-8 encoding 
15ad0 75 73 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a  used by SQLite.*
15ae0 2a 20 61 6e 64 20 77 68 61 74 65 76 65 72 20 66  * and whatever f
15af0 69 6c 65 6e 61 6d 65 20 65 6e 63 6f 64 69 6e 67  ilename encoding
15b00 20 69 73 20 75 73 65 64 20 62 79 20 74 68 65 20   is used by the 
15b10 70 61 72 74 69 63 75 6c 61 72 20 57 69 6e 64 6f  particular Windo
15b20 77 73 0a 2a 2a 20 69 6e 73 74 61 6c 6c 61 74 69  ws.** installati
15b30 6f 6e 2e 20 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f  on.  Memory allo
15b40 63 61 74 69 6f 6e 20 65 72 72 6f 72 73 20 61 72  cation errors ar
15b50 65 20 64 65 74 65 63 74 65 64 2c 20 62 75 74 0a  e detected, but.
15b60 2a 2a 20 74 68 65 79 20 61 72 65 20 72 65 70 6f  ** they are repo
15b70 72 74 65 64 20 62 61 63 6b 20 61 73 20 5b 53 51  rted back as [SQ
15b80 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 6f  LITE_CANTOPEN] o
15b90 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f 45  r.** [SQLITE_IOE
15ba0 52 52 5d 20 72 61 74 68 65 72 20 74 68 61 6e 20  RR] rather than 
15bb0 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a  [SQLITE_NOMEM]..
15bc0 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
15bd0 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33 30 33 7d  :.**.** {H17303}
15be0 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d    The [sqlite3_m
15bf0 61 6c 6c 6f 63 28 4e 29 5d 20 69 6e 74 65 72 66  alloc(N)] interf
15c00 61 63 65 20 72 65 74 75 72 6e 73 20 65 69 74 68  ace returns eith
15c10 65 72 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 0a  er a pointer to.
15c20 2a 2a 20 20 20 20 20 20 20 20 20 20 20 61 20 6e  **           a n
15c30 65 77 6c 79 20 63 68 65 63 6b 65 64 2d 6f 75 74  ewly checked-out
15c40 20 62 6c 6f 63 6b 20 6f 66 20 61 74 20 6c 65 61   block of at lea
15c50 73 74 20 4e 20 62 79 74 65 73 20 6f 66 20 6d 65  st N bytes of me
15c60 6d 6f 72 79 0a 2a 2a 20 20 20 20 20 20 20 20 20  mory.**         
15c70 20 20 74 68 61 74 20 69 73 20 38 2d 62 79 74 65    that is 8-byte
15c80 20 61 6c 69 67 6e 65 64 2c 20 6f 72 20 69 74 20   aligned, or it 
15c90 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20 69 66 20  returns NULL if 
15ca0 69 74 20 69 73 20 75 6e 61 62 6c 65 0a 2a 2a 20  it is unable.** 
15cb0 20 20 20 20 20 20 20 20 20 20 74 6f 20 66 75 6c            to ful
15cc0 66 69 6c 6c 20 74 68 65 20 72 65 71 75 65 73 74  fill the request
15cd0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33 30 34 7d  ..**.** {H17304}
15ce0 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d    The [sqlite3_m
15cf0 61 6c 6c 6f 63 28 4e 29 5d 20 69 6e 74 65 72 66  alloc(N)] interf
15d00 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 4e 55  ace returns a NU
15d10 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 0a 2a 2a  LL pointer if.**
15d20 20 20 20 20 20 20 20 20 20 20 20 4e 20 69 73 20             N is 
15d30 6c 65 73 73 20 74 68 61 6e 20 6f 72 20 65 71 75  less than or equ
15d40 61 6c 20 74 6f 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a  al to zero..**.*
15d50 2a 20 7b 48 31 37 33 30 35 7d 20 20 54 68 65 20  * {H17305}  The 
15d60 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 50 29  [sqlite3_free(P)
15d70 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 6c 65  ] interface rele
15d80 61 73 65 73 20 6d 65 6d 6f 72 79 20 70 72 65 76  ases memory prev
15d90 69 6f 75 73 6c 79 0a 2a 2a 20 20 20 20 20 20 20  iously.**       
15da0 20 20 20 20 72 65 74 75 72 6e 65 64 20 66 72 6f      returned fro
15db0 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  m [sqlite3_mallo
15dc0 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  c()] or [sqlite3
15dd0 5f 72 65 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20  _realloc()],.** 
15de0 20 20 20 20 20 20 20 20 20 20 6d 61 6b 69 6e 67            making
15df0 20 69 74 20 61 76 61 69 6c 61 62 6c 65 20 66 6f   it available fo
15e00 72 20 72 65 75 73 65 2e 0a 2a 2a 0a 2a 2a 20 7b  r reuse..**.** {
15e10 48 31 37 33 30 36 7d 20 20 41 20 63 61 6c 6c 20  H17306}  A call 
15e20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  to [sqlite3_free
15e30 28 4e 55 4c 4c 29 5d 20 69 73 20 61 20 68 61 72  (NULL)] is a har
15e40 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2a 0a  mless no-op..**.
15e50 2a 2a 20 7b 48 31 37 33 31 30 7d 20 20 41 20 63  ** {H17310}  A c
15e60 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
15e70 72 65 61 6c 6c 6f 63 28 30 2c 4e 29 5d 20 69 73  realloc(0,N)] is
15e80 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 61   equivalent to a
15e90 20 63 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20   call.**        
15ea0 20 20 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d     to [sqlite3_m
15eb0 61 6c 6c 6f 63 28 4e 29 5d 2e 0a 2a 2a 0a 2a 2a  alloc(N)]..**.**
15ec0 20 7b 48 31 37 33 31 32 7d 20 20 41 20 63 61 6c   {H17312}  A cal
15ed0 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65  l to [sqlite3_re
15ee0 61 6c 6c 6f 63 28 50 2c 30 29 5d 20 69 73 20 65  alloc(P,0)] is e
15ef0 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 61 20 63  quivalent to a c
15f00 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  all.**          
15f10 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65   to [sqlite3_fre
15f20 65 28 50 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  e(P)]..**.** {H1
15f30 37 33 31 35 7d 20 20 54 68 65 20 53 51 4c 69 74  7315}  The SQLit
15f40 65 20 63 6f 72 65 20 75 73 65 73 20 5b 73 71 6c  e core uses [sql
15f50 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20  ite3_malloc()], 
15f60 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  [sqlite3_realloc
15f70 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  ()],.**         
15f80 20 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 66    and [sqlite3_f
15f90 72 65 65 28 29 5d 20 66 6f 72 20 61 6c 6c 20 6f  ree()] for all o
15fa0 66 20 69 74 73 20 6d 65 6d 6f 72 79 20 61 6c 6c  f its memory all
15fb0 6f 63 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 20  ocation and.**  
15fc0 20 20 20 20 20 20 20 20 20 64 65 61 6c 6c 6f 63           dealloc
15fd0 61 74 69 6f 6e 20 6e 65 65 64 73 2e 0a 2a 2a 0a  ation needs..**.
15fe0 2a 2a 20 7b 48 31 37 33 31 38 7d 20 20 54 68 65  ** {H17318}  The
15ff0 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   [sqlite3_reallo
16000 63 28 50 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63  c(P,N)] interfac
16010 65 20 72 65 74 75 72 6e 73 20 65 69 74 68 65 72  e returns either
16020 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 20 20   a pointer.**   
16030 20 20 20 20 20 20 20 20 74 6f 20 61 20 62 6c 6f          to a blo
16040 63 6b 20 6f 66 20 63 68 65 63 6b 65 64 2d 6f 75  ck of checked-ou
16050 74 20 6d 65 6d 6f 72 79 20 6f 66 20 61 74 20 6c  t memory of at l
16060 65 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20  east N bytes in 
16070 73 69 7a 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  size.**         
16080 20 20 74 68 61 74 20 69 73 20 38 2d 62 79 74 65    that is 8-byte
16090 20 61 6c 69 67 6e 65 64 2c 20 6f 72 20 61 20 4e   aligned, or a N
160a0 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a  ULL pointer..**.
160b0 2a 2a 20 7b 48 31 37 33 32 31 7d 20 20 57 68 65  ** {H17321}  Whe
160c0 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  n [sqlite3_reall
160d0 6f 63 28 50 2c 4e 29 5d 20 72 65 74 75 72 6e 73  oc(P,N)] returns
160e0 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e   a non-NULL poin
160f0 74 65 72 2c 20 69 74 20 66 69 72 73 74 0a 2a 2a  ter, it first.**
16100 20 20 20 20 20 20 20 20 20 20 20 63 6f 70 69 65             copie
16110 73 20 74 68 65 20 66 69 72 73 74 20 4b 20 62 79  s the first K by
16120 74 65 73 20 6f 66 20 63 6f 6e 74 65 6e 74 20 66  tes of content f
16130 72 6f 6d 20 50 20 69 6e 74 6f 20 74 68 65 20 6e  rom P into the n
16140 65 77 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20 20  ewly.**         
16150 20 20 61 6c 6c 6f 63 61 74 65 64 20 62 6c 6f 63    allocated bloc
16160 6b 2c 20 77 68 65 72 65 20 4b 20 69 73 20 74 68  k, where K is th
16170 65 20 6c 65 73 73 65 72 20 6f 66 20 4e 20 61 6e  e lesser of N an
16180 64 20 74 68 65 20 73 69 7a 65 20 6f 66 0a 2a 2a  d the size of.**
16190 20 20 20 20 20 20 20 20 20 20 20 74 68 65 20 62             the b
161a0 75 66 66 65 72 20 50 2e 0a 2a 2a 0a 2a 2a 20 7b  uffer P..**.** {
161b0 48 31 37 33 32 32 7d 20 20 57 68 65 6e 20 5b 73  H17322}  When [s
161c0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 50  qlite3_realloc(P
161d0 2c 4e 29 5d 20 72 65 74 75 72 6e 73 20 61 20 6e  ,N)] returns a n
161e0 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c  on-NULL pointer,
161f0 20 69 74 20 66 69 72 73 74 0a 2a 2a 20 20 20 20   it first.**    
16200 20 20 20 20 20 20 20 72 65 6c 65 61 73 65 73 20         releases 
16210 74 68 65 20 62 75 66 66 65 72 20 50 2e 0a 2a 2a  the buffer P..**
16220 0a 2a 2a 20 7b 48 31 37 33 32 33 7d 20 20 57 68  .** {H17323}  Wh
16230 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c  en [sqlite3_real
16240 6c 6f 63 28 50 2c 4e 29 5d 20 72 65 74 75 72 6e  loc(P,N)] return
16250 73 20 4e 55 4c 4c 2c 20 74 68 65 20 62 75 66 66  s NULL, the buff
16260 65 72 20 50 20 69 73 0a 2a 2a 20 20 20 20 20 20  er P is.**      
16270 20 20 20 20 20 6e 6f 74 20 6d 6f 64 69 66 69 65       not modifie
16280 64 20 6f 72 20 72 65 6c 65 61 73 65 64 2e 0a 2a  d or released..*
16290 2a 0a 2a 2a 20 41 53 53 55 4d 50 54 49 4f 4e 53  *.** ASSUMPTIONS
162a0 3a 0a 2a 2a 0a 2a 2a 20 7b 41 31 37 33 35 30 7d  :.**.** {A17350}
162b0 20 20 54 68 65 20 70 6f 69 6e 74 65 72 20 61 72    The pointer ar
162c0 67 75 6d 65 6e 74 73 20 74 6f 20 5b 73 71 6c 69  guments to [sqli
162d0 74 65 33 5f 66 72 65 65 28 29 5d 20 61 6e 64 20  te3_free()] and 
162e0 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  [sqlite3_realloc
162f0 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ()].**          
16300 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 20   must be either 
16310 4e 55 4c 4c 20 6f 72 20 65 6c 73 65 20 70 6f 69  NULL or else poi
16320 6e 74 65 72 73 20 6f 62 74 61 69 6e 65 64 20 66  nters obtained f
16330 72 6f 6d 20 61 20 70 72 69 6f 72 0a 2a 2a 20 20  rom a prior.**  
16340 20 20 20 20 20 20 20 20 20 69 6e 76 6f 63 61 74           invocat
16350 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f  ion of [sqlite3_
16360 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 73 71  malloc()] or [sq
16370 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d  lite3_realloc()]
16380 20 74 68 61 74 20 68 61 76 65 0a 2a 2a 20 20 20   that have.**   
16390 20 20 20 20 20 20 20 20 6e 6f 74 20 79 65 74 20          not yet 
163a0 62 65 65 6e 20 72 65 6c 65 61 73 65 64 2e 0a 2a  been released..*
163b0 2a 0a 2a 2a 20 7b 41 31 37 33 35 31 7d 20 20 54  *.** {A17351}  T
163c0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  he application m
163d0 75 73 74 20 6e 6f 74 20 72 65 61 64 20 6f 72 20  ust not read or 
163e0 77 72 69 74 65 20 61 6e 79 20 70 61 72 74 20 6f  write any part o
163f0 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 61  f.**           a
16400 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72 79   block of memory
16410 20 61 66 74 65 72 20 69 74 20 68 61 73 20 62 65   after it has be
16420 65 6e 20 72 65 6c 65 61 73 65 64 20 75 73 69 6e  en released usin
16430 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 5b  g.**           [
16440 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20  sqlite3_free()] 
16450 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c  or [sqlite3_real
16460 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 76 6f 69 64 20  loc()]..*/.void 
16470 2a 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  *sqlite3_malloc(
16480 69 6e 74 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69  int);.void *sqli
16490 74 65 33 5f 72 65 61 6c 6c 6f 63 28 76 6f 69 64  te3_realloc(void
164a0 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71  *, int);.void sq
164b0 6c 69 74 65 33 5f 66 72 65 65 28 76 6f 69 64 2a  lite3_free(void*
164c0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
164d0 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63  EF: Memory Alloc
164e0 61 74 6f 72 20 53 74 61 74 69 73 74 69 63 73 20  ator Statistics 
164f0 7b 48 31 37 33 37 30 7d 20 3c 53 33 30 32 31 30  {H17370} <S30210
16500 3e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 70  >.**.** SQLite p
16510 72 6f 76 69 64 65 73 20 74 68 65 73 65 20 74 77  rovides these tw
16520 6f 20 69 6e 74 65 72 66 61 63 65 73 20 66 6f 72  o interfaces for
16530 20 72 65 70 6f 72 74 69 6e 67 20 6f 6e 20 74 68   reporting on th
16540 65 20 73 74 61 74 75 73 0a 2a 2a 20 6f 66 20 74  e status.** of t
16550 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  he [sqlite3_mall
16560 6f 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  oc()], [sqlite3_
16570 66 72 65 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71  free()], and [sq
16580 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d  lite3_realloc()]
16590 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 2c 20 77 68  .** routines, wh
165a0 69 63 68 20 66 6f 72 6d 20 74 68 65 20 62 75 69  ich form the bui
165b0 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c  lt-in memory all
165c0 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65  ocation subsyste
165d0 6d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  m..**.** INVARIA
165e0 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33  NTS:.**.** {H173
165f0 37 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  71} The [sqlite3
16600 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20  _memory_used()] 
16610 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
16620 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
16630 74 65 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  tes.**          
16640 6f 66 20 6d 65 6d 6f 72 79 20 63 75 72 72 65 6e  of memory curren
16650 74 6c 79 20 6f 75 74 73 74 61 6e 64 69 6e 67 20  tly outstanding 
16660 28 6d 61 6c 6c 6f 63 65 64 20 62 75 74 20 6e 6f  (malloced but no
16670 74 20 66 72 65 65 64 29 2e 0a 2a 2a 0a 2a 2a 20  t freed)..**.** 
16680 7b 48 31 37 33 37 33 7d 20 54 68 65 20 5b 73 71  {H17373} The [sq
16690 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67  lite3_memory_hig
166a0 68 77 61 74 65 72 28 29 5d 20 72 6f 75 74 69 6e  hwater()] routin
166b0 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6d 61  e returns the ma
166c0 78 69 6d 75 6d 0a 2a 2a 20 20 20 20 20 20 20 20  ximum.**        
166d0 20 20 76 61 6c 75 65 20 6f 66 20 5b 73 71 6c 69    value of [sqli
166e0 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28  te3_memory_used(
166f0 29 5d 20 73 69 6e 63 65 20 74 68 65 20 68 69 67  )] since the hig
16700 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20  h-water mark.** 
16710 20 20 20 20 20 20 20 20 20 77 61 73 20 6c 61 73           was las
16720 74 20 72 65 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 7b  t reset..**.** {
16730 48 31 37 33 37 34 7d 20 54 68 65 20 76 61 6c 75  H17374} The valu
16740 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b  es returned by [
16750 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75  sqlite3_memory_u
16760 73 65 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 20 20  sed()] and.**   
16770 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
16780 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72  memory_highwater
16790 28 29 5d 20 69 6e 63 6c 75 64 65 20 61 6e 79 20  ()] include any 
167a0 6f 76 65 72 68 65 61 64 0a 2a 2a 20 20 20 20 20  overhead.**     
167b0 20 20 20 20 20 61 64 64 65 64 20 62 79 20 53 51       added by SQ
167c0 4c 69 74 65 20 69 6e 20 69 74 73 20 69 6d 70 6c  Lite in its impl
167d0 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 73  ementation of [s
167e0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
167f0 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 75  ,.**          bu
16800 74 20 6e 6f 74 20 6f 76 65 72 68 65 61 64 20 61  t not overhead a
16810 64 64 65 64 20 62 79 20 74 68 65 20 61 6e 79 20  dded by the any 
16820 75 6e 64 65 72 6c 79 69 6e 67 20 73 79 73 74 65  underlying syste
16830 6d 20 6c 69 62 72 61 72 79 0a 2a 2a 20 20 20 20  m library.**    
16840 20 20 20 20 20 20 72 6f 75 74 69 6e 65 73 20 74        routines t
16850 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  hat [sqlite3_mal
16860 6c 6f 63 28 29 5d 20 6d 61 79 20 63 61 6c 6c 2e  loc()] may call.
16870 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33 37 35 7d 20  .**.** {H17375} 
16880 54 68 65 20 6d 65 6d 6f 72 79 20 68 69 67 68 2d  The memory high-
16890 77 61 74 65 72 20 6d 61 72 6b 20 69 73 20 72 65  water mark is re
168a0 73 65 74 20 74 6f 20 74 68 65 20 63 75 72 72 65  set to the curre
168b0 6e 74 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 20  nt value of.**  
168c0 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
168d0 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20  _memory_used()] 
168e0 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74  if and only if t
168f0 68 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  he parameter to.
16900 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
16910 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68  ite3_memory_high
16920 77 61 74 65 72 28 29 5d 20 69 73 20 74 72 75 65  water()] is true
16930 2e 20 20 54 68 65 20 76 61 6c 75 65 20 72 65 74  .  The value ret
16940 75 72 6e 65 64 0a 2a 2a 20 20 20 20 20 20 20 20  urned.**        
16950 20 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65    by [sqlite3_me
16960 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 31  mory_highwater(1
16970 29 5d 20 69 73 20 74 68 65 20 68 69 67 68 2d 77  )] is the high-w
16980 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 20 20 20  ater mark.**    
16990 20 20 20 20 20 20 70 72 69 6f 72 20 74 6f 20 74        prior to t
169a0 68 65 20 72 65 73 65 74 2e 0a 2a 2f 0a 73 71 6c  he reset..*/.sql
169b0 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74  ite3_int64 sqlit
169c0 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 76  e3_memory_used(v
169d0 6f 69 64 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e  oid);.sqlite3_in
169e0 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  t64 sqlite3_memo
169f0 72 79 5f 68 69 67 68 77 61 74 65 72 28 69 6e 74  ry_highwater(int
16a00 20 72 65 73 65 74 46 6c 61 67 29 3b 0a 0a 2f 2a   resetFlag);../*
16a10 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 50 73  .** CAPI3REF: Ps
16a20 65 75 64 6f 2d 52 61 6e 64 6f 6d 20 4e 75 6d 62  eudo-Random Numb
16a30 65 72 20 47 65 6e 65 72 61 74 6f 72 20 7b 48 31  er Generator {H1
16a40 37 33 39 30 7d 20 3c 53 32 30 30 30 30 3e 0a 2a  7390} <S20000>.*
16a50 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63 6f 6e 74  *.** SQLite cont
16a60 61 69 6e 73 20 61 20 68 69 67 68 2d 71 75 61 6c  ains a high-qual
16a70 69 74 79 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f  ity pseudo-rando
16a80 6d 20 6e 75 6d 62 65 72 20 67 65 6e 65 72 61 74  m number generat
16a90 6f 72 20 28 50 52 4e 47 29 20 75 73 65 64 20 74  or (PRNG) used t
16aa0 6f 0a 2a 2a 20 73 65 6c 65 63 74 20 72 61 6e 64  o.** select rand
16ab0 6f 6d 20 52 4f 57 49 44 73 20 77 68 65 6e 20 69  om ROWIDs when i
16ac0 6e 73 65 72 74 69 6e 67 20 6e 65 77 20 72 65 63  nserting new rec
16ad0 6f 72 64 73 20 69 6e 74 6f 20 61 20 74 61 62 6c  ords into a tabl
16ae0 65 20 74 68 61 74 0a 2a 2a 20 61 6c 72 65 61 64  e that.** alread
16af0 79 20 75 73 65 73 20 74 68 65 20 6c 61 72 67 65  y uses the large
16b00 73 74 20 70 6f 73 73 69 62 6c 65 20 52 4f 57 49  st possible ROWI
16b10 44 2e 20 20 54 68 65 20 50 52 4e 47 20 69 73 20  D.  The PRNG is 
16b20 61 6c 73 6f 20 75 73 65 64 20 66 6f 72 0a 2a 2a  also used for.**
16b30 20 74 68 65 20 62 75 69 6c 64 2d 69 6e 20 72 61   the build-in ra
16b40 6e 64 6f 6d 28 29 20 61 6e 64 20 72 61 6e 64 6f  ndom() and rando
16b50 6d 62 6c 6f 62 28 29 20 53 51 4c 20 66 75 6e 63  mblob() SQL func
16b60 74 69 6f 6e 73 2e 20 20 54 68 69 73 20 69 6e 74  tions.  This int
16b70 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 0a 2a 2a  erface allows.**
16b80 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 6f   applications to
16b90 20 61 63 63 65 73 73 20 74 68 65 20 73 61 6d 65   access the same
16ba0 20 50 52 4e 47 20 66 6f 72 20 6f 74 68 65 72 20   PRNG for other 
16bb0 70 75 72 70 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a 20  purposes..**.** 
16bc0 41 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20 72  A call to this r
16bd0 6f 75 74 69 6e 65 20 73 74 6f 72 65 73 20 4e 20  outine stores N 
16be0 62 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e  bytes of randomn
16bf0 65 73 73 20 69 6e 74 6f 20 62 75 66 66 65 72 20  ess into buffer 
16c00 50 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72  P..**.** The fir
16c10 73 74 20 74 69 6d 65 20 74 68 69 73 20 72 6f 75  st time this rou
16c20 74 69 6e 65 20 69 73 20 69 6e 76 6f 6b 65 64 20  tine is invoked 
16c30 28 65 69 74 68 65 72 20 69 6e 74 65 72 6e 61 6c  (either internal
16c40 6c 79 20 6f 72 20 62 79 0a 2a 2a 20 74 68 65 20  ly or by.** the 
16c50 61 70 70 6c 69 63 61 74 69 6f 6e 29 20 74 68 65  application) the
16c60 20 50 52 4e 47 20 69 73 20 73 65 65 64 65 64 20   PRNG is seeded 
16c70 75 73 69 6e 67 20 72 61 6e 64 6f 6d 6e 65 73 73  using randomness
16c80 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f   obtained.** fro
16c90 6d 20 74 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73  m the xRandomnes
16ca0 73 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20  s method of the 
16cb0 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33  default [sqlite3
16cc0 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a  _vfs] object..**
16cd0 20 4f 6e 20 61 6c 6c 20 73 75 62 73 65 71 75 65   On all subseque
16ce0 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e 73 2c 20  nt invocations, 
16cf0 74 68 65 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f  the pseudo-rando
16d00 6d 6e 65 73 73 20 69 73 20 67 65 6e 65 72 61 74  mness is generat
16d10 65 64 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 6c 79  ed.** internally
16d20 20 61 6e 64 20 77 69 74 68 6f 75 74 20 72 65 63   and without rec
16d30 6f 75 72 73 65 20 74 6f 20 74 68 65 20 5b 73 71  ourse to the [sq
16d40 6c 69 74 65 33 5f 76 66 73 5d 20 78 52 61 6e 64  lite3_vfs] xRand
16d50 6f 6d 6e 65 73 73 0a 2a 2a 20 6d 65 74 68 6f 64  omness.** method
16d60 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  ..**.** INVARIAN
16d70 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33 39  TS:.**.** {H1739
16d80 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  2} The [sqlite3_
16d90 72 61 6e 64 6f 6d 6e 65 73 73 28 4e 2c 50 29 5d  randomness(N,P)]
16da0 20 69 6e 74 65 72 66 61 63 65 20 77 72 69 74 65   interface write
16db0 73 20 4e 20 62 79 74 65 73 20 6f 66 0a 2a 2a 20  s N bytes of.** 
16dc0 20 20 20 20 20 20 20 20 20 68 69 67 68 2d 71 75           high-qu
16dd0 61 6c 69 74 79 20 70 73 65 75 64 6f 2d 72 61 6e  ality pseudo-ran
16de0 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 62 75 66  domness into buf
16df0 66 65 72 20 50 2e 0a 2a 2f 0a 76 6f 69 64 20 73  fer P..*/.void s
16e00 71 6c 69 74 65 33 5f 72 61 6e 64 6f 6d 6e 65 73  qlite3_randomnes
16e10 73 28 69 6e 74 20 4e 2c 20 76 6f 69 64 20 2a 50  s(int N, void *P
16e20 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
16e30 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d 65  EF: Compile-Time
16e40 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 43   Authorization C
16e50 61 6c 6c 62 61 63 6b 73 20 7b 48 31 32 35 30 30  allbacks {H12500
16e60 7d 20 3c 53 37 30 31 30 30 3e 0a 2a 2a 0a 2a 2a  } <S70100>.**.**
16e70 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65   This routine re
16e80 67 69 73 74 65 72 73 20 61 20 61 75 74 68 6f 72  gisters a author
16e90 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 77 69  izer callback wi
16ea0 74 68 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a  th a particular.
16eb0 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
16ec0 6e 65 63 74 69 6f 6e 5d 2c 20 73 75 70 70 6c 69  nection], suppli
16ed0 65 64 20 69 6e 20 74 68 65 20 66 69 72 73 74 20  ed in the first 
16ee0 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65  argument..** The
16ef0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
16f00 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20  back is invoked 
16f10 61 73 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  as SQL statement
16f20 73 20 61 72 65 20 62 65 69 6e 67 20 63 6f 6d 70  s are being comp
16f30 69 6c 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69  iled.** by [sqli
16f40 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f  te3_prepare()] o
16f50 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 20 5b  r its variants [
16f60 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
16f70 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  v2()],.** [sqlit
16f80 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20  e3_prepare16()] 
16f90 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  and [sqlite3_pre
16fa0 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 20 20 41  pare16_v2()].  A
16fb0 74 20 76 61 72 69 6f 75 73 0a 2a 2a 20 70 6f 69  t various.** poi
16fc0 6e 74 73 20 64 75 72 69 6e 67 20 74 68 65 20 63  nts during the c
16fd0 6f 6d 70 69 6c 61 74 69 6f 6e 20 70 72 6f 63 65  ompilation proce
16fe0 73 73 2c 20 61 73 20 6c 6f 67 69 63 20 69 73 20  ss, as logic is 
16ff0 62 65 69 6e 67 20 63 72 65 61 74 65 64 0a 2a 2a  being created.**
17000 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69   to perform vari
17010 6f 75 73 20 61 63 74 69 6f 6e 73 2c 20 74 68 65  ous actions, the
17020 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
17030 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20  back is invoked 
17040 74 6f 0a 2a 2a 20 73 65 65 20 69 66 20 74 68 6f  to.** see if tho
17050 73 65 20 61 63 74 69 6f 6e 73 20 61 72 65 20 61  se actions are a
17060 6c 6c 6f 77 65 64 2e 20 20 54 68 65 20 61 75 74  llowed.  The aut
17070 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
17080 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72   should.** retur
17090 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 74 6f  n [SQLITE_OK] to
170a0 20 61 6c 6c 6f 77 20 74 68 65 20 61 63 74 69 6f   allow the actio
170b0 6e 2c 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52  n, [SQLITE_IGNOR
170c0 45 5d 20 74 6f 20 64 69 73 61 6c 6c 6f 77 20 74  E] to disallow t
170d0 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 61  he.** specific a
170e0 63 74 69 6f 6e 20 62 75 74 20 61 6c 6c 6f 77 20  ction but allow 
170f0 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
17100 74 20 74 6f 20 63 6f 6e 74 69 6e 75 65 20 74 6f  t to continue to
17110 20 62 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 2c   be.** compiled,
17120 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59   or [SQLITE_DENY
17130 5d 20 74 6f 20 63 61 75 73 65 20 74 68 65 20 65  ] to cause the e
17140 6e 74 69 72 65 20 53 51 4c 20 73 74 61 74 65 6d  ntire SQL statem
17150 65 6e 74 20 74 6f 20 62 65 0a 2a 2a 20 72 65 6a  ent to be.** rej
17160 65 63 74 65 64 20 77 69 74 68 20 61 6e 20 65 72  ected with an er
17170 72 6f 72 2e 20 20 49 66 20 74 68 65 20 61 75 74  ror.  If the aut
17180 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
17190 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20   returns.** any 
171a0 76 61 6c 75 65 20 6f 74 68 65 72 20 74 68 61 6e  value other than
171b0 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d   [SQLITE_IGNORE]
171c0 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 6f  , [SQLITE_OK], o
171d0 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 0a  r [SQLITE_DENY].
171e0 2a 2a 20 74 68 65 6e 20 74 68 65 20 5b 73 71 6c  ** then the [sql
171f0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
17200 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74  )] or equivalent
17210 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67   call that trigg
17220 65 72 65 64 0a 2a 2a 20 74 68 65 20 61 75 74 68  ered.** the auth
17230 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c  orizer will fail
17240 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 6d   with an error m
17250 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 57 68  essage..**.** Wh
17260 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  en the callback 
17270 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
17280 4f 4b 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73 20  OK], that means 
17290 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a  the operation.**
172a0 20 72 65 71 75 65 73 74 65 64 20 69 73 20 6f 6b   requested is ok
172b0 2e 20 20 57 68 65 6e 20 74 68 65 20 63 61 6c 6c  .  When the call
172c0 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51  back returns [SQ
172d0 4c 49 54 45 5f 44 45 4e 59 5d 2c 20 74 68 65 0a  LITE_DENY], the.
172e0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
172f0 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75  are_v2()] or equ
17300 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61  ivalent call tha
17310 74 20 74 72 69 67 67 65 72 65 64 20 74 68 65 0a  t triggered the.
17320 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 77 69  ** authorizer wi
17330 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20  ll fail with an 
17340 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 65 78  error message ex
17350 70 6c 61 69 6e 69 6e 67 20 74 68 61 74 0a 2a 2a  plaining that.**
17360 20 61 63 63 65 73 73 20 69 73 20 64 65 6e 69 65   access is denie
17370 64 2e 20 20 49 66 20 74 68 65 20 61 75 74 68 6f  d.  If the autho
17380 72 69 7a 65 72 20 63 6f 64 65 20 69 73 20 5b 53  rizer code is [S
17390 51 4c 49 54 45 5f 52 45 41 44 5d 0a 2a 2a 20 61  QLITE_READ].** a
173a0 6e 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  nd the callback 
173b0 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
173c0 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65  IGNORE] then the
173d0 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
173e0 61 74 65 6d 65 6e 74 5d 20 73 74 61 74 65 6d 65  atement] stateme
173f0 6e 74 20 69 73 20 63 6f 6e 73 74 72 75 63 74 65  nt is constructe
17400 64 20 74 6f 20 73 75 62 73 74 69 74 75 74 65 0a  d to substitute.
17410 2a 2a 20 61 20 4e 55 4c 4c 20 76 61 6c 75 65 20  ** a NULL value 
17420 69 6e 20 70 6c 61 63 65 20 6f 66 20 74 68 65 20  in place of the 
17430 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61  table column tha
17440 74 20 77 6f 75 6c 64 20 68 61 76 65 0a 2a 2a 20  t would have.** 
17450 62 65 65 6e 20 72 65 61 64 20 69 66 20 5b 53 51  been read if [SQ
17460 4c 49 54 45 5f 4f 4b 5d 20 68 61 64 20 62 65 65  LITE_OK] had bee
17470 6e 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65  n returned.  The
17480 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d   [SQLITE_IGNORE]
17490 0a 2a 2a 20 72 65 74 75 72 6e 20 63 61 6e 20 62  .** return can b
174a0 65 20 75 73 65 64 20 74 6f 20 64 65 6e 79 20 61  e used to deny a
174b0 6e 20 75 6e 74 72 75 73 74 65 64 20 75 73 65 72  n untrusted user
174c0 20 61 63 63 65 73 73 20 74 6f 20 69 6e 64 69 76   access to indiv
174d0 69 64 75 61 6c 0a 2a 2a 20 63 6f 6c 75 6d 6e 73  idual.** columns
174e0 20 6f 66 20 61 20 74 61 62 6c 65 2e 0a 2a 2a 0a   of a table..**.
174f0 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 61 72  ** The first par
17500 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 75  ameter to the au
17510 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
17520 6b 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74  k is a copy of t
17530 68 65 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 61  he third.** para
17540 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c  meter to the sql
17550 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
17560 7a 65 72 28 29 20 69 6e 74 65 72 66 61 63 65 2e  zer() interface.
17570 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   The second para
17580 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20  meter.** to the 
17590 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69  callback is an i
175a0 6e 74 65 67 65 72 20 5b 53 51 4c 49 54 45 5f 43  nteger [SQLITE_C
175b0 4f 50 59 20 7c 20 61 63 74 69 6f 6e 20 63 6f 64  OPY | action cod
175c0 65 5d 20 74 68 61 74 20 73 70 65 63 69 66 69 65  e] that specifie
175d0 73 0a 2a 2a 20 74 68 65 20 70 61 72 74 69 63 75  s.** the particu
175e0 6c 61 72 20 61 63 74 69 6f 6e 20 74 6f 20 62 65  lar action to be
175f0 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 54 68 65   authorized. The
17600 20 74 68 69 72 64 20 74 68 72 6f 75 67 68 20 73   third through s
17610 69 78 74 68 20 70 61 72 61 6d 65 74 65 72 73 0a  ixth parameters.
17620 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61  ** to the callba
17630 63 6b 20 61 72 65 20 7a 65 72 6f 2d 74 65 72 6d  ck are zero-term
17640 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20 74  inated strings t
17650 68 61 74 20 63 6f 6e 74 61 69 6e 20 61 64 64 69  hat contain addi
17660 74 69 6f 6e 61 6c 0a 2a 2a 20 64 65 74 61 69 6c  tional.** detail
17670 73 20 61 62 6f 75 74 20 74 68 65 20 61 63 74 69  s about the acti
17680 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69  on to be authori
17690 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75  zed..**.** An au
176a0 74 68 6f 72 69 7a 65 72 20 69 73 20 75 73 65 64  thorizer is used
176b0 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70   when [sqlite3_p
176c0 72 65 70 61 72 65 20 7c 20 70 72 65 70 61 72 69  repare | prepari
176d0 6e 67 5d 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65  ng].** SQL state
176e0 6d 65 6e 74 73 20 66 72 6f 6d 20 61 6e 20 75 6e  ments from an un
176f0 74 72 75 73 74 65 64 20 73 6f 75 72 63 65 2c 20  trusted source, 
17700 74 6f 20 65 6e 73 75 72 65 20 74 68 61 74 20 74  to ensure that t
17710 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
17720 73 0a 2a 2a 20 64 6f 20 6e 6f 74 20 74 72 79 20  s.** do not try 
17730 74 6f 20 61 63 63 65 73 73 20 64 61 74 61 20 74  to access data t
17740 68 65 79 20 61 72 65 20 6e 6f 74 20 61 6c 6c 6f  hey are not allo
17750 77 65 64 20 74 6f 20 73 65 65 2c 20 6f 72 20 74  wed to see, or t
17760 68 61 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a  hat they do not.
17770 2a 2a 20 74 72 79 20 74 6f 20 65 78 65 63 75 74  ** try to execut
17780 65 20 6d 61 6c 69 63 69 6f 75 73 20 73 74 61 74  e malicious stat
17790 65 6d 65 6e 74 73 20 74 68 61 74 20 64 61 6d 61  ements that dama
177a0 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65 2e  ge the database.
177b0 20 20 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65    For.** example
177c0 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  , an application
177d0 20 6d 61 79 20 61 6c 6c 6f 77 20 61 20 75 73 65   may allow a use
177e0 72 20 74 6f 20 65 6e 74 65 72 20 61 72 62 69 74  r to enter arbit
177f0 72 61 72 79 0a 2a 2a 20 53 51 4c 20 71 75 65 72  rary.** SQL quer
17800 69 65 73 20 66 6f 72 20 65 76 61 6c 75 61 74 69  ies for evaluati
17810 6f 6e 20 62 79 20 61 20 64 61 74 61 62 61 73 65  on by a database
17820 2e 20 20 42 75 74 20 74 68 65 20 61 70 70 6c 69  .  But the appli
17830 63 61 74 69 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e  cation does.** n
17840 6f 74 20 77 61 6e 74 20 74 68 65 20 75 73 65 72  ot want the user
17850 20 74 6f 20 62 65 20 61 62 6c 65 20 74 6f 20 6d   to be able to m
17860 61 6b 65 20 61 72 62 69 74 72 61 72 79 20 63 68  ake arbitrary ch
17870 61 6e 67 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20  anges to the.** 
17880 64 61 74 61 62 61 73 65 2e 20 20 41 6e 20 61 75  database.  An au
17890 74 68 6f 72 69 7a 65 72 20 63 6f 75 6c 64 20 74  thorizer could t
178a0 68 65 6e 20 62 65 20 70 75 74 20 69 6e 20 70 6c  hen be put in pl
178b0 61 63 65 20 77 68 69 6c 65 20 74 68 65 0a 2a 2a  ace while the.**
178c0 20 75 73 65 72 2d 65 6e 74 65 72 65 64 20 53 51   user-entered SQ
178d0 4c 20 69 73 20 62 65 69 6e 67 20 5b 73 71 6c 69  L is being [sqli
178e0 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72  te3_prepare | pr
178f0 65 70 61 72 65 64 5d 20 74 68 61 74 0a 2a 2a 20  epared] that.** 
17900 64 69 73 61 6c 6c 6f 77 73 20 65 76 65 72 79 74  disallows everyt
17910 68 69 6e 67 20 65 78 63 65 70 74 20 5b 53 45 4c  hing except [SEL
17920 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e  ECT] statements.
17930 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69  .**.** Applicati
17940 6f 6e 73 20 74 68 61 74 20 6e 65 65 64 20 74 6f  ons that need to
17950 20 70 72 6f 63 65 73 73 20 53 51 4c 20 66 72 6f   process SQL fro
17960 6d 20 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72  m untrusted sour
17970 63 65 73 0a 2a 2a 20 6d 69 67 68 74 20 61 6c 73  ces.** might als
17980 6f 20 63 6f 6e 73 69 64 65 72 20 6c 6f 77 65 72  o consider lower
17990 69 6e 67 20 72 65 73 6f 75 72 63 65 20 6c 69 6d  ing resource lim
179a0 69 74 73 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  its using [sqlit
179b0 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 61  e3_limit()].** a
179c0 6e 64 20 6c 69 6d 69 74 69 6e 67 20 64 61 74 61  nd limiting data
179d0 62 61 73 65 20 73 69 7a 65 20 75 73 69 6e 67 20  base size using 
179e0 74 68 65 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f  the [max_page_co
179f0 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 0a 2a 2a  unt] [PRAGMA].**
17a00 20 69 6e 20 61 64 64 69 74 69 6f 6e 20 74 6f 20   in addition to 
17a10 75 73 69 6e 67 20 61 6e 20 61 75 74 68 6f 72 69  using an authori
17a20 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 4f 6e 6c 79 20  zer..**.** Only 
17a30 61 20 73 69 6e 67 6c 65 20 61 75 74 68 6f 72 69  a single authori
17a40 7a 65 72 20 63 61 6e 20 62 65 20 69 6e 20 70 6c  zer can be in pl
17a50 61 63 65 20 6f 6e 20 61 20 64 61 74 61 62 61 73  ace on a databas
17a60 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20  e connection.** 
17a70 61 74 20 61 20 74 69 6d 65 2e 20 20 45 61 63 68  at a time.  Each
17a80 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
17a90 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20  _set_authorizer 
17aa0 6f 76 65 72 72 69 64 65 73 20 74 68 65 0a 2a 2a  overrides the.**
17ab0 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 2e 20   previous call. 
17ac0 20 44 69 73 61 62 6c 65 20 74 68 65 20 61 75 74   Disable the aut
17ad0 68 6f 72 69 7a 65 72 20 62 79 20 69 6e 73 74 61  horizer by insta
17ae0 6c 6c 69 6e 67 20 61 20 4e 55 4c 4c 20 63 61 6c  lling a NULL cal
17af0 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68 65 20 61 75  lback..** The au
17b00 74 68 6f 72 69 7a 65 72 20 69 73 20 64 69 73 61  thorizer is disa
17b10 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e  bled by default.
17b20 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 5b 73 71 6c  .**.** When [sql
17b30 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
17b40 29 5d 20 69 73 20 75 73 65 64 20 74 6f 20 70 72  )] is used to pr
17b50 65 70 61 72 65 20 61 20 73 74 61 74 65 6d 65 6e  epare a statemen
17b60 74 2c 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d  t, the.** statem
17b70 65 6e 74 20 6d 69 67 68 74 20 62 65 20 72 65 70  ent might be rep
17b80 72 65 70 61 72 65 64 20 64 75 72 69 6e 67 20 5b  repared during [
17b90 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
17ba0 64 75 65 20 74 6f 20 61 20 0a 2a 2a 20 73 63 68  due to a .** sch
17bb0 65 6d 61 20 63 68 61 6e 67 65 2e 20 20 48 65 6e  ema change.  Hen
17bc0 63 65 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74  ce, the applicat
17bd0 69 6f 6e 20 73 68 6f 75 6c 64 20 65 6e 73 75 72  ion should ensur
17be0 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 63 6f  e that the.** co
17bf0 72 72 65 63 74 20 61 75 74 68 6f 72 69 7a 65 72  rrect authorizer
17c00 20 63 61 6c 6c 62 61 63 6b 20 72 65 6d 61 69 6e   callback remain
17c10 73 20 69 6e 20 70 6c 61 63 65 20 64 75 72 69 6e  s in place durin
17c20 67 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  g the [sqlite3_s
17c30 74 65 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 6f  tep()]..**.** No
17c40 74 65 20 74 68 61 74 20 74 68 65 20 61 75 74 68  te that the auth
17c50 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
17c60 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 6c 79 20  is invoked only 
17c70 64 75 72 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74  during.** [sqlit
17c80 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72  e3_prepare()] or
17c90 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e 20 20   its variants.  
17ca0 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 69 73  Authorization is
17cb0 20 6e 6f 74 0a 2a 2a 20 70 65 72 66 6f 72 6d 65   not.** performe
17cc0 64 20 64 75 72 69 6e 67 20 73 74 61 74 65 6d 65  d during stateme
17cd0 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 69 6e  nt evaluation in
17ce0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
17cf0 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  ]..**.** INVARIA
17d00 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35  NTS:.**.** {H125
17d10 30 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  01} The [sqlite3
17d20 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28  _set_authorizer(
17d30 44 2c 2e 2e 2e 29 5d 20 69 6e 74 65 72 66 61 63  D,...)] interfac
17d40 65 20 72 65 67 69 73 74 65 72 73 20 61 0a 2a 2a  e registers a.**
17d50 20 20 20 20 20 20 20 20 20 20 61 75 74 68 6f 72            author
17d60 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 77 69  izer callback wi
17d70 74 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  th database conn
17d80 65 63 74 69 6f 6e 20 44 2e 0a 2a 2a 0a 2a 2a 20  ection D..**.** 
17d90 7b 48 31 32 35 30 32 7d 20 54 68 65 20 61 75 74  {H12502} The aut
17da0 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
17db0 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 73 20 53   is invoked as S
17dc0 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72  QL statements ar
17dd0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 65  e.**          be
17de0 69 6e 67 20 70 61 72 73 65 65 64 20 61 6e 64 20  ing parseed and 
17df0 63 6f 6d 70 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20  compiled..**.** 
17e00 7b 48 31 32 35 30 33 7d 20 49 66 20 74 68 65 20  {H12503} If the 
17e10 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
17e20 61 63 6b 20 72 65 74 75 72 6e 73 20 61 6e 79 20  ack returns any 
17e30 76 61 6c 75 65 20 6f 74 68 65 72 20 74 68 61 6e  value other than
17e40 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51  .**          [SQ
17e50 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53  LITE_IGNORE], [S
17e60 51 4c 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53  QLITE_OK], or [S
17e70 51 4c 49 54 45 5f 44 45 4e 59 5d 2c 20 74 68 65  QLITE_DENY], the
17e80 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  n.**          th
17e90 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 6e  e application in
17ea0 74 65 72 66 61 63 65 20 63 61 6c 6c 20 74 68 61  terface call tha
17eb0 74 20 63 61 75 73 65 64 0a 2a 2a 20 20 20 20 20  t caused.**     
17ec0 20 20 20 20 20 74 68 65 20 61 75 74 68 6f 72 69       the authori
17ed0 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 74 6f 20  zer callback to 
17ee0 72 75 6e 20 73 68 61 6c 6c 20 66 61 69 6c 20 77  run shall fail w
17ef0 69 74 68 20 61 6e 0a 2a 2a 20 20 20 20 20 20 20  ith an.**       
17f00 20 20 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52     [SQLITE_ERROR
17f10 5d 20 65 72 72 6f 72 20 63 6f 64 65 20 61 6e 64  ] error code and
17f20 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20   an appropriate 
17f30 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a  error message..*
17f40 2a 0a 2a 2a 20 7b 48 31 32 35 30 34 7d 20 57 68  *.** {H12504} Wh
17f50 65 6e 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  en the authorize
17f60 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  r callback retur
17f70 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20  ns [SQLITE_OK], 
17f80 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a  the operation.**
17f90 20 20 20 20 20 20 20 20 20 20 64 65 73 63 72 69            descri
17fa0 62 65 64 20 69 73 20 70 72 6f 63 65 73 73 65 64  bed is processed
17fb0 20 6e 6f 72 6d 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a   normally..**.**
17fc0 20 7b 48 31 32 35 30 35 7d 20 57 68 65 6e 20 74   {H12505} When t
17fd0 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
17fe0 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b  llback returns [
17ff0 53 51 4c 49 54 45 5f 44 45 4e 59 5d 2c 20 74 68  SQLITE_DENY], th
18000 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 70  e.**          ap
18010 70 6c 69 63 61 74 69 6f 6e 20 69 6e 74 65 72 66  plication interf
18020 61 63 65 20 63 61 6c 6c 20 74 68 61 74 20 63 61  ace call that ca
18030 75 73 65 64 20 74 68 65 0a 2a 2a 20 20 20 20 20  used the.**     
18040 20 20 20 20 20 61 75 74 68 6f 72 69 7a 65 72 20       authorizer 
18050 63 61 6c 6c 62 61 63 6b 20 74 6f 20 72 75 6e 20  callback to run 
18060 73 68 61 6c 6c 20 66 61 69 6c 0a 2a 2a 20 20 20  shall fail.**   
18070 20 20 20 20 20 20 20 77 69 74 68 20 61 6e 20 5b         with an [
18080 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 65 72  SQLITE_ERROR] er
18090 72 6f 72 20 63 6f 64 65 20 61 6e 64 20 61 6e 20  ror code and an 
180a0 65 72 72 6f 72 20 6d 65 73 73 61 67 65 0a 2a 2a  error message.**
180b0 20 20 20 20 20 20 20 20 20 20 65 78 70 6c 61 69            explai
180c0 6e 69 6e 67 20 74 68 61 74 20 61 63 63 65 73 73  ning that access
180d0 20 69 73 20 64 65 6e 69 65 64 2e 0a 2a 2a 0a 2a   is denied..**.*
180e0 2a 20 7b 48 31 32 35 30 36 7d 20 49 66 20 74 68  * {H12506} If th
180f0 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 6f 64  e authorizer cod
18100 65 20 28 74 68 65 20 32 6e 64 20 70 61 72 61 6d  e (the 2nd param
18110 65 74 65 72 20 74 6f 20 74 68 65 20 61 75 74 68  eter to the auth
18120 6f 72 69 7a 65 72 0a 2a 2a 20 20 20 20 20 20 20  orizer.**       
18130 20 20 20 63 61 6c 6c 62 61 63 6b 29 20 69 73 20     callback) is 
18140 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d 20 61 6e  [SQLITE_READ] an
18150 64 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  d the authorizer
18160 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
18170 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53  s.**          [S
18180 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 2c 20 74  QLITE_IGNORE], t
18190 68 65 6e 20 74 68 65 20 70 72 65 70 61 72 65 64  hen the prepared
181a0 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 63 6f   statement is co
181b0 6e 73 74 72 75 63 74 65 64 20 74 6f 0a 2a 2a 20  nstructed to.** 
181c0 20 20 20 20 20 20 20 20 20 69 6e 73 65 72 74 20           insert 
181d0 61 20 4e 55 4c 4c 20 76 61 6c 75 65 20 69 6e 20  a NULL value in 
181e0 70 6c 61 63 65 20 6f 66 20 74 68 65 20 74 61 62  place of the tab
181f0 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 77  le column that w
18200 6f 75 6c 64 20 68 61 76 65 0a 2a 2a 20 20 20 20  ould have.**    
18210 20 20 20 20 20 20 62 65 65 6e 20 72 65 61 64 20        been read 
18220 69 66 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 68  if [SQLITE_OK] h
18230 61 64 20 62 65 65 6e 20 72 65 74 75 72 6e 65 64  ad been returned
18240 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 30 37 7d  ..**.** {H12507}
18250 20 49 66 20 74 68 65 20 61 75 74 68 6f 72 69 7a   If the authoriz
18260 65 72 20 63 6f 64 65 20 28 74 68 65 20 32 6e 64  er code (the 2nd
18270 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
18280 65 20 61 75 74 68 6f 72 69 7a 65 72 0a 2a 2a 20  e authorizer.** 
18290 20 20 20 20 20 20 20 20 20 63 61 6c 6c 62 61 63           callbac
182a0 6b 29 20 69 73 20 61 6e 79 74 68 69 6e 67 20 6f  k) is anything o
182b0 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54  ther than [SQLIT
182c0 45 5f 52 45 41 44 5d 2c 20 74 68 65 6e 0a 2a 2a  E_READ], then.**
182d0 20 20 20 20 20 20 20 20 20 20 61 20 72 65 74 75            a retu
182e0 72 6e 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49 47  rn of [SQLITE_IG
182f0 4e 4f 52 45 5d 20 68 61 73 20 74 68 65 20 73 61  NORE] has the sa
18300 6d 65 20 65 66 66 65 63 74 20 61 73 20 5b 53 51  me effect as [SQ
18310 4c 49 54 45 5f 44 45 4e 59 5d 2e 0a 2a 2a 0a 2a  LITE_DENY]..**.*
18320 2a 20 7b 48 31 32 35 31 30 7d 20 54 68 65 20 66  * {H12510} The f
18330 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74  irst parameter t
18340 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  o the authorizer
18350 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 63   callback is a c
18360 6f 70 79 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20  opy of.**       
18370 20 20 20 74 68 65 20 74 68 69 72 64 20 70 61 72     the third par
18380 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 5b 73  ameter to the [s
18390 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
183a0 72 69 7a 65 72 28 29 5d 20 69 6e 74 65 72 66 61  rizer()] interfa
183b0 63 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 31  ce..**.** {H1251
183c0 31 7d 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61  1} The second pa
183d0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63  rameter to the c
183e0 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e  allback is an in
183f0 74 65 67 65 72 0a 2a 2a 20 20 20 20 20 20 20 20  teger.**        
18400 20 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c    [SQLITE_COPY |
18410 20 61 63 74 69 6f 6e 20 63 6f 64 65 5d 20 74 68   action code] th
18420 61 74 20 73 70 65 63 69 66 69 65 73 20 74 68 65  at specifies the
18430 20 70 61 72 74 69 63 75 6c 61 72 20 61 63 74 69   particular acti
18440 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  on.**          t
18450 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e  o be authorized.
18460 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 31 32 7d 20  .**.** {H12512} 
18470 54 68 65 20 74 68 69 72 64 20 74 68 72 6f 75 67  The third throug
18480 68 20 73 69 78 74 68 20 70 61 72 61 6d 65 74 65  h sixth paramete
18490 72 73 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61  rs to the callba
184a0 63 6b 20 61 72 65 0a 2a 2a 20 20 20 20 20 20 20  ck are.**       
184b0 20 20 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74     zero-terminat
184c0 65 64 20 73 74 72 69 6e 67 73 20 74 68 61 74 20  ed strings that 
184d0 63 6f 6e 74 61 69 6e 0a 2a 2a 20 20 20 20 20 20  contain.**      
184e0 20 20 20 20 61 64 64 69 74 69 6f 6e 61 6c 20 64      additional d
184f0 65 74 61 69 6c 73 20 61 62 6f 75 74 20 74 68 65  etails about the
18500 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75   action to be au
18510 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20  thorized..**.** 
18520 7b 48 31 32 35 32 30 7d 20 45 61 63 68 20 63 61  {H12520} Each ca
18530 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73  ll to [sqlite3_s
18540 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d  et_authorizer()]
18550 20 6f 76 65 72 72 69 64 65 73 0a 2a 2a 20 20 20   overrides.**   
18560 20 20 20 20 20 20 20 61 6e 79 20 70 72 65 76 69         any previ
18570 6f 75 73 6c 79 20 69 6e 73 74 61 6c 6c 65 64 20  ously installed 
18580 61 75 74 68 6f 72 69 7a 65 72 2e 0a 2a 2a 0a 2a  authorizer..**.*
18590 2a 20 7b 48 31 32 35 32 31 7d 20 41 20 4e 55 4c  * {H12521} A NUL
185a0 4c 20 61 75 74 68 6f 72 69 7a 65 72 20 6d 65 61  L authorizer mea
185b0 6e 73 20 74 68 61 74 20 6e 6f 20 61 75 74 68 6f  ns that no autho
185c0 72 69 7a 61 74 69 6f 6e 0a 2a 2a 20 20 20 20 20  rization.**     
185d0 20 20 20 20 20 63 61 6c 6c 62 61 63 6b 20 69 73       callback is
185e0 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20   invoked..**.** 
185f0 7b 48 31 32 35 32 32 7d 20 54 68 65 20 64 65 66  {H12522} The def
18600 61 75 6c 74 20 61 75 74 68 6f 72 69 7a 65 72 20  ault authorizer 
18610 69 73 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20  is NULL..*/.int 
18620 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
18630 6f 72 69 7a 65 72 28 0a 20 20 73 71 6c 69 74 65  orizer(.  sqlite
18640 33 2a 2c 0a 20 20 69 6e 74 20 28 2a 78 41 75 74  3*,.  int (*xAut
18650 68 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e  h)(void*,int,con
18660 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63  st char*,const c
18670 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  har*,const char*
18680 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 0a 20  ,const char*),. 
18690 20 76 6f 69 64 20 2a 70 55 73 65 72 44 61 74 61   void *pUserData
186a0 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
186b0 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20  REF: Authorizer 
186c0 52 65 74 75 72 6e 20 43 6f 64 65 73 20 7b 48 31  Return Codes {H1
186d0 32 35 39 30 7d 20 3c 48 31 32 35 30 30 3e 0a 2a  2590} <H12500>.*
186e0 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65  *.** The [sqlite
186f0 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
18700 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61   | authorizer ca
18710 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 5d  llback function]
18720 20 6d 75 73 74 0a 2a 2a 20 72 65 74 75 72 6e 20   must.** return 
18730 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 4f  either [SQLITE_O
18740 4b 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65  K] or one of the
18750 73 65 20 74 77 6f 20 63 6f 6e 73 74 61 6e 74 73  se two constants
18760 20 69 6e 20 6f 72 64 65 72 0a 2a 2a 20 74 6f 20   in order.** to 
18770 73 69 67 6e 61 6c 20 53 51 4c 69 74 65 20 77 68  signal SQLite wh
18780 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65  ether or not the
18790 20 61 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69   action is permi
187a0 74 74 65 64 2e 20 20 53 65 65 20 74 68 65 0a 2a  tted.  See the.*
187b0 2a 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  * [sqlite3_set_a
187c0 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68  uthorizer | auth
187d0 6f 72 69 7a 65 72 20 64 6f 63 75 6d 65 6e 74 61  orizer documenta
187e0 74 69 6f 6e 5d 20 66 6f 72 20 61 64 64 69 74 69  tion] for additi
187f0 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74  onal.** informat
18800 69 6f 6e 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ion..*/.#define 
18810 53 51 4c 49 54 45 5f 44 45 4e 59 20 20 20 31 20  SQLITE_DENY   1 
18820 20 20 2f 2a 20 41 62 6f 72 74 20 74 68 65 20 53    /* Abort the S
18830 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74  QL statement wit
18840 68 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 23 64  h an error */.#d
18850 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 47 4e  efine SQLITE_IGN
18860 4f 52 45 20 32 20 20 20 2f 2a 20 44 6f 6e 27 74  ORE 2   /* Don't
18870 20 61 6c 6c 6f 77 20 61 63 63 65 73 73 2c 20 62   allow access, b
18880 75 74 20 64 6f 6e 27 74 20 67 65 6e 65 72 61 74  ut don't generat
18890 65 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 0a 2f  e an error */../
188a0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41  *.** CAPI3REF: A
188b0 75 74 68 6f 72 69 7a 65 72 20 41 63 74 69 6f 6e  uthorizer Action
188c0 20 43 6f 64 65 73 20 7b 48 31 32 35 35 30 7d 20   Codes {H12550} 
188d0 3c 48 31 32 35 30 30 3e 0a 2a 2a 0a 2a 2a 20 54  <H12500>.**.** T
188e0 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f  he [sqlite3_set_
188f0 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 20 69 6e  authorizer()] in
18900 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65 72  terface register
18910 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  s a callback fun
18920 63 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 69 73  ction.** that is
18930 20 69 6e 76 6f 6b 65 64 20 74 6f 20 61 75 74 68   invoked to auth
18940 6f 72 69 7a 65 20 63 65 72 74 61 69 6e 20 53 51  orize certain SQ
18950 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 63 74 69  L statement acti
18960 6f 6e 73 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63  ons.  The.** sec
18970 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ond parameter to
18980 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73   the callback is
18990 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 64 65   an integer code
189a0 20 74 68 61 74 20 73 70 65 63 69 66 69 65 73 0a   that specifies.
189b0 2a 2a 20 77 68 61 74 20 61 63 74 69 6f 6e 20 69  ** what action i
189c0 73 20 62 65 69 6e 67 20 61 75 74 68 6f 72 69 7a  s being authoriz
189d0 65 64 2e 20 20 54 68 65 73 65 20 61 72 65 20 74  ed.  These are t
189e0 68 65 20 69 6e 74 65 67 65 72 20 61 63 74 69 6f  he integer actio
189f0 6e 20 63 6f 64 65 73 20 74 68 61 74 0a 2a 2a 20  n codes that.** 
18a00 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
18a10 61 6c 6c 62 61 63 6b 20 6d 61 79 20 62 65 20 70  allback may be p
18a20 61 73 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  assed..**.** The
18a30 73 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 76  se action code v
18a40 61 6c 75 65 73 20 73 69 67 6e 69 66 79 20 77 68  alues signify wh
18a50 61 74 20 6b 69 6e 64 20 6f 66 20 6f 70 65 72 61  at kind of opera
18a60 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 0a 2a 2a  tion is to be.**
18a70 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 68   authorized.  Th
18a80 65 20 33 72 64 20 61 6e 64 20 34 74 68 20 70 61  e 3rd and 4th pa
18a90 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68 65 20  rameters to the 
18aa0 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e 0a 2a 2a  authorization.**
18ab0 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
18ac0 6f 6e 20 77 69 6c 6c 20 62 65 20 70 61 72 61 6d  on will be param
18ad0 65 74 65 72 73 20 6f 72 20 4e 55 4c 4c 20 64 65  eters or NULL de
18ae0 70 65 6e 64 69 6e 67 20 6f 6e 20 77 68 69 63 68  pending on which
18af0 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 63 6f 64   of these.** cod
18b00 65 73 20 69 73 20 75 73 65 64 20 61 73 20 74 68  es is used as th
18b10 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
18b20 65 72 2e 20 20 54 68 65 20 35 74 68 20 70 61 72  er.  The 5th par
18b30 61 6d 65 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a  ameter to the.**
18b40 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
18b50 62 61 63 6b 20 69 73 20 74 68 65 20 6e 61 6d 65  back is the name
18b60 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
18b70 20 28 22 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22   ("main", "temp"
18b80 2c 0a 2a 2a 20 65 74 63 2e 29 20 69 66 20 61 70  ,.** etc.) if ap
18b90 70 6c 69 63 61 62 6c 65 2e 20 20 54 68 65 20 36  plicable.  The 6
18ba0 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
18bb0 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
18bc0 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 74 68  allback.** is th
18bd0 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 69 6e  e name of the in
18be0 6e 65 72 2d 6d 6f 73 74 20 74 72 69 67 67 65 72  ner-most trigger
18bf0 20 6f 72 20 76 69 65 77 20 74 68 61 74 20 69 73   or view that is
18c00 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72   responsible for
18c10 0a 2a 2a 20 74 68 65 20 61 63 63 65 73 73 20 61  .** the access a
18c20 74 74 65 6d 70 74 20 6f 72 20 4e 55 4c 4c 20 69  ttempt or NULL i
18c30 66 20 74 68 69 73 20 61 63 63 65 73 73 20 61 74  f this access at
18c40 74 65 6d 70 74 20 69 73 20 64 69 72 65 63 74 6c  tempt is directl
18c50 79 20 66 72 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c 65  y from.** top-le
18c60 76 65 6c 20 53 51 4c 20 63 6f 64 65 2e 0a 2a 2a  vel SQL code..**
18c70 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
18c80 2a 2a 0a 2a 2a 20 7b 48 31 32 35 35 31 7d 20 54  **.** {H12551} T
18c90 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
18ca0 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 20 20 20  ter to an.**    
18cb0 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 73        [sqlite3_s
18cc0 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20  et_authorizer | 
18cd0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
18ce0 61 63 6b 5d 20 73 68 61 6c 6c 20 62 65 20 61 6e  ack] shall be an
18cf0 20 69 6e 74 65 67 65 72 0a 2a 2a 20 20 20 20 20   integer.**     
18d00 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 43 4f 50       [SQLITE_COP
18d10 59 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 63  Y | authorizer c
18d20 6f 64 65 5d 20 74 68 61 74 20 73 70 65 63 69 66  ode] that specif
18d30 69 65 73 20 77 68 61 74 20 61 63 74 69 6f 6e 0a  ies what action.
18d40 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 62  **          is b
18d50 65 69 6e 67 20 61 75 74 68 6f 72 69 7a 65 64 2e  eing authorized.
18d60 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 35 32 7d 20  .**.** {H12552} 
18d70 54 68 65 20 33 72 64 20 61 6e 64 20 34 74 68 20  The 3rd and 4th 
18d80 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68  parameters to th
18d90 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  e.**          [s
18da0 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
18db0 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a  rizer | authoriz
18dc0 61 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 5d 0a  ation callback].
18dd0 2a 2a 20 20 20 20 20 20 20 20 20 20 73 68 61 6c  **          shal
18de0 6c 20 62 65 20 70 61 72 61 6d 65 74 65 72 73 20  l be parameters 
18df0 6f 72 20 4e 55 4c 4c 20 64 65 70 65 6e 64 69 6e  or NULL dependin
18e00 67 20 6f 6e 20 77 68 69 63 68 0a 2a 2a 20 20 20  g on which.**   
18e10 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 43         [SQLITE_C
18e20 4f 50 59 20 7c 20 61 75 74 68 6f 72 69 7a 65 72  OPY | authorizer
18e30 20 63 6f 64 65 5d 20 69 73 20 75 73 65 64 20 61   code] is used a
18e40 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72  s the second par
18e50 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48  ameter..**.** {H
18e60 31 32 35 35 33 7d 20 54 68 65 20 35 74 68 20 70  12553} The 5th p
18e70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 0a  arameter to the.
18e80 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
18e90 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
18ea0 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72  zer | authorizer
18eb0 20 63 61 6c 6c 62 61 63 6b 5d 20 73 68 61 6c 6c   callback] shall
18ec0 20 62 65 20 74 68 65 20 6e 61 6d 65 0a 2a 2a 20   be the name.** 
18ed0 20 20 20 20 20 20 20 20 20 6f 66 20 74 68 65 20           of the 
18ee0 64 61 74 61 62 61 73 65 20 28 65 78 61 6d 70 6c  database (exampl
18ef0 65 3a 20 22 6d 61 69 6e 22 2c 20 22 74 65 6d 70  e: "main", "temp
18f00 22 2c 20 65 74 63 2e 29 20 69 66 20 61 70 70 6c  ", etc.) if appl
18f10 69 63 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48  icable..**.** {H
18f20 31 32 35 35 34 7d 20 54 68 65 20 36 74 68 20 70  12554} The 6th p
18f30 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 0a  arameter to the.
18f40 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
18f50 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
18f60 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72  zer | authorizer
18f70 20 63 61 6c 6c 62 61 63 6b 5d 20 73 68 61 6c 6c   callback] shall
18f80 20 62 65 20 74 68 65 20 6e 61 6d 65 0a 2a 2a 20   be the name.** 
18f90 20 20 20 20 20 20 20 20 20 6f 66 20 74 68 65 20           of the 
18fa0 69 6e 6e 65 72 2d 6d 6f 73 74 20 74 72 69 67 67  inner-most trigg
18fb0 65 72 20 6f 72 20 76 69 65 77 20 74 68 61 74 20  er or view that 
18fc0 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66  is responsible f
18fd0 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  or.**          t
18fe0 68 65 20 61 63 63 65 73 73 20 61 74 74 65 6d 70  he access attemp
18ff0 74 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 69  t or NULL if thi
19000 73 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 74  s access attempt
19010 20 69 73 20 64 69 72 65 63 74 6c 79 20 66 72 6f   is directly fro
19020 6d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f  m.**          to
19030 70 2d 6c 65 76 65 6c 20 53 51 4c 20 63 6f 64 65  p-level SQL code
19040 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ..*/./**********
19050 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
19060 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
19070 2a 20 33 72 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  * 3rd **********
19080 2a 2a 20 34 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a  ** 4th *********
19090 2a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  **/.#define SQLI
190a0 54 45 5f 43 52 45 41 54 45 5f 49 4e 44 45 58 20  TE_CREATE_INDEX 
190b0 20 20 20 20 20 20 20 20 20 31 20 20 20 2f 2a 20           1   /* 
190c0 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20  Index Name      
190d0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
190e0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
190f0 45 5f 43 52 45 41 54 45 5f 54 41 42 4c 45 20 20  E_CREATE_TABLE  
19100 20 20 20 20 20 20 20 20 32 20 20 20 2f 2a 20 54          2   /* T
19110 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
19120 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
19130 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
19140 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 49 4e 44  _CREATE_TEMP_IND
19150 45 58 20 20 20 20 20 33 20 20 20 2f 2a 20 49 6e  EX     3   /* In
19160 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61  dex Name      Ta
19170 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
19180 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
19190 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 41 42 4c  CREATE_TEMP_TABL
191a0 45 20 20 20 20 20 34 20 20 20 2f 2a 20 54 61 62  E     4   /* Tab
191b0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
191c0 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
191d0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
191e0 52 45 41 54 45 5f 54 45 4d 50 5f 54 52 49 47 47  REATE_TEMP_TRIGG
191f0 45 52 20 20 20 35 20 20 20 2f 2a 20 54 72 69 67  ER   5   /* Trig
19200 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c  ger Name    Tabl
19210 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
19220 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
19230 45 41 54 45 5f 54 45 4d 50 5f 56 49 45 57 20 20  EATE_TEMP_VIEW  
19240 20 20 20 20 36 20 20 20 2f 2a 20 56 69 65 77 20      6   /* View 
19250 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20  Name       NULL 
19260 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
19270 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
19280 41 54 45 5f 54 52 49 47 47 45 52 20 20 20 20 20  ATE_TRIGGER     
19290 20 20 20 37 20 20 20 2f 2a 20 54 72 69 67 67 65     7   /* Trigge
192a0 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20  r Name    Table 
192b0 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
192c0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
192d0 54 45 5f 56 49 45 57 20 20 20 20 20 20 20 20 20  TE_VIEW         
192e0 20 20 38 20 20 20 2f 2a 20 56 69 65 77 20 4e 61    8   /* View Na
192f0 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  me       NULL   
19300 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
19310 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4c 45 54  ine SQLITE_DELET
19320 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  E               
19330 20 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61   9   /* Table Na
19340 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
19350 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
19360 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 49  ne SQLITE_DROP_I
19370 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 20 31  NDEX           1
19380 30 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d  0   /* Index Nam
19390 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  e      Table Nam
193a0 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
193b0 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 41  e SQLITE_DROP_TA
193c0 42 4c 45 20 20 20 20 20 20 20 20 20 20 20 31 31  BLE           11
193d0 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
193e0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
193f0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
19400 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d   SQLITE_DROP_TEM
19410 50 5f 49 4e 44 45 58 20 20 20 20 20 20 31 32 20  P_INDEX      12 
19420 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20    /* Index Name 
19430 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20       Table Name 
19440 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
19450 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50  SQLITE_DROP_TEMP
19460 5f 54 41 42 4c 45 20 20 20 20 20 20 31 33 20 20  _TABLE      13  
19470 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
19480 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
19490 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
194a0 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f  QLITE_DROP_TEMP_
194b0 54 52 49 47 47 45 52 20 20 20 20 31 34 20 20 20  TRIGGER    14   
194c0 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20  /* Trigger Name 
194d0 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
194e0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
194f0 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 56  LITE_DROP_TEMP_V
19500 49 45 57 20 20 20 20 20 20 20 31 35 20 20 20 2f  IEW       15   /
19510 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20  * View Name     
19520 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
19530 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
19540 49 54 45 5f 44 52 4f 50 5f 54 52 49 47 47 45 52  ITE_DROP_TRIGGER
19550 20 20 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a           16   /*
19560 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20   Trigger Name   
19570 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
19580 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
19590 54 45 5f 44 52 4f 50 5f 56 49 45 57 20 20 20 20  TE_DROP_VIEW    
195a0 20 20 20 20 20 20 20 20 31 37 20 20 20 2f 2a 20          17   /* 
195b0 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20  View Name       
195c0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
195d0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
195e0 45 5f 49 4e 53 45 52 54 20 20 20 20 20 20 20 20  E_INSERT        
195f0 20 20 20 20 20 20 20 31 38 20 20 20 2f 2a 20 54         18   /* T
19600 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
19610 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
19620 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
19630 5f 50 52 41 47 4d 41 20 20 20 20 20 20 20 20 20  _PRAGMA         
19640 20 20 20 20 20 20 31 39 20 20 20 2f 2a 20 50 72        19   /* Pr
19650 61 67 6d 61 20 4e 61 6d 65 20 20 20 20 20 31 73  agma Name     1s
19660 74 20 61 72 67 20 6f 72 20 4e 55 4c 4c 20 2a 2f  t arg or NULL */
19670 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
19680 52 45 41 44 20 20 20 20 20 20 20 20 20 20 20 20  READ            
19690 20 20 20 20 20 32 30 20 20 20 2f 2a 20 54 61 62       20   /* Tab
196a0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c  le Name      Col
196b0 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a  umn Name     */.
196c0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
196d0 45 4c 45 43 54 20 20 20 20 20 20 20 20 20 20 20  ELECT           
196e0 20 20 20 20 32 31 20 20 20 2f 2a 20 4e 55 4c 4c      21   /* NULL
196f0 20 20 20 20 20 20 20 20 20 20 20 20 4e 55 4c 4c              NULL
19700 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
19710 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52  define SQLITE_TR
19720 41 4e 53 41 43 54 49 4f 4e 20 20 20 20 20 20 20  ANSACTION       
19730 20 20 20 32 32 20 20 20 2f 2a 20 4e 55 4c 4c 20     22   /* NULL 
19740 20 20 20 20 20 20 20 20 20 20 20 4e 55 4c 4c 20             NULL 
19750 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
19760 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 50 44  efine SQLITE_UPD
19770 41 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20  ATE             
19780 20 20 32 33 20 20 20 2f 2a 20 54 61 62 6c 65 20    23   /* Table 
19790 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e  Name      Column
197a0 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65   Name     */.#de
197b0 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 54 54 41  fine SQLITE_ATTA
197c0 43 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20  CH              
197d0 20 32 34 20 20 20 2f 2a 20 46 69 6c 65 6e 61 6d   24   /* Filenam
197e0 65 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  e        NULL   
197f0 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
19800 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 54 41 43  ine SQLITE_DETAC
19810 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  H               
19820 32 35 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65  25   /* Database
19830 20 4e 61 6d 65 20 20 20 4e 55 4c 4c 20 20 20 20   Name   NULL    
19840 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
19850 6e 65 20 53 51 4c 49 54 45 5f 41 4c 54 45 52 5f  ne SQLITE_ALTER_
19860 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 32  TABLE          2
19870 36 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20  6   /* Database 
19880 4e 61 6d 65 20 20 20 54 61 62 6c 65 20 4e 61 6d  Name   Table Nam
19890 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
198a0 65 20 53 51 4c 49 54 45 5f 52 45 49 4e 44 45 58  e SQLITE_REINDEX
198b0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 37                27
198c0 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65     /* Index Name
198d0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
198e0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
198f0 20 53 51 4c 49 54 45 5f 41 4e 41 4c 59 5a 45 20   SQLITE_ANALYZE 
19900 20 20 20 20 20 20 20 20 20 20 20 20 20 32 38 20               28 
19910 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
19920 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
19930 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
19940 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 54  SQLITE_CREATE_VT
19950 41 42 4c 45 20 20 20 20 20 20 20 20 32 39 20 20  ABLE        29  
19960 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
19970 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20      Module Name 
19980 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
19990 51 4c 49 54 45 5f 44 52 4f 50 5f 56 54 41 42 4c  QLITE_DROP_VTABL
199a0 45 20 20 20 20 20 20 20 20 20 20 33 30 20 20 20  E          30   
199b0 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
199c0 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20     Module Name  
199d0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
199e0 4c 49 54 45 5f 46 55 4e 43 54 49 4f 4e 20 20 20  LITE_FUNCTION   
199f0 20 20 20 20 20 20 20 20 20 20 33 31 20 20 20 2f            31   /
19a00 2a 20 46 75 6e 63 74 69 6f 6e 20 4e 61 6d 65 20  * Function Name 
19a10 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
19a20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
19a30 49 54 45 5f 43 4f 50 59 20 20 20 20 20 20 20 20  ITE_COPY        
19a40 20 20 20 20 20 20 20 20 20 20 30 20 20 20 2f 2a            0   /*
19a50 20 4e 6f 20 6c 6f 6e 67 65 72 20 75 73 65 64 20   No longer used 
19a60 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  */../*.** CAPI3R
19a70 45 46 3a 20 54 72 61 63 69 6e 67 20 41 6e 64 20  EF: Tracing And 
19a80 50 72 6f 66 69 6c 69 6e 67 20 46 75 6e 63 74 69  Profiling Functi
19a90 6f 6e 73 20 7b 48 31 32 32 38 30 7d 20 3c 53 36  ons {H12280} <S6
19aa0 30 34 30 30 3e 0a 2a 2a 20 45 58 50 45 52 49 4d  0400>.** EXPERIM
19ab0 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ENTAL.**.** Thes
19ac0 65 20 72 6f 75 74 69 6e 65 73 20 72 65 67 69 73  e routines regis
19ad0 74 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  ter callback fun
19ae0 63 74 69 6f 6e 73 20 74 68 61 74 20 63 61 6e 20  ctions that can 
19af0 62 65 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74  be used for.** t
19b00 72 61 63 69 6e 67 20 61 6e 64 20 70 72 6f 66 69  racing and profi
19b10 6c 69 6e 67 20 74 68 65 20 65 78 65 63 75 74 69  ling the executi
19b20 6f 6e 20 6f 66 20 53 51 4c 20 73 74 61 74 65 6d  on of SQL statem
19b30 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ents..**.** The 
19b40 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
19b50 6e 20 72 65 67 69 73 74 65 72 65 64 20 62 79 20  n registered by 
19b60 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20  sqlite3_trace() 
19b70 69 73 20 69 6e 76 6f 6b 65 64 20 61 74 0a 2a 2a  is invoked at.**
19b80 20 76 61 72 69 6f 75 73 20 74 69 6d 65 73 20 77   various times w
19b90 68 65 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65  hen an SQL state
19ba0 6d 65 6e 74 20 69 73 20 62 65 69 6e 67 20 72 75  ment is being ru
19bb0 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 74  n by [sqlite3_st
19bc0 65 70 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 63 61  ep()]..** The ca
19bd0 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 61  llback returns a
19be0 20 55 54 46 2d 38 20 72 65 6e 64 65 72 69 6e 67   UTF-8 rendering
19bf0 20 6f 66 20 74 68 65 20 53 51 4c 20 73 74 61 74   of the SQL stat
19c00 65 6d 65 6e 74 20 74 65 78 74 0a 2a 2a 20 61 73  ement text.** as
19c10 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 66   the statement f
19c20 69 72 73 74 20 62 65 67 69 6e 73 20 65 78 65 63  irst begins exec
19c30 75 74 69 6e 67 2e 20 20 41 64 64 69 74 69 6f 6e  uting.  Addition
19c40 61 6c 20 63 61 6c 6c 62 61 63 6b 73 20 6f 63 63  al callbacks occ
19c50 75 72 0a 2a 2a 20 61 73 20 65 61 63 68 20 74 72  ur.** as each tr
19c60 69 67 67 65 72 65 64 20 73 75 62 70 72 6f 67 72  iggered subprogr
19c70 61 6d 20 69 73 20 65 6e 74 65 72 65 64 2e 20 20  am is entered.  
19c80 54 68 65 20 63 61 6c 6c 62 61 63 6b 73 20 66 6f  The callbacks fo
19c90 72 20 74 72 69 67 67 65 72 73 0a 2a 2a 20 63 6f  r triggers.** co
19ca0 6e 74 61 69 6e 20 61 20 55 54 46 2d 38 20 53 51  ntain a UTF-8 SQ
19cb0 4c 20 63 6f 6d 6d 65 6e 74 20 74 68 61 74 20 69  L comment that i
19cc0 64 65 6e 74 69 66 69 65 73 20 74 68 65 20 74 72  dentifies the tr
19cd0 69 67 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  igger..**.** The
19ce0 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
19cf0 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 62 79  on registered by
19d00 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65   sqlite3_profile
19d10 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a  () is invoked.**
19d20 20 61 73 20 65 61 63 68 20 53 51 4c 20 73 74 61   as each SQL sta
19d30 74 65 6d 65 6e 74 20 66 69 6e 69 73 68 65 73 2e  tement finishes.
19d40 20 20 54 68 65 20 70 72 6f 66 69 6c 65 20 63 61    The profile ca
19d50 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e 73 0a  llback contains.
19d60 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20  ** the original 
19d70 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 61  statement text a
19d80 6e 64 20 61 6e 20 65 73 74 69 6d 61 74 65 20 6f  nd an estimate o
19d90 66 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d  f wall-clock tim
19da0 65 0a 2a 2a 20 6f 66 20 68 6f 77 20 6c 6f 6e 67  e.** of how long
19db0 20 74 68 61 74 20 73 74 61 74 65 6d 65 6e 74 20   that statement 
19dc0 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e 0a 2a 2a 0a  took to run..**.
19dd0 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
19de0 2a 0a 2a 2a 20 7b 48 31 32 32 38 31 7d 20 54 68  *.** {H12281} Th
19df0 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  e callback funct
19e00 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 62  ion registered b
19e10 79 20 5b 73 71 6c 69 74 65 33 5f 74 72 61 63 65  y [sqlite3_trace
19e20 28 29 5d 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  ()] .**         
19e30 20 73 68 61 6c 6c 20 62 65 20 69 6e 76 6f 6b 65   shall be invoke
19e40 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 68  d.**          wh
19e50 65 6e 65 76 65 72 20 61 6e 20 53 51 4c 20 73 74  enever an SQL st
19e60 61 74 65 6d 65 6e 74 20 66 69 72 73 74 20 62 65  atement first be
19e70 67 69 6e 73 20 74 6f 20 65 78 65 63 75 74 65 20  gins to execute 
19e80 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  and.**          
19e90 77 68 65 6e 65 76 65 72 20 61 20 74 72 69 67 67  whenever a trigg
19ea0 65 72 20 73 75 62 70 72 6f 67 72 61 6d 20 66 69  er subprogram fi
19eb0 72 73 74 20 62 65 67 69 6e 73 20 74 6f 20 72 75  rst begins to ru
19ec0 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 38 32  n..**.** {H12282
19ed0 7d 20 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 5b  } Each call to [
19ee0 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 5d  sqlite3_trace()]
19ef0 20 73 68 61 6c 6c 20 6f 76 65 72 72 69 64 65 20   shall override 
19f00 74 68 65 20 70 72 65 76 69 6f 75 73 6c 79 0a 2a  the previously.*
19f10 2a 20 20 20 20 20 20 20 20 20 20 72 65 67 69 73  *          regis
19f20 74 65 72 65 64 20 74 72 61 63 65 20 63 61 6c 6c  tered trace call
19f30 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  back..**.** {H12
19f40 32 38 33 7d 20 41 20 4e 55 4c 4c 20 74 72 61 63  283} A NULL trac
19f50 65 20 63 61 6c 6c 62 61 63 6b 20 73 68 61 6c 6c  e callback shall
19f60 20 64 69 73 61 62 6c 65 20 74 72 61 63 69 6e 67   disable tracing
19f70 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 38 34 7d  ..**.** {H12284}
19f80 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
19f90 65 6e 74 20 74 6f 20 74 68 65 20 74 72 61 63 65  ent to the trace
19fa0 20 63 61 6c 6c 62 61 63 6b 20 73 68 61 6c 6c 20   callback shall 
19fb0 62 65 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20  be a copy of.** 
19fc0 20 20 20 20 20 20 20 20 20 74 68 65 20 70 6f 69           the poi
19fd0 6e 74 65 72 20 77 68 69 63 68 20 77 61 73 20 74  nter which was t
19fe0 68 65 20 33 72 64 20 61 72 67 75 6d 65 6e 74 20  he 3rd argument 
19ff0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 74 72 61 63  to [sqlite3_trac
1a000 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  e()]..**.** {H12
1a010 32 38 35 7d 20 54 68 65 20 73 65 63 6f 6e 64 20  285} The second 
1a020 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
1a030 74 72 61 63 65 20 63 61 6c 6c 62 61 63 6b 20 69  trace callback i
1a040 73 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  s a.**          
1a050 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
1a060 55 54 46 2d 38 20 73 74 72 69 6e 67 20 63 6f 6e  UTF-8 string con
1a070 74 61 69 6e 69 6e 67 20 74 68 65 20 6f 72 69 67  taining the orig
1a080 69 6e 61 6c 20 74 65 78 74 0a 2a 2a 20 20 20 20  inal text.**    
1a090 20 20 20 20 20 20 6f 66 20 74 68 65 20 53 51 4c        of the SQL
1a0a0 20 73 74 61 74 65 6d 65 6e 74 20 61 73 20 69 74   statement as it
1a0b0 20 77 61 73 20 70 61 73 73 65 64 20 69 6e 74 6f   was passed into
1a0c0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1a0d0 65 5f 76 32 28 29 5d 0a 2a 2a 20 20 20 20 20 20  e_v2()].**      
1a0e0 20 20 20 20 6f 72 20 74 68 65 20 65 71 75 69 76      or the equiv
1a0f0 61 6c 65 6e 74 2c 20 6f 72 20 61 6e 20 53 51 4c  alent, or an SQL
1a100 20 63 6f 6d 6d 65 6e 74 20 69 6e 64 69 63 61 74   comment indicat
1a110 69 6e 67 20 74 68 65 20 62 65 67 69 6e 6e 69 6e  ing the beginnin
1a120 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66  g.**          of
1a130 20 61 20 74 72 69 67 67 65 72 20 73 75 62 70 72   a trigger subpr
1a140 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  ogram..**.** {H1
1a150 32 32 38 37 7d 20 54 68 65 20 63 61 6c 6c 62 61  2287} The callba
1a160 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69  ck function regi
1a170 73 74 65 72 65 64 20 62 79 20 5b 73 71 6c 69 74  stered by [sqlit
1a180 65 33 5f 70 72 6f 66 69 6c 65 28 29 5d 20 69 73  e3_profile()] is
1a190 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 20 20 20 20   invoked.**     
1a1a0 20 20 20 20 20 61 73 20 65 61 63 68 20 53 51 4c       as each SQL
1a1b0 20 73 74 61 74 65 6d 65 6e 74 20 66 69 6e 69 73   statement finis
1a1c0 68 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32  hes..**.** {H122
1a1d0 38 38 7d 20 54 68 65 20 66 69 72 73 74 20 70 61  88} The first pa
1a1e0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 70  rameter to the p
1a1f0 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20  rofile callback 
1a200 69 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20  is a copy of.** 
1a210 20 20 20 20 20 20 20 20 20 74 68 65 20 33 72 64           the 3rd
1a220 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73   parameter to [s
1a230 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29  qlite3_profile()
1a240 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 38 39  ]..**.** {H12289
1a250 7d 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72  } The second par
1a260 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 70 72  ameter to the pr
1a270 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20 69  ofile callback i
1a280 73 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  s a.**          
1a290 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
1a2a0 55 54 46 2d 38 20 73 74 72 69 6e 67 20 74 68 61  UTF-8 string tha
1a2b0 74 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 63  t contains the c
1a2c0 6f 6d 70 6c 65 74 65 20 74 65 78 74 20 6f 66 0a  omplete text of.
1a2d0 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
1a2e0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 73  SQL statement as
1a2f0 20 69 74 20 77 61 73 20 70 72 6f 63 65 73 73 65   it was processe
1a300 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 70 72  d by [sqlite3_pr
1a310 65 70 61 72 65 5f 76 32 28 29 5d 0a 2a 2a 20 20  epare_v2()].**  
1a320 20 20 20 20 20 20 20 20 6f 72 20 74 68 65 20 65          or the e
1a330 71 75 69 76 61 6c 65 6e 74 2e 0a 2a 2a 0a 2a 2a  quivalent..**.**
1a340 20 7b 48 31 32 32 39 30 7d 20 54 68 65 20 74 68   {H12290} The th
1a350 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ird parameter to
1a360 20 74 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c   the profile cal
1a370 6c 62 61 63 6b 20 69 73 20 61 6e 20 65 73 74 69  lback is an esti
1a380 6d 61 74 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  mate.**         
1a390 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   of the number o
1a3a0 66 20 6e 61 6e 6f 73 65 63 6f 6e 64 73 20 6f 66  f nanoseconds of
1a3b0 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d 65   wall-clock time
1a3c0 20 72 65 71 75 69 72 65 64 20 74 6f 0a 2a 2a 20   required to.** 
1a3d0 20 20 20 20 20 20 20 20 20 72 75 6e 20 74 68 65           run the
1a3e0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 66   SQL statement f
1a3f0 72 6f 6d 20 73 74 61 72 74 20 74 6f 20 66 69 6e  rom start to fin
1a400 69 73 68 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45  ish..*/.SQLITE_E
1a410 58 50 45 52 49 4d 45 4e 54 41 4c 20 76 6f 69 64  XPERIMENTAL void
1a420 20 2a 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28   *sqlite3_trace(
1a430 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 28 2a  sqlite3*, void(*
1a440 78 54 72 61 63 65 29 28 76 6f 69 64 2a 2c 63 6f  xTrace)(void*,co
1a450 6e 73 74 20 63 68 61 72 2a 29 2c 20 76 6f 69 64  nst char*), void
1a460 2a 29 3b 0a 53 51 4c 49 54 45 5f 45 58 50 45 52  *);.SQLITE_EXPER
1a470 49 4d 45 4e 54 41 4c 20 76 6f 69 64 20 2a 73 71  IMENTAL void *sq
1a480 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 73 71  lite3_profile(sq
1a490 6c 69 74 65 33 2a 2c 0a 20 20 20 76 6f 69 64 28  lite3*,.   void(
1a4a0 2a 78 50 72 6f 66 69 6c 65 29 28 76 6f 69 64 2a  *xProfile)(void*
1a4b0 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 73 71 6c  ,const char*,sql
1a4c0 69 74 65 33 5f 75 69 6e 74 36 34 29 2c 20 76 6f  ite3_uint64), vo
1a4d0 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  id*);../*.** CAP
1a4e0 49 33 52 45 46 3a 20 51 75 65 72 79 20 50 72 6f  I3REF: Query Pro
1a4f0 67 72 65 73 73 20 43 61 6c 6c 62 61 63 6b 73 20  gress Callbacks 
1a500 7b 48 31 32 39 31 30 7d 20 3c 53 36 30 34 30 30  {H12910} <S60400
1a510 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75  >.**.** This rou
1a520 74 69 6e 65 20 63 6f 6e 66 69 67 75 72 65 73 20  tine configures 
1a530 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  a callback funct
1a540 69 6f 6e 20 2d 20 74 68 65 0a 2a 2a 20 70 72 6f  ion - the.** pro
1a550 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 2d  gress callback -
1a560 20 74 68 61 74 20 69 73 20 69 6e 76 6f 6b 65 64   that is invoked
1a570 20 70 65 72 69 6f 64 69 63 61 6c 6c 79 20 64 75   periodically du
1a580 72 69 6e 67 20 6c 6f 6e 67 0a 2a 2a 20 72 75 6e  ring long.** run
1a590 6e 69 6e 67 20 63 61 6c 6c 73 20 74 6f 20 5b 73  ning calls to [s
1a5a0 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20  qlite3_exec()], 
1a5b0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
1a5c0 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
1a5d0 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 2e 20 20  _get_table()].  
1a5e0 41 6e 20 65 78 61 6d 70 6c 65 20 75 73 65 20 66  An example use f
1a5f0 6f 72 20 74 68 69 73 0a 2a 2a 20 69 6e 74 65 72  or this.** inter
1a600 66 61 63 65 20 69 73 20 74 6f 20 6b 65 65 70 20  face is to keep 
1a610 61 20 47 55 49 20 75 70 64 61 74 65 64 20 64 75  a GUI updated du
1a620 72 69 6e 67 20 61 20 6c 61 72 67 65 20 71 75 65  ring a large que
1a630 72 79 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  ry..**.** If the
1a640 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61   progress callba
1a650 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a  ck returns non-z
1a660 65 72 6f 2c 20 74 68 65 20 6f 70 65 72 61 74 69  ero, the operati
1a670 6f 6e 20 69 73 0a 2a 2a 20 69 6e 74 65 72 72 75  on is.** interru
1a680 70 74 65 64 2e 20 20 54 68 69 73 20 66 65 61 74  pted.  This feat
1a690 75 72 65 20 63 61 6e 20 62 65 20 75 73 65 64 20  ure can be used 
1a6a0 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 0a 2a  to implement a.*
1a6b0 2a 20 22 43 61 6e 63 65 6c 22 20 62 75 74 74 6f  * "Cancel" butto
1a6c0 6e 20 6f 6e 20 61 20 47 55 49 20 64 69 61 6c 6f  n on a GUI dialo
1a6d0 67 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56  g box..**.** INV
1a6e0 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
1a6f0 48 31 32 39 31 31 7d 20 54 68 65 20 63 61 6c 6c  H12911} The call
1a700 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65  back function re
1a710 67 69 73 74 65 72 65 64 20 62 79 20 73 71 6c 69  gistered by sqli
1a720 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e  te3_progress_han
1a730 64 6c 65 72 28 29 0a 2a 2a 20 20 20 20 20 20 20  dler().**       
1a740 20 20 20 69 73 20 69 6e 76 6f 6b 65 64 20 70 65     is invoked pe
1a750 72 69 6f 64 69 63 61 6c 6c 79 20 64 75 72 69 6e  riodically durin
1a760 67 20 6c 6f 6e 67 20 72 75 6e 6e 69 6e 67 20 63  g long running c
1a770 61 6c 6c 73 20 74 6f 0a 2a 2a 20 20 20 20 20 20  alls to.**      
1a780 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 73 74 65      [sqlite3_ste
1a790 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  p()]..**.** {H12
1a7a0 39 31 32 7d 20 54 68 65 20 70 72 6f 67 72 65 73  912} The progres
1a7b0 73 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  s callback is in
1a7c0 76 6f 6b 65 64 20 6f 6e 63 65 20 66 6f 72 20 65  voked once for e
1a7d0 76 65 72 79 20 4e 20 76 69 72 74 75 61 6c 0a 2a  very N virtual.*
1a7e0 2a 20 20 20 20 20 20 20 20 20 20 6d 61 63 68 69  *          machi
1a7f0 6e 65 20 6f 70 63 6f 64 65 73 2c 20 77 68 65 72  ne opcodes, wher
1a800 65 20 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e  e N is the secon
1a810 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a  d argument to.**
1a820 20 20 20 20 20 20 20 20 20 20 74 68 65 20 5b 73            the [s
1a830 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f  qlite3_progress_
1a840 68 61 6e 64 6c 65 72 28 29 5d 20 63 61 6c 6c 20  handler()] call 
1a850 74 68 61 74 20 72 65 67 69 73 74 65 72 65 64 0a  that registered.
1a860 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
1a870 63 61 6c 6c 62 61 63 6b 2e 20 20 49 66 20 4e 20  callback.  If N 
1a880 69 73 20 6c 65 73 73 20 74 68 61 6e 20 31 2c 20  is less than 1, 
1a890 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73  sqlite3_progress
1a8a0 5f 68 61 6e 64 6c 65 72 28 29 0a 2a 2a 20 20 20  _handler().**   
1a8b0 20 20 20 20 20 20 20 61 63 74 73 20 61 73 20 69         acts as i
1a8c0 66 20 61 20 4e 55 4c 4c 20 70 72 6f 67 72 65 73  f a NULL progres
1a8d0 73 20 68 61 6e 64 6c 65 72 20 68 61 64 20 62 65  s handler had be
1a8e0 65 6e 20 73 70 65 63 69 66 69 65 64 2e 0a 2a 2a  en specified..**
1a8f0 0a 2a 2a 20 7b 48 31 32 39 31 33 7d 20 54 68 65  .** {H12913} The
1a900 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61   progress callba
1a910 63 6b 20 69 74 73 65 6c 66 20 69 73 20 69 64 65  ck itself is ide
1a920 6e 74 69 66 69 65 64 20 62 79 20 74 68 65 20 74  ntified by the t
1a930 68 69 72 64 0a 2a 2a 20 20 20 20 20 20 20 20 20  hird.**         
1a940 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
1a950 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61  ite3_progress_ha
1a960 6e 64 6c 65 72 28 29 2e 0a 2a 2a 0a 2a 2a 20 7b  ndler()..**.** {
1a970 48 31 32 39 31 34 7d 20 54 68 65 20 66 6f 75 72  H12914} The four
1a980 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  th argument to s
1a990 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f  qlite3_progress_
1a9a0 68 61 6e 64 6c 65 72 28 29 20 69 73 20 61 0a 2a  handler() is a.*
1a9b0 2a 20 20 20 20 20 20 20 20 20 20 76 6f 69 64 20  *          void 
1a9c0 70 6f 69 6e 74 65 72 20 70 61 73 73 65 64 20 74  pointer passed t
1a9d0 6f 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 63  o the progress c
1a9e0 61 6c 6c 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20  allback.**      
1a9f0 20 20 20 20 66 75 6e 63 74 69 6f 6e 20 65 61 63      function eac
1aa00 68 20 74 69 6d 65 20 69 74 20 69 73 20 69 6e 76  h time it is inv
1aa10 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  oked..**.** {H12
1aa20 39 31 35 7d 20 49 66 20 61 20 63 61 6c 6c 20 74  915} If a call t
1aa30 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  o [sqlite3_step(
1aa40 29 5d 20 72 65 73 75 6c 74 73 20 69 6e 20 66 65  )] results in fe
1aa50 77 65 72 20 74 68 61 6e 20 4e 20 6f 70 63 6f 64  wer than N opcod
1aa60 65 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62  es.**          b
1aa70 65 69 6e 67 20 65 78 65 63 75 74 65 64 2c 20 74  eing executed, t
1aa80 68 65 6e 20 74 68 65 20 70 72 6f 67 72 65 73 73  hen the progress
1aa90 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 6e 65 76   callback is nev
1aaa0 65 72 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a  er invoked..**.*
1aab0 2a 20 7b 48 31 32 39 31 36 7d 20 45 76 65 72 79  * {H12916} Every
1aac0 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
1aad0 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c  3_progress_handl
1aae0 65 72 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20  er()].**        
1aaf0 20 20 6f 76 65 72 77 72 69 74 65 73 20 61 6e 79    overwrites any
1ab00 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 67 69   previously regi
1ab10 73 74 65 72 65 64 20 70 72 6f 67 72 65 73 73 20  stered progress 
1ab20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b  handler..**.** {
1ab30 48 31 32 39 31 37 7d 20 49 66 20 74 68 65 20 70  H12917} If the p
1ab40 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20  rogress handler 
1ab50 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c  callback is NULL
1ab60 20 74 68 65 6e 20 6e 6f 20 70 72 6f 67 72 65 73   then no progres
1ab70 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 68 61  s.**          ha
1ab80 6e 64 6c 65 72 20 69 73 20 69 6e 76 6f 6b 65 64  ndler is invoked
1ab90 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 31 38 7d  ..**.** {H12918}
1aba0 20 49 66 20 74 68 65 20 70 72 6f 67 72 65 73 73   If the progress
1abb0 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
1abc0 73 20 61 20 72 65 73 75 6c 74 20 6f 74 68 65 72  s a result other
1abd0 20 74 68 61 6e 20 30 2c 20 74 68 65 6e 0a 2a 2a   than 0, then.**
1abe0 20 20 20 20 20 20 20 20 20 20 74 68 65 20 62 65            the be
1abf0 68 61 76 69 6f 72 20 69 73 20 61 20 69 66 20 5b  havior is a if [
1ac00 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
1ac10 74 28 29 5d 20 68 61 64 20 62 65 65 6e 20 63 61  t()] had been ca
1ac20 6c 6c 65 64 2e 0a 2a 2a 20 20 20 20 20 20 20 20  lled..**        
1ac30 20 20 3c 53 33 30 35 30 30 3e 0a 2a 2f 0a 76 6f    <S30500>.*/.vo
1ac40 69 64 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72  id sqlite3_progr
1ac50 65 73 73 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69  ess_handler(sqli
1ac60 74 65 33 2a 2c 20 69 6e 74 2c 20 69 6e 74 28 2a  te3*, int, int(*
1ac70 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29  )(void*), void*)
1ac80 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1ac90 46 3a 20 4f 70 65 6e 69 6e 67 20 41 20 4e 65 77  F: Opening A New
1aca0 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63   Database Connec
1acb0 74 69 6f 6e 20 7b 48 31 32 37 30 30 7d 20 3c 53  tion {H12700} <S
1acc0 34 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  40200>.**.** The
1acd0 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 70 65 6e  se routines open
1ace0 20 61 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62   an SQLite datab
1acf0 61 73 65 20 66 69 6c 65 20 77 68 6f 73 65 20 6e  ase file whose n
1ad00 61 6d 65 20 69 73 20 67 69 76 65 6e 20 62 79 20  ame is given by 
1ad10 74 68 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20  the.** filename 
1ad20 61 72 67 75 6d 65 6e 74 2e 20 54 68 65 20 66 69  argument. The fi
1ad30 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 20  lename argument 
1ad40 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61  is interpreted a
1ad50 73 20 55 54 46 2d 38 20 66 6f 72 0a 2a 2a 20 73  s UTF-8 for.** s
1ad60 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e  qlite3_open() an
1ad70 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  d sqlite3_open_v
1ad80 32 28 29 20 61 6e 64 20 61 73 20 55 54 46 2d 31  2() and as UTF-1
1ad90 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20  6 in the native 
1ada0 62 79 74 65 0a 2a 2a 20 6f 72 64 65 72 20 66 6f  byte.** order fo
1adb0 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36  r sqlite3_open16
1adc0 28 29 2e 20 41 20 5b 64 61 74 61 62 61 73 65 20  (). A [database 
1add0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64  connection] hand
1ade0 6c 65 20 69 73 20 75 73 75 61 6c 6c 79 0a 2a 2a  le is usually.**
1adf0 20 72 65 74 75 72 6e 65 64 20 69 6e 20 2a 70 70   returned in *pp
1ae00 44 62 2c 20 65 76 65 6e 20 69 66 20 61 6e 20 65  Db, even if an e
1ae10 72 72 6f 72 20 6f 63 63 75 72 73 2e 20 20 54 68  rror occurs.  Th
1ae20 65 20 6f 6e 6c 79 20 65 78 63 65 70 74 69 6f 6e  e only exception
1ae30 20 69 73 20 74 68 61 74 0a 2a 2a 20 69 66 20 53   is that.** if S
1ae40 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20  QLite is unable 
1ae50 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f  to allocate memo
1ae60 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 5b  ry to hold the [
1ae70 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2c  sqlite3] object,
1ae80 0a 2a 2a 20 61 20 4e 55 4c 4c 20 77 69 6c 6c 20  .** a NULL will 
1ae90 62 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20  be written into 
1aea0 2a 70 70 44 62 20 69 6e 73 74 65 61 64 20 6f 66  *ppDb instead of
1aeb0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
1aec0 65 20 5b 73 71 6c 69 74 65 33 5d 0a 2a 2a 20 6f  e [sqlite3].** o
1aed0 62 6a 65 63 74 2e 20 49 66 20 74 68 65 20 64 61  bject. If the da
1aee0 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64  tabase is opened
1aef0 20 28 61 6e 64 2f 6f 72 20 63 72 65 61 74 65 64   (and/or created
1af00 29 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2c 20  ) successfully, 
1af10 74 68 65 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  then.** [SQLITE_
1af20 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e  OK] is returned.
1af30 20 20 4f 74 68 65 72 77 69 73 65 20 61 6e 20 5b    Otherwise an [
1af40 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72  error code] is r
1af50 65 74 75 72 6e 65 64 2e 20 20 54 68 65 0a 2a 2a  eturned.  The.**
1af60 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
1af70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
1af80 65 72 72 6d 73 67 31 36 28 29 5d 20 72 6f 75 74  errmsg16()] rout
1af90 69 6e 65 73 20 63 61 6e 20 62 65 20 75 73 65 64  ines can be used
1afa0 20 74 6f 20 6f 62 74 61 69 6e 0a 2a 2a 20 61 6e   to obtain.** an
1afb0 20 45 6e 67 6c 69 73 68 20 6c 61 6e 67 75 61 67   English languag
1afc0 65 20 64 65 73 63 72 69 70 74 69 6f 6e 20 6f 66  e description of
1afd0 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a 0a 2a   the error..**.*
1afe0 2a 20 54 68 65 20 64 65 66 61 75 6c 74 20 65 6e  * The default en
1aff0 63 6f 64 69 6e 67 20 66 6f 72 20 74 68 65 20 64  coding for the d
1b000 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 20  atabase will be 
1b010 55 54 46 2d 38 20 69 66 0a 2a 2a 20 73 71 6c 69  UTF-8 if.** sqli
1b020 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71  te3_open() or sq
1b030 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
1b040 69 73 20 63 61 6c 6c 65 64 20 61 6e 64 0a 2a 2a  is called and.**
1b050 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e   UTF-16 in the n
1b060 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
1b070 20 69 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   if sqlite3_open
1b080 31 36 28 29 20 69 73 20 75 73 65 64 2e 0a 2a 2a  16() is used..**
1b090 0a 2a 2a 20 57 68 65 74 68 65 72 20 6f 72 20 6e  .** Whether or n
1b0a0 6f 74 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75  ot an error occu
1b0b0 72 73 20 77 68 65 6e 20 69 74 20 69 73 20 6f 70  rs when it is op
1b0c0 65 6e 65 64 2c 20 72 65 73 6f 75 72 63 65 73 0a  ened, resources.
1b0d0 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ** associated wi
1b0e0 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  th the [database
1b0f0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e   connection] han
1b100 64 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 72 65  dle should be re
1b110 6c 65 61 73 65 64 20 62 79 0a 2a 2a 20 70 61 73  leased by.** pas
1b120 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69  sing it to [sqli
1b130 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20 77 68 65  te3_close()] whe
1b140 6e 20 69 74 20 69 73 20 6e 6f 20 6c 6f 6e 67 65  n it is no longe
1b150 72 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a  r required..**.*
1b160 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 70  * The sqlite3_op
1b170 65 6e 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63  en_v2() interfac
1b180 65 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c  e works like sql
1b190 69 74 65 33 5f 6f 70 65 6e 28 29 0a 2a 2a 20 65  ite3_open().** e
1b1a0 78 63 65 70 74 20 74 68 61 74 20 69 74 20 61 63  xcept that it ac
1b1b0 63 65 70 74 73 20 74 77 6f 20 61 64 64 69 74 69  cepts two additi
1b1c0 6f 6e 61 6c 20 70 61 72 61 6d 65 74 65 72 73 20  onal parameters 
1b1d0 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 63  for additional c
1b1e0 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f 76 65 72 20 74  ontrol.** over t
1b1f0 68 65 20 6e 65 77 20 64 61 74 61 62 61 73 65 20  he new database 
1b200 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 54 68 65  connection.  The
1b210 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72   flags parameter
1b220 20 63 61 6e 20 74 61 6b 65 20 6f 6e 65 20 6f 66   can take one of
1b230 0a 2a 2a 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e  .** the followin
1b240 67 20 74 68 72 65 65 20 76 61 6c 75 65 73 2c 20  g three values, 
1b250 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69  optionally combi
1b260 6e 65 64 20 77 69 74 68 20 74 68 65 20 0a 2a 2a  ned with the .**
1b270 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f   [SQLITE_OPEN_NO
1b280 4d 55 54 45 58 5d 20 66 6c 61 67 3a 0a 2a 2a 0a  MUTEX] flag:.**.
1b290 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 5b  ** <dl>.** <dt>[
1b2a0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
1b2b0 4f 4e 4c 59 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ONLY]</dt>.** <d
1b2c0 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 69  d>The database i
1b2d0 73 20 6f 70 65 6e 65 64 20 69 6e 20 72 65 61 64  s opened in read
1b2e0 2d 6f 6e 6c 79 20 6d 6f 64 65 2e 20 20 49 66 20  -only mode.  If 
1b2f0 74 68 65 20 64 61 74 61 62 61 73 65 20 64 6f 65  the database doe
1b300 73 20 6e 6f 74 0a 2a 2a 20 61 6c 72 65 61 64 79  s not.** already
1b310 20 65 78 69 73 74 2c 20 61 6e 20 65 72 72 6f 72   exist, an error
1b320 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64   is returned.</d
1b330 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 5b 53 51  d>.**.** <dt>[SQ
1b340 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52  LITE_OPEN_READWR
1b350 49 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  ITE]</dt>.** <dd
1b360 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73  >The database is
1b370 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64   opened for read
1b380 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67 20  ing and writing 
1b390 69 66 20 70 6f 73 73 69 62 6c 65 2c 20 6f 72 20  if possible, or 
1b3a0 72 65 61 64 69 6e 67 0a 2a 2a 20 6f 6e 6c 79 20  reading.** only 
1b3b0 69 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 77  if the file is w
1b3c0 72 69 74 65 20 70 72 6f 74 65 63 74 65 64 20 62  rite protected b
1b3d0 79 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20  y the operating 
1b3e0 73 79 73 74 65 6d 2e 20 20 49 6e 20 65 69 74 68  system.  In eith
1b3f0 65 72 0a 2a 2a 20 63 61 73 65 20 74 68 65 20 64  er.** case the d
1b400 61 74 61 62 61 73 65 20 6d 75 73 74 20 61 6c 72  atabase must alr
1b410 65 61 64 79 20 65 78 69 73 74 2c 20 6f 74 68 65  eady exist, othe
1b420 72 77 69 73 65 20 61 6e 20 65 72 72 6f 72 20 69  rwise an error i
1b430 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e  s returned.</dd>
1b440 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 5b 53 51 4c 49  .**.** <dt>[SQLI
1b450 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54  TE_OPEN_READWRIT
1b460 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45  E] | [SQLITE_OPE
1b470 4e 5f 43 52 45 41 54 45 5d 3c 2f 64 74 3e 0a 2a  N_CREATE]</dt>.*
1b480 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61  * <dd>The databa
1b490 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72  se is opened for
1b4a0 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69   reading and wri
1b4b0 74 69 6e 67 2c 20 61 6e 64 20 69 73 20 63 72 65  ting, and is cre
1b4c0 61 74 65 73 20 69 74 20 69 66 0a 2a 2a 20 69 74  ates it if.** it
1b4d0 20 64 6f 65 73 20 6e 6f 74 20 61 6c 72 65 61 64   does not alread
1b4e0 79 20 65 78 69 73 74 2e 20 54 68 69 73 20 69 73  y exist. This is
1b4f0 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 74 68   the behavior th
1b500 61 74 20 69 73 20 61 6c 77 61 79 73 20 75 73 65  at is always use
1b510 64 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  d for.** sqlite3
1b520 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69  _open() and sqli
1b530 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 3c 2f 64  te3_open16().</d
1b540 64 3e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a  d>.** </dl>.**.*
1b550 2a 20 49 66 20 74 68 65 20 33 72 64 20 70 61 72  * If the 3rd par
1b560 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
1b570 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 6e  3_open_v2() is n
1b580 6f 74 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a  ot one of the.**
1b590 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 73 68   combinations sh
1b5a0 6f 77 6e 20 61 62 6f 76 65 20 6f 72 20 6f 6e 65  own above or one
1b5b0 20 6f 66 20 74 68 65 20 63 6f 6d 62 69 6e 61 74   of the combinat
1b5c0 69 6f 6e 73 20 73 68 6f 77 6e 20 61 62 6f 76 65  ions shown above
1b5d0 20 63 6f 6d 62 69 6e 65 64 0a 2a 2a 20 77 69 74   combined.** wit
1b5e0 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50  h the [SQLITE_OP
1b5f0 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20 66 6c 61 67  EN_NOMUTEX] flag
1b600 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76  , then the behav
1b610 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ior is undefined
1b620 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 5b  ..**.** If the [
1b630 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55  SQLITE_OPEN_NOMU
1b640 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74  TEX] flag is set
1b650 2c 20 74 68 65 6e 20 6d 75 74 65 78 65 73 20 6f  , then mutexes o
1b660 6e 20 74 68 65 0a 2a 2a 20 6f 70 65 6e 65 64 20  n the.** opened 
1b670 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
1b680 74 69 6f 6e 5d 20 61 72 65 20 64 69 73 61 62 6c  tion] are disabl
1b690 65 64 20 61 6e 64 20 74 68 65 20 61 70 70 6c 69  ed and the appli
1b6a0 61 74 69 6f 6e 20 6d 75 73 74 0a 2a 2a 20 69 6e  ation must.** in
1b6b0 73 75 72 65 20 74 68 61 74 20 61 63 63 65 73 73  sure that access
1b6c0 20 74 6f 20 74 68 65 20 5b 64 61 74 61 62 61 73   to the [databas
1b6d0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e  e connection] an
1b6e0 64 20 69 74 73 20 61 73 73 6f 63 69 61 74 65 64  d its associated
1b6f0 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
1b700 61 74 65 6d 65 6e 74 73 5d 20 69 73 20 73 65 72  atements] is ser
1b710 69 61 6c 69 7a 65 64 2e 20 20 54 68 65 20 5b 53  ialized.  The [S
1b720 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54  QLITE_OPEN_NOMUT
1b730 45 58 5d 20 66 6c 61 67 0a 2a 2a 20 69 73 20 74  EX] flag.** is t
1b740 68 65 20 64 65 66 61 75 6c 74 20 62 65 68 61 76  he default behav
1b750 69 6f 72 20 69 73 20 53 51 4c 69 74 65 20 69 73  ior is SQLite is
1b760 20 63 6f 6e 66 69 67 75 72 65 64 20 75 73 69 6e   configured usin
1b770 67 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  g the.** [SQLITE
1b780 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
1b790 45 41 44 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  EAD] or [SQLITE_
1b7a0 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52  CONFIG_SINGLETHR
1b7b0 45 41 44 5d 20 6f 70 74 69 6f 6e 73 0a 2a 2a 20  EAD] options.** 
1b7c0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  to [sqlite3_conf
1b7d0 69 67 28 29 5d 2e 20 20 54 68 65 20 5b 53 51 4c  ig()].  The [SQL
1b7e0 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58  ITE_OPEN_NOMUTEX
1b7f0 5d 20 66 6c 61 67 20 6f 6e 6c 79 20 6d 61 6b 65  ] flag only make
1b800 73 20 61 0a 2a 2a 20 64 69 66 66 65 72 65 6e 63  s a.** differenc
1b810 65 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73  e when SQLite is
1b820 20 69 6e 20 69 74 73 20 64 65 66 61 75 6c 74 20   in its default 
1b830 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  [SQLITE_CONFIG_S
1b840 45 52 49 41 4c 49 5a 45 44 5d 20 6d 6f 64 65 2e  ERIALIZED] mode.
1b850 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 66 69  .**.** If the fi
1b860 6c 65 6e 61 6d 65 20 69 73 20 22 3a 6d 65 6d 6f  lename is ":memo
1b870 72 79 3a 22 2c 20 74 68 65 6e 20 61 20 70 72 69  ry:", then a pri
1b880 76 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 20  vate, temporary 
1b890 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61  in-memory databa
1b8a0 73 65 0a 2a 2a 20 69 73 20 63 72 65 61 74 65 64  se.** is created
1b8b0 20 66 6f 72 20 74 68 65 20 63 6f 6e 6e 65 63 74   for the connect
1b8c0 69 6f 6e 2e 20 20 54 68 69 73 20 69 6e 2d 6d 65  ion.  This in-me
1b8d0 6d 6f 72 79 20 64 61 74 61 62 61 73 65 20 77 69  mory database wi
1b8e0 6c 6c 20 76 61 6e 69 73 68 20 77 68 65 6e 0a 2a  ll vanish when.*
1b8f0 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  * the database c
1b900 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f  onnection is clo
1b910 73 65 64 2e 20 20 46 75 74 75 72 65 20 76 65 72  sed.  Future ver
1b920 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20  sions of SQLite 
1b930 6d 69 67 68 74 0a 2a 2a 20 6d 61 6b 65 20 75 73  might.** make us
1b940 65 20 6f 66 20 61 64 64 69 74 69 6f 6e 61 6c 20  e of additional 
1b950 73 70 65 63 69 61 6c 20 66 69 6c 65 6e 61 6d 65  special filename
1b960 73 20 74 68 61 74 20 62 65 67 69 6e 20 77 69 74  s that begin wit
1b970 68 20 74 68 65 20 22 3a 22 20 63 68 61 72 61 63  h the ":" charac
1b980 74 65 72 2e 0a 2a 2a 20 49 74 20 69 73 20 72 65  ter..** It is re
1b990 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 77  commended that w
1b9a0 68 65 6e 20 61 20 64 61 74 61 62 61 73 65 20 66  hen a database f
1b9b0 69 6c 65 6e 61 6d 65 20 61 63 74 75 61 6c 6c 79  ilename actually
1b9c0 20 64 6f 65 73 20 62 65 67 69 6e 20 77 69 74 68   does begin with
1b9d0 0a 2a 2a 20 61 20 22 3a 22 20 63 68 61 72 61 63  .** a ":" charac
1b9e0 74 65 72 20 79 6f 75 20 73 68 6f 75 6c 64 20 70  ter you should p
1b9f0 72 65 66 69 78 20 74 68 65 20 66 69 6c 65 6e 61  refix the filena
1ba00 6d 65 20 77 69 74 68 20 61 20 70 61 74 68 6e 61  me with a pathna
1ba10 6d 65 20 73 75 63 68 20 61 73 0a 2a 2a 20 22 2e  me such as.** ".
1ba20 2f 22 20 74 6f 20 61 76 6f 69 64 20 61 6d 62 69  /" to avoid ambi
1ba30 67 75 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  guity..**.** If 
1ba40 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20  the filename is 
1ba50 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c  an empty string,
1ba60 20 74 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c   then a private,
1ba70 20 74 65 6d 70 6f 72 61 72 79 0a 2a 2a 20 6f 6e   temporary.** on
1ba80 2d 64 69 73 6b 20 64 61 74 61 62 61 73 65 20 77  -disk database w
1ba90 69 6c 6c 20 62 65 20 63 72 65 61 74 65 64 2e 20  ill be created. 
1baa0 20 54 68 69 73 20 70 72 69 76 61 74 65 20 64 61   This private da
1bab0 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 0a 2a  tabase will be.*
1bac0 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  * automatically 
1bad0 64 65 6c 65 74 65 64 20 61 73 20 73 6f 6f 6e 20  deleted as soon 
1bae0 61 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  as the database 
1baf0 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c  connection is cl
1bb00 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  osed..**.** The 
1bb10 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
1bb20 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   to sqlite3_open
1bb30 5f 76 32 28 29 20 69 73 20 74 68 65 20 6e 61 6d  _v2() is the nam
1bb40 65 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  e of the.** [sql
1bb50 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74  ite3_vfs] object
1bb60 20 74 68 61 74 20 64 65 66 69 6e 65 73 20 74 68   that defines th
1bb70 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74  e operating syst
1bb80 65 6d 20 69 6e 74 65 72 66 61 63 65 20 74 68 61  em interface tha
1bb90 74 0a 2a 2a 20 74 68 65 20 6e 65 77 20 64 61 74  t.** the new dat
1bba0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1bbb0 20 73 68 6f 75 6c 64 20 75 73 65 2e 20 20 49 66   should use.  If
1bbc0 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   the fourth para
1bbd0 6d 65 74 65 72 20 69 73 0a 2a 2a 20 61 20 4e 55  meter is.** a NU
1bbe0 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20  LL pointer then 
1bbf0 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c  the default [sql
1bc00 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74  ite3_vfs] object
1bc10 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20   is used..**.** 
1bc20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f  <b>Note to Windo
1bc30 77 73 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54  ws users:</b>  T
1bc40 68 65 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64  he encoding used
1bc50 20 66 6f 72 20 74 68 65 20 66 69 6c 65 6e 61 6d   for the filenam
1bc60 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 6f 66  e argument.** of
1bc70 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20   sqlite3_open() 
1bc80 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  and sqlite3_open
1bc90 5f 76 32 28 29 20 6d 75 73 74 20 62 65 20 55 54  _v2() must be UT
1bca0 46 2d 38 2c 20 6e 6f 74 20 77 68 61 74 65 76 65  F-8, not whateve
1bcb0 72 0a 2a 2a 20 63 6f 64 65 70 61 67 65 20 69 73  r.** codepage is
1bcc0 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e   currently defin
1bcd0 65 64 2e 20 20 46 69 6c 65 6e 61 6d 65 73 20 63  ed.  Filenames c
1bce0 6f 6e 74 61 69 6e 69 6e 67 20 69 6e 74 65 72 6e  ontaining intern
1bcf0 61 74 69 6f 6e 61 6c 0a 2a 2a 20 63 68 61 72 61  ational.** chara
1bd00 63 74 65 72 73 20 6d 75 73 74 20 62 65 20 63 6f  cters must be co
1bd10 6e 76 65 72 74 65 64 20 74 6f 20 55 54 46 2d 38  nverted to UTF-8
1bd20 20 70 72 69 6f 72 20 74 6f 20 70 61 73 73 69 6e   prior to passin
1bd30 67 20 74 68 65 6d 20 69 6e 74 6f 0a 2a 2a 20 73  g them into.** s
1bd40 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72  qlite3_open() or
1bd50 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
1bd60 28 29 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  ()..**.** INVARI
1bd70 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  ANTS:.**.** {H12
1bd80 37 30 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  701} The [sqlite
1bd90 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69  3_open()], [sqli
1bda0 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 61  te3_open16()], a
1bdb0 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  nd.**          [
1bdc0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
1bdd0 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 63 72  )] interfaces cr
1bde0 65 61 74 65 20 61 20 6e 65 77 0a 2a 2a 20 20 20  eate a new.**   
1bdf0 20 20 20 20 20 20 20 5b 64 61 74 61 62 61 73 65         [database
1be00 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 73 73   connection] ass
1be10 6f 63 69 61 74 65 64 20 77 69 74 68 0a 2a 2a 20  ociated with.** 
1be20 20 20 20 20 20 20 20 20 20 74 68 65 20 64 61 74           the dat
1be30 61 62 61 73 65 20 66 69 6c 65 20 67 69 76 65 6e  abase file given
1be40 20 69 6e 20 74 68 65 69 72 20 66 69 72 73 74 20   in their first 
1be50 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a  parameter..**.**
1be60 20 7b 48 31 32 37 30 32 7d 20 54 68 65 20 66 69   {H12702} The fi
1be70 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 20  lename argument 
1be80 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61  is interpreted a
1be90 73 20 55 54 46 2d 38 0a 2a 2a 20 20 20 20 20 20  s UTF-8.**      
1bea0 20 20 20 20 66 6f 72 20 5b 73 71 6c 69 74 65 33      for [sqlite3
1beb0 5f 6f 70 65 6e 28 29 5d 20 61 6e 64 20 5b 73 71  _open()] and [sq
1bec0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
1bed0 20 61 6e 64 20 61 73 20 55 54 46 2d 31 36 0a 2a   and as UTF-16.*
1bee0 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20 74 68  *          in th
1bef0 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  e native byte or
1bf00 64 65 72 20 66 6f 72 20 5b 73 71 6c 69 74 65 33  der for [sqlite3
1bf10 5f 6f 70 65 6e 31 36 28 29 5d 2e 0a 2a 2a 0a 2a  _open16()]..**.*
1bf20 2a 20 7b 48 31 32 37 30 33 7d 20 41 20 73 75 63  * {H12703} A suc
1bf30 63 65 73 73 66 75 6c 20 69 6e 76 6f 63 61 74 69  cessful invocati
1bf40 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6f  on of [sqlite3_o
1bf50 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  pen()], [sqlite3
1bf60 5f 6f 70 65 6e 31 36 28 29 5d 2c 0a 2a 2a 20 20  _open16()],.**  
1bf70 20 20 20 20 20 20 20 20 6f 72 20 5b 73 71 6c 69          or [sqli
1bf80 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 77  te3_open_v2()] w
1bf90 72 69 74 65 73 20 61 20 70 6f 69 6e 74 65 72 20  rites a pointer 
1bfa0 74 6f 20 61 20 6e 65 77 0a 2a 2a 20 20 20 20 20  to a new.**     
1bfb0 20 20 20 20 20 5b 64 61 74 61 62 61 73 65 20 63       [database c
1bfc0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 6e 74 6f 20  onnection] into 
1bfd0 2a 70 70 44 62 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  *ppDb..**.** {H1
1bfe0 32 37 30 34 7d 20 54 68 65 20 5b 73 71 6c 69 74  2704} The [sqlit
1bff0 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c  e3_open()], [sql
1c000 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20  ite3_open16()], 
1c010 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  and.**          
1c020 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
1c030 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 72  ()] interfaces r
1c040 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b  eturn [SQLITE_OK
1c050 5d 20 75 70 6f 6e 20 73 75 63 63 65 73 73 2c 0a  ] upon success,.
1c060 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 61  **          or a
1c070 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65  n appropriate [e
1c080 72 72 6f 72 20 63 6f 64 65 5d 20 6f 6e 20 66 61  rror code] on fa
1c090 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  ilure..**.** {H1
1c0a0 32 37 30 36 7d 20 54 68 65 20 64 65 66 61 75 6c  2706} The defaul
1c0b0 74 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 20  t text encoding 
1c0c0 66 6f 72 20 61 20 6e 65 77 20 64 61 74 61 62 61  for a new databa
1c0d0 73 65 20 63 72 65 61 74 65 64 20 75 73 69 6e 67  se created using
1c0e0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
1c0f0 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 6f 72  lite3_open()] or
1c100 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
1c110 32 28 29 5d 20 77 69 6c 6c 20 62 65 20 55 54 46  2()] will be UTF
1c120 2d 38 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 30  -8..**.** {H1270
1c130 37 7d 20 54 68 65 20 64 65 66 61 75 6c 74 20 74  7} The default t
1c140 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 66 6f 72  ext encoding for
1c150 20 61 20 6e 65 77 20 64 61 74 61 62 61 73 65 20   a new database 
1c160 63 72 65 61 74 65 64 20 75 73 69 6e 67 0a 2a 2a  created using.**
1c170 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
1c180 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 77 69 6c  e3_open16()] wil
1c190 6c 20 62 65 20 55 54 46 2d 31 36 2e 0a 2a 2a 0a  l be UTF-16..**.
1c1a0 2a 2a 20 7b 48 31 32 37 30 39 7d 20 54 68 65 20  ** {H12709} The 
1c1b0 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 46 2c  [sqlite3_open(F,
1c1c0 44 29 5d 20 69 6e 74 65 72 66 61 63 65 20 69 73  D)] interface is
1c1d0 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 0a 2a   equivalent to.*
1c1e0 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
1c1f0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 46 2c 44 2c  te3_open_v2(F,D,
1c200 47 2c 30 29 5d 20 77 68 65 72 65 20 74 68 65 20  G,0)] where the 
1c210 47 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a  G parameter is.*
1c220 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49  *          [SQLI
1c230 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54  TE_OPEN_READWRIT
1c240 45 5d 7c 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  E]|[SQLITE_OPEN_
1c250 43 52 45 41 54 45 5d 2e 0a 2a 2a 0a 2a 2a 20 7b  CREATE]..**.** {
1c260 48 31 32 37 31 31 7d 20 49 66 20 74 68 65 20 47  H12711} If the G
1c270 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73   parameter to [s
1c280 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 46  qlite3_open_v2(F
1c290 2c 44 2c 47 2c 56 29 5d 20 63 6f 6e 74 61 69 6e  ,D,G,V)] contain
1c2a0 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  s the.**        
1c2b0 20 20 62 69 74 20 76 61 6c 75 65 20 5b 53 51 4c    bit value [SQL
1c2c0 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c  ITE_OPEN_READONL
1c2d0 59 5d 20 74 68 65 6e 20 74 68 65 20 64 61 74 61  Y] then the data
1c2e0 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 0a 2a  base is opened.*
1c2f0 2a 20 20 20 20 20 20 20 20 20 20 66 6f 72 20 72  *          for r
1c300 65 61 64 69 6e 67 20 6f 6e 6c 79 2e 0a 2a 2a 0a  eading only..**.
1c310 2a 2a 20 7b 48 31 32 37 31 32 7d 20 49 66 20 74  ** {H12712} If t
1c320 68 65 20 47 20 70 61 72 61 6d 65 74 65 72 20 74  he G parameter t
1c330 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  o [sqlite3_open_
1c340 76 32 28 46 2c 44 2c 47 2c 56 29 5d 20 63 6f 6e  v2(F,D,G,V)] con
1c350 74 61 69 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20  tains the.**    
1c360 20 20 20 20 20 20 62 69 74 20 76 61 6c 75 65 20        bit value 
1c370 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
1c380 44 57 52 49 54 45 5d 20 74 68 65 6e 20 74 68 65  DWRITE] then the
1c390 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65   database is ope
1c3a0 6e 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ned.**          
1c3b0 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74  reading and writ
1c3c0 69 6e 67 20 69 66 20 70 6f 73 73 69 62 6c 65 2c  ing if possible,
1c3d0 20 6f 72 20 66 6f 72 20 72 65 61 64 69 6e 67 20   or for reading 
1c3e0 6f 6e 6c 79 20 69 66 20 74 68 65 0a 2a 2a 20 20  only if the.**  
1c3f0 20 20 20 20 20 20 20 20 66 69 6c 65 20 69 73 20          file is 
1c400 77 72 69 74 65 20 70 72 6f 74 65 63 74 65 64 20  write protected 
1c410 62 79 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67  by the operating
1c420 20 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20 7b   system..**.** {
1c430 48 31 32 37 31 33 7d 20 49 66 20 74 68 65 20 47  H12713} If the G
1c440 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73   parameter to [s
1c450 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 46  qlite3_open_v2(F
1c460 2c 44 2c 47 2c 56 29 5d 20 6f 6d 69 74 73 20 74  ,D,G,V)] omits t
1c470 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62  he.**          b
1c480 69 74 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45  it value [SQLITE
1c490 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 20 61 6e  _OPEN_CREATE] an
1c4a0 64 20 74 68 65 20 64 61 74 61 62 61 73 65 20 64  d the database d
1c4b0 6f 65 73 20 6e 6f 74 0a 2a 2a 20 20 20 20 20 20  oes not.**      
1c4c0 20 20 20 20 70 72 65 76 69 6f 75 73 6c 79 20 65      previously e
1c4d0 78 69 73 74 2c 20 61 6e 20 65 72 72 6f 72 20 69  xist, an error i
1c4e0 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  s returned..**.*
1c4f0 2a 20 7b 48 31 32 37 31 34 7d 20 49 66 20 74 68  * {H12714} If th
1c500 65 20 47 20 70 61 72 61 6d 65 74 65 72 20 74 6f  e G parameter to
1c510 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
1c520 32 28 46 2c 44 2c 47 2c 56 29 5d 20 63 6f 6e 74  2(F,D,G,V)] cont
1c530 61 69 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20 20  ains the.**     
1c540 20 20 20 20 20 62 69 74 20 76 61 6c 75 65 20 5b       bit value [
1c550 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41  SQLITE_OPEN_CREA
1c560 54 45 5d 20 61 6e 64 20 74 68 65 20 64 61 74 61  TE] and the data
1c570 62 61 73 65 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a  base does not.**
1c580 20 20 20 20 20 20 20 20 20 20 70 72 65 76 69 6f            previo
1c590 75 73 6c 79 20 65 78 69 73 74 2c 20 74 68 65 6e  usly exist, then
1c5a0 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73 20 6d   an attempt is m
1c5b0 61 64 65 20 74 6f 20 63 72 65 61 74 65 20 61 6e  ade to create an
1c5c0 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e  d.**          in
1c5d0 69 74 69 61 6c 69 7a 65 20 74 68 65 20 64 61 74  itialize the dat
1c5e0 61 62 61 73 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  abase..**.** {H1
1c5f0 32 37 31 37 7d 20 49 66 20 74 68 65 20 66 69 6c  2717} If the fil
1c600 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 20 74  ename argument t
1c610 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  o [sqlite3_open(
1c620 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  )], [sqlite3_ope
1c630 6e 31 36 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 20  n16()],.**      
1c640 20 20 20 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f      or [sqlite3_
1c650 6f 70 65 6e 5f 76 32 28 29 5d 20 69 73 20 22 3a  open_v2()] is ":
1c660 6d 65 6d 6f 72 79 3a 22 2c 20 74 68 65 6e 20 61  memory:", then a
1c670 6e 20 70 72 69 76 61 74 65 2c 0a 2a 2a 20 20 20  n private,.**   
1c680 20 20 20 20 20 20 20 65 70 68 65 6d 65 72 61 6c         ephemeral
1c690 2c 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61  , in-memory data
1c6a0 62 61 73 65 20 69 73 20 63 72 65 61 74 65 64 20  base is created 
1c6b0 66 6f 72 20 74 68 65 20 63 6f 6e 6e 65 63 74 69  for the connecti
1c6c0 6f 6e 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  on..**          
1c6d0 3c 74 6f 64 6f 3e 49 73 20 53 51 4c 49 54 45 5f  <todo>Is SQLITE_
1c6e0 4f 50 45 4e 5f 43 52 45 41 54 45 7c 53 51 4c 49  OPEN_CREATE|SQLI
1c6f0 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54  TE_OPEN_READWRIT
1c700 45 20 72 65 71 75 69 72 65 64 0a 2a 2a 20 20 20  E required.**   
1c710 20 20 20 20 20 20 20 69 6e 20 73 71 6c 69 74 65         in sqlite
1c720 33 5f 6f 70 65 6e 5f 76 32 28 29 3f 3c 2f 74 6f  3_open_v2()?</to
1c730 64 6f 3e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 31  do>.**.** {H1271
1c740 39 7d 20 49 66 20 74 68 65 20 66 69 6c 65 6e 61  9} If the filena
1c750 6d 65 20 69 73 20 4e 55 4c 4c 20 6f 72 20 61 6e  me is NULL or an
1c760 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 74   empty string, t
1c770 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c 0a 2a  hen a private,.*
1c780 2a 20 20 20 20 20 20 20 20 20 20 65 70 68 65 6d  *          ephem
1c790 65 72 61 6c 20 6f 6e 2d 64 69 73 6b 20 64 61 74  eral on-disk dat
1c7a0 61 62 61 73 65 20 77 69 6c 6c 20 62 65 20 63 72  abase will be cr
1c7b0 65 61 74 65 64 2e 0a 2a 2a 20 20 20 20 20 20 20  eated..**       
1c7c0 20 20 20 3c 74 6f 64 6f 3e 49 73 20 53 51 4c 49     <todo>Is SQLI
1c7d0 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 7c 53  TE_OPEN_CREATE|S
1c7e0 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57  QLITE_OPEN_READW
1c7f0 52 49 54 45 20 72 65 71 75 69 72 65 64 0a 2a 2a  RITE required.**
1c800 20 20 20 20 20 20 20 20 20 20 69 6e 20 73 71 6c            in sql
1c810 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 3f 3c  ite3_open_v2()?<
1c820 2f 74 6f 64 6f 3e 0a 2a 2a 0a 2a 2a 20 7b 48 31  /todo>.**.** {H1
1c830 32 37 32 31 7d 20 54 68 65 20 5b 64 61 74 61 62  2721} The [datab
1c840 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
1c850 63 72 65 61 74 65 64 20 62 79 20 5b 73 71 6c 69  created by [sqli
1c860 74 65 33 5f 6f 70 65 6e 5f 76 32 28 46 2c 44 2c  te3_open_v2(F,D,
1c870 47 2c 56 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20  G,V)].**        
1c880 20 20 77 69 6c 6c 20 75 73 65 20 74 68 65 20 5b    will use the [
1c890 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a  sqlite3_vfs] obj
1c8a0 65 63 74 20 69 64 65 6e 74 69 66 69 65 64 20 62  ect identified b
1c8b0 79 20 74 68 65 20 56 20 70 61 72 61 6d 65 74 65  y the V paramete
1c8c0 72 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  r,.**          o
1c8d0 72 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73  r the default [s
1c8e0 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65  qlite3_vfs] obje
1c8f0 63 74 20 69 66 20 56 20 69 73 20 61 20 4e 55 4c  ct if V is a NUL
1c900 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a  L pointer..**.**
1c910 20 7b 48 31 32 37 32 33 7d 20 54 77 6f 20 5b 64   {H12723} Two [d
1c920 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1c930 6f 6e 73 5d 20 77 69 6c 6c 20 73 68 61 72 65 20  ons] will share 
1c940 61 20 63 6f 6d 6d 6f 6e 20 63 61 63 68 65 20 69  a common cache i
1c950 66 20 62 6f 74 68 20 77 65 72 65 0a 2a 2a 20 20  f both were.**  
1c960 20 20 20 20 20 20 20 20 6f 70 65 6e 65 64 20 77          opened w
1c970 69 74 68 20 74 68 65 20 73 61 6d 65 20 56 46 53  ith the same VFS
1c980 20 77 68 69 6c 65 20 5b 73 68 61 72 65 64 20 63   while [shared c
1c990 61 63 68 65 20 6d 6f 64 65 5d 20 77 61 73 20 65  ache mode] was e
1c9a0 6e 61 62 6c 65 64 20 61 6e 64 0a 2a 2a 20 20 20  nabled and.**   
1c9b0 20 20 20 20 20 20 20 69 66 20 62 6f 74 68 20 66         if both f
1c9c0 69 6c 65 6e 61 6d 65 73 20 63 6f 6d 70 61 72 65  ilenames compare
1c9d0 20 65 71 75 61 6c 20 75 73 69 6e 67 20 6d 65 6d   equal using mem
1c9e0 63 6d 70 28 29 20 61 66 74 65 72 20 68 61 76 69  cmp() after havi
1c9f0 6e 67 20 62 65 65 6e 0a 2a 2a 20 20 20 20 20 20  ng been.**      
1ca00 20 20 20 20 70 72 6f 63 65 73 73 65 64 20 62 79      processed by
1ca10 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66   the [sqlite3_vf
1ca20 73 20 7c 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d  s | xFullPathnam
1ca30 65 5d 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65  e] method of the
1ca40 20 56 46 53 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c   VFS..*/.int sql
1ca50 69 74 65 33 5f 6f 70 65 6e 28 0a 20 20 63 6f 6e  ite3_open(.  con
1ca60 73 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d  st char *filenam
1ca70 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65  e,   /* Database
1ca80 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38   filename (UTF-8
1ca90 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a  ) */.  sqlite3 *
1caa0 2a 70 70 44 62 20 20 20 20 20 20 20 20 20 20 2f  *ppDb          /
1cab0 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62  * OUT: SQLite db
1cac0 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e   handle */.);.in
1cad0 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36  t sqlite3_open16
1cae0 28 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  (.  const void *
1caf0 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44  filename,   /* D
1cb00 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65  atabase filename
1cb10 20 28 55 54 46 2d 31 36 29 20 2a 2f 0a 20 20 73   (UTF-16) */.  s
1cb20 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20  qlite3 **ppDb   
1cb30 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53         /* OUT: S
1cb40 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20  QLite db handle 
1cb50 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  */.);.int sqlite
1cb60 33 5f 6f 70 65 6e 5f 76 32 28 0a 20 20 63 6f 6e  3_open_v2(.  con
1cb70 73 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d  st char *filenam
1cb80 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65  e,   /* Database
1cb90 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38   filename (UTF-8
1cba0 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a  ) */.  sqlite3 *
1cbb0 2a 70 70 44 62 2c 20 20 20 20 20 20 20 20 20 2f  *ppDb,         /
1cbc0 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62  * OUT: SQLite db
1cbd0 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 69 6e 74   handle */.  int
1cbe0 20 66 6c 61 67 73 2c 20 20 20 20 20 20 20 20 20   flags,         
1cbf0 20 20 20 20 20 2f 2a 20 46 6c 61 67 73 20 2a 2f       /* Flags */
1cc00 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
1cc10 56 66 73 20 20 20 20 20 20 20 20 2f 2a 20 4e 61  Vfs        /* Na
1cc20 6d 65 20 6f 66 20 56 46 53 20 6d 6f 64 75 6c 65  me of VFS module
1cc30 20 74 6f 20 75 73 65 20 2a 2f 0a 29 3b 0a 0a 2f   to use */.);../
1cc40 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45  *.** CAPI3REF: E
1cc50 72 72 6f 72 20 43 6f 64 65 73 20 41 6e 64 20 4d  rror Codes And M
1cc60 65 73 73 61 67 65 73 20 7b 48 31 32 38 30 30 7d  essages {H12800}
1cc70 20 3c 53 36 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20   <S60200>.**.** 
1cc80 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72 63  The sqlite3_errc
1cc90 6f 64 65 28 29 20 69 6e 74 65 72 66 61 63 65 20  ode() interface 
1cca0 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 65  returns the nume
1ccb0 72 69 63 20 5b 72 65 73 75 6c 74 20 63 6f 64 65  ric [result code
1ccc0 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65  ] or.** [extende
1ccd0 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 66  d result code] f
1cce0 6f 72 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  or the most rece
1ccf0 6e 74 20 66 61 69 6c 65 64 20 73 71 6c 69 74 65  nt failed sqlite
1cd00 33 5f 2a 20 41 50 49 20 63 61 6c 6c 0a 2a 2a 20  3_* API call.** 
1cd10 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
1cd20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  a [database conn
1cd30 65 63 74 69 6f 6e 5d 2e 20 49 66 20 61 20 70 72  ection]. If a pr
1cd40 69 6f 72 20 41 50 49 20 63 61 6c 6c 20 66 61 69  ior API call fai
1cd50 6c 65 64 0a 2a 2a 20 62 75 74 20 74 68 65 20 6d  led.** but the m
1cd60 6f 73 74 20 72 65 63 65 6e 74 20 41 50 49 20 63  ost recent API c
1cd70 61 6c 6c 20 73 75 63 63 65 65 64 65 64 2c 20 74  all succeeded, t
1cd80 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
1cd90 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  from.** sqlite3_
1cda0 65 72 72 63 6f 64 65 28 29 20 69 73 20 75 6e 64  errcode() is und
1cdb0 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  efined..**.** Th
1cdc0 65 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67  e sqlite3_errmsg
1cdd0 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 65  () and sqlite3_e
1cde0 72 72 6d 73 67 31 36 28 29 20 72 65 74 75 72 6e  rrmsg16() return
1cdf0 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67   English-languag
1ce00 65 0a 2a 2a 20 74 65 78 74 20 74 68 61 74 20 64  e.** text that d
1ce10 65 73 63 72 69 62 65 73 20 74 68 65 20 65 72 72  escribes the err
1ce20 6f 72 2c 20 61 73 20 65 69 74 68 65 72 20 55 54  or, as either UT
1ce30 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 72 65  F-8 or UTF-16 re
1ce40 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 4d  spectively..** M
1ce50 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68  emory to hold th
1ce60 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20  e error message 
1ce70 73 74 72 69 6e 67 20 69 73 20 6d 61 6e 61 67 65  string is manage
1ce80 64 20 69 6e 74 65 72 6e 61 6c 6c 79 2e 0a 2a 2a  d internally..**
1ce90 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
1cea0 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74   does not need t
1ceb0 6f 20 77 6f 72 72 79 20 61 62 6f 75 74 20 66 72  o worry about fr
1cec0 65 65 69 6e 67 20 74 68 65 20 72 65 73 75 6c 74  eeing the result
1ced0 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74 68  ..** However, th
1cee0 65 20 65 72 72 6f 72 20 73 74 72 69 6e 67 20 6d  e error string m
1cef0 69 67 68 74 20 62 65 20 6f 76 65 72 77 72 69 74  ight be overwrit
1cf00 74 65 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74  ten or deallocat
1cf10 65 64 20 62 79 0a 2a 2a 20 73 75 62 73 65 71 75  ed by.** subsequ
1cf20 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 6f 74 68  ent calls to oth
1cf30 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  er SQLite interf
1cf40 61 63 65 20 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a  ace functions..*
1cf50 2a 0a 2a 2a 20 49 66 20 61 6e 20 69 6e 74 65 72  *.** If an inter
1cf60 66 61 63 65 20 66 61 69 6c 73 20 77 69 74 68 20  face fails with 
1cf70 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 2c 20 74  SQLITE_MISUSE, t
1cf80 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20 69 6e  hat means the in
1cf90 74 65 72 66 61 63 65 0a 2a 2a 20 77 61 73 20 69  terface.** was i
1cfa0 6e 76 6f 6b 65 64 20 69 6e 63 6f 72 72 65 63 74  nvoked incorrect
1cfb0 6c 79 20 62 79 20 74 68 65 20 61 70 70 6c 69 63  ly by the applic
1cfc0 61 74 69 6f 6e 2e 20 20 49 6e 20 74 68 61 74 20  ation.  In that 
1cfd0 63 61 73 65 2c 20 74 68 65 0a 2a 2a 20 65 72 72  case, the.** err
1cfe0 6f 72 20 63 6f 64 65 20 61 6e 64 20 6d 65 73 73  or code and mess
1cff0 61 67 65 20 6d 61 79 20 6f 72 20 6d 61 79 20 6e  age may or may n
1d000 6f 74 20 62 65 20 73 65 74 2e 0a 2a 2a 0a 2a 2a  ot be set..**.**
1d010 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
1d020 2a 2a 20 7b 48 31 32 38 30 31 7d 20 54 68 65 20  ** {H12801} The 
1d030 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65  [sqlite3_errcode
1d040 28 44 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  (D)] interface r
1d050 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 65 72  eturns the numer
1d060 69 63 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  ic.**          [
1d070 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 20  result code] or 
1d080 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  [extended result
1d090 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 6d   code] for the m
1d0a0 6f 73 74 20 72 65 63 65 6e 74 6c 79 0a 2a 2a 20  ost recently.** 
1d0b0 20 20 20 20 20 20 20 20 20 66 61 69 6c 65 64 20           failed 
1d0c0 69 6e 74 65 72 66 61 63 65 20 63 61 6c 6c 20 61  interface call a
1d0d0 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74  ssociated with t
1d0e0 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
1d0f0 6e 65 63 74 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a  nection] D..**.*
1d100 2a 20 7b 48 31 32 38 30 33 7d 20 54 68 65 20 5b  * {H12803} The [
1d110 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 44  sqlite3_errmsg(D
1d120 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
1d130 65 72 72 6d 73 67 31 36 28 44 29 5d 0a 2a 2a 20  errmsg16(D)].** 
1d140 20 20 20 20 20 20 20 20 20 69 6e 74 65 72 66 61           interfa
1d150 63 65 73 20 72 65 74 75 72 6e 20 45 6e 67 6c 69  ces return Engli
1d160 73 68 2d 6c 61 6e 67 75 61 67 65 20 74 65 78 74  sh-language text
1d170 20 74 68 61 74 20 64 65 73 63 72 69 62 65 73 0a   that describes.
1d180 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
1d190 65 72 72 6f 72 20 69 6e 20 74 68 65 20 6d 6f 73  error in the mos
1d1a0 74 6c 79 20 72 65 63 65 6e 74 6c 79 20 66 61 69  tly recently fai
1d1b0 6c 65 64 20 69 6e 74 65 72 66 61 63 65 20 63 61  led interface ca
1d1c0 6c 6c 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ll,.**          
1d1d0 65 6e 63 6f 64 65 64 20 61 73 20 65 69 74 68 65  encoded as eithe
1d1e0 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31  r UTF-8 or UTF-1
1d1f0 36 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a  6 respectively..
1d200 2a 2a 0a 2a 2a 20 7b 48 31 32 38 30 37 7d 20 54  **.** {H12807} T
1d210 68 65 20 73 74 72 69 6e 67 73 20 72 65 74 75 72  he strings retur
1d220 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ned by [sqlite3_
1d230 65 72 72 6d 73 67 28 29 5d 20 61 6e 64 20 5b 73  errmsg()] and [s
1d240 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28  qlite3_errmsg16(
1d250 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  )].**          a
1d260 72 65 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 74  re valid until t
1d270 68 65 20 6e 65 78 74 20 53 51 4c 69 74 65 20 69  he next SQLite i
1d280 6e 74 65 72 66 61 63 65 20 63 61 6c 6c 2e 0a 2a  nterface call..*
1d290 2a 0a 2a 2a 20 7b 48 31 32 38 30 38 7d 20 43 61  *.** {H12808} Ca
1d2a0 6c 6c 73 20 74 6f 20 41 50 49 20 72 6f 75 74 69  lls to API routi
1d2b0 6e 65 73 20 74 68 61 74 20 64 6f 20 6e 6f 74 20  nes that do not 
1d2c0 72 65 74 75 72 6e 20 61 6e 20 65 72 72 6f 72 20  return an error 
1d2d0 63 6f 64 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  code.**         
1d2e0 20 28 65 78 61 6d 70 6c 65 3a 20 5b 73 71 6c 69   (example: [sqli
1d2f0 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 29  te3_data_count()
1d300 5d 29 20 64 6f 20 6e 6f 74 0a 2a 2a 20 20 20 20  ]) do not.**    
1d310 20 20 20 20 20 20 63 68 61 6e 67 65 20 74 68 65        change the
1d320 20 65 72 72 6f 72 20 63 6f 64 65 20 6f 72 20 6d   error code or m
1d330 65 73 73 61 67 65 20 72 65 74 75 72 6e 65 64 20  essage returned 
1d340 62 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  by.**          [
1d350 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28  sqlite3_errcode(
1d360 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 65 72 72  )], [sqlite3_err
1d370 6d 73 67 28 29 5d 2c 20 6f 72 20 5b 73 71 6c 69  msg()], or [sqli
1d380 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 5d 2e  te3_errmsg16()].
1d390 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 38 30 39 7d 20  .**.** {H12809} 
1d3a0 49 6e 74 65 72 66 61 63 65 73 20 74 68 61 74 20  Interfaces that 
1d3b0 61 72 65 20 6e 6f 74 20 61 73 73 6f 63 69 61 74  are not associat
1d3c0 65 64 20 77 69 74 68 20 61 20 73 70 65 63 69 66  ed with a specif
1d3d0 69 63 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  ic.**          [
1d3e0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1d3f0 69 6f 6e 5d 20 28 65 78 61 6d 70 6c 65 73 3a 0a  ion] (examples:.
1d400 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
1d410 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 5d 20  ite3_mprintf()] 
1d420 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62  or [sqlite3_enab
1d430 6c 65 5f 73 68 61 72 65 64 5f 63 61 63 68 65 28  le_shared_cache(
1d440 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64  )].**          d
1d450 6f 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65  o not change the
1d460 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64   values returned
1d470 20 62 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   by.**          
1d480 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65  [sqlite3_errcode
1d490 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 65 72  ()], [sqlite3_er
1d4a0 72 6d 73 67 28 29 5d 2c 20 6f 72 20 5b 73 71 6c  rmsg()], or [sql
1d4b0 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 5d  ite3_errmsg16()]
1d4c0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
1d4d0 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33  _errcode(sqlite3
1d4e0 20 2a 64 62 29 3b 0a 63 6f 6e 73 74 20 63 68 61   *db);.const cha
1d4f0 72 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  r *sqlite3_errms
1d500 67 28 73 71 6c 69 74 65 33 2a 29 3b 0a 63 6f 6e  g(sqlite3*);.con
1d510 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
1d520 5f 65 72 72 6d 73 67 31 36 28 73 71 6c 69 74 65  _errmsg16(sqlite
1d530 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  3*);../*.** CAPI
1d540 33 52 45 46 3a 20 53 51 4c 20 53 74 61 74 65 6d  3REF: SQL Statem
1d550 65 6e 74 20 4f 62 6a 65 63 74 20 7b 48 31 33 30  ent Object {H130
1d560 30 30 7d 20 3c 48 31 33 30 31 30 3e 0a 2a 2a 20  00} <H13010>.** 
1d570 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 65 70 61  KEYWORDS: {prepa
1d580 72 65 64 20 73 74 61 74 65 6d 65 6e 74 7d 20 7b  red statement} {
1d590 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
1d5a0 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e  nts}.**.** An in
1d5b0 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f  stance of this o
1d5c0 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74 73  bject represents
1d5d0 20 61 20 73 69 6e 67 6c 65 20 53 51 4c 20 73 74   a single SQL st
1d5e0 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 54 68 69 73  atement..** This
1d5f0 20 6f 62 6a 65 63 74 20 69 73 20 76 61 72 69 6f   object is vario
1d600 75 73 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 61 20  usly known as a 
1d610 22 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  "prepared statem
1d620 65 6e 74 22 20 6f 72 20 61 0a 2a 2a 20 22 63 6f  ent" or a.** "co
1d630 6d 70 69 6c 65 64 20 53 51 4c 20 73 74 61 74 65  mpiled SQL state
1d640 6d 65 6e 74 22 20 6f 72 20 73 69 6d 70 6c 79 20  ment" or simply 
1d650 61 73 20 61 20 22 73 74 61 74 65 6d 65 6e 74 22  as a "statement"
1d660 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6c 69 66 65  ..**.** The life
1d670 20 6f 66 20 61 20 73 74 61 74 65 6d 65 6e 74 20   of a statement 
1d680 6f 62 6a 65 63 74 20 67 6f 65 73 20 73 6f 6d 65  object goes some
1d690 74 68 69 6e 67 20 6c 69 6b 65 20 74 68 69 73 3a  thing like this:
1d6a0 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c  .**.** <ol>.** <
1d6b0 6c 69 3e 20 43 72 65 61 74 65 20 74 68 65 20 6f  li> Create the o
1d6c0 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73 71 6c  bject using [sql
1d6d0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
1d6e0 29 5d 20 6f 72 20 61 20 72 65 6c 61 74 65 64 0a  )] or a related.
1d6f0 2a 2a 20 20 20 20 20 20 66 75 6e 63 74 69 6f 6e  **      function
1d700 2e 0a 2a 2a 20 3c 6c 69 3e 20 42 69 6e 64 20 76  ..** <li> Bind v
1d710 61 6c 75 65 73 20 74 6f 20 5b 68 6f 73 74 20 70  alues to [host p
1d720 61 72 61 6d 65 74 65 72 73 5d 20 75 73 69 6e 67  arameters] using
1d730 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e   the sqlite3_bin
1d740 64 5f 2a 28 29 0a 2a 2a 20 20 20 20 20 20 69 6e  d_*().**      in
1d750 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 3c 6c 69  terfaces..** <li
1d760 3e 20 52 75 6e 20 74 68 65 20 53 51 4c 20 62 79  > Run the SQL by
1d770 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   calling [sqlite
1d780 33 5f 73 74 65 70 28 29 5d 20 6f 6e 65 20 6f 72  3_step()] one or
1d790 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20   more times..** 
1d7a0 3c 6c 69 3e 20 52 65 73 65 74 20 74 68 65 20 73  <li> Reset the s
1d7b0 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b  tatement using [
1d7c0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
1d7d0 20 74 68 65 6e 20 67 6f 20 62 61 63 6b 0a 2a 2a   then go back.**
1d7e0 20 20 20 20 20 20 74 6f 20 73 74 65 70 20 32 2e        to step 2.
1d7f0 20 20 44 6f 20 74 68 69 73 20 7a 65 72 6f 20 6f    Do this zero o
1d800 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a  r more times..**
1d810 20 3c 6c 69 3e 20 44 65 73 74 72 6f 79 20 74 68   <li> Destroy th
1d820 65 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b  e object using [
1d830 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
1d840 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a  ()]..** </ol>.**
1d850 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20 64 6f 63  .** Refer to doc
1d860 75 6d 65 6e 74 61 74 69 6f 6e 20 6f 6e 20 69 6e  umentation on in
1d870 64 69 76 69 64 75 61 6c 20 6d 65 74 68 6f 64 73  dividual methods
1d880 20 61 62 6f 76 65 20 66 6f 72 20 61 64 64 69 74   above for addit
1d890 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61  ional.** informa
1d8a0 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  tion..*/.typedef
1d8b0 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
1d8c0 73 74 6d 74 20 73 71 6c 69 74 65 33 5f 73 74 6d  stmt sqlite3_stm
1d8d0 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  t;../*.** CAPI3R
1d8e0 45 46 3a 20 52 75 6e 2d 74 69 6d 65 20 4c 69 6d  EF: Run-time Lim
1d8f0 69 74 73 20 7b 48 31 32 37 36 30 7d 20 3c 53 32  its {H12760} <S2
1d900 30 36 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  0600>.**.** This
1d910 20 69 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f 77   interface allow
1d920 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 76 61  s the size of va
1d930 72 69 6f 75 73 20 63 6f 6e 73 74 72 75 63 74 73  rious constructs
1d940 20 74 6f 20 62 65 20 6c 69 6d 69 74 65 64 0a 2a   to be limited.*
1d950 2a 20 6f 6e 20 61 20 63 6f 6e 6e 65 63 74 69 6f  * on a connectio
1d960 6e 20 62 79 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  n by connection 
1d970 62 61 73 69 73 2e 20 20 54 68 65 20 66 69 72 73  basis.  The firs
1d980 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  t parameter is t
1d990 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  he.** [database 
1d9a0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 68 6f 73  connection] whos
1d9b0 65 20 6c 69 6d 69 74 20 69 73 20 74 6f 20 62 65  e limit is to be
1d9c0 20 73 65 74 20 6f 72 20 71 75 65 72 69 65 64 2e   set or queried.
1d9d0 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20    The.** second 
1d9e0 70 61 72 61 6d 65 74 65 72 20 69 73 20 6f 6e 65  parameter is one
1d9f0 20 6f 66 20 74 68 65 20 5b 6c 69 6d 69 74 20 63   of the [limit c
1da00 61 74 65 67 6f 72 69 65 73 5d 20 74 68 61 74 20  ategories] that 
1da10 64 65 66 69 6e 65 20 61 0a 2a 2a 20 63 6c 61 73  define a.** clas
1da20 73 20 6f 66 20 63 6f 6e 73 74 72 75 63 74 73 20  s of constructs 
1da30 74 6f 20 62 65 20 73 69 7a 65 20 6c 69 6d 69 74  to be size limit
1da40 65 64 2e 20 20 54 68 65 20 74 68 69 72 64 20 70  ed.  The third p
1da50 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a  arameter is the.
1da60 2a 2a 20 6e 65 77 20 6c 69 6d 69 74 20 66 6f 72  ** new limit for
1da70 20 74 68 61 74 20 63 6f 6e 73 74 72 75 63 74 2e   that construct.
1da80 20 20 54 68 65 20 66 75 6e 63 74 69 6f 6e 20 72    The function r
1da90 65 74 75 72 6e 73 20 74 68 65 20 6f 6c 64 20 6c  eturns the old l
1daa0 69 6d 69 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  imit..**.** If t
1dab0 68 65 20 6e 65 77 20 6c 69 6d 69 74 20 69 73 20  he new limit is 
1dac0 61 20 6e 65 67 61 74 69 76 65 20 6e 75 6d 62 65  a negative numbe
1dad0 72 2c 20 74 68 65 20 6c 69 6d 69 74 20 69 73 20  r, the limit is 
1dae0 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 46 6f  unchanged..** Fo
1daf0 72 20 74 68 65 20 6c 69 6d 69 74 20 63 61 74 65  r the limit cate
1db00 67 6f 72 79 20 6f 66 20 53 51 4c 49 54 45 5f 4c  gory of SQLITE_L
1db10 49 4d 49 54 5f 58 59 5a 20 74 68 65 72 65 20 69  IMIT_XYZ there i
1db20 73 20 61 20 68 61 72 64 20 75 70 70 65 72 0a 2a  s a hard upper.*
1db30 2a 20 62 6f 75 6e 64 20 73 65 74 20 62 79 20 61  * bound set by a
1db40 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 43 20   compile-time C 
1db50 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63  preprocessor mac
1db60 72 6f 20 6e 61 6d 65 64 20 53 51 4c 49 54 45 5f  ro named SQLITE_
1db70 4d 41 58 5f 58 59 5a 2e 0a 2a 2a 20 28 54 68 65  MAX_XYZ..** (The
1db80 20 22 5f 4c 49 4d 49 54 5f 22 20 69 6e 20 74 68   "_LIMIT_" in th
1db90 65 20 6e 61 6d 65 20 69 73 20 63 68 61 6e 67 65  e name is change
1dba0 64 20 74 6f 20 22 5f 4d 41 58 5f 22 2e 29 0a 2a  d to "_MAX_".).*
1dbb0 2a 20 41 74 74 65 6d 70 74 73 20 74 6f 20 69 6e  * Attempts to in
1dbc0 63 72 65 61 73 65 20 61 20 6c 69 6d 69 74 20 61  crease a limit a
1dbd0 62 6f 76 65 20 69 74 73 20 68 61 72 64 20 75 70  bove its hard up
1dbe0 70 65 72 20 62 6f 75 6e 64 20 61 72 65 0a 2a 2a  per bound are.**
1dbf0 20 73 69 6c 65 6e 74 6c 79 20 74 72 75 6e 63 61   silently trunca
1dc00 74 65 64 20 74 6f 20 74 68 65 20 68 61 72 64 20  ted to the hard 
1dc10 75 70 70 65 72 20 6c 69 6d 69 74 2e 0a 2a 2a 0a  upper limit..**.
1dc20 2a 2a 20 52 75 6e 20 74 69 6d 65 20 6c 69 6d 69  ** Run time limi
1dc30 74 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20  ts are intended 
1dc40 66 6f 72 20 75 73 65 20 69 6e 20 61 70 70 6c 69  for use in appli
1dc50 63 61 74 69 6f 6e 73 20 74 68 61 74 20 6d 61 6e  cations that man
1dc60 61 67 65 0a 2a 2a 20 62 6f 74 68 20 74 68 65 69  age.** both thei
1dc70 72 20 6f 77 6e 20 69 6e 74 65 72 6e 61 6c 20 64  r own internal d
1dc80 61 74 61 62 61 73 65 20 61 6e 64 20 61 6c 73 6f  atabase and also
1dc90 20 64 61 74 61 62 61 73 65 73 20 74 68 61 74 20   databases that 
1dca0 61 72 65 20 63 6f 6e 74 72 6f 6c 6c 65 64 0a 2a  are controlled.*
1dcb0 2a 20 62 79 20 75 6e 74 72 75 73 74 65 64 20 65  * by untrusted e
1dcc0 78 74 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 2e  xternal sources.
1dcd0 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 61 70 70    An example app
1dce0 6c 69 63 61 74 69 6f 6e 20 6d 69 67 68 74 20 62  lication might b
1dcf0 65 20 61 0a 2a 2a 20 77 65 62 62 72 6f 77 73 65  e a.** webbrowse
1dd00 72 20 74 68 61 74 20 68 61 73 20 69 74 73 20 6f  r that has its o
1dd10 77 6e 20 64 61 74 61 62 61 73 65 73 20 66 6f 72  wn databases for
1dd20 20 73 74 6f 72 69 6e 67 20 68 69 73 74 6f 72 79   storing history
1dd30 20 61 6e 64 0a 2a 2a 20 73 65 70 61 72 61 74 65   and.** separate
1dd40 20 64 61 74 61 62 61 73 65 73 20 63 6f 6e 74 72   databases contr
1dd50 6f 6c 6c 65 64 20 62 79 20 4a 61 76 61 53 63 72  olled by JavaScr
1dd60 69 70 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  ipt applications
1dd70 20 64 6f 77 6e 6c 6f 61 64 65 64 0a 2a 2a 20 6f   downloaded.** o
1dd80 66 66 20 74 68 65 20 49 6e 74 65 72 6e 65 74 2e  ff the Internet.
1dd90 20 20 54 68 65 20 69 6e 74 65 72 6e 61 6c 20 64    The internal d
1dda0 61 74 61 62 61 73 65 73 20 63 61 6e 20 62 65 20  atabases can be 
1ddb0 67 69 76 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 72  given the.** lar
1ddc0 67 65 2c 20 64 65 66 61 75 6c 74 20 6c 69 6d 69  ge, default limi
1ddd0 74 73 2e 20 20 44 61 74 61 62 61 73 65 73 20 6d  ts.  Databases m
1dde0 61 6e 61 67 65 64 20 62 79 20 65 78 74 65 72 6e  anaged by extern
1ddf0 61 6c 20 73 6f 75 72 63 65 73 20 63 61 6e 0a 2a  al sources can.*
1de00 2a 20 62 65 20 67 69 76 65 6e 20 6d 75 63 68 20  * be given much 
1de10 73 6d 61 6c 6c 65 72 20 6c 69 6d 69 74 73 20 64  smaller limits d
1de20 65 73 69 67 6e 65 64 20 74 6f 20 70 72 65 76 65  esigned to preve
1de30 6e 74 20 61 20 64 65 6e 69 61 6c 20 6f 66 20 73  nt a denial of s
1de40 65 72 76 69 63 65 0a 2a 2a 20 61 74 74 61 63 6b  ervice.** attack
1de50 2e 20 20 44 65 76 65 6c 6f 70 65 72 73 20 6d 69  .  Developers mi
1de60 67 68 74 20 61 6c 73 6f 20 77 61 6e 74 20 74 6f  ght also want to
1de70 20 75 73 65 20 74 68 65 20 5b 73 71 6c 69 74 65   use the [sqlite
1de80 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
1de90 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  ()].** interface
1dea0 20 74 6f 20 66 75 72 74 68 65 72 20 63 6f 6e 74   to further cont
1deb0 72 6f 6c 20 75 6e 74 72 75 73 74 65 64 20 53 51  rol untrusted SQ
1dec0 4c 2e 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20  L.  The size of 
1ded0 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  the database.** 
1dee0 63 72 65 61 74 65 64 20 62 79 20 61 6e 20 75 6e  created by an un
1def0 74 72 75 73 74 65 64 20 73 63 72 69 70 74 20 63  trusted script c
1df00 61 6e 20 62 65 20 63 6f 6e 74 61 69 6e 65 64 20  an be contained 
1df10 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 6d 61  using the.** [ma
1df20 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50  x_page_count] [P
1df30 52 41 47 4d 41 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 65  RAGMA]..**.** Ne
1df40 77 20 72 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74  w run-time limit
1df50 20 63 61 74 65 67 6f 72 69 65 73 20 6d 61 79 20   categories may 
1df60 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75  be added in futu
1df70 72 65 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2a 0a  re releases..**.
1df80 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
1df90 2a 0a 2a 2a 20 7b 48 31 32 37 36 32 7d 20 41 20  *.** {H12762} A 
1dfa0 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20  successful call 
1dfb0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69  to [sqlite3_limi
1dfc0 74 28 44 2c 43 2c 56 29 5d 20 77 68 65 72 65 20  t(D,C,V)] where 
1dfd0 56 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  V is.**         
1dfe0 20 70 6f 73 69 74 69 76 65 20 63 68 61 6e 67 65   positive change
1dff0 73 20 74 68 65 20 6c 69 6d 69 74 20 6f 6e 20 74  s the limit on t
1e000 68 65 20 73 69 7a 65 20 6f 66 20 63 6f 6e 73 74  he size of const
1e010 72 75 63 74 20 43 20 69 6e 20 74 68 65 0a 2a 2a  ruct C in the.**
1e020 20 20 20 20 20 20 20 20 20 20 5b 64 61 74 61 62            [datab
1e030 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
1e040 44 20 74 6f 20 74 68 65 20 6c 65 73 73 65 72 20  D to the lesser 
1e050 6f 66 20 56 20 61 6e 64 20 74 68 65 20 68 61 72  of V and the har
1e060 64 20 75 70 70 65 72 0a 2a 2a 20 20 20 20 20 20  d upper.**      
1e070 20 20 20 20 62 6f 75 6e 64 20 6f 6e 20 74 68 65      bound on the
1e080 20 73 69 7a 65 20 6f 66 20 43 20 74 68 61 74 20   size of C that 
1e090 69 73 20 73 65 74 20 61 74 20 63 6f 6d 70 69 6c  is set at compil
1e0a0 65 2d 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48  e-time..**.** {H
1e0b0 31 32 37 36 36 7d 20 41 20 73 75 63 63 65 73 73  12766} A success
1e0c0 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ful call to [sql
1e0d0 69 74 65 33 5f 6c 69 6d 69 74 28 44 2c 43 2c 56  ite3_limit(D,C,V
1e0e0 29 5d 20 77 68 65 72 65 20 56 20 69 73 20 6e 65  )] where V is ne
1e0f0 67 61 74 69 76 65 0a 2a 2a 20 20 20 20 20 20 20  gative.**       
1e100 20 20 20 6c 65 61 76 65 73 20 74 68 65 20 73 74     leaves the st
1e110 61 74 65 20 6f 66 20 74 68 65 20 5b 64 61 74 61  ate of the [data
1e120 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
1e130 20 44 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a   D unchanged..**
1e140 0a 2a 2a 20 7b 48 31 32 37 36 39 7d 20 41 20 73  .** {H12769} A s
1e150 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74  uccessful call t
1e160 6f 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74  o [sqlite3_limit
1e170 28 44 2c 43 2c 56 29 5d 20 72 65 74 75 72 6e 73  (D,C,V)] returns
1e180 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
1e190 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 6c 69   value of the li
1e1a0 6d 69 74 20 6f 6e 20 74 68 65 20 73 69 7a 65 20  mit on the size 
1e1b0 6f 66 20 63 6f 6e 73 74 72 75 63 74 20 43 20 69  of construct C i
1e1c0 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  n the.**        
1e1d0 20 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e    [database conn
1e1e0 65 63 74 69 6f 6e 5d 20 44 20 61 73 20 69 74 20  ection] D as it 
1e1f0 77 61 73 20 70 72 69 6f 72 20 74 6f 20 74 68 65  was prior to the
1e200 20 63 61 6c 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71   call..*/.int sq
1e210 6c 69 74 65 33 5f 6c 69 6d 69 74 28 73 71 6c 69  lite3_limit(sqli
1e220 74 65 33 2a 2c 20 69 6e 74 20 69 64 2c 20 69 6e  te3*, int id, in
1e230 74 20 6e 65 77 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a  t newVal);../*.*
1e240 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d  * CAPI3REF: Run-
1e250 54 69 6d 65 20 4c 69 6d 69 74 20 43 61 74 65 67  Time Limit Categ
1e260 6f 72 69 65 73 20 7b 48 31 32 37 39 30 7d 20 3c  ories {H12790} <
1e270 48 31 32 37 36 30 3e 0a 2a 2a 20 4b 45 59 57 4f  H12760>.** KEYWO
1e280 52 44 53 3a 20 7b 6c 69 6d 69 74 20 63 61 74 65  RDS: {limit cate
1e290 67 6f 72 79 7d 20 7b 6c 69 6d 69 74 20 63 61 74  gory} {limit cat
1e2a0 65 67 6f 72 69 65 73 7d 0a 2a 2a 0a 2a 2a 20 54  egories}.**.** T
1e2b0 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 64  hese constants d
1e2c0 65 66 69 6e 65 20 76 61 72 69 6f 75 73 20 61 73  efine various as
1e2d0 70 65 63 74 73 20 6f 66 20 61 20 5b 64 61 74 61  pects of a [data
1e2e0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
1e2f0 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65 20  .** that can be 
1e300 6c 69 6d 69 74 65 64 20 69 6e 20 73 69 7a 65 20  limited in size 
1e310 62 79 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c  by calls to [sql
1e320 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 2e 0a 2a  ite3_limit()]..*
1e330 2a 20 54 68 65 20 6d 65 61 6e 69 6e 67 73 20 6f  * The meanings o
1e340 66 20 74 68 65 20 76 61 72 69 6f 75 73 20 6c 69  f the various li
1e350 6d 69 74 73 20 61 72 65 20 61 73 20 66 6f 6c 6c  mits are as foll
1e360 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a  ows:.**.** <dl>.
1e370 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49  ** <dt>SQLITE_LI
1e380 4d 49 54 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a  MIT_LENGTH</dt>.
1e390 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
1e3a0 75 6d 20 73 69 7a 65 20 6f 66 20 61 6e 79 20 73  um size of any s
1e3b0 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 6f 72  tring or BLOB or
1e3c0 20 74 61 62 6c 65 20 72 6f 77 2e 3c 64 64 3e 0a   table row.<dd>.
1e3d0 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
1e3e0 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54  _LIMIT_SQL_LENGT
1e3f0 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  H</dt>.** <dd>Th
1e400 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  e maximum length
1e410 20 6f 66 20 61 6e 20 53 51 4c 20 73 74 61 74 65   of an SQL state
1e420 6d 65 6e 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ment.</dd>.**.**
1e430 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49   <dt>SQLITE_LIMI
1e440 54 5f 43 4f 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a  T_COLUMN</dt>.**
1e450 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
1e460 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
1e470 6e 73 20 69 6e 20 61 20 74 61 62 6c 65 20 64 65  ns in a table de
1e480 66 69 6e 69 74 69 6f 6e 20 6f 72 20 69 6e 20 74  finition or in t
1e490 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 73 65 74  he.** result set
1e4a0 20 6f 66 20 61 20 53 45 4c 45 43 54 20 6f 72 20   of a SELECT or 
1e4b0 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  the maximum numb
1e4c0 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e  er of columns in
1e4d0 20 61 6e 20 69 6e 64 65 78 0a 2a 2a 20 6f 72 20   an index.** or 
1e4e0 69 6e 20 61 6e 20 4f 52 44 45 52 20 42 59 20 6f  in an ORDER BY o
1e4f0 72 20 47 52 4f 55 50 20 42 59 20 63 6c 61 75 73  r GROUP BY claus
1e500 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  e.</dd>.**.** <d
1e510 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45  t>SQLITE_LIMIT_E
1e520 58 50 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a  XPR_DEPTH</dt>.*
1e530 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
1e540 6d 20 64 65 70 74 68 20 6f 66 20 74 68 65 20 70  m depth of the p
1e550 61 72 73 65 20 74 72 65 65 20 6f 6e 20 61 6e 79  arse tree on any
1e560 20 65 78 70 72 65 73 73 69 6f 6e 2e 3c 2f 64 64   expression.</dd
1e570 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
1e580 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e  TE_LIMIT_COMPOUN
1e590 44 5f 53 45 4c 45 43 54 3c 2f 64 74 3e 0a 2a 2a  D_SELECT</dt>.**
1e5a0 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
1e5b0 20 6e 75 6d 62 65 72 20 6f 66 20 74 65 72 6d 73   number of terms
1e5c0 20 69 6e 20 61 20 63 6f 6d 70 6f 75 6e 64 20 53   in a compound S
1e5d0 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74 2e  ELECT statement.
1e5e0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
1e5f0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42  SQLITE_LIMIT_VDB
1e600 45 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  E_OP</dt>.** <dd
1e610 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  >The maximum num
1e620 62 65 72 20 6f 66 20 69 6e 73 74 72 75 63 74 69  ber of instructi
1e630 6f 6e 73 20 69 6e 20 61 20 76 69 72 74 75 61 6c  ons in a virtual
1e640 20 6d 61 63 68 69 6e 65 20 70 72 6f 67 72 61 6d   machine program
1e650 0a 2a 2a 20 75 73 65 64 20 74 6f 20 69 6d 70 6c  .** used to impl
1e660 65 6d 65 6e 74 20 61 6e 20 53 51 4c 20 73 74 61  ement an SQL sta
1e670 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a  tement.</dd>.**.
1e680 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49  ** <dt>SQLITE_LI
1e690 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47  MIT_FUNCTION_ARG
1e6a0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
1e6b0 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
1e6c0 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 6f 6e 20  of arguments on 
1e6d0 61 20 66 75 6e 63 74 69 6f 6e 2e 3c 2f 64 64 3e  a function.</dd>
1e6e0 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
1e6f0 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44  E_LIMIT_ATTACHED
1e700 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
1e710 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
1e720 6f 66 20 61 74 74 61 63 68 65 64 20 64 61 74 61  of attached data
1e730 62 61 73 65 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  bases.</dd>.**.*
1e740 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  * <dt>SQLITE_LIM
1e750 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f  IT_LIKE_PATTERN_
1e760 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c  LENGTH</dt>.** <
1e770 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c  dd>The maximum l
1e780 65 6e 67 74 68 20 6f 66 20 74 68 65 20 70 61 74  ength of the pat
1e790 74 65 72 6e 20 61 72 67 75 6d 65 6e 74 20 74 6f  tern argument to
1e7a0 20 74 68 65 20 4c 49 4b 45 20 6f 72 0a 2a 2a 20   the LIKE or.** 
1e7b0 47 4c 4f 42 20 6f 70 65 72 61 74 6f 72 73 2e 3c  GLOB operators.<
1e7c0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
1e7d0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49  QLITE_LIMIT_VARI
1e7e0 41 42 4c 45 5f 4e 55 4d 42 45 52 3c 2f 64 74 3e  ABLE_NUMBER</dt>
1e7f0 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
1e800 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 76 61  mum number of va
1e810 72 69 61 62 6c 65 73 20 69 6e 20 61 6e 20 53 51  riables in an SQ
1e820 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74  L statement that
1e830 20 63 61 6e 0a 2a 2a 20 62 65 20 62 6f 75 6e 64   can.** be bound
1e840 2e 3c 2f 64 64 3e 0a 2a 2a 20 3c 2f 64 6c 3e 0a  .</dd>.** </dl>.
1e850 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1e860 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 20 20  E_LIMIT_LENGTH  
1e870 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1e880 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    0.#define SQLI
1e890 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e  TE_LIMIT_SQL_LEN
1e8a0 47 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20  GTH             
1e8b0 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c     1.#define SQL
1e8c0 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e  ITE_LIMIT_COLUMN
1e8d0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1e8e0 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51      2.#define SQ
1e8f0 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f  LITE_LIMIT_EXPR_
1e900 44 45 50 54 48 20 20 20 20 20 20 20 20 20 20 20  DEPTH           
1e910 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53       3.#define S
1e920 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50  QLITE_LIMIT_COMP
1e930 4f 55 4e 44 5f 53 45 4c 45 43 54 20 20 20 20 20  OUND_SELECT     
1e940 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20        4.#define 
1e950 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42  SQLITE_LIMIT_VDB
1e960 45 5f 4f 50 20 20 20 20 20 20 20 20 20 20 20 20  E_OP            
1e970 20 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e 65         5.#define
1e980 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55   SQLITE_LIMIT_FU
1e990 4e 43 54 49 4f 4e 5f 41 52 47 20 20 20 20 20 20  NCTION_ARG      
1e9a0 20 20 20 20 20 20 20 20 36 0a 23 64 65 66 69 6e          6.#defin
1e9b0 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41  e SQLITE_LIMIT_A
1e9c0 54 54 41 43 48 45 44 20 20 20 20 20 20 20 20 20  TTACHED         
1e9d0 20 20 20 20 20 20 20 20 20 37 0a 23 64 65 66 69           7.#defi
1e9e0 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
1e9f0 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e  LIKE_PATTERN_LEN
1ea00 47 54 48 20 20 20 20 20 20 20 38 0a 23 64 65 66  GTH       8.#def
1ea10 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
1ea20 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52  _VARIABLE_NUMBER
1ea30 20 20 20 20 20 20 20 20 20 20 20 39 0a 0a 2f 2a             9../*
1ea40 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
1ea50 6d 70 69 6c 69 6e 67 20 41 6e 20 53 51 4c 20 53  mpiling An SQL S
1ea60 74 61 74 65 6d 65 6e 74 20 7b 48 31 33 30 31 30  tatement {H13010
1ea70 7d 20 3c 53 31 30 30 30 30 3e 0a 2a 2a 20 4b 45  } <S10000>.** KE
1ea80 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 73 74 61  YWORDS: {SQL sta
1ea90 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 72 7d  tement compiler}
1eaa0 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65 63 75 74  .**.** To execut
1eab0 65 20 61 6e 20 53 51 4c 20 71 75 65 72 79 2c 20  e an SQL query, 
1eac0 69 74 20 6d 75 73 74 20 66 69 72 73 74 20 62 65  it must first be
1ead0 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20 61   compiled into a
1eae0 20 62 79 74 65 2d 63 6f 64 65 0a 2a 2a 20 70 72   byte-code.** pr
1eaf0 6f 67 72 61 6d 20 75 73 69 6e 67 20 6f 6e 65 20  ogram using one 
1eb00 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
1eb10 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72  s..**.** The fir
1eb20 73 74 20 61 72 67 75 6d 65 6e 74 2c 20 22 64 62  st argument, "db
1eb30 22 2c 20 69 73 20 61 20 5b 64 61 74 61 62 61 73  ", is a [databas
1eb40 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62  e connection] ob
1eb50 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 0a 2a 2a  tained from a.**
1eb60 20 70 72 69 6f 72 20 63 61 6c 6c 20 74 6f 20 5b   prior call to [
1eb70 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c  sqlite3_open()],
1eb80 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
1eb90 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  2()] or [sqlite3
1eba0 5f 6f 70 65 6e 31 36 28 29 5d 2e 0a 2a 2a 0a 2a  _open16()]..**.*
1ebb0 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67  * The second arg
1ebc0 75 6d 65 6e 74 2c 20 22 7a 53 71 6c 22 2c 20 69  ument, "zSql", i
1ebd0 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  s the statement 
1ebe0 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 2c 20  to be compiled, 
1ebf0 65 6e 63 6f 64 65 64 0a 2a 2a 20 61 73 20 65 69  encoded.** as ei
1ec00 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54  ther UTF-8 or UT
1ec10 46 2d 31 36 2e 20 20 54 68 65 20 73 71 6c 69 74  F-16.  The sqlit
1ec20 65 33 5f 70 72 65 70 61 72 65 28 29 20 61 6e 64  e3_prepare() and
1ec30 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
1ec40 5f 76 32 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61  _v2().** interfa
1ec50 63 65 73 20 75 73 65 20 55 54 46 2d 38 2c 20 61  ces use UTF-8, a
1ec60 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nd sqlite3_prepa
1ec70 72 65 31 36 28 29 20 61 6e 64 20 73 71 6c 69 74  re16() and sqlit
1ec80 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
1ec90 29 0a 2a 2a 20 75 73 65 20 55 54 46 2d 31 36 2e  ).** use UTF-16.
1eca0 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 6e 42  .**.** If the nB
1ecb0 79 74 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20  yte argument is 
1ecc0 6c 65 73 73 20 74 68 61 6e 20 7a 65 72 6f 2c 20  less than zero, 
1ecd0 74 68 65 6e 20 7a 53 71 6c 20 69 73 20 72 65 61  then zSql is rea
1ece0 64 20 75 70 20 74 6f 20 74 68 65 0a 2a 2a 20 66  d up to the.** f
1ecf0 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e  irst zero termin
1ed00 61 74 6f 72 2e 20 49 66 20 6e 42 79 74 65 20 69  ator. If nByte i
1ed10 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20  s non-negative, 
1ed20 74 68 65 6e 20 69 74 20 69 73 20 74 68 65 20 6d  then it is the m
1ed30 61 78 69 6d 75 6d 0a 2a 2a 20 6e 75 6d 62 65 72  aximum.** number
1ed40 20 6f 66 20 20 62 79 74 65 73 20 72 65 61 64 20   of  bytes read 
1ed50 66 72 6f 6d 20 7a 53 71 6c 2e 20 20 57 68 65 6e  from zSql.  When
1ed60 20 6e 42 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65   nByte is non-ne
1ed70 67 61 74 69 76 65 2c 20 74 68 65 0a 2a 2a 20 7a  gative, the.** z
1ed80 53 71 6c 20 73 74 72 69 6e 67 20 65 6e 64 73 20  Sql string ends 
1ed90 61 74 20 65 69 74 68 65 72 20 74 68 65 20 66 69  at either the fi
1eda0 72 73 74 20 27 5c 30 30 30 27 20 6f 72 20 27 5c  rst '\000' or '\
1edb0 75 30 30 30 30 27 20 63 68 61 72 61 63 74 65 72  u0000' character
1edc0 20 6f 72 0a 2a 2a 20 74 68 65 20 6e 42 79 74 65   or.** the nByte
1edd0 2d 74 68 20 62 79 74 65 2c 20 77 68 69 63 68 65  -th byte, whiche
1ede0 76 65 72 20 63 6f 6d 65 73 20 66 69 72 73 74 2e  ver comes first.
1edf0 20 49 66 20 74 68 65 20 63 61 6c 6c 65 72 20 6b   If the caller k
1ee00 6e 6f 77 73 0a 2a 2a 20 74 68 61 74 20 74 68 65  nows.** that the
1ee10 20 73 75 70 70 6c 69 65 64 20 73 74 72 69 6e 67   supplied string
1ee20 20 69 73 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74   is nul-terminat
1ee30 65 64 2c 20 74 68 65 6e 20 74 68 65 72 65 20 69  ed, then there i
1ee40 73 20 61 20 73 6d 61 6c 6c 0a 2a 2a 20 70 65 72  s a small.** per
1ee50 66 6f 72 6d 61 6e 63 65 20 61 64 76 61 6e 74 61  formance advanta
1ee60 67 65 20 74 6f 20 62 65 20 67 61 69 6e 65 64 20  ge to be gained 
1ee70 62 79 20 70 61 73 73 69 6e 67 20 61 6e 20 6e 42  by passing an nB
1ee80 79 74 65 20 70 61 72 61 6d 65 74 65 72 20 74 68  yte parameter th
1ee90 61 74 0a 2a 2a 20 69 73 20 65 71 75 61 6c 20 74  at.** is equal t
1eea0 6f 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  o the number of 
1eeb0 62 79 74 65 73 20 69 6e 20 74 68 65 20 69 6e 70  bytes in the inp
1eec0 75 74 20 73 74 72 69 6e 67 20 3c 69 3e 69 6e 63  ut string <i>inc
1eed0 6c 75 64 69 6e 67 3c 2f 69 3e 0a 2a 2a 20 74 68  luding</i>.** th
1eee0 65 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 6f 72  e nul-terminator
1eef0 20 62 79 74 65 73 2e 0a 2a 2a 0a 2a 2a 20 2a 70   bytes..**.** *p
1ef00 7a 54 61 69 6c 20 69 73 20 6d 61 64 65 20 74 6f  zTail is made to
1ef10 20 70 6f 69 6e 74 20 74 6f 20 74 68 65 20 66 69   point to the fi
1ef20 72 73 74 20 62 79 74 65 20 70 61 73 74 20 74 68  rst byte past th
1ef30 65 20 65 6e 64 20 6f 66 20 74 68 65 0a 2a 2a 20  e end of the.** 
1ef40 66 69 72 73 74 20 53 51 4c 20 73 74 61 74 65 6d  first SQL statem
1ef50 65 6e 74 20 69 6e 20 7a 53 71 6c 2e 20 20 54 68  ent in zSql.  Th
1ef60 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e 6c  ese routines onl
1ef70 79 20 63 6f 6d 70 69 6c 65 20 74 68 65 20 66 69  y compile the fi
1ef80 72 73 74 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  rst.** statement
1ef90 20 69 6e 20 7a 53 71 6c 2c 20 73 6f 20 2a 70 7a   in zSql, so *pz
1efa0 54 61 69 6c 20 69 73 20 6c 65 66 74 20 70 6f 69  Tail is left poi
1efb0 6e 74 69 6e 67 20 74 6f 20 77 68 61 74 20 72 65  nting to what re
1efc0 6d 61 69 6e 73 0a 2a 2a 20 75 6e 63 6f 6d 70 69  mains.** uncompi
1efd0 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 2a 70 70 53 74  led..**.** *ppSt
1efe0 6d 74 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74  mt is left point
1eff0 69 6e 67 20 74 6f 20 61 20 63 6f 6d 70 69 6c 65  ing to a compile
1f000 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  d [prepared stat
1f010 65 6d 65 6e 74 5d 20 74 68 61 74 20 63 61 6e 20  ement] that can 
1f020 62 65 0a 2a 2a 20 65 78 65 63 75 74 65 64 20 75  be.** executed u
1f030 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74  sing [sqlite3_st
1f040 65 70 28 29 5d 2e 20 20 49 66 20 74 68 65 72 65  ep()].  If there
1f050 20 69 73 20 61 6e 20 65 72 72 6f 72 2c 20 2a 70   is an error, *p
1f060 70 53 74 6d 74 20 69 73 20 73 65 74 0a 2a 2a 20  pStmt is set.** 
1f070 74 6f 20 4e 55 4c 4c 2e 20 20 49 66 20 74 68 65  to NULL.  If the
1f080 20 69 6e 70 75 74 20 74 65 78 74 20 63 6f 6e 74   input text cont
1f090 61 69 6e 73 20 6e 6f 20 53 51 4c 20 28 69 66 20  ains no SQL (if 
1f0a0 74 68 65 20 69 6e 70 75 74 20 69 73 20 61 6e 20  the input is an 
1f0b0 65 6d 70 74 79 0a 2a 2a 20 73 74 72 69 6e 67 20  empty.** string 
1f0c0 6f 72 20 61 20 63 6f 6d 6d 65 6e 74 29 20 74 68  or a comment) th
1f0d0 65 6e 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65  en *ppStmt is se
1f0e0 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 7b 41  t to NULL..** {A
1f0f0 31 33 30 31 38 7d 20 54 68 65 20 63 61 6c 6c 69  13018} The calli
1f100 6e 67 20 70 72 6f 63 65 64 75 72 65 20 69 73 20  ng procedure is 
1f110 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20  responsible for 
1f120 64 65 6c 65 74 69 6e 67 20 74 68 65 20 63 6f 6d  deleting the com
1f130 70 69 6c 65 64 0a 2a 2a 20 53 51 4c 20 73 74 61  piled.** SQL sta
1f140 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 71  tement using [sq
1f150 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
1f160 5d 20 61 66 74 65 72 20 69 74 20 68 61 73 20 66  ] after it has f
1f170 69 6e 69 73 68 65 64 20 77 69 74 68 20 69 74 2e  inished with it.
1f180 0a 2a 2a 0a 2a 2a 20 4f 6e 20 73 75 63 63 65 73  .**.** On succes
1f190 73 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69  s, [SQLITE_OK] i
1f1a0 73 20 72 65 74 75 72 6e 65 64 2c 20 6f 74 68 65  s returned, othe
1f1b0 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 20  rwise an [error 
1f1c0 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65  code] is returne
1f1d0 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  d..**.** The sql
1f1e0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
1f1f0 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72  ) and sqlite3_pr
1f200 65 70 61 72 65 31 36 5f 76 32 28 29 20 69 6e 74  epare16_v2() int
1f210 65 72 66 61 63 65 73 20 61 72 65 0a 2a 2a 20 72  erfaces are.** r
1f220 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 61  ecommended for a
1f230 6c 6c 20 6e 65 77 20 70 72 6f 67 72 61 6d 73 2e  ll new programs.
1f240 20 54 68 65 20 74 77 6f 20 6f 6c 64 65 72 20 69   The two older i
1f250 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 72 65  nterfaces are re
1f260 74 61 69 6e 65 64 0a 2a 2a 20 66 6f 72 20 62 61  tained.** for ba
1f270 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62  ckwards compatib
1f280 69 6c 69 74 79 2c 20 62 75 74 20 74 68 65 69 72  ility, but their
1f290 20 75 73 65 20 69 73 20 64 69 73 63 6f 75 72 61   use is discoura
1f2a0 67 65 64 2e 0a 2a 2a 20 49 6e 20 74 68 65 20 22  ged..** In the "
1f2b0 76 32 22 20 69 6e 74 65 72 66 61 63 65 73 2c 20  v2" interfaces, 
1f2c0 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61  the prepared sta
1f2d0 74 65 6d 65 6e 74 0a 2a 2a 20 74 68 61 74 20 69  tement.** that i
1f2e0 73 20 72 65 74 75 72 6e 65 64 20 28 74 68 65 20  s returned (the 
1f2f0 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f  [sqlite3_stmt] o
1f300 62 6a 65 63 74 29 20 63 6f 6e 74 61 69 6e 73 20  bject) contains 
1f310 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a  a copy of the.**
1f320 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20 74 65   original SQL te
1f330 78 74 2e 20 54 68 69 73 20 63 61 75 73 65 73 20  xt. This causes 
1f340 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  the [sqlite3_ste
1f350 70 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 74  p()] interface t
1f360 6f 0a 2a 2a 20 62 65 68 61 76 65 20 61 20 64 69  o.** behave a di
1f370 66 66 65 72 65 6e 74 6c 79 20 69 6e 20 74 77 6f  fferently in two
1f380 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c   ways:.**.** <ol
1f390 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 49 66 20  >.** <li>.** If 
1f3a0 74 68 65 20 64 61 74 61 62 61 73 65 20 73 63 68  the database sch
1f3b0 65 6d 61 20 63 68 61 6e 67 65 73 2c 20 69 6e 73  ema changes, ins
1f3c0 74 65 61 64 20 6f 66 20 72 65 74 75 72 6e 69 6e  tead of returnin
1f3d0 67 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41  g [SQLITE_SCHEMA
1f3e0 5d 20 61 73 20 69 74 0a 2a 2a 20 61 6c 77 61 79  ] as it.** alway
1f3f0 73 20 75 73 65 64 20 74 6f 20 64 6f 2c 20 5b 73  s used to do, [s
1f400 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77  qlite3_step()] w
1f410 69 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  ill automaticall
1f420 79 20 72 65 63 6f 6d 70 69 6c 65 20 74 68 65 20  y recompile the 
1f430 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  SQL.** statement
1f440 20 61 6e 64 20 74 72 79 20 74 6f 20 72 75 6e 20   and try to run 
1f450 69 74 20 61 67 61 69 6e 2e 20 20 49 66 20 74 68  it again.  If th
1f460 65 20 73 63 68 65 6d 61 20 68 61 73 20 63 68 61  e schema has cha
1f470 6e 67 65 64 20 69 6e 0a 2a 2a 20 61 20 77 61 79  nged in.** a way
1f480 20 74 68 61 74 20 6d 61 6b 65 73 20 74 68 65 20   that makes the 
1f490 73 74 61 74 65 6d 65 6e 74 20 6e 6f 20 6c 6f 6e  statement no lon
1f4a0 67 65 72 20 76 61 6c 69 64 2c 20 5b 73 71 6c 69  ger valid, [sqli
1f4b0 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c  te3_step()] will
1f4c0 20 73 74 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e   still.** return
1f4d0 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d   [SQLITE_SCHEMA]
1f4e0 2e 20 20 42 75 74 20 75 6e 6c 69 6b 65 20 74 68  .  But unlike th
1f4f0 65 20 6c 65 67 61 63 79 20 62 65 68 61 76 69 6f  e legacy behavio
1f500 72 2c 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d  r, [SQLITE_SCHEM
1f510 41 5d 20 69 73 0a 2a 2a 20 6e 6f 77 20 61 20 66  A] is.** now a f
1f520 61 74 61 6c 20 65 72 72 6f 72 2e 20 20 43 61 6c  atal error.  Cal
1f530 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72  ling [sqlite3_pr
1f540 65 70 61 72 65 5f 76 32 28 29 5d 20 61 67 61 69  epare_v2()] agai
1f550 6e 20 77 69 6c 6c 20 6e 6f 74 20 6d 61 6b 65 20  n will not make 
1f560 74 68 65 0a 2a 2a 20 65 72 72 6f 72 20 67 6f 20  the.** error go 
1f570 61 77 61 79 2e 20 20 4e 6f 74 65 3a 20 75 73 65  away.  Note: use
1f580 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
1f590 28 29 5d 20 74 6f 20 66 69 6e 64 20 74 68 65 20  ()] to find the 
1f5a0 74 65 78 74 0a 2a 2a 20 6f 66 20 74 68 65 20 70  text.** of the p
1f5b0 61 72 73 69 6e 67 20 65 72 72 6f 72 20 74 68 61  arsing error tha
1f5c0 74 20 72 65 73 75 6c 74 73 20 69 6e 20 61 6e 20  t results in an 
1f5d0 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20  [SQLITE_SCHEMA] 
1f5e0 72 65 74 75 72 6e 2e 0a 2a 2a 20 3c 2f 6c 69 3e  return..** </li>
1f5f0 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 57  .**.** <li>.** W
1f600 68 65 6e 20 61 6e 20 65 72 72 6f 72 20 6f 63 63  hen an error occ
1f610 75 72 73 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74  urs, [sqlite3_st
1f620 65 70 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72  ep()] will retur
1f630 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 64 65 74  n one of the det
1f640 61 69 6c 65 64 0a 2a 2a 20 5b 65 72 72 6f 72 20  ailed.** [error 
1f650 63 6f 64 65 73 5d 20 6f 72 20 5b 65 78 74 65 6e  codes] or [exten
1f660 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 73 5d  ded error codes]
1f670 2e 20 20 54 68 65 20 6c 65 67 61 63 79 20 62 65  .  The legacy be
1f680 68 61 76 69 6f 72 20 77 61 73 20 74 68 61 74 0a  havior was that.
1f690 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ** [sqlite3_step
1f6a0 28 29 5d 20 77 6f 75 6c 64 20 6f 6e 6c 79 20 72  ()] would only r
1f6b0 65 74 75 72 6e 20 61 20 67 65 6e 65 72 69 63 20  eturn a generic 
1f6c0 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 72  [SQLITE_ERROR] r
1f6d0 65 73 75 6c 74 20 63 6f 64 65 0a 2a 2a 20 61 6e  esult code.** an
1f6e0 64 20 79 6f 75 20 77 6f 75 6c 64 20 68 61 76 65  d you would have
1f6f0 20 74 6f 20 6d 61 6b 65 20 61 20 73 65 63 6f 6e   to make a secon
1f700 64 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  d call to [sqlit
1f710 65 33 5f 72 65 73 65 74 28 29 5d 20 69 6e 20 6f  e3_reset()] in o
1f720 72 64 65 72 0a 2a 2a 20 74 6f 20 66 69 6e 64 20  rder.** to find 
1f730 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 63  the underlying c
1f740 61 75 73 65 20 6f 66 20 74 68 65 20 70 72 6f 62  ause of the prob
1f750 6c 65 6d 2e 20 57 69 74 68 20 74 68 65 20 22 76  lem. With the "v
1f760 32 22 20 70 72 65 70 61 72 65 0a 2a 2a 20 69 6e  2" prepare.** in
1f770 74 65 72 66 61 63 65 73 2c 20 74 68 65 20 75 6e  terfaces, the un
1f780 64 65 72 6c 79 69 6e 67 20 72 65 61 73 6f 6e 20  derlying reason 
1f790 66 6f 72 20 74 68 65 20 65 72 72 6f 72 20 69 73  for the error is
1f7a0 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69   returned immedi
1f7b0 61 74 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a  ately..** </li>.
1f7c0 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 49  ** </ol>.**.** I
1f7d0 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
1f7e0 20 7b 48 31 33 30 31 31 7d 20 54 68 65 20 5b 73   {H13011} The [s
1f7f0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 64  qlite3_prepare(d
1f800 62 2c 7a 53 71 6c 2c 2e 2e 2e 29 5d 20 61 6e 64  b,zSql,...)] and
1f810 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
1f820 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
1f830 28 64 62 2c 7a 53 71 6c 2c 2e 2e 2e 29 5d 20 69  (db,zSql,...)] i
1f840 6e 74 65 72 66 61 63 65 73 20 69 6e 74 65 72 70  nterfaces interp
1f850 72 65 74 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  ret the.**      
1f860 20 20 20 20 74 65 78 74 20 69 6e 20 74 68 65 69      text in thei
1f870 72 20 7a 53 71 6c 20 70 61 72 61 6d 65 74 65 72  r zSql parameter
1f880 20 61 73 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a   as UTF-8..**.**
1f890 20 7b 48 31 33 30 31 32 7d 20 54 68 65 20 5b 73   {H13012} The [s
1f8a0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
1f8b0 28 64 62 2c 7a 53 71 6c 2c 2e 2e 2e 29 5d 20 61  (db,zSql,...)] a
1f8c0 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  nd.**          [
1f8d0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
1f8e0 36 5f 76 32 28 64 62 2c 7a 53 71 6c 2c 2e 2e 2e  6_v2(db,zSql,...
1f8f0 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 69 6e  )] interfaces in
1f900 74 65 72 70 72 65 74 20 74 68 65 0a 2a 2a 20 20  terpret the.**  
1f910 20 20 20 20 20 20 20 20 74 65 78 74 20 69 6e 20          text in 
1f920 74 68 65 69 72 20 7a 53 71 6c 20 70 61 72 61 6d  their zSql param
1f930 65 74 65 72 20 61 73 20 55 54 46 2d 31 36 20 69  eter as UTF-16 i
1f940 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74  n the native byt
1f950 65 20 6f 72 64 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b  e order..**.** {
1f960 48 31 33 30 31 33 7d 20 49 66 20 74 68 65 20 6e  H13013} If the n
1f970 42 79 74 65 20 61 72 67 75 6d 65 6e 74 20 74 6f  Byte argument to
1f980 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1f990 65 5f 76 32 28 64 62 2c 7a 53 71 6c 2c 6e 42 79  e_v2(db,zSql,nBy
1f9a0 74 65 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20  te,...)].**     
1f9b0 20 20 20 20 20 61 6e 64 20 69 74 73 20 76 61 72       and its var
1f9c0 69 61 6e 74 73 20 69 73 20 6c 65 73 73 20 74 68  iants is less th
1f9d0 61 6e 20 7a 65 72 6f 2c 20 74 68 65 20 53 51 4c  an zero, the SQL
1f9e0 20 74 65 78 74 20 69 73 0a 2a 2a 20 20 20 20 20   text is.**     
1f9f0 20 20 20 20 20 72 65 61 64 20 66 72 6f 6d 20 7a       read from z
1fa00 53 71 6c 20 69 73 20 72 65 61 64 20 75 70 20 74  Sql is read up t
1fa10 6f 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f  o the first zero
1fa20 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 0a   terminator..**.
1fa30 2a 2a 20 7b 48 31 33 30 31 34 7d 20 49 66 20 74  ** {H13014} If t
1fa40 68 65 20 6e 42 79 74 65 20 61 72 67 75 6d 65 6e  he nByte argumen
1fa50 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72  t to [sqlite3_pr
1fa60 65 70 61 72 65 5f 76 32 28 64 62 2c 7a 53 71 6c  epare_v2(db,zSql
1fa70 2c 6e 42 79 74 65 2c 2e 2e 2e 29 5d 0a 2a 2a 20  ,nByte,...)].** 
1fa80 20 20 20 20 20 20 20 20 20 61 6e 64 20 69 74 73           and its
1fa90 20 76 61 72 69 61 6e 74 73 20 69 73 20 6e 6f 6e   variants is non
1faa0 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20  -negative, then 
1fab0 61 74 20 6d 6f 73 74 20 6e 42 79 74 65 73 20 62  at most nBytes b
1fac0 79 74 65 73 20 6f 66 0a 2a 2a 20 20 20 20 20 20  ytes of.**      
1fad0 20 20 20 20 53 51 4c 20 74 65 78 74 20 69 73 20      SQL text is 
1fae0 72 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c 2e 0a  read from zSql..
1faf0 2a 2a 0a 2a 2a 20 7b 48 31 33 30 31 35 7d 20 49  **.** {H13015} I
1fb00 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  n [sqlite3_prepa
1fb10 72 65 5f 76 32 28 64 62 2c 7a 53 71 6c 2c 4e 2c  re_v2(db,zSql,N,
1fb20 50 2c 70 7a 54 61 69 6c 29 5d 20 61 6e 64 20 69  P,pzTail)] and i
1fb30 74 73 20 76 61 72 69 61 6e 74 73 0a 2a 2a 20 20  ts variants.**  
1fb40 20 20 20 20 20 20 20 20 69 66 20 74 68 65 20 7a          if the z
1fb50 53 71 6c 20 69 6e 70 75 74 20 74 65 78 74 20 63  Sql input text c
1fb60 6f 6e 74 61 69 6e 73 20 6d 6f 72 65 20 74 68 61  ontains more tha
1fb70 6e 20 6f 6e 65 20 53 51 4c 20 73 74 61 74 65 6d  n one SQL statem
1fb80 65 6e 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ent.**          
1fb90 61 6e 64 20 70 7a 54 61 69 6c 20 69 73 20 6e 6f  and pzTail is no
1fba0 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 2a 70 7a  t NULL, then *pz
1fbb0 54 61 69 6c 20 69 73 20 6d 61 64 65 20 74 6f 20  Tail is made to 
1fbc0 70 6f 69 6e 74 20 74 6f 20 74 68 65 0a 2a 2a 20  point to the.** 
1fbd0 20 20 20 20 20 20 20 20 20 66 69 72 73 74 20 62           first b
1fbe0 79 74 65 20 70 61 73 74 20 74 68 65 20 65 6e 64  yte past the end
1fbf0 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 53 51   of the first SQ
1fc00 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a  L statement in z
1fc10 53 71 6c 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20  Sql..**         
1fc20 20 3c 74 6f 64 6f 3e 57 68 61 74 20 64 6f 65 73   <todo>What does
1fc30 20 2a 70 7a 54 61 69 6c 20 70 6f 69 6e 74 20 74   *pzTail point t
1fc40 6f 20 69 66 20 74 68 65 72 65 20 69 73 20 6f 6e  o if there is on
1fc50 65 20 73 74 61 74 65 6d 65 6e 74 3f 3c 2f 74 6f  e statement?</to
1fc60 64 6f 3e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 30 31  do>.**.** {H1301
1fc70 36 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c 20  6} A successful 
1fc80 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
1fc90 5f 70 72 65 70 61 72 65 5f 76 32 28 64 62 2c 7a  _prepare_v2(db,z
1fca0 53 71 6c 2c 4e 2c 70 70 53 74 6d 74 2c 2e 2e 2e  Sql,N,ppStmt,...
1fcb0 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  )].**          o
1fcc0 72 20 6f 6e 65 20 6f 66 20 69 74 73 20 76 61 72  r one of its var
1fcd0 69 61 6e 74 73 20 77 72 69 74 65 73 20 69 6e 74  iants writes int
1fce0 6f 20 2a 70 70 53 74 6d 74 20 61 20 70 6f 69 6e  o *ppStmt a poin
1fcf0 74 65 72 20 74 6f 20 61 20 6e 65 77 0a 2a 2a 20  ter to a new.** 
1fd00 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72           [prepar
1fd10 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 72  ed statement] or
1fd20 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 4e 55   a pointer to NU
1fd30 4c 4c 20 69 66 20 7a 53 71 6c 20 63 6f 6e 74 61  LL if zSql conta
1fd40 69 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ins.**          
1fd50 6e 6f 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68  nothing other th
1fd60 61 6e 20 77 68 69 74 65 73 70 61 63 65 20 6f 72  an whitespace or
1fd70 20 63 6f 6d 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a   comments..**.**
1fd80 20 7b 48 31 33 30 31 39 7d 20 54 68 65 20 5b 73   {H13019} The [s
1fd90 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
1fda0 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 61  2()] interface a
1fdb0 6e 64 20 69 74 73 20 76 61 72 69 61 6e 74 73 20  nd its variants 
1fdc0 72 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20  return.**       
1fdd0 20 20 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f     [SQLITE_OK] o
1fde0 72 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65  r an appropriate
1fdf0 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 75 70   [error code] up
1fe00 6f 6e 20 66 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a  on failure..**.*
1fe10 2a 20 7b 48 31 33 30 32 31 7d 20 42 65 66 6f 72  * {H13021} Befor
1fe20 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  e [sqlite3_prepa
1fe30 72 65 28 64 62 2c 7a 53 71 6c 2c 6e 42 79 74 65  re(db,zSql,nByte
1fe40 2c 70 70 53 74 6d 74 2c 70 7a 54 61 69 6c 29 5d  ,ppStmt,pzTail)]
1fe50 20 6f 72 20 69 74 73 0a 2a 2a 20 20 20 20 20 20   or its.**      
1fe60 20 20 20 20 76 61 72 69 61 6e 74 73 20 72 65 74      variants ret
1fe70 75 72 6e 73 20 61 6e 20 65 72 72 6f 72 20 28 61  urns an error (a
1fe80 6e 79 20 76 61 6c 75 65 20 6f 74 68 65 72 20 74  ny value other t
1fe90 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 29  han [SQLITE_OK])
1fea0 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  ,.**          th
1feb0 65 79 20 66 69 72 73 74 20 73 65 74 20 2a 70 70  ey first set *pp
1fec0 53 74 6d 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f  Stmt to NULL..*/
1fed0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65  .int sqlite3_pre
1fee0 70 61 72 65 28 0a 20 20 73 71 6c 69 74 65 33 20  pare(.  sqlite3 
1fef0 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20  *db,            
1ff00 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64  /* Database hand
1ff10 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  le */.  const ch
1ff20 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20  ar *zSql,       
1ff30 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  /* SQL statement
1ff40 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20  , UTF-8 encoded 
1ff50 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20  */.  int nByte, 
1ff60 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
1ff70 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  Maximum length o
1ff80 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e  f zSql in bytes.
1ff90 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74   */.  sqlite3_st
1ffa0 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a  mt **ppStmt,  /*
1ffb0 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20   OUT: Statement 
1ffc0 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
1ffd0 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20  t char **pzTail 
1ffe0 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e      /* OUT: Poin
1fff0 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f  ter to unused po
20000 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f  rtion of zSql */
20010 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
20020 70 72 65 70 61 72 65 5f 76 32 28 0a 20 20 73 71  prepare_v2(.  sq
20030 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
20040 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
20050 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  e handle */.  co
20060 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20  nst char *zSql, 
20070 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61        /* SQL sta
20080 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e  tement, UTF-8 en
20090 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e  coded */.  int n
200a0 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20  Byte,           
200b0 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65     /* Maximum le
200c0 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20  ngth of zSql in 
200d0 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69  bytes. */.  sqli
200e0 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d  te3_stmt **ppStm
200f0 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74  t,  /* OUT: Stat
20100 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a  ement handle */.
20110 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70    const char **p
20120 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54  zTail     /* OUT
20130 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75  : Pointer to unu
20140 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a  sed portion of z
20150 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71  Sql */.);.int sq
20160 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
20170 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
20180 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61             /* Da
20190 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f  tabase handle */
201a0 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a  .  const void *z
201b0 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51  Sql,       /* SQ
201c0 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46  L statement, UTF
201d0 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20  -16 encoded */. 
201e0 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20   int nByte,     
201f0 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69           /* Maxi
20200 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53  mum length of zS
20210 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a  ql in bytes. */.
20220 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a    sqlite3_stmt *
20230 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54  *ppStmt,  /* OUT
20240 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64  : Statement hand
20250 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f  le */.  const vo
20260 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20  id **pzTail     
20270 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20  /* OUT: Pointer 
20280 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f  to unused portio
20290 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a  n of zSql */.);.
202a0 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70  int sqlite3_prep
202b0 61 72 65 31 36 5f 76 32 28 0a 20 20 73 71 6c 69  are16_v2(.  sqli
202c0 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
202d0 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20      /* Database 
202e0 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
202f0 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20  t void *zSql,   
20300 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65      /* SQL state
20310 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63  ment, UTF-16 enc
20320 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42  oded */.  int nB
20330 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20  yte,            
20340 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e    /* Maximum len
20350 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62  gth of zSql in b
20360 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74  ytes. */.  sqlit
20370 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74  e3_stmt **ppStmt
20380 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65  ,  /* OUT: State
20390 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  ment handle */. 
203a0 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a   const void **pz
203b0 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a  Tail     /* OUT:
203c0 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73   Pointer to unus
203d0 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53  ed portion of zS
203e0 71 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  ql */.);../*.** 
203f0 43 41 50 49 52 45 46 3a 20 52 65 74 72 69 65 76  CAPIREF: Retriev
20400 69 6e 67 20 53 74 61 74 65 6d 65 6e 74 20 53 51  ing Statement SQ
20410 4c 20 7b 48 31 33 31 30 30 7d 20 3c 48 31 33 30  L {H13100} <H130
20420 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69  00>.**.** This i
20430 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20  nterface can be 
20440 75 73 65 64 20 74 6f 20 72 65 74 72 69 65 76 65  used to retrieve
20450 20 61 20 73 61 76 65 64 20 63 6f 70 79 20 6f 66   a saved copy of
20460 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 0a 2a 2a   the original.**
20470 20 53 51 4c 20 74 65 78 74 20 75 73 65 64 20 74   SQL text used t
20480 6f 20 63 72 65 61 74 65 20 61 20 5b 70 72 65 70  o create a [prep
20490 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
204a0 69 66 20 74 68 61 74 20 73 74 61 74 65 6d 65 6e  if that statemen
204b0 74 20 77 61 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65  t was.** compile
204c0 64 20 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b  d using either [
204d0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
204e0 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  v2()] or [sqlite
204f0 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
20500 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  ]..**.** INVARIA
20510 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 31  NTS:.**.** {H131
20520 30 31 7d 20 49 66 20 74 68 65 20 5b 70 72 65 70  01} If the [prep
20530 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
20540 70 61 73 73 65 64 20 61 73 20 74 68 65 20 61 72  passed as the ar
20550 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 20 20 20  gument to.**    
20560 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 73        [sqlite3_s
20570 71 6c 28 29 5d 20 77 61 73 20 63 6f 6d 70 69 6c  ql()] was compil
20580 65 64 20 75 73 69 6e 67 20 65 69 74 68 65 72 20  ed using either 
20590 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
205a0 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a 20 20 20 20  _v2()] or.**    
205b0 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 70        [sqlite3_p
205c0 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2c 20  repare16_v2()], 
205d0 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 73 71  then [sqlite3_sq
205e0 6c 28 29 5d 20 72 65 74 75 72 6e 73 0a 2a 2a 20  l()] returns.** 
205f0 20 20 20 20 20 20 20 20 20 61 20 70 6f 69 6e 74           a point
20600 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72  er to a zero-ter
20610 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 20 63  minated string c
20620 6f 6e 74 61 69 6e 69 6e 67 20 61 20 55 54 46 2d  ontaining a UTF-
20630 38 20 72 65 6e 64 65 72 69 6e 67 0a 2a 2a 20 20  8 rendering.**  
20640 20 20 20 20 20 20 20 20 6f 66 20 74 68 65 20 6f          of the o
20650 72 69 67 69 6e 61 6c 20 53 51 4c 20 73 74 61 74  riginal SQL stat
20660 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  ement..**.** {H1
20670 33 31 30 32 7d 20 49 66 20 74 68 65 20 5b 70 72  3102} If the [pr
20680 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
20690 5d 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  ] passed as the 
206a0 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 20  argument to.**  
206b0 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
206c0 5f 73 71 6c 28 29 5d 20 77 61 73 20 63 6f 6d 70  _sql()] was comp
206d0 69 6c 65 64 20 75 73 69 6e 67 20 65 69 74 68 65  iled using eithe
206e0 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  r [sqlite3_prepa
206f0 72 65 28 29 5d 20 6f 72 0a 2a 2a 20 20 20 20 20  re()] or.**     
20700 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 70 72       [sqlite3_pr
20710 65 70 61 72 65 31 36 28 29 5d 2c 20 74 68 65 6e  epare16()], then
20720 20 5b 73 71 6c 69 74 65 33 5f 73 71 6c 28 29 5d   [sqlite3_sql()]
20730 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20   returns a NULL 
20740 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b  pointer..**.** {
20750 48 31 33 31 30 33 7d 20 54 68 65 20 73 74 72 69  H13103} The stri
20760 6e 67 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b  ng returned by [
20770 73 71 6c 69 74 65 33 5f 73 71 6c 28 53 29 5d 20  sqlite3_sql(S)] 
20780 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 74  is valid until t
20790 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  he.**          [
207a0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
207b0 6e 74 5d 20 53 20 69 73 20 64 65 6c 65 74 65 64  nt] S is deleted
207c0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
207d0 66 69 6e 61 6c 69 7a 65 28 53 29 5d 2e 0a 2a 2f  finalize(S)]..*/
207e0 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
207f0 69 74 65 33 5f 73 71 6c 28 73 71 6c 69 74 65 33  ite3_sql(sqlite3
20800 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a  _stmt *pStmt);..
20810 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
20820 44 79 6e 61 6d 69 63 61 6c 6c 79 20 54 79 70 65  Dynamically Type
20830 64 20 56 61 6c 75 65 20 4f 62 6a 65 63 74 20 7b  d Value Object {
20840 48 31 35 30 30 30 7d 20 3c 53 32 30 32 30 30 3e  H15000} <S20200>
20850 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70  .** KEYWORDS: {p
20860 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
20870 5f 76 61 6c 75 65 7d 20 7b 75 6e 70 72 6f 74 65  _value} {unprote
20880 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
20890 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  ue}.**.** SQLite
208a0 20 75 73 65 73 20 74 68 65 20 73 71 6c 69 74 65   uses the sqlite
208b0 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 74  3_value object t
208c0 6f 20 72 65 70 72 65 73 65 6e 74 20 61 6c 6c 20  o represent all 
208d0 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20 63  values.** that c
208e0 61 6e 20 62 65 20 73 74 6f 72 65 64 20 69 6e 20  an be stored in 
208f0 61 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65  a database table
20900 2e 20 53 51 4c 69 74 65 20 75 73 65 73 20 64 79  . SQLite uses dy
20910 6e 61 6d 69 63 20 74 79 70 69 6e 67 0a 2a 2a 20  namic typing.** 
20920 66 6f 72 20 74 68 65 20 76 61 6c 75 65 73 20 69  for the values i
20930 74 20 73 74 6f 72 65 73 2e 20 56 61 6c 75 65 73  t stores. Values
20940 20 73 74 6f 72 65 64 20 69 6e 20 73 71 6c 69 74   stored in sqlit
20950 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73  e3_value objects
20960 0a 2a 2a 20 63 61 6e 20 62 65 20 69 6e 74 65 67  .** can be integ
20970 65 72 73 2c 20 66 6c 6f 61 74 69 6e 67 20 70 6f  ers, floating po
20980 69 6e 74 20 76 61 6c 75 65 73 2c 20 73 74 72 69  int values, stri
20990 6e 67 73 2c 20 42 4c 4f 42 73 2c 20 6f 72 20 4e  ngs, BLOBs, or N
209a0 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 73 71  ULL..**.** An sq
209b0 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
209c0 63 74 20 6d 61 79 20 62 65 20 65 69 74 68 65 72  ct may be either
209d0 20 22 70 72 6f 74 65 63 74 65 64 22 20 6f 72 20   "protected" or 
209e0 22 75 6e 70 72 6f 74 65 63 74 65 64 22 2e 0a 2a  "unprotected"..*
209f0 2a 20 53 6f 6d 65 20 69 6e 74 65 72 66 61 63 65  * Some interface
20a00 73 20 72 65 71 75 69 72 65 20 61 20 70 72 6f 74  s require a prot
20a10 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
20a20 6c 75 65 2e 20 20 4f 74 68 65 72 20 69 6e 74 65  lue.  Other inte
20a30 72 66 61 63 65 73 0a 2a 2a 20 77 69 6c 6c 20 61  rfaces.** will a
20a40 63 63 65 70 74 20 65 69 74 68 65 72 20 61 20 70  ccept either a p
20a50 72 6f 74 65 63 74 65 64 20 6f 72 20 61 6e 20 75  rotected or an u
20a60 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
20a70 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 20 45 76 65  e3_value..** Eve
20a80 72 79 20 69 6e 74 65 72 66 61 63 65 20 74 68 61  ry interface tha
20a90 74 20 61 63 63 65 70 74 73 20 73 71 6c 69 74 65  t accepts sqlite
20aa0 33 5f 76 61 6c 75 65 20 61 72 67 75 6d 65 6e 74  3_value argument
20ab0 73 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77  s specifies.** w
20ac0 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 69 74  hether or not it
20ad0 20 72 65 71 75 69 72 65 73 20 61 20 70 72 6f 74   requires a prot
20ae0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
20af0 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74  lue..**.** The t
20b00 65 72 6d 73 20 22 70 72 6f 74 65 63 74 65 64 22  erms "protected"
20b10 20 61 6e 64 20 22 75 6e 70 72 6f 74 65 63 74 65   and "unprotecte
20b20 64 22 20 72 65 66 65 72 20 74 6f 20 77 68 65 74  d" refer to whet
20b30 68 65 72 20 6f 72 20 6e 6f 74 0a 2a 2a 20 61 20  her or not.** a 
20b40 6d 75 74 65 78 20 69 73 20 68 65 6c 64 2e 20 20  mutex is held.  
20b50 41 20 69 6e 74 65 72 6e 61 6c 20 6d 75 74 65 78  A internal mutex
20b60 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61 20 70   is held for a p
20b70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69  rotected.** sqli
20b80 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
20b90 20 62 75 74 20 6e 6f 20 6d 75 74 65 78 20 69 73   but no mutex is
20ba0 20 68 65 6c 64 20 66 6f 72 20 61 6e 20 75 6e 70   held for an unp
20bb0 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69  rotected.** sqli
20bc0 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
20bd0 2e 20 20 49 66 20 53 51 4c 69 74 65 20 69 73 20  .  If SQLite is 
20be0 63 6f 6d 70 69 6c 65 64 20 74 6f 20 62 65 20 73  compiled to be s
20bf0 69 6e 67 6c 65 2d 74 68 72 65 61 64 65 64 0a 2a  ingle-threaded.*
20c00 2a 20 28 77 69 74 68 20 5b 53 51 4c 49 54 45 5f  * (with [SQLITE_
20c10 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 61 6e  THREADSAFE=0] an
20c20 64 20 77 69 74 68 20 5b 73 71 6c 69 74 65 33 5f  d with [sqlite3_
20c30 74 68 72 65 61 64 73 61 66 65 28 29 5d 20 72 65  threadsafe()] re
20c40 74 75 72 6e 69 6e 67 20 30 29 0a 2a 2a 20 6f 72  turning 0).** or
20c50 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 72 75   if SQLite is ru
20c60 6e 20 69 6e 20 6f 6e 65 20 6f 66 20 72 65 64 75  n in one of redu
20c70 63 65 64 20 6d 75 74 65 78 20 6d 6f 64 65 73 20  ced mutex modes 
20c80 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  .** [SQLITE_CONF
20c90 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d  IG_SINGLETHREAD]
20ca0 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46   or [SQLITE_CONF
20cb0 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 0a  IG_MULTITHREAD].
20cc0 2a 2a 20 74 68 65 6e 20 74 68 65 72 65 20 69 73  ** then there is
20cd0 20 6e 6f 20 64 69 73 74 69 6e 63 74 69 6f 6e 20   no distinction 
20ce0 62 65 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65  between protecte
20cf0 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65  d and unprotecte
20d00 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c  d.** sqlite3_val
20d10 75 65 20 6f 62 6a 65 63 74 73 20 61 6e 64 20 74  ue objects and t
20d20 68 65 79 20 63 61 6e 20 62 65 20 75 73 65 64 20  hey can be used 
20d30 69 6e 74 65 72 63 68 61 6e 67 65 61 62 6c 79 2e  interchangeably.
20d40 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 6f    However,.** fo
20d50 72 20 6d 61 78 69 6d 75 6d 20 63 6f 64 65 20 70  r maximum code p
20d60 6f 72 74 61 62 69 6c 69 74 79 20 69 74 20 69 73  ortability it is
20d70 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61   recommended tha
20d80 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a  t applications.*
20d90 2a 20 73 74 69 6c 6c 20 6d 61 6b 65 20 74 68 65  * still make the
20da0 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74   distinction bet
20db0 77 65 65 6e 20 62 65 74 77 65 65 6e 20 70 72 6f  ween between pro
20dc0 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70 72 6f  tected and unpro
20dd0 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65  tected.** sqlite
20de0 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20  3_value objects 
20df0 65 76 65 6e 20 77 68 65 6e 20 6e 6f 74 20 73 74  even when not st
20e00 72 69 63 74 6c 79 20 72 65 71 75 69 72 65 64 2e  rictly required.
20e10 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
20e20 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73  e3_value objects
20e30 20 74 68 61 74 20 61 72 65 20 70 61 73 73 65 64   that are passed
20e40 20 61 73 20 70 61 72 61 6d 65 74 65 72 73 20 69   as parameters i
20e50 6e 74 6f 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65  nto the.** imple
20e60 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 61 70  mentation of [ap
20e70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
20e80 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d  d SQL functions]
20e90 20 61 72 65 20 70 72 6f 74 65 63 74 65 64 2e 0a   are protected..
20ea0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 76  ** The sqlite3_v
20eb0 61 6c 75 65 20 6f 62 6a 65 63 74 20 72 65 74 75  alue object retu
20ec0 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69  rned by.** [sqli
20ed0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65  te3_column_value
20ee0 28 29 5d 20 69 73 20 75 6e 70 72 6f 74 65 63 74  ()] is unprotect
20ef0 65 64 2e 0a 2a 2a 20 55 6e 70 72 6f 74 65 63 74  ed..** Unprotect
20f00 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
20f10 20 6f 62 6a 65 63 74 73 20 6d 61 79 20 6f 6e 6c   objects may onl
20f20 79 20 62 65 20 75 73 65 64 20 77 69 74 68 0a 2a  y be used with.*
20f30 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  * [sqlite3_resul
20f40 74 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b  t_value()] and [
20f50 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c  sqlite3_bind_val
20f60 75 65 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 5b 73  ue()]..** The [s
20f70 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f  qlite3_value_blo
20f80 62 20 7c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  b | sqlite3_valu
20f90 65 5f 74 79 70 65 28 29 5d 20 66 61 6d 69 6c 79  e_type()] family
20fa0 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65   of.** interface
20fb0 73 20 72 65 71 75 69 72 65 20 70 72 6f 74 65 63  s require protec
20fc0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
20fd0 65 20 6f 62 6a 65 63 74 73 2e 0a 2a 2f 0a 74 79  e objects..*/.ty
20fe0 70 65 64 65 66 20 73 74 72 75 63 74 20 4d 65 6d  pedef struct Mem
20ff0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 3b 0a   sqlite3_value;.
21000 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
21010 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 43 6f   SQL Function Co
21020 6e 74 65 78 74 20 4f 62 6a 65 63 74 20 7b 48 31  ntext Object {H1
21030 36 30 30 31 7d 20 3c 53 32 30 32 30 30 3e 0a 2a  6001} <S20200>.*
21040 2a 0a 2a 2a 20 54 68 65 20 63 6f 6e 74 65 78 74  *.** The context
21050 20 69 6e 20 77 68 69 63 68 20 61 6e 20 53 51 4c   in which an SQL
21060 20 66 75 6e 63 74 69 6f 6e 20 65 78 65 63 75 74   function execut
21070 65 73 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20  es is stored in 
21080 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  an.** sqlite3_co
21090 6e 74 65 78 74 20 6f 62 6a 65 63 74 2e 20 20 41  ntext object.  A
210a0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 73   pointer to an s
210b0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f  qlite3_context o
210c0 62 6a 65 63 74 0a 2a 2a 20 69 73 20 61 6c 77 61  bject.** is alwa
210d0 79 73 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  ys first paramet
210e0 65 72 20 74 6f 20 5b 61 70 70 6c 69 63 61 74 69  er to [applicati
210f0 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66  on-defined SQL f
21100 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68  unctions]..** Th
21110 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
21120 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
21130 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  on implementatio
21140 6e 20 77 69 6c 6c 20 70 61 73 73 20 74 68 69 73  n will pass this
21150 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 68 72 6f  .** pointer thro
21160 75 67 68 20 69 6e 74 6f 20 63 61 6c 6c 73 20 74  ugh into calls t
21170 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  o [sqlite3_resul
21180 74 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f  t_int | sqlite3_
21190 72 65 73 75 6c 74 28 29 5d 2c 0a 2a 2a 20 5b 73  result()],.** [s
211a0 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
211b0 5f 63 6f 6e 74 65 78 74 28 29 5d 2c 20 5b 73 71  _context()], [sq
211c0 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28  lite3_user_data(
211d0 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
211e0 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c  context_db_handl
211f0 65 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 67  e()], [sqlite3_g
21200 65 74 5f 61 75 78 64 61 74 61 28 29 5d 2c 0a 2a  et_auxdata()],.*
21210 2a 20 61 6e 64 2f 6f 72 20 5b 73 71 6c 69 74 65  * and/or [sqlite
21220 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 5d  3_set_auxdata()]
21230 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
21240 75 63 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74  uct sqlite3_cont
21250 65 78 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ext sqlite3_cont
21260 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ext;../*.** CAPI
21270 33 52 45 46 3a 20 42 69 6e 64 69 6e 67 20 56 61  3REF: Binding Va
21280 6c 75 65 73 20 54 6f 20 50 72 65 70 61 72 65 64  lues To Prepared
21290 20 53 74 61 74 65 6d 65 6e 74 73 20 7b 48 31 33   Statements {H13
212a0 35 30 30 7d 20 3c 53 37 30 33 30 30 3e 0a 2a 2a  500} <S70300>.**
212b0 20 4b 45 59 57 4f 52 44 53 3a 20 7b 68 6f 73 74   KEYWORDS: {host
212c0 20 70 61 72 61 6d 65 74 65 72 7d 20 7b 68 6f 73   parameter} {hos
212d0 74 20 70 61 72 61 6d 65 74 65 72 73 7d 20 7b 68  t parameters} {h
212e0 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61  ost parameter na
212f0 6d 65 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  me}.** KEYWORDS:
21300 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 7d   {SQL parameter}
21310 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73   {SQL parameters
21320 7d 20 7b 70 61 72 61 6d 65 74 65 72 20 62 69 6e  } {parameter bin
21330 64 69 6e 67 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20 74  ding}.**.** In t
21340 68 65 20 53 51 4c 20 73 74 72 69 6e 67 73 20 69  he SQL strings i
21350 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  nput to [sqlite3
21360 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61  _prepare_v2()] a
21370 6e 64 20 69 74 73 20 76 61 72 69 61 6e 74 73 2c  nd its variants,
21380 0a 2a 2a 20 6c 69 74 65 72 61 6c 73 20 6d 61 79  .** literals may
21390 20 62 65 20 72 65 70 6c 61 63 65 64 20 62 79 20   be replaced by 
213a0 61 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20 6f  a parameter in o
213b0 6e 65 20 6f 66 20 74 68 65 73 65 20 66 6f 72 6d  ne of these form
213c0 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  s:.**.** <ul>.**
213d0 20 3c 6c 69 3e 20 20 3f 0a 2a 2a 20 3c 6c 69 3e   <li>  ?.** <li>
213e0 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20 20    ?NNN.** <li>  
213f0 3a 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 40 56  :VVV.** <li>  @V
21400 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 24 56 56 56  VV.** <li>  $VVV
21410 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
21420 49 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  In the parameter
21430 20 66 6f 72 6d 73 20 73 68 6f 77 6e 20 61 62 6f   forms shown abo
21440 76 65 20 4e 4e 4e 20 69 73 20 61 6e 20 69 6e 74  ve NNN is an int
21450 65 67 65 72 20 6c 69 74 65 72 61 6c 2c 0a 2a 2a  eger literal,.**
21460 20 61 6e 64 20 56 56 56 20 69 73 20 61 6e 20 61   and VVV is an a
21470 6c 70 68 61 2d 6e 75 6d 65 72 69 63 20 70 61 72  lpha-numeric par
21480 61 6d 65 74 65 72 20 6e 61 6d 65 2e 20 54 68 65  ameter name. The
21490 20 76 61 6c 75 65 73 20 6f 66 20 74 68 65 73 65   values of these
214a0 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 20 28  .** parameters (
214b0 61 6c 73 6f 20 63 61 6c 6c 65 64 20 22 68 6f 73  also called "hos
214c0 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65  t parameter name
214d0 73 22 20 6f 72 20 22 53 51 4c 20 70 61 72 61 6d  s" or "SQL param
214e0 65 74 65 72 73 22 29 0a 2a 2a 20 63 61 6e 20 62  eters").** can b
214f0 65 20 73 65 74 20 75 73 69 6e 67 20 74 68 65 20  e set using the 
21500 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29  sqlite3_bind_*()
21510 20 72 6f 75 74 69 6e 65 73 20 64 65 66 69 6e 65   routines define
21520 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  d here..**.** Th
21530 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
21540 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
21550 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65  bind_*() routine
21560 73 20 69 73 20 61 6c 77 61 79 73 0a 2a 2a 20 61  s is always.** a
21570 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
21580 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f  [sqlite3_stmt] o
21590 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 66  bject returned f
215a0 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  rom.** [sqlite3_
215b0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
215c0 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e 0a 2a   its variants..*
215d0 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  *.** The second 
215e0 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20  argument is the 
215f0 69 6e 64 65 78 20 6f 66 20 74 68 65 20 53 51 4c  index of the SQL
21600 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62 65   parameter to be
21610 20 73 65 74 2e 0a 2a 2a 20 54 68 65 20 6c 65 66   set..** The lef
21620 74 6d 6f 73 74 20 53 51 4c 20 70 61 72 61 6d 65  tmost SQL parame
21630 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78  ter has an index
21640 20 6f 66 20 31 2e 20 20 57 68 65 6e 20 74 68 65   of 1.  When the
21650 20 73 61 6d 65 20 6e 61 6d 65 64 0a 2a 2a 20 53   same named.** S
21660 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  QL parameter is 
21670 75 73 65 64 20 6d 6f 72 65 20 74 68 61 6e 20 6f  used more than o
21680 6e 63 65 2c 20 73 65 63 6f 6e 64 20 61 6e 64 20  nce, second and 
21690 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 6f 63  subsequent.** oc
216a0 63 75 72 72 65 6e 63 65 73 20 68 61 76 65 20 74  currences have t
216b0 68 65 20 73 61 6d 65 20 69 6e 64 65 78 20 61 73  he same index as
216c0 20 74 68 65 20 66 69 72 73 74 20 6f 63 63 75 72   the first occur
216d0 72 65 6e 63 65 2e 0a 2a 2a 20 54 68 65 20 69 6e  rence..** The in
216e0 64 65 78 20 66 6f 72 20 6e 61 6d 65 64 20 70 61  dex for named pa
216f0 72 61 6d 65 74 65 72 73 20 63 61 6e 20 62 65 20  rameters can be 
21700 6c 6f 6f 6b 65 64 20 75 70 20 75 73 69 6e 67 20  looked up using 
21710 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
21720 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69  bind_parameter_i
21730 6e 64 65 78 28 29 5d 20 41 50 49 20 69 66 20 64  ndex()] API if d
21740 65 73 69 72 65 64 2e 20 20 54 68 65 20 69 6e 64  esired.  The ind
21750 65 78 0a 2a 2a 20 66 6f 72 20 22 3f 4e 4e 4e 22  ex.** for "?NNN"
21760 20 70 61 72 61 6d 65 74 65 72 73 20 69 73 20 74   parameters is t
21770 68 65 20 76 61 6c 75 65 20 6f 66 20 4e 4e 4e 2e  he value of NNN.
21780 0a 2a 2a 20 54 68 65 20 4e 4e 4e 20 76 61 6c 75  .** The NNN valu
21790 65 20 6d 75 73 74 20 62 65 20 62 65 74 77 65 65  e must be betwee
217a0 6e 20 31 20 61 6e 64 20 74 68 65 20 5b 73 71 6c  n 1 and the [sql
217b0 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a  ite3_limit()].**
217c0 20 70 61 72 61 6d 65 74 65 72 20 5b 53 51 4c 49   parameter [SQLI
217d0 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c  TE_LIMIT_VARIABL
217e0 45 5f 4e 55 4d 42 45 52 5d 20 28 64 65 66 61 75  E_NUMBER] (defau
217f0 6c 74 20 76 61 6c 75 65 3a 20 39 39 39 29 2e 0a  lt value: 999)..
21800 2a 2a 0a 2a 2a 20 54 68 65 20 74 68 69 72 64 20  **.** The third 
21810 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20  argument is the 
21820 76 61 6c 75 65 20 74 6f 20 62 69 6e 64 20 74 6f  value to bind to
21830 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a   the parameter..
21840 2a 2a 0a 2a 2a 20 49 6e 20 74 68 6f 73 65 20 72  **.** In those r
21850 6f 75 74 69 6e 65 73 20 74 68 61 74 20 68 61 76  outines that hav
21860 65 20 61 20 66 6f 75 72 74 68 20 61 72 67 75 6d  e a fourth argum
21870 65 6e 74 2c 20 69 74 73 20 76 61 6c 75 65 20 69  ent, its value i
21880 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20  s the.** number 
21890 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20  of bytes in the 
218a0 70 61 72 61 6d 65 74 65 72 2e 20 20 54 6f 20 62  parameter.  To b
218b0 65 20 63 6c 65 61 72 3a 20 74 68 65 20 76 61 6c  e clear: the val
218c0 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d  ue is the.** num
218d0 62 65 72 20 6f 66 20 3c 75 3e 62 79 74 65 73 3c  ber of <u>bytes<
218e0 2f 75 3e 20 69 6e 20 74 68 65 20 76 61 6c 75 65  /u> in the value
218f0 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72  , not the number
21900 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e 0a   of characters..
21910 2a 2a 20 49 66 20 74 68 65 20 66 6f 75 72 74 68  ** If the fourth
21920 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6e 65   parameter is ne
21930 67 61 74 69 76 65 2c 20 74 68 65 20 6c 65 6e 67  gative, the leng
21940 74 68 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67  th of the string
21950 20 69 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65   is.** the numbe
21960 72 20 6f 66 20 62 79 74 65 73 20 75 70 20 74 6f  r of bytes up to
21970 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20   the first zero 
21980 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a  terminator..**.*
21990 2a 20 54 68 65 20 66 69 66 74 68 20 61 72 67 75  * The fifth argu
219a0 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
219b0 62 69 6e 64 5f 62 6c 6f 62 28 29 2c 20 73 71 6c  bind_blob(), sql
219c0 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29  ite3_bind_text()
219d0 2c 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33  , and.** sqlite3
219e0 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 20 69  _bind_text16() i
219f0 73 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 75  s a destructor u
21a00 73 65 64 20 74 6f 20 64 69 73 70 6f 73 65 20 6f  sed to dispose o
21a10 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 0a 2a 2a  f the BLOB or.**
21a20 20 73 74 72 69 6e 67 20 61 66 74 65 72 20 53 51   string after SQ
21a30 4c 69 74 65 20 68 61 73 20 66 69 6e 69 73 68 65  Lite has finishe
21a40 64 20 77 69 74 68 20 69 74 2e 20 49 66 20 74 68  d with it. If th
21a50 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74  e fifth argument
21a60 20 69 73 0a 2a 2a 20 74 68 65 20 73 70 65 63 69   is.** the speci
21a70 61 6c 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45  al value [SQLITE
21a80 5f 53 54 41 54 49 43 5d 2c 20 74 68 65 6e 20 53  _STATIC], then S
21a90 51 4c 69 74 65 20 61 73 73 75 6d 65 73 20 74 68  QLite assumes th
21aa0 61 74 20 74 68 65 0a 2a 2a 20 69 6e 66 6f 72 6d  at the.** inform
21ab0 61 74 69 6f 6e 20 69 73 20 69 6e 20 73 74 61 74  ation is in stat
21ac0 69 63 2c 20 75 6e 6d 61 6e 61 67 65 64 20 73 70  ic, unmanaged sp
21ad0 61 63 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74  ace and does not
21ae0 20 6e 65 65 64 20 74 6f 20 62 65 20 66 72 65 65   need to be free
21af0 64 2e 0a 2a 2a 20 49 66 20 74 68 65 20 66 69 66  d..** If the fif
21b00 74 68 20 61 72 67 75 6d 65 6e 74 20 68 61 73 20  th argument has 
21b10 74 68 65 20 76 61 6c 75 65 20 5b 53 51 4c 49 54  the value [SQLIT
21b20 45 5f 54 52 41 4e 53 49 45 4e 54 5d 2c 20 74 68  E_TRANSIENT], th
21b30 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 61 6b  en.** SQLite mak
21b40 65 73 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61  es its own priva
21b50 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20 64  te copy of the d
21b60 61 74 61 20 69 6d 6d 65 64 69 61 74 65 6c 79 2c  ata immediately,
21b70 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65 20 73   before.** the s
21b80 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20  qlite3_bind_*() 
21b90 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 2e  routine returns.
21ba0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
21bb0 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62  e3_bind_zeroblob
21bc0 28 29 20 72 6f 75 74 69 6e 65 20 62 69 6e 64 73  () routine binds
21bd0 20 61 20 42 4c 4f 42 20 6f 66 20 6c 65 6e 67 74   a BLOB of lengt
21be0 68 20 4e 20 74 68 61 74 0a 2a 2a 20 69 73 20 66  h N that.** is f
21bf0 69 6c 6c 65 64 20 77 69 74 68 20 7a 65 72 6f 65  illed with zeroe
21c00 73 2e 20 20 41 20 7a 65 72 6f 62 6c 6f 62 20 75  s.  A zeroblob u
21c10 73 65 73 20 61 20 66 69 78 65 64 20 61 6d 6f 75  ses a fixed amou
21c20 6e 74 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a 20  nt of memory.** 
21c30 28 6a 75 73 74 20 61 6e 20 69 6e 74 65 67 65 72  (just an integer
21c40 20 74 6f 20 68 6f 6c 64 20 69 74 73 20 73 69 7a   to hold its siz
21c50 65 29 20 77 68 69 6c 65 20 69 74 20 69 73 20 62  e) while it is b
21c60 65 69 6e 67 20 70 72 6f 63 65 73 73 65 64 2e 0a  eing processed..
21c70 2a 2a 20 5a 65 72 6f 62 6c 6f 62 73 20 61 72 65  ** Zeroblobs are
21c80 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 73 65 72   intended to ser
21c90 76 65 20 61 73 20 70 6c 61 63 65 68 6f 6c 64 65  ve as placeholde
21ca0 72 73 20 66 6f 72 20 42 4c 4f 42 73 20 77 68 6f  rs for BLOBs who
21cb0 73 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 69 73  se.** content is
21cc0 20 6c 61 74 65 72 20 77 72 69 74 74 65 6e 20 75   later written u
21cd0 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  sing.** [sqlite3
21ce0 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69 6e 63  _blob_open | inc
21cf0 72 65 6d 65 6e 74 61 6c 20 42 4c 4f 42 20 49 2f  remental BLOB I/
21d00 4f 5d 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20  O] routines..** 
21d10 41 20 6e 65 67 61 74 69 76 65 20 76 61 6c 75 65  A negative value
21d20 20 66 6f 72 20 74 68 65 20 7a 65 72 6f 62 6c 6f   for the zeroblo
21d30 62 20 72 65 73 75 6c 74 73 20 69 6e 20 61 20 7a  b results in a z
21d40 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 2e  ero-length BLOB.
21d50 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
21d60 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74  e3_bind_*() rout
21d70 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c  ines must be cal
21d80 6c 65 64 20 61 66 74 65 72 0a 2a 2a 20 5b 73 71  led after.** [sq
21d90 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
21da0 28 29 5d 20 28 61 6e 64 20 69 74 73 20 76 61 72  ()] (and its var
21db0 69 61 6e 74 73 29 20 6f 72 20 5b 73 71 6c 69 74  iants) or [sqlit
21dc0 65 33 5f 72 65 73 65 74 28 29 5d 20 61 6e 64 0a  e3_reset()] and.
21dd0 2a 2a 20 62 65 66 6f 72 65 20 5b 73 71 6c 69 74  ** before [sqlit
21de0 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 20 42  e3_step()]..** B
21df0 69 6e 64 69 6e 67 73 20 61 72 65 20 6e 6f 74 20  indings are not 
21e00 63 6c 65 61 72 65 64 20 62 79 20 74 68 65 20 5b  cleared by the [
21e10 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
21e20 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a 20 55 6e 62   routine..** Unb
21e30 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72 73 20  ound parameters 
21e40 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64 20  are interpreted 
21e50 61 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54  as NULL..**.** T
21e60 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65  hese routines re
21e70 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  turn [SQLITE_OK]
21e80 20 6f 6e 20 73 75 63 63 65 73 73 20 6f 72 20 61   on success or a
21e90 6e 20 65 72 72 6f 72 20 63 6f 64 65 20 69 66 0a  n error code if.
21ea0 2a 2a 20 61 6e 79 74 68 69 6e 67 20 67 6f 65 73  ** anything goes
21eb0 20 77 72 6f 6e 67 2e 20 20 5b 53 51 4c 49 54 45   wrong.  [SQLITE
21ec0 5f 52 41 4e 47 45 5d 20 69 73 20 72 65 74 75 72  _RANGE] is retur
21ed0 6e 65 64 20 69 66 20 74 68 65 20 70 61 72 61 6d  ned if the param
21ee0 65 74 65 72 0a 2a 2a 20 69 6e 64 65 78 20 69 73  eter.** index is
21ef0 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2e 20 20   out of range.  
21f00 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20 69  [SQLITE_NOMEM] i
21f10 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 6d 61  s returned if ma
21f20 6c 6c 6f 63 28 29 20 66 61 69 6c 73 2e 0a 2a 2a  lloc() fails..**
21f30 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d   [SQLITE_MISUSE]
21f40 20 6d 69 67 68 74 20 62 65 20 72 65 74 75 72 6e   might be return
21f50 65 64 20 69 66 20 74 68 65 73 65 20 72 6f 75 74  ed if these rout
21f60 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20  ines are called 
21f70 6f 6e 20 61 0a 2a 2a 20 76 69 72 74 75 61 6c 20  on a.** virtual 
21f80 6d 61 63 68 69 6e 65 20 74 68 61 74 20 69 73 20  machine that is 
21f90 74 68 65 20 77 72 6f 6e 67 20 73 74 61 74 65 20  the wrong state 
21fa0 6f 72 20 77 68 69 63 68 20 68 61 73 20 61 6c 72  or which has alr
21fb0 65 61 64 79 20 62 65 65 6e 20 66 69 6e 61 6c 69  eady been finali
21fc0 7a 65 64 2e 0a 2a 2a 20 44 65 74 65 63 74 69 6f  zed..** Detectio
21fd0 6e 20 6f 66 20 6d 69 73 75 73 65 20 69 73 20 75  n of misuse is u
21fe0 6e 72 65 6c 69 61 62 6c 65 2e 20 20 41 70 70 6c  nreliable.  Appl
21ff0 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20  ications should 
22000 6e 6f 74 20 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e  not depend.** on
22010 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 20 72   SQLITE_MISUSE r
22020 65 74 75 72 6e 73 2e 20 20 53 51 4c 49 54 45 5f  eturns.  SQLITE_
22030 4d 49 53 55 53 45 20 69 73 20 69 6e 74 65 6e 64  MISUSE is intend
22040 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20 61  ed to indicate a
22050 0a 2a 2a 20 61 20 6c 6f 67 69 63 20 65 72 72 6f  .** a logic erro
22060 72 20 69 6e 20 74 68 65 20 61 70 70 6c 69 63 61  r in the applica
22070 74 69 6f 6e 2e 20 20 46 75 74 75 72 65 20 76 65  tion.  Future ve
22080 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
22090 20 6d 69 67 68 74 0a 2a 2a 20 70 61 6e 69 63 20   might.** panic 
220a0 72 61 74 68 65 72 20 74 68 61 6e 20 72 65 74 75  rather than retu
220b0 72 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  rn SQLITE_MISUSE
220c0 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
220d0 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  : [sqlite3_bind_
220e0 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28  parameter_count(
220f0 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
22100 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e  bind_parameter_n
22110 61 6d 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c  ame()], and [sql
22120 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
22130 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2a  ter_index()]..**
22140 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
22150 2a 2a 0a 2a 2a 20 7b 48 31 33 35 30 36 7d 20 54  **.** {H13506} T
22160 68 65 20 5b 53 51 4c 20 73 74 61 74 65 6d 65 6e  he [SQL statemen
22170 74 20 63 6f 6d 70 69 6c 65 72 5d 20 72 65 63 6f  t compiler] reco
22180 67 6e 69 7a 65 73 20 74 6f 6b 65 6e 73 20 6f 66  gnizes tokens of
22190 20 74 68 65 20 66 6f 72 6d 73 0a 2a 2a 20 20 20   the forms.**   
221a0 20 20 20 20 20 20 20 22 3f 22 2c 20 22 3f 4e 4e         "?", "?NN
221b0 4e 22 2c 20 22 24 56 56 56 22 2c 20 22 3a 56 56  N", "$VVV", ":VV
221c0 56 22 2c 20 61 6e 64 20 22 40 56 56 56 22 20 61  V", and "@VVV" a
221d0 73 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73  s SQL parameters
221e0 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 68  ,.**          wh
221f0 65 72 65 20 4e 4e 4e 20 69 73 20 61 6e 79 20 73  ere NNN is any s
22200 65 71 75 65 6e 63 65 20 6f 66 20 6f 6e 65 20 6f  equence of one o
22210 72 20 6d 6f 72 65 20 64 69 67 69 74 73 0a 2a 2a  r more digits.**
22220 20 20 20 20 20 20 20 20 20 20 61 6e 64 20 77 68            and wh
22230 65 72 65 20 56 56 56 20 69 73 20 61 6e 79 20 73  ere VVV is any s
22240 65 71 75 65 6e 63 65 20 6f 66 20 6f 6e 65 20 6f  equence of one o
22250 72 20 6d 6f 72 65 20 61 6c 70 68 61 6e 75 6d 65  r more alphanume
22260 72 69 63 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ric.**          
22270 63 68 61 72 61 63 74 65 72 73 20 6f 72 20 22 3a  characters or ":
22280 3a 22 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 66 6f  :" optionally fo
22290 6c 6c 6f 77 65 64 20 62 79 20 61 20 73 74 72 69  llowed by a stri
222a0 6e 67 20 63 6f 6e 74 61 69 6e 69 6e 67 0a 2a 2a  ng containing.**
222b0 20 20 20 20 20 20 20 20 20 20 6e 6f 20 73 70 61            no spa
222c0 63 65 73 20 61 6e 64 20 63 6f 6e 74 61 69 6e 65  ces and containe
222d0 64 20 77 69 74 68 69 6e 20 70 61 72 65 6e 74 68  d within parenth
222e0 65 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33  eses..**.** {H13
222f0 35 30 39 7d 20 54 68 65 20 69 6e 69 74 69 61 6c  509} The initial
22300 20 76 61 6c 75 65 20 6f 66 20 61 6e 20 53 51 4c   value of an SQL
22310 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 4e 55   parameter is NU
22320 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 31  LL..**.** {H1351
22330 32 7d 20 54 68 65 20 69 6e 64 65 78 20 6f 66 20  2} The index of 
22340 61 6e 20 22 3f 22 20 53 51 4c 20 70 61 72 61 6d  an "?" SQL param
22350 65 74 65 72 20 69 73 20 6f 6e 65 20 6c 61 72 67  eter is one larg
22360 65 72 20 74 68 61 6e 20 74 68 65 0a 2a 2a 20 20  er than the.**  
22370 20 20 20 20 20 20 20 20 6c 61 72 67 65 73 74 20          largest 
22380 69 6e 64 65 78 20 6f 66 20 53 51 4c 20 70 61 72  index of SQL par
22390 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 6c 65  ameter to the le
223a0 66 74 2c 20 6f 72 20 31 20 69 66 0a 2a 2a 20 20  ft, or 1 if.**  
223b0 20 20 20 20 20 20 20 20 74 68 65 20 22 3f 22 20          the "?" 
223c0 69 73 20 74 68 65 20 6c 65 66 74 6d 6f 73 74 20  is the leftmost 
223d0 53 51 4c 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  SQL parameter..*
223e0 2a 0a 2a 2a 20 7b 48 31 33 35 31 35 7d 20 54 68  *.** {H13515} Th
223f0 65 20 69 6e 64 65 78 20 6f 66 20 61 6e 20 22 3f  e index of an "?
22400 4e 4e 4e 22 20 53 51 4c 20 70 61 72 61 6d 65 74  NNN" SQL paramet
22410 65 72 20 69 73 20 74 68 65 20 69 6e 74 65 67 65  er is the intege
22420 72 20 4e 4e 4e 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  r NNN..**.** {H1
22430 33 35 31 38 7d 20 54 68 65 20 69 6e 64 65 78 20  3518} The index 
22440 6f 66 20 61 6e 20 22 3a 56 56 56 22 2c 20 22 24  of an ":VVV", "$
22450 56 56 56 22 2c 20 6f 72 20 22 40 56 56 56 22 20  VVV", or "@VVV" 
22460 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69 73  SQL parameter is
22470 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
22480 20 73 61 6d 65 20 61 73 20 74 68 65 20 69 6e 64   same as the ind
22490 65 78 20 6f 66 20 6c 65 66 74 6d 6f 73 74 20 6f  ex of leftmost o
224a0 63 63 75 72 72 65 6e 63 65 73 20 6f 66 20 74 68  ccurrences of th
224b0 65 20 73 61 6d 65 0a 2a 2a 20 20 20 20 20 20 20  e same.**       
224c0 20 20 20 70 61 72 61 6d 65 74 65 72 2c 20 6f 72     parameter, or
224d0 20 6f 6e 65 20 6d 6f 72 65 20 74 68 61 6e 20 74   one more than t
224e0 68 65 20 6c 61 72 67 65 73 74 20 69 6e 64 65 78  he largest index
224f0 20 6f 76 65 72 20 61 6c 6c 0a 2a 2a 20 20 20 20   over all.**    
22500 20 20 20 20 20 20 70 61 72 61 6d 65 74 65 72 73        parameters
22510 20 74 6f 20 74 68 65 20 6c 65 66 74 20 69 66 20   to the left if 
22520 74 68 69 73 20 69 73 20 74 68 65 20 66 69 72 73  this is the firs
22530 74 20 6f 63 63 75 72 72 65 6e 63 65 0a 2a 2a 20  t occurrence.** 
22540 20 20 20 20 20 20 20 20 20 6f 66 20 74 68 69 73           of this
22550 20 70 61 72 61 6d 65 74 65 72 2c 20 6f 72 20 31   parameter, or 1
22560 20 69 66 20 74 68 69 73 20 69 73 20 74 68 65 20   if this is the 
22570 6c 65 66 74 6d 6f 73 74 20 70 61 72 61 6d 65 74  leftmost paramet
22580 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 32  er..**.** {H1352
22590 31 7d 20 54 68 65 20 5b 53 51 4c 20 73 74 61 74  1} The [SQL stat
225a0 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 72 5d 20  ement compiler] 
225b0 66 61 69 6c 73 20 77 69 74 68 20 61 6e 20 5b 53  fails with an [S
225c0 51 4c 49 54 45 5f 52 41 4e 47 45 5d 0a 2a 2a 20  QLITE_RANGE].** 
225d0 20 20 20 20 20 20 20 20 20 65 72 72 6f 72 20 69           error i
225e0 66 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 61  f the index of a
225f0 6e 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20  n SQL parameter 
22600 69 73 20 6c 65 73 73 20 74 68 61 6e 20 31 0a 2a  is less than 1.*
22610 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 67 72  *          or gr
22620 65 61 74 65 72 20 74 68 61 6e 20 74 68 65 20 63  eater than the c
22630 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 53 51 4c 49  ompile-time SQLI
22640 54 45 5f 4d 41 58 5f 56 41 52 49 41 42 4c 45 5f  TE_MAX_VARIABLE_
22650 4e 55 4d 42 45 52 0a 2a 2a 20 20 20 20 20 20 20  NUMBER.**       
22660 20 20 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a     parameter..**
22670 0a 2a 2a 20 7b 48 31 33 35 32 34 7d 20 43 61 6c  .** {H13524} Cal
22680 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62  ls to [sqlite3_b
22690 69 6e 64 5f 74 65 78 74 20 7c 20 73 71 6c 69 74  ind_text | sqlit
226a0 65 33 5f 62 69 6e 64 28 53 2c 4e 2c 56 2c 2e 2e  e3_bind(S,N,V,..
226b0 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  .)].**          
226c0 61 73 73 6f 63 69 61 74 65 20 74 68 65 20 76 61  associate the va
226d0 6c 75 65 20 56 20 77 69 74 68 20 61 6c 6c 20 53  lue V with all S
226e0 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20 68 61  QL parameters ha
226f0 76 69 6e 67 20 61 6e 0a 2a 2a 20 20 20 20 20 20  ving an.**      
22700 20 20 20 20 69 6e 64 65 78 20 6f 66 20 4e 20 69      index of N i
22710 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  n the [prepared 
22720 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2a  statement] S..**
22730 0a 2a 2a 20 7b 48 31 33 35 32 37 7d 20 43 61 6c  .** {H13527} Cal
22740 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62  ls to [sqlite3_b
22750 69 6e 64 5f 74 65 78 74 20 7c 20 73 71 6c 69 74  ind_text | sqlit
22760 65 33 5f 62 69 6e 64 28 53 2c 4e 2c 2e 2e 2e 29  e3_bind(S,N,...)
22770 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 76  ].**          ov
22780 65 72 72 69 64 65 20 70 72 69 6f 72 20 63 61 6c  erride prior cal
22790 6c 73 20 77 69 74 68 20 74 68 65 20 73 61 6d 65  ls with the same
227a0 20 76 61 6c 75 65 73 20 6f 66 20 53 20 61 6e 64   values of S and
227b0 20 4e 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 33   N..**.** {H1353
227c0 30 7d 20 42 69 6e 64 69 6e 67 73 20 65 73 74 61  0} Bindings esta
227d0 62 6c 69 73 68 65 64 20 62 79 20 5b 73 71 6c 69  blished by [sqli
227e0 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 20 7c 20  te3_bind_text | 
227f0 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 53 2c 2e  sqlite3_bind(S,.
22800 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  ..)].**         
22810 20 70 65 72 73 69 73 74 20 61 63 72 6f 73 73 20   persist across 
22820 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  calls to [sqlite
22830 33 5f 72 65 73 65 74 28 53 29 5d 2e 0a 2a 2a 0a  3_reset(S)]..**.
22840 2a 2a 20 7b 48 31 33 35 33 33 7d 20 49 6e 20 63  ** {H13533} In c
22850 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
22860 5f 62 69 6e 64 5f 62 6c 6f 62 28 53 2c 4e 2c 56  _bind_blob(S,N,V
22870 2c 4c 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20  ,L,D)],.**      
22880 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e      [sqlite3_bin
22890 64 5f 74 65 78 74 28 53 2c 4e 2c 56 2c 4c 2c 44  d_text(S,N,V,L,D
228a0 29 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20  )], or.**       
228b0 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64     [sqlite3_bind
228c0 5f 74 65 78 74 31 36 28 53 2c 4e 2c 56 2c 4c 2c  _text16(S,N,V,L,
228d0 44 29 5d 20 53 51 4c 69 74 65 20 62 69 6e 64 73  D)] SQLite binds
228e0 20 74 68 65 20 66 69 72 73 74 20 4c 0a 2a 2a 20   the first L.** 
228f0 20 20 20 20 20 20 20 20 20 62 79 74 65 73 20 6f           bytes o
22900 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 20 73 74  f the BLOB or st
22910 72 69 6e 67 20 70 6f 69 6e 74 65 64 20 74 6f 20  ring pointed to 
22920 62 79 20 56 2c 20 77 68 65 6e 20 4c 0a 2a 2a 20  by V, when L.** 
22930 20 20 20 20 20 20 20 20 20 69 73 20 6e 6f 6e 2d           is non-
22940 6e 65 67 61 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20  negative..**.** 
22950 7b 48 31 33 35 33 36 7d 20 49 6e 20 63 61 6c 6c  {H13536} In call
22960 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69  s to [sqlite3_bi
22970 6e 64 5f 74 65 78 74 28 53 2c 4e 2c 56 2c 4c 2c  nd_text(S,N,V,L,
22980 44 29 5d 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20  D)] or.**       
22990 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64     [sqlite3_bind
229a0 5f 74 65 78 74 31 36 28 53 2c 4e 2c 56 2c 4c 2c  _text16(S,N,V,L,
229b0 44 29 5d 20 53 51 4c 69 74 65 20 62 69 6e 64 73  D)] SQLite binds
229c0 20 63 68 61 72 61 63 74 65 72 73 0a 2a 2a 20 20   characters.**  
229d0 20 20 20 20 20 20 20 20 66 72 6f 6d 20 56 20 74          from V t
229e0 68 72 6f 75 67 68 20 74 68 65 20 66 69 72 73 74  hrough the first
229f0 20 7a 65 72 6f 20 63 68 61 72 61 63 74 65 72 20   zero character 
22a00 77 68 65 6e 20 4c 20 69 73 20 6e 65 67 61 74 69  when L is negati
22a10 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 33  ve..**.** {H1353
22a20 39 7d 20 49 6e 20 63 61 6c 6c 73 20 74 6f 20 5b  9} In calls to [
22a30 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
22a40 62 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c 0a 2a  b(S,N,V,L,D)],.*
22a50 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
22a60 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 53 2c  te3_bind_text(S,
22a70 4e 2c 56 2c 4c 2c 44 29 5d 2c 20 6f 72 0a 2a 2a  N,V,L,D)], or.**
22a80 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
22a90 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 53  e3_bind_text16(S
22aa0 2c 4e 2c 56 2c 4c 2c 44 29 5d 20 77 68 65 6e 20  ,N,V,L,D)] when 
22ab0 44 20 69 73 20 74 68 65 20 73 70 65 63 69 61 6c  D is the special
22ac0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6e  .**          con
22ad0 73 74 61 6e 74 20 5b 53 51 4c 49 54 45 5f 53 54  stant [SQLITE_ST
22ae0 41 54 49 43 5d 2c 20 53 51 4c 69 74 65 20 61 73  ATIC], SQLite as
22af0 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 20 76  sumes that the v
22b00 61 6c 75 65 20 56 0a 2a 2a 20 20 20 20 20 20 20  alue V.**       
22b10 20 20 20 69 73 20 68 65 6c 64 20 69 6e 20 73 74     is held in st
22b20 61 74 69 63 20 75 6e 6d 61 6e 61 67 65 64 20 73  atic unmanaged s
22b30 70 61 63 65 20 74 68 61 74 20 77 69 6c 6c 20 6e  pace that will n
22b40 6f 74 20 63 68 61 6e 67 65 0a 2a 2a 20 20 20 20  ot change.**    
22b50 20 20 20 20 20 20 64 75 72 69 6e 67 20 74 68 65        during the
22b60 20 6c 69 66 65 74 69 6d 65 20 6f 66 20 74 68 65   lifetime of the
22b70 20 62 69 6e 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20   binding..**.** 
22b80 7b 48 31 33 35 34 32 7d 20 49 6e 20 63 61 6c 6c  {H13542} In call
22b90 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69  s to [sqlite3_bi
22ba0 6e 64 5f 62 6c 6f 62 28 53 2c 4e 2c 56 2c 4c 2c  nd_blob(S,N,V,L,
22bb0 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  D)],.**         
22bc0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74   [sqlite3_bind_t
22bd0 65 78 74 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c  ext(S,N,V,L,D)],
22be0 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   or.**          
22bf0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65  [sqlite3_bind_te
22c00 78 74 31 36 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d  xt16(S,N,V,L,D)]
22c10 20 77 68 65 6e 20 44 20 69 73 20 74 68 65 20 73   when D is the s
22c20 70 65 63 69 61 6c 0a 2a 2a 20 20 20 20 20 20 20  pecial.**       
22c30 20 20 20 63 6f 6e 73 74 61 6e 74 20 5b 53 51 4c     constant [SQL
22c40 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d 2c 20  ITE_TRANSIENT], 
22c50 74 68 65 20 72 6f 75 74 69 6e 65 20 6d 61 6b 65  the routine make
22c60 73 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  s a.**          
22c70 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20  private copy of 
22c80 74 68 65 20 76 61 6c 75 65 20 56 20 62 65 66 6f  the value V befo
22c90 72 65 20 69 74 20 72 65 74 75 72 6e 73 2e 0a 2a  re it returns..*
22ca0 2a 0a 2a 2a 20 7b 48 31 33 35 34 35 7d 20 49 6e  *.** {H13545} In
22cb0 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74   calls to [sqlit
22cc0 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 53 2c 4e  e3_bind_blob(S,N
22cd0 2c 56 2c 4c 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20  ,V,L,D)],.**    
22ce0 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 62        [sqlite3_b
22cf0 69 6e 64 5f 74 65 78 74 28 53 2c 4e 2c 56 2c 4c  ind_text(S,N,V,L
22d00 2c 44 29 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20 20  ,D)], or.**     
22d10 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 69       [sqlite3_bi
22d20 6e 64 5f 74 65 78 74 31 36 28 53 2c 4e 2c 56 2c  nd_text16(S,N,V,
22d30 4c 2c 44 29 5d 20 77 68 65 6e 20 44 20 69 73 20  L,D)] when D is 
22d40 61 20 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20  a pointer to.** 
22d50 20 20 20 20 20 20 20 20 20 61 20 66 75 6e 63 74           a funct
22d60 69 6f 6e 2c 20 53 51 4c 69 74 65 20 69 6e 76 6f  ion, SQLite invo
22d70 6b 65 73 20 74 68 61 74 20 66 75 6e 63 74 69 6f  kes that functio
22d80 6e 20 74 6f 20 64 65 73 74 72 6f 79 20 74 68 65  n to destroy the
22d90 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 76 61 6c  .**          val
22da0 75 65 20 56 20 61 66 74 65 72 20 69 74 20 68 61  ue V after it ha
22db0 73 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67  s finished using
22dc0 20 74 68 65 20 76 61 6c 75 65 20 56 2e 0a 2a 2a   the value V..**
22dd0 0a 2a 2a 20 7b 48 31 33 35 34 38 7d 20 49 6e 20  .** {H13548} In 
22de0 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  calls to [sqlite
22df0 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28  3_bind_zeroblob(
22e00 53 2c 4e 2c 56 2c 4c 29 5d 20 74 68 65 20 76 61  S,N,V,L)] the va
22e10 6c 75 65 20 62 6f 75 6e 64 0a 2a 2a 20 20 20 20  lue bound.**    
22e20 20 20 20 20 20 20 69 73 20 61 20 42 4c 4f 42 20        is a BLOB 
22e30 6f 66 20 4c 20 62 79 74 65 73 2c 20 6f 72 20 61  of L bytes, or a
22e40 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f   zero-length BLO
22e50 42 20 69 66 20 4c 20 69 73 20 6e 65 67 61 74 69  B if L is negati
22e60 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 35  ve..**.** {H1355
22e70 31 7d 20 49 6e 20 63 61 6c 6c 73 20 74 6f 20 5b  1} In calls to [
22e80 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c  sqlite3_bind_val
22e90 75 65 28 53 2c 4e 2c 56 29 5d 20 74 68 65 20 56  ue(S,N,V)] the V
22ea0 20 61 72 67 75 6d 65 6e 74 20 6d 61 79 0a 2a 2a   argument may.**
22eb0 20 20 20 20 20 20 20 20 20 20 62 65 20 65 69 74            be eit
22ec0 68 65 72 20 61 20 5b 70 72 6f 74 65 63 74 65 64  her a [protected
22ed0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
22ee0 6f 62 6a 65 63 74 20 6f 72 20 61 6e 0a 2a 2a 20  object or an.** 
22ef0 20 20 20 20 20 20 20 20 20 5b 75 6e 70 72 6f 74           [unprot
22f00 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
22f10 6c 75 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a  lue] object..*/.
22f20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
22f30 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74  _blob(sqlite3_st
22f40 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20  mt*, int, const 
22f50 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f  void*, int n, vo
22f60 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69  id(*)(void*));.i
22f70 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
22f80 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73  double(sqlite3_s
22f90 74 6d 74 2a 2c 20 69 6e 74 2c 20 64 6f 75 62 6c  tmt*, int, doubl
22fa0 65 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  e);.int sqlite3_
22fb0 62 69 6e 64 5f 69 6e 74 28 73 71 6c 69 74 65 33  bind_int(sqlite3
22fc0 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74  _stmt*, int, int
22fd0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
22fe0 69 6e 64 5f 69 6e 74 36 34 28 73 71 6c 69 74 65  ind_int64(sqlite
22ff0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71  3_stmt*, int, sq
23000 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 69 6e  lite3_int64);.in
23010 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e  t sqlite3_bind_n
23020 75 6c 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ull(sqlite3_stmt
23030 2a 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c  *, int);.int sql
23040 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 73  ite3_bind_text(s
23050 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
23060 74 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20  t, const char*, 
23070 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76  int n, void(*)(v
23080 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69  oid*));.int sqli
23090 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28  te3_bind_text16(
230a0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
230b0 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  nt, const void*,
230c0 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f   int, void(*)(vo
230d0 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74  id*));.int sqlit
230e0 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 73 71  e3_bind_value(sq
230f0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
23100 2c 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f  , const sqlite3_
23110 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c  value*);.int sql
23120 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c  ite3_bind_zerobl
23130 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ob(sqlite3_stmt*
23140 2c 20 69 6e 74 2c 20 69 6e 74 20 6e 29 3b 0a 0a  , int, int n);..
23150 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
23160 4e 75 6d 62 65 72 20 4f 66 20 53 51 4c 20 50 61  Number Of SQL Pa
23170 72 61 6d 65 74 65 72 73 20 7b 48 31 33 36 30 30  rameters {H13600
23180 7d 20 3c 53 37 30 33 30 30 3e 0a 2a 2a 0a 2a 2a  } <S70300>.**.**
23190 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 63 61   This routine ca
231a0 6e 20 62 65 20 75 73 65 64 20 74 6f 20 66 69 6e  n be used to fin
231b0 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  d the number of 
231c0 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 5d  [SQL parameters]
231d0 0a 2a 2a 20 69 6e 20 61 20 5b 70 72 65 70 61 72  .** in a [prepar
231e0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20  ed statement].  
231f0 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20 61  SQL parameters a
23200 72 65 20 74 6f 6b 65 6e 73 20 6f 66 20 74 68 65  re tokens of the
23210 0a 2a 2a 20 66 6f 72 6d 20 22 3f 22 2c 20 22 3f  .** form "?", "?
23220 4e 4e 4e 22 2c 20 22 3a 41 41 41 22 2c 20 22 24  NNN", ":AAA", "$
23230 41 41 41 22 2c 20 6f 72 20 22 40 41 41 41 22 20  AAA", or "@AAA" 
23240 74 68 61 74 20 73 65 72 76 65 20 61 73 0a 2a 2a  that serve as.**
23250 20 70 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 6f   placeholders fo
23260 72 20 76 61 6c 75 65 73 20 74 68 61 74 20 61 72  r values that ar
23270 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  e [sqlite3_bind_
23280 62 6c 6f 62 20 7c 20 62 6f 75 6e 64 5d 0a 2a 2a  blob | bound].**
23290 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65   to the paramete
232a0 72 73 20 61 74 20 61 20 6c 61 74 65 72 20 74 69  rs at a later ti
232b0 6d 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72  me..**.** This r
232c0 6f 75 74 69 6e 65 20 61 63 74 75 61 6c 6c 79 20  outine actually 
232d0 72 65 74 75 72 6e 73 20 74 68 65 20 69 6e 64 65  returns the inde
232e0 78 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74  x of the largest
232f0 20 28 72 69 67 68 74 6d 6f 73 74 29 0a 2a 2a 20   (rightmost).** 
23300 70 61 72 61 6d 65 74 65 72 2e 20 46 6f 72 20 61  parameter. For a
23310 6c 6c 20 66 6f 72 6d 73 20 65 78 63 65 70 74 20  ll forms except 
23320 3f 4e 4e 4e 2c 20 74 68 69 73 20 77 69 6c 6c 20  ?NNN, this will 
23330 63 6f 72 72 65 73 70 6f 6e 64 20 74 6f 20 74 68  correspond to th
23340 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 75  e.** number of u
23350 6e 69 71 75 65 20 70 61 72 61 6d 65 74 65 72 73  nique parameters
23360 2e 20 20 49 66 20 70 61 72 61 6d 65 74 65 72 73  .  If parameters
23370 20 6f 66 20 74 68 65 20 3f 4e 4e 4e 20 61 72 65   of the ?NNN are
23380 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65 72 65 20   used,.** there 
23390 6d 61 79 20 62 65 20 67 61 70 73 20 69 6e 20 74  may be gaps in t
233a0 68 65 20 6c 69 73 74 2e 0a 2a 2a 0a 2a 2a 20 53  he list..**.** S
233b0 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
233c0 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69  3_bind_blob|sqli
233d0 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20  te3_bind()],.** 
233e0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
233f0 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c  rameter_name()],
23400 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
23410 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
23420 69 6e 64 65 78 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  index()]..**.** 
23430 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
23440 2a 20 7b 48 31 33 36 30 31 7d 20 54 68 65 20 5b  * {H13601} The [
23450 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
23460 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 53 29 5d  ameter_count(S)]
23470 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
23480 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  ns.**          t
23490 68 65 20 6c 61 72 67 65 73 74 20 69 6e 64 65 78  he largest index
234a0 20 6f 66 20 61 6c 6c 20 53 51 4c 20 70 61 72 61   of all SQL para
234b0 6d 65 74 65 72 73 20 69 6e 20 74 68 65 0a 2a 2a  meters in the.**
234c0 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 61            [prepa
234d0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
234e0 2c 20 6f 72 20 30 20 69 66 20 53 20 63 6f 6e 74  , or 0 if S cont
234f0 61 69 6e 73 20 6e 6f 20 53 51 4c 20 70 61 72 61  ains no SQL para
23500 6d 65 74 65 72 73 2e 0a 2a 2f 0a 69 6e 74 20 73  meters..*/.int s
23510 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
23520 6d 65 74 65 72 5f 63 6f 75 6e 74 28 73 71 6c 69  meter_count(sqli
23530 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a  te3_stmt*);../*.
23540 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 61 6d  ** CAPI3REF: Nam
23550 65 20 4f 66 20 41 20 48 6f 73 74 20 50 61 72 61  e Of A Host Para
23560 6d 65 74 65 72 20 7b 48 31 33 36 32 30 7d 20 3c  meter {H13620} <
23570 53 37 30 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68  S70300>.**.** Th
23580 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  is routine retur
23590 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
235a0 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
235b0 6e 2d 74 68 0a 2a 2a 20 5b 53 51 4c 20 70 61 72  n-th.** [SQL par
235c0 61 6d 65 74 65 72 5d 20 69 6e 20 61 20 5b 70 72  ameter] in a [pr
235d0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
235e0 5d 2e 0a 2a 2a 20 53 51 4c 20 70 61 72 61 6d 65  ]..** SQL parame
235f0 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d  ters of the form
23600 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41   "?NNN" or ":AAA
23610 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22  " or "@AAA" or "
23620 24 41 41 41 22 0a 2a 2a 20 68 61 76 65 20 61 20  $AAA".** have a 
23630 6e 61 6d 65 20 77 68 69 63 68 20 69 73 20 74 68  name which is th
23640 65 20 73 74 72 69 6e 67 20 22 3f 4e 4e 4e 22 20  e string "?NNN" 
23650 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41  or ":AAA" or "@A
23660 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a  AA" or "$AAA".**
23670 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a   respectively..*
23680 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73  * In other words
23690 2c 20 74 68 65 20 69 6e 69 74 69 61 6c 20 22 3a  , the initial ":
236a0 22 20 6f 72 20 22 24 22 20 6f 72 20 22 40 22 20  " or "$" or "@" 
236b0 6f 72 20 22 3f 22 0a 2a 2a 20 69 73 20 69 6e 63  or "?".** is inc
236c0 6c 75 64 65 64 20 61 73 20 70 61 72 74 20 6f 66  luded as part of
236d0 20 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a 20 50 61   the name..** Pa
236e0 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20  rameters of the 
236f0 66 6f 72 6d 20 22 3f 22 20 77 69 74 68 6f 75 74  form "?" without
23700 20 61 20 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74   a following int
23710 65 67 65 72 20 68 61 76 65 20 6e 6f 20 6e 61 6d  eger have no nam
23720 65 0a 2a 2a 20 61 6e 64 20 61 72 65 20 61 6c 73  e.** and are als
23730 6f 20 72 65 66 65 72 72 65 64 20 74 6f 20 61 73  o referred to as
23740 20 22 61 6e 6f 6e 79 6d 6f 75 73 20 70 61 72 61   "anonymous para
23750 6d 65 74 65 72 73 22 2e 0a 2a 2a 0a 2a 2a 20 54  meters"..**.** T
23760 68 65 20 66 69 72 73 74 20 68 6f 73 74 20 70 61  he first host pa
23770 72 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69  rameter has an i
23780 6e 64 65 78 20 6f 66 20 31 2c 20 6e 6f 74 20 30  ndex of 1, not 0
23790 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 76  ..**.** If the v
237a0 61 6c 75 65 20 6e 20 69 73 20 6f 75 74 20 6f 66  alue n is out of
237b0 20 72 61 6e 67 65 20 6f 72 20 69 66 20 74 68 65   range or if the
237c0 20 6e 2d 74 68 20 70 61 72 61 6d 65 74 65 72 20   n-th parameter 
237d0 69 73 0a 2a 2a 20 6e 61 6d 65 6c 65 73 73 2c 20  is.** nameless, 
237e0 74 68 65 6e 20 4e 55 4c 4c 20 69 73 20 72 65 74  then NULL is ret
237f0 75 72 6e 65 64 2e 20 20 54 68 65 20 72 65 74 75  urned.  The retu
23800 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 0a 2a  rned string is.*
23810 2a 20 61 6c 77 61 79 73 20 69 6e 20 55 54 46 2d  * always in UTF-
23820 38 20 65 6e 63 6f 64 69 6e 67 20 65 76 65 6e 20  8 encoding even 
23830 69 66 20 74 68 65 20 6e 61 6d 65 64 20 70 61 72  if the named par
23840 61 6d 65 74 65 72 20 77 61 73 0a 2a 2a 20 6f 72  ameter was.** or
23850 69 67 69 6e 61 6c 6c 79 20 73 70 65 63 69 66 69  iginally specifi
23860 65 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20  ed as UTF-16 in 
23870 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
23880 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c  16()] or.** [sql
23890 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
238a0 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  2()]..**.** See 
238b0 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62  also: [sqlite3_b
238c0 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33  ind_blob|sqlite3
238d0 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71  _bind()],.** [sq
238e0 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
238f0 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61  eter_count()], a
23900 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  nd.** [sqlite3_b
23910 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e  ind_parameter_in
23920 64 65 78 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e  dex()]..**.** IN
23930 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
23940 7b 48 31 33 36 32 31 7d 20 54 68 65 20 5b 73 71  {H13621} The [sq
23950 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
23960 65 74 65 72 5f 6e 61 6d 65 28 53 2c 4e 29 5d 20  eter_name(S,N)] 
23970 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
23980 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20  s.**          a 
23990 55 54 46 2d 38 20 72 65 6e 64 65 72 69 6e 67 20  UTF-8 rendering 
239a0 6f 66 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  of the name of t
239b0 68 65 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  he SQL parameter
239c0 20 69 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   in.**          
239d0 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
239e0 61 74 65 6d 65 6e 74 5d 20 53 20 68 61 76 69 6e  atement] S havin
239f0 67 20 69 6e 64 65 78 20 4e 2c 20 6f 72 0a 2a 2a  g index N, or.**
23a00 20 20 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 69            NULL i
23a10 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20 53 51  f there is no SQ
23a20 4c 20 70 61 72 61 6d 65 74 65 72 20 77 69 74 68  L parameter with
23a30 20 69 6e 64 65 78 20 4e 20 6f 72 20 69 66 20 74   index N or if t
23a40 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70  he.**          p
23a50 61 72 61 6d 65 74 65 72 20 77 69 74 68 20 69 6e  arameter with in
23a60 64 65 78 20 4e 20 69 73 20 61 6e 20 61 6e 6f 6e  dex N is an anon
23a70 79 6d 6f 75 73 20 70 61 72 61 6d 65 74 65 72 20  ymous parameter 
23a80 22 3f 22 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68  "?"..*/.const ch
23a90 61 72 20 2a 73 71 6c 69 74 65 33 5f 62 69 6e 64  ar *sqlite3_bind
23aa0 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28  _parameter_name(
23ab0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
23ac0 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  nt);../*.** CAPI
23ad0 33 52 45 46 3a 20 49 6e 64 65 78 20 4f 66 20 41  3REF: Index Of A
23ae0 20 50 61 72 61 6d 65 74 65 72 20 57 69 74 68 20   Parameter With 
23af0 41 20 47 69 76 65 6e 20 4e 61 6d 65 20 7b 48 31  A Given Name {H1
23b00 33 36 34 30 7d 20 3c 53 37 30 33 30 30 3e 0a 2a  3640} <S70300>.*
23b10 2a 0a 2a 2a 20 52 65 74 75 72 6e 20 74 68 65 20  *.** Return the 
23b20 69 6e 64 65 78 20 6f 66 20 61 6e 20 53 51 4c 20  index of an SQL 
23b30 70 61 72 61 6d 65 74 65 72 20 67 69 76 65 6e 20  parameter given 
23b40 69 74 73 20 6e 61 6d 65 2e 20 20 54 68 65 0a 2a  its name.  The.*
23b50 2a 20 69 6e 64 65 78 20 76 61 6c 75 65 20 72 65  * index value re
23b60 74 75 72 6e 65 64 20 69 73 20 73 75 69 74 61 62  turned is suitab
23b70 6c 65 20 66 6f 72 20 75 73 65 20 61 73 20 74 68  le for use as th
23b80 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 70 61 72 61  e second.** para
23b90 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65  meter to [sqlite
23ba0 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69  3_bind_blob|sqli
23bb0 74 65 33 5f 62 69 6e 64 28 29 5d 2e 20 20 41 20  te3_bind()].  A 
23bc0 7a 65 72 6f 0a 2a 2a 20 69 73 20 72 65 74 75 72  zero.** is retur
23bd0 6e 65 64 20 69 66 20 6e 6f 20 6d 61 74 63 68 69  ned if no matchi
23be0 6e 67 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  ng parameter is 
23bf0 66 6f 75 6e 64 2e 20 20 54 68 65 20 70 61 72 61  found.  The para
23c00 6d 65 74 65 72 0a 2a 2a 20 6e 61 6d 65 20 6d 75  meter.** name mu
23c10 73 74 20 62 65 20 67 69 76 65 6e 20 69 6e 20 55  st be given in U
23c20 54 46 2d 38 20 65 76 65 6e 20 69 66 20 74 68 65  TF-8 even if the
23c30 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d   original statem
23c40 65 6e 74 0a 2a 2a 20 77 61 73 20 70 72 65 70 61  ent.** was prepa
23c50 72 65 64 20 66 72 6f 6d 20 55 54 46 2d 31 36 20  red from UTF-16 
23c60 74 65 78 74 20 75 73 69 6e 67 20 5b 73 71 6c 69  text using [sqli
23c70 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
23c80 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ()]..**.** See a
23c90 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69  lso: [sqlite3_bi
23ca0 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f  nd_blob|sqlite3_
23cb0 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  bind()],.** [sql
23cc0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
23cd0 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e  ter_count()], an
23ce0 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  d.** [sqlite3_bi
23cf0 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64  nd_parameter_ind
23d00 65 78 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56  ex()]..**.** INV
23d10 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
23d20 48 31 33 36 34 31 7d 20 54 68 65 20 5b 73 71 6c  H13641} The [sql
23d30 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
23d40 74 65 72 5f 69 6e 64 65 78 28 53 2c 4e 29 5d 20  ter_index(S,N)] 
23d50 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
23d60 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  s.**          th
23d70 65 20 69 6e 64 65 78 20 6f 66 20 53 51 4c 20 70  e index of SQL p
23d80 61 72 61 6d 65 74 65 72 20 69 6e 20 74 68 65 20  arameter in the 
23d90 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
23da0 65 6e 74 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  ent].**         
23db0 20 53 20 77 68 6f 73 65 20 6e 61 6d 65 20 6d 61   S whose name ma
23dc0 74 63 68 65 73 20 74 68 65 20 55 54 46 2d 38 20  tches the UTF-8 
23dd0 73 74 72 69 6e 67 20 4e 2c 20 6f 72 20 30 20 69  string N, or 0 i
23de0 66 20 74 68 65 72 65 20 69 73 0a 2a 2a 20 20 20  f there is.**   
23df0 20 20 20 20 20 20 20 6e 6f 20 6d 61 74 63 68 2e         no match.
23e00 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
23e10 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69  bind_parameter_i
23e20 6e 64 65 78 28 73 71 6c 69 74 65 33 5f 73 74 6d  ndex(sqlite3_stm
23e30 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  t*, const char *
23e40 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  zName);../*.** C
23e50 41 50 49 33 52 45 46 3a 20 52 65 73 65 74 20 41  API3REF: Reset A
23e60 6c 6c 20 42 69 6e 64 69 6e 67 73 20 4f 6e 20 41  ll Bindings On A
23e70 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d   Prepared Statem
23e80 65 6e 74 20 7b 48 31 33 36 36 30 7d 20 3c 53 37  ent {H13660} <S7
23e90 30 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 43 6f 6e 74  0300>.**.** Cont
23ea0 72 61 72 79 20 74 6f 20 74 68 65 20 69 6e 74 75  rary to the intu
23eb0 69 74 69 6f 6e 20 6f 66 20 6d 61 6e 79 2c 20 5b  ition of many, [
23ec0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
23ed0 20 64 6f 65 73 20 6e 6f 74 20 72 65 73 65 74 0a   does not reset.
23ee0 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** the [sqlite3_
23ef0 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 69 6e 64  bind_blob | bind
23f00 69 6e 67 73 5d 20 6f 6e 20 61 20 5b 70 72 65 70  ings] on a [prep
23f10 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
23f20 0a 2a 2a 20 55 73 65 20 74 68 69 73 20 72 6f 75  .** Use this rou
23f30 74 69 6e 65 20 74 6f 20 72 65 73 65 74 20 61 6c  tine to reset al
23f40 6c 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72  l host parameter
23f50 73 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  s to NULL..**.**
23f60 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
23f70 2a 2a 20 7b 48 31 33 36 36 31 7d 20 54 68 65 20  ** {H13661} The 
23f80 5b 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62  [sqlite3_clear_b
23f90 69 6e 64 69 6e 67 73 28 53 29 5d 20 69 6e 74 65  indings(S)] inte
23fa0 72 66 61 63 65 20 72 65 73 65 74 73 20 61 6c 6c  rface resets all
23fb0 20 53 51 4c 0a 2a 2a 20 20 20 20 20 20 20 20 20   SQL.**         
23fc0 20 70 61 72 61 6d 65 74 65 72 20 62 69 6e 64 69   parameter bindi
23fd0 6e 67 73 20 69 6e 20 74 68 65 20 5b 70 72 65 70  ngs in the [prep
23fe0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
23ff0 53 20 62 61 63 6b 20 74 6f 20 4e 55 4c 4c 2e 0a  S back to NULL..
24000 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  */.int sqlite3_c
24010 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 73 71  lear_bindings(sq
24020 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f  lite3_stmt*);../
24030 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e  *.** CAPI3REF: N
24040 75 6d 62 65 72 20 4f 66 20 43 6f 6c 75 6d 6e 73  umber Of Columns
24050 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74   In A Result Set
24060 20 7b 48 31 33 37 31 30 7d 20 3c 53 31 30 37 30   {H13710} <S1070
24070 30 3e 0a 2a 2a 0a 2a 2a 20 52 65 74 75 72 6e 20  0>.**.** Return 
24080 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f  the number of co
24090 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73  lumns in the res
240a0 75 6c 74 20 73 65 74 20 72 65 74 75 72 6e 65 64  ult set returned
240b0 20 62 79 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70   by the.** [prep
240c0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
240d0 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65   This routine re
240e0 74 75 72 6e 73 20 30 20 69 66 20 70 53 74 6d 74  turns 0 if pStmt
240f0 20 69 73 20 61 6e 20 53 51 4c 0a 2a 2a 20 73 74   is an SQL.** st
24100 61 74 65 6d 65 6e 74 20 74 68 61 74 20 64 6f 65  atement that doe
24110 73 20 6e 6f 74 20 72 65 74 75 72 6e 20 64 61 74  s not return dat
24120 61 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 61  a (for example a
24130 6e 20 5b 55 50 44 41 54 45 5d 29 2e 0a 2a 2a 0a  n [UPDATE])..**.
24140 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
24150 2a 0a 2a 2a 20 7b 48 31 33 37 31 31 7d 20 54 68  *.** {H13711} Th
24160 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  e [sqlite3_colum
24170 6e 5f 63 6f 75 6e 74 28 53 29 5d 20 69 6e 74 65  n_count(S)] inte
24180 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68  rface returns th
24190 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 20  e number of.**  
241a0 20 20 20 20 20 20 20 20 63 6f 6c 75 6d 6e 73 20          columns 
241b0 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  in the result se
241c0 74 20 67 65 6e 65 72 61 74 65 64 20 62 79 20 74  t generated by t
241d0 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
241e0 74 65 6d 65 6e 74 5d 20 53 2c 0a 2a 2a 20 20 20  tement] S,.**   
241f0 20 20 20 20 20 20 20 6f 72 20 30 20 69 66 20 53         or 0 if S
24200 20 64 6f 65 73 20 6e 6f 74 20 67 65 6e 65 72 61   does not genera
24210 74 65 20 61 20 72 65 73 75 6c 74 20 73 65 74 2e  te a result set.
24220 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
24230 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 73 71 6c  column_count(sql
24240 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
24250 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
24260 45 46 3a 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 73  EF: Column Names
24270 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74   In A Result Set
24280 20 7b 48 31 33 37 32 30 7d 20 3c 53 31 30 37 30   {H13720} <S1070
24290 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  0>.**.** These r
242a0 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74  outines return t
242b0 68 65 20 6e 61 6d 65 20 61 73 73 69 67 6e 65 64  he name assigned
242c0 20 74 6f 20 61 20 70 61 72 74 69 63 75 6c 61 72   to a particular
242d0 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e 20 74 68   column.** in th
242e0 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20  e result set of 
242f0 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65  a [SELECT] state
24300 6d 65 6e 74 2e 20 20 54 68 65 20 73 71 6c 69 74  ment.  The sqlit
24310 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29  e3_column_name()
24320 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 72 65  .** interface re
24330 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
24340 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  to a zero-termin
24350 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e  ated UTF-8 strin
24360 67 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65 33  g.** and sqlite3
24370 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29  _column_name16()
24380 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
24390 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72  er to a zero-ter
243a0 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31  minated.** UTF-1
243b0 36 20 73 74 72 69 6e 67 2e 20 20 54 68 65 20 66  6 string.  The f
243c0 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69  irst parameter i
243d0 73 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  s the [prepared 
243e0 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 74 68  statement].** th
243f0 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68  at implements th
24400 65 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65  e [SELECT] state
24410 6d 65 6e 74 2e 20 54 68 65 20 73 65 63 6f 6e 64  ment. The second
24420 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
24430 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62  e.** column numb
24440 65 72 2e 20 20 54 68 65 20 6c 65 66 74 6d 6f 73  er.  The leftmos
24450 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6e 75 6d 62  t column is numb
24460 65 72 20 30 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  er 0..**.** The 
24470 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20  returned string 
24480 70 6f 69 6e 74 65 72 20 69 73 20 76 61 6c 69 64  pointer is valid
24490 20 75 6e 74 69 6c 20 65 69 74 68 65 72 20 74 68   until either th
244a0 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
244b0 65 6d 65 6e 74 5d 0a 2a 2a 20 69 73 20 64 65 73  ement].** is des
244c0 74 72 6f 79 65 64 20 62 79 20 5b 73 71 6c 69 74  troyed by [sqlit
244d0 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f  e3_finalize()] o
244e0 72 20 75 6e 74 69 6c 20 74 68 65 20 6e 65 78 74  r until the next
244f0 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69   call to.** sqli
24500 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28  te3_column_name(
24510 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c  ) or sqlite3_col
24520 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 6f 6e 20  umn_name16() on 
24530 74 68 65 20 73 61 6d 65 20 63 6f 6c 75 6d 6e 2e  the same column.
24540 0a 2a 2a 0a 2a 2a 20 49 66 20 73 71 6c 69 74 65  .**.** If sqlite
24550 33 5f 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73  3_malloc() fails
24560 20 64 75 72 69 6e 67 20 74 68 65 20 70 72 6f 63   during the proc
24570 65 73 73 69 6e 67 20 6f 66 20 65 69 74 68 65 72  essing of either
24580 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 28 66 6f 72   routine.** (for
24590 20 65 78 61 6d 70 6c 65 20 64 75 72 69 6e 67 20   example during 
245a0 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 66 72 6f  a conversion fro
245b0 6d 20 55 54 46 2d 38 20 74 6f 20 55 54 46 2d 31  m UTF-8 to UTF-1
245c0 36 29 20 74 68 65 6e 20 61 0a 2a 2a 20 4e 55 4c  6) then a.** NUL
245d0 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74  L pointer is ret
245e0 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  urned..**.** The
245f0 20 6e 61 6d 65 20 6f 66 20 61 20 72 65 73 75 6c   name of a resul
24600 74 20 63 6f 6c 75 6d 6e 20 69 73 20 74 68 65 20  t column is the 
24610 76 61 6c 75 65 20 6f 66 20 74 68 65 20 22 41 53  value of the "AS
24620 22 20 63 6c 61 75 73 65 20 66 6f 72 0a 2a 2a 20  " clause for.** 
24630 74 68 61 74 20 63 6f 6c 75 6d 6e 2c 20 69 66 20  that column, if 
24640 74 68 65 72 65 20 69 73 20 61 6e 20 41 53 20 63  there is an AS c
24650 6c 61 75 73 65 2e 20 20 49 66 20 74 68 65 72 65  lause.  If there
24660 20 69 73 20 6e 6f 20 41 53 20 63 6c 61 75 73 65   is no AS clause
24670 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 6e 61 6d  .** then the nam
24680 65 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20  e of the column 
24690 69 73 20 75 6e 73 70 65 63 69 66 69 65 64 20 61  is unspecified a
246a0 6e 64 20 6d 61 79 20 63 68 61 6e 67 65 20 66 72  nd may change fr
246b0 6f 6d 0a 2a 2a 20 6f 6e 65 20 72 65 6c 65 61 73  om.** one releas
246c0 65 20 6f 66 20 53 51 4c 69 74 65 20 74 6f 20 74  e of SQLite to t
246d0 68 65 20 6e 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 49  he next..**.** I
246e0 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
246f0 20 7b 48 31 33 37 32 31 7d 20 41 20 73 75 63 63   {H13721} A succ
24700 65 73 73 66 75 6c 20 69 6e 76 6f 63 61 74 69 6f  essful invocatio
24710 6e 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  n of the [sqlite
24720 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 53 2c  3_column_name(S,
24730 4e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  N)].**          
24740 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
24750 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
24760 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 28 77 68  e Nth column (wh
24770 65 72 65 20 30 20 69 73 0a 2a 2a 20 20 20 20 20  ere 0 is.**     
24780 20 20 20 20 20 74 68 65 20 6c 65 66 74 6d 6f 73       the leftmos
24790 74 20 63 6f 6c 75 6d 6e 29 20 66 6f 72 20 74 68  t column) for th
247a0 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20  e result set of 
247b0 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
247c0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
247d0 65 6e 74 5d 20 53 20 61 73 20 61 20 7a 65 72 6f  ent] S as a zero
247e0 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d  -terminated UTF-
247f0 38 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  8 string..**.** 
24800 7b 48 31 33 37 32 33 7d 20 41 20 73 75 63 63 65  {H13723} A succe
24810 73 73 66 75 6c 20 69 6e 76 6f 63 61 74 69 6f 6e  ssful invocation
24820 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
24830 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 53  _column_name16(S
24840 2c 4e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  ,N)].**         
24850 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
24860 6e 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  ns the name of t
24870 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 28 77  he Nth column (w
24880 68 65 72 65 20 30 20 69 73 0a 2a 2a 20 20 20 20  here 0 is.**    
24890 20 20 20 20 20 20 74 68 65 20 6c 65 66 74 6d 6f        the leftmo
248a0 73 74 20 63 6f 6c 75 6d 6e 29 20 66 6f 72 20 74  st column) for t
248b0 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66  he result set of
248c0 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
248d0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
248e0 6d 65 6e 74 5d 20 53 20 61 73 20 61 20 7a 65 72  ment] S as a zer
248f0 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46  o-terminated UTF
24900 2d 31 36 20 73 74 72 69 6e 67 0a 2a 2a 20 20 20  -16 string.**   
24910 20 20 20 20 20 20 20 69 6e 20 74 68 65 20 6e 61         in the na
24920 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e  tive byte order.
24930 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 32 34 7d 20  .**.** {H13724} 
24940 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  The [sqlite3_col
24950 75 6d 6e 5f 6e 61 6d 65 28 29 5d 20 61 6e 64 20  umn_name()] and 
24960 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
24970 6e 61 6d 65 31 36 28 29 5d 0a 2a 2a 20 20 20 20  name16()].**    
24980 20 20 20 20 20 20 69 6e 74 65 72 66 61 63 65 73        interfaces
24990 20 72 65 74 75 72 6e 20 61 20 4e 55 4c 4c 20 70   return a NULL p
249a0 6f 69 6e 74 65 72 20 69 66 20 74 68 65 79 20 61  ointer if they a
249b0 72 65 20 75 6e 61 62 6c 65 20 74 6f 0a 2a 2a 20  re unable to.** 
249c0 20 20 20 20 20 20 20 20 20 61 6c 6c 6f 63 61 74           allocat
249d0 65 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64  e memory to hold
249e0 20 74 68 65 69 72 20 6e 6f 72 6d 61 6c 20 72 65   their normal re
249f0 74 75 72 6e 20 73 74 72 69 6e 67 73 2e 0a 2a 2a  turn strings..**
24a00 0a 2a 2a 20 7b 48 31 33 37 32 35 7d 20 49 66 20  .** {H13725} If 
24a10 74 68 65 20 4e 20 70 61 72 61 6d 65 74 65 72 20  the N parameter 
24a20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  to [sqlite3_colu
24a30 6d 6e 5f 6e 61 6d 65 28 53 2c 4e 29 5d 20 6f 72  mn_name(S,N)] or
24a40 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
24a50 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
24a60 65 31 36 28 53 2c 4e 29 5d 20 69 73 20 6f 75 74  e16(S,N)] is out
24a70 20 6f 66 20 72 61 6e 67 65 2c 20 74 68 65 6e 20   of range, then 
24a80 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
24a90 69 6e 74 65 72 66 61 63 65 73 20 72 65 74 75 72  interfaces retur
24aa0 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  n a NULL pointer
24ab0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 32 36 7d  ..**.** {H13726}
24ac0 20 54 68 65 20 73 74 72 69 6e 67 73 20 72 65 74   The strings ret
24ad0 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65  urned by [sqlite
24ae0 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 53 2c  3_column_name(S,
24af0 4e 29 5d 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20  N)] and.**      
24b00 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c      [sqlite3_col
24b10 75 6d 6e 5f 6e 61 6d 65 31 36 28 53 2c 4e 29 5d  umn_name16(S,N)]
24b20 20 61 72 65 20 76 61 6c 69 64 20 75 6e 74 69 6c   are valid until
24b30 20 74 68 65 20 6e 65 78 74 0a 2a 2a 20 20 20 20   the next.**    
24b40 20 20 20 20 20 20 63 61 6c 6c 20 74 6f 20 65 69        call to ei
24b50 74 68 65 72 20 72 6f 75 74 69 6e 65 20 77 69 74  ther routine wit
24b60 68 20 74 68 65 20 73 61 6d 65 20 53 20 61 6e 64  h the same S and
24b70 20 4e 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a   N parameters.**
24b80 20 20 20 20 20 20 20 20 20 20 6f 72 20 75 6e 74            or unt
24b90 69 6c 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  il [sqlite3_fina
24ba0 6c 69 7a 65 28 53 29 5d 20 69 73 20 63 61 6c 6c  lize(S)] is call
24bb0 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 32  ed..**.** {H1372
24bc0 37 7d 20 57 68 65 6e 20 61 20 72 65 73 75 6c 74  7} When a result
24bd0 20 63 6f 6c 75 6d 6e 20 6f 66 20 61 20 5b 53 45   column of a [SE
24be0 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20  LECT] statement 
24bf0 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 20 20 20 20  contains.**     
24c00 20 20 20 20 20 61 6e 20 41 53 20 63 6c 61 75 73       an AS claus
24c10 65 2c 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  e, the name of t
24c20 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20 74 68  hat column is th
24c30 65 20 69 64 65 6e 74 69 66 69 65 72 0a 2a 2a 20  e identifier.** 
24c40 20 20 20 20 20 20 20 20 20 74 6f 20 74 68 65 20           to the 
24c50 72 69 67 68 74 20 6f 66 20 74 68 65 20 41 53 20  right of the AS 
24c60 6b 65 79 77 6f 72 64 2e 0a 2a 2f 0a 63 6f 6e 73  keyword..*/.cons
24c70 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
24c80 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73 71 6c 69  column_name(sqli
24c90 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e  te3_stmt*, int N
24ca0 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
24cb0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
24cc0 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  me16(sqlite3_stm
24cd0 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a  t*, int N);../*.
24ce0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 6f 75  ** CAPI3REF: Sou
24cf0 72 63 65 20 4f 66 20 44 61 74 61 20 49 6e 20 41  rce Of Data In A
24d00 20 51 75 65 72 79 20 52 65 73 75 6c 74 20 7b 48   Query Result {H
24d10 31 33 37 34 30 7d 20 3c 53 31 30 37 30 30 3e 0a  13740} <S10700>.
24d20 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
24d30 69 6e 65 73 20 70 72 6f 76 69 64 65 20 61 20 6d  ines provide a m
24d40 65 61 6e 73 20 74 6f 20 64 65 74 65 72 6d 69 6e  eans to determin
24d50 65 20 77 68 61 74 20 63 6f 6c 75 6d 6e 20 6f 66  e what column of
24d60 20 77 68 61 74 0a 2a 2a 20 74 61 62 6c 65 20 69   what.** table i
24d70 6e 20 77 68 69 63 68 20 64 61 74 61 62 61 73 65  n which database
24d80 20 61 20 72 65 73 75 6c 74 20 6f 66 20 61 20 5b   a result of a [
24d90 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e  SELECT] statemen
24da0 74 20 63 6f 6d 65 73 20 66 72 6f 6d 2e 0a 2a 2a  t comes from..**
24db0 20 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   The name of the
24dc0 20 64 61 74 61 62 61 73 65 20 6f 72 20 74 61 62   database or tab
24dd0 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 20 63 61 6e  le or column can
24de0 20 62 65 20 72 65 74 75 72 6e 65 64 20 61 73 0a   be returned as.
24df0 2a 2a 20 65 69 74 68 65 72 20 61 20 55 54 46 2d  ** either a UTF-
24e00 38 20 6f 72 20 55 54 46 2d 31 36 20 73 74 72 69  8 or UTF-16 stri
24e10 6e 67 2e 20 20 54 68 65 20 5f 64 61 74 61 62 61  ng.  The _databa
24e20 73 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74  se_ routines ret
24e30 75 72 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 62  urn.** the datab
24e40 61 73 65 20 6e 61 6d 65 2c 20 74 68 65 20 5f 74  ase name, the _t
24e50 61 62 6c 65 5f 20 72 6f 75 74 69 6e 65 73 20 72  able_ routines r
24e60 65 74 75 72 6e 20 74 68 65 20 74 61 62 6c 65 20  eturn the table 
24e70 6e 61 6d 65 2c 20 61 6e 64 0a 2a 2a 20 74 68 65  name, and.** the
24e80 20 6f 72 69 67 69 6e 5f 20 72 6f 75 74 69 6e 65   origin_ routine
24e90 73 20 72 65 74 75 72 6e 20 74 68 65 20 63 6f 6c  s return the col
24ea0 75 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a 20 54 68 65  umn name..** The
24eb0 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67   returned string
24ec0 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20   is valid until 
24ed0 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
24ee0 61 74 65 6d 65 6e 74 5d 20 69 73 20 64 65 73 74  atement] is dest
24ef0 72 6f 79 65 64 0a 2a 2a 20 75 73 69 6e 67 20 5b  royed.** using [
24f00 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
24f10 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65  ()] or until the
24f20 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f   same informatio
24f30 6e 20 69 73 20 72 65 71 75 65 73 74 65 64 0a 2a  n is requested.*
24f40 2a 20 61 67 61 69 6e 20 69 6e 20 61 20 64 69 66  * again in a dif
24f50 66 65 72 65 6e 74 20 65 6e 63 6f 64 69 6e 67 2e  ferent encoding.
24f60 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 73  .**.** The names
24f70 20 72 65 74 75 72 6e 65 64 20 61 72 65 20 74 68   returned are th
24f80 65 20 6f 72 69 67 69 6e 61 6c 20 75 6e 2d 61 6c  e original un-al
24f90 69 61 73 65 64 20 6e 61 6d 65 73 20 6f 66 20 74  iased names of t
24fa0 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2c 20  he.** database, 
24fb0 74 61 62 6c 65 2c 20 61 6e 64 20 63 6f 6c 75 6d  table, and colum
24fc0 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72  n..**.** The fir
24fd0 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  st argument to t
24fe0 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 61 6c  he following cal
24ff0 6c 73 20 69 73 20 61 20 5b 70 72 65 70 61 72 65  ls is a [prepare
25000 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a  d statement]..**
25010 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   These functions
25020 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74   return informat
25030 69 6f 6e 20 61 62 6f 75 74 20 74 68 65 20 4e 74  ion about the Nt
25040 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65  h column returne
25050 64 20 62 79 0a 2a 2a 20 74 68 65 20 73 74 61 74  d by.** the stat
25060 65 6d 65 6e 74 2c 20 77 68 65 72 65 20 4e 20 69  ement, where N i
25070 73 20 74 68 65 20 73 65 63 6f 6e 64 20 66 75 6e  s the second fun
25080 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a  ction argument..
25090 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 4e 74 68  **.** If the Nth
250a0 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64   column returned
250b0 20 62 79 20 74 68 65 20 73 74 61 74 65 6d 65 6e   by the statemen
250c0 74 20 69 73 20 61 6e 20 65 78 70 72 65 73 73 69  t is an expressi
250d0 6f 6e 20 6f 72 0a 2a 2a 20 73 75 62 71 75 65 72  on or.** subquer
250e0 79 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 63  y and is not a c
250f0 6f 6c 75 6d 6e 20 76 61 6c 75 65 2c 20 74 68 65  olumn value, the
25100 6e 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 66  n all of these f
25110 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 0a  unctions return.
25120 2a 2a 20 4e 55 4c 4c 2e 20 20 54 68 65 73 65 20  ** NULL.  These 
25130 72 6f 75 74 69 6e 65 20 6d 69 67 68 74 20 61 6c  routine might al
25140 73 6f 20 72 65 74 75 72 6e 20 4e 55 4c 4c 20 69  so return NULL i
25150 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  f a memory alloc
25160 61 74 69 6f 6e 20 65 72 72 6f 72 0a 2a 2a 20 6f  ation error.** o
25170 63 63 75 72 73 2e 20 20 4f 74 68 65 72 77 69 73  ccurs.  Otherwis
25180 65 2c 20 74 68 65 79 20 72 65 74 75 72 6e 20 74  e, they return t
25190 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 61  he name of the a
251a0 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65  ttached database
251b0 2c 20 74 61 62 6c 65 0a 2a 2a 20 61 6e 64 20 63  , table.** and c
251c0 6f 6c 75 6d 6e 20 74 68 61 74 20 71 75 65 72 79  olumn that query
251d0 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 77   result column w
251e0 61 73 20 65 78 74 72 61 63 74 65 64 20 66 72 6f  as extracted fro
251f0 6d 2e 0a 2a 2a 0a 2a 2a 20 41 73 20 77 69 74 68  m..**.** As with
25200 20 61 6c 6c 20 6f 74 68 65 72 20 53 51 4c 69 74   all other SQLit
25210 65 20 41 50 49 73 2c 20 74 68 6f 73 65 20 70 6f  e APIs, those po
25220 73 74 66 69 78 65 64 20 77 69 74 68 20 22 31 36  stfixed with "16
25230 22 20 72 65 74 75 72 6e 0a 2a 2a 20 55 54 46 2d  " return.** UTF-
25240 31 36 20 65 6e 63 6f 64 65 64 20 73 74 72 69 6e  16 encoded strin
25250 67 73 2c 20 74 68 65 20 6f 74 68 65 72 20 66 75  gs, the other fu
25260 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 55  nctions return U
25270 54 46 2d 38 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a  TF-8. {END}.**.*
25280 2a 20 54 68 65 73 65 20 41 50 49 73 20 61 72 65  * These APIs are
25290 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20   only available 
252a0 69 66 20 74 68 65 20 6c 69 62 72 61 72 79 20 77  if the library w
252b0 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  as compiled with
252c0 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
252d0 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45  ENABLE_COLUMN_ME
252e0 54 41 44 41 54 41 5d 20 43 2d 70 72 65 70 72 6f  TADATA] C-prepro
252f0 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c 20 64 65  cessor symbol de
25300 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 41 31  fined..**.** {A1
25310 33 37 35 31 7d 0a 2a 2a 20 49 66 20 74 77 6f 20  3751}.** If two 
25320 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20  or more threads 
25330 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  call one or more
25340 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
25350 65 73 20 61 67 61 69 6e 73 74 20 74 68 65 20 73  es against the s
25360 61 6d 65 0a 2a 2a 20 70 72 65 70 61 72 65 64 20  ame.** prepared 
25370 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 63 6f  statement and co
25380 6c 75 6d 6e 20 61 74 20 74 68 65 20 73 61 6d 65  lumn at the same
25390 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72   time then the r
253a0 65 73 75 6c 74 73 20 61 72 65 0a 2a 2a 20 75 6e  esults are.** un
253b0 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49  defined..**.** I
253c0 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
253d0 20 7b 48 31 33 37 34 31 7d 20 54 68 65 20 5b 73   {H13741} The [s
253e0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61  qlite3_column_da
253f0 74 61 62 61 73 65 5f 6e 61 6d 65 28 53 2c 4e 29  tabase_name(S,N)
25400 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ] interface retu
25410 72 6e 73 20 65 69 74 68 65 72 0a 2a 2a 20 20 20  rns either.**   
25420 20 20 20 20 20 20 20 74 68 65 20 55 54 46 2d 38         the UTF-8
25430 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
25440 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74   name of the dat
25450 61 62 61 73 65 20 66 72 6f 6d 20 77 68 69 63 68  abase from which
25460 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
25470 20 4e 74 68 20 72 65 73 75 6c 74 20 63 6f 6c 75   Nth result colu
25480 6d 6e 20 6f 66 20 74 68 65 20 5b 70 72 65 70 61  mn of the [prepa
25490 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
254a0 20 69 73 20 65 78 74 72 61 63 74 65 64 2c 0a 2a   is extracted,.*
254b0 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 4e 55  *          or NU
254c0 4c 4c 20 69 66 20 74 68 65 20 4e 74 68 20 63 6f  LL if the Nth co
254d0 6c 75 6d 6e 20 6f 66 20 53 20 69 73 20 61 20 67  lumn of S is a g
254e0 65 6e 65 72 61 6c 20 65 78 70 72 65 73 73 69 6f  eneral expressio
254f0 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72  n.**          or
25500 20 69 66 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c   if unable to al
25510 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f  locate memory to
25520 20 73 74 6f 72 65 20 74 68 65 20 6e 61 6d 65 2e   store the name.
25530 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 34 32 7d 20  .**.** {H13742} 
25540 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  The [sqlite3_col
25550 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d  umn_database_nam
25560 65 31 36 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66  e16(S,N)] interf
25570 61 63 65 20 72 65 74 75 72 6e 73 20 65 69 74 68  ace returns eith
25580 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  er.**          t
25590 68 65 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65  he UTF-16 native
255a0 20 62 79 74 65 20 6f 72 64 65 72 20 7a 65 72 6f   byte order zero
255b0 2d 74 65 72 6d 69 6e 61 74 65 64 20 6e 61 6d 65  -terminated name
255c0 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
255d0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 72 6f  .**          fro
255e0 6d 20 77 68 69 63 68 20 74 68 65 20 4e 74 68 20  m which the Nth 
255f0 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66  result column of
25600 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
25610 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 73 0a 2a  tatement] S is.*
25620 2a 20 20 20 20 20 20 20 20 20 20 65 78 74 72 61  *          extra
25630 63 74 65 64 2c 20 6f 72 20 4e 55 4c 4c 20 69 66  cted, or NULL if
25640 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20   the Nth column 
25650 6f 66 20 53 20 69 73 20 61 20 67 65 6e 65 72 61  of S is a genera
25660 6c 20 65 78 70 72 65 73 73 69 6f 6e 0a 2a 2a 20  l expression.** 
25670 20 20 20 20 20 20 20 20 20 6f 72 20 69 66 20 75           or if u
25680 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74  nable to allocat
25690 65 20 6d 65 6d 6f 72 79 20 74 6f 20 73 74 6f 72  e memory to stor
256a0 65 20 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a  e the name..**.*
256b0 2a 20 7b 48 31 33 37 34 33 7d 20 54 68 65 20 5b  * {H13743} The [
256c0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
256d0 61 62 6c 65 5f 6e 61 6d 65 28 53 2c 4e 29 5d 20  able_name(S,N)] 
256e0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
256f0 73 20 65 69 74 68 65 72 0a 2a 2a 20 20 20 20 20  s either.**     
25700 20 20 20 20 20 74 68 65 20 55 54 46 2d 38 20 7a       the UTF-8 z
25710 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 6e  ero-terminated n
25720 61 6d 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65  ame of the table
25730 20 66 72 6f 6d 20 77 68 69 63 68 20 74 68 65 0a   from which the.
25740 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 74 68 20  **          Nth 
25750 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66  result column of
25760 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
25770 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 73 20 65  tatement] S is e
25780 78 74 72 61 63 74 65 64 2c 0a 2a 2a 20 20 20 20  xtracted,.**    
25790 20 20 20 20 20 20 6f 72 20 4e 55 4c 4c 20 69 66        or NULL if
257a0 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20   the Nth column 
257b0 6f 66 20 53 20 69 73 20 61 20 67 65 6e 65 72 61  of S is a genera
257c0 6c 20 65 78 70 72 65 73 73 69 6f 6e 0a 2a 2a 20  l expression.** 
257d0 20 20 20 20 20 20 20 20 20 6f 72 20 69 66 20 75           or if u
257e0 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74  nable to allocat
257f0 65 20 6d 65 6d 6f 72 79 20 74 6f 20 73 74 6f 72  e memory to stor
25800 65 20 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a  e the name..**.*
25810 2a 20 7b 48 31 33 37 34 34 7d 20 54 68 65 20 5b  * {H13744} The [
25820 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
25830 61 62 6c 65 5f 6e 61 6d 65 31 36 28 53 2c 4e 29  able_name16(S,N)
25840 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ] interface retu
25850 72 6e 73 20 65 69 74 68 65 72 0a 2a 2a 20 20 20  rns either.**   
25860 20 20 20 20 20 20 20 74 68 65 20 55 54 46 2d 31         the UTF-1
25870 36 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  6 native byte or
25880 64 65 72 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  der zero-termina
25890 74 65 64 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  ted name of the 
258a0 74 61 62 6c 65 0a 2a 2a 20 20 20 20 20 20 20 20  table.**        
258b0 20 20 66 72 6f 6d 20 77 68 69 63 68 20 74 68 65    from which the
258c0 20 4e 74 68 20 72 65 73 75 6c 74 20 63 6f 6c 75   Nth result colu
258d0 6d 6e 20 6f 66 20 74 68 65 20 5b 70 72 65 70 61  mn of the [prepa
258e0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
258f0 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   is.**          
25900 65 78 74 72 61 63 74 65 64 2c 20 6f 72 20 4e 55  extracted, or NU
25910 4c 4c 20 69 66 20 74 68 65 20 4e 74 68 20 63 6f  LL if the Nth co
25920 6c 75 6d 6e 20 6f 66 20 53 20 69 73 20 61 20 67  lumn of S is a g
25930 65 6e 65 72 61 6c 20 65 78 70 72 65 73 73 69 6f  eneral expressio
25940 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72  n.**          or
25950 20 69 66 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c   if unable to al
25960 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f  locate memory to
25970 20 73 74 6f 72 65 20 74 68 65 20 6e 61 6d 65 2e   store the name.
25980 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 34 35 7d 20  .**.** {H13745} 
25990 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  The [sqlite3_col
259a0 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 28  umn_origin_name(
259b0 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20  S,N)] interface 
259c0 72 65 74 75 72 6e 73 20 65 69 74 68 65 72 0a 2a  returns either.*
259d0 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 55  *          the U
259e0 54 46 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  TF-8 zero-termin
259f0 61 74 65 64 20 6e 61 6d 65 20 6f 66 20 74 68 65  ated name of the
25a00 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 66 72   table column fr
25a10 6f 6d 20 77 68 69 63 68 20 74 68 65 0a 2a 2a 20  om which the.** 
25a20 20 20 20 20 20 20 20 20 20 4e 74 68 20 72 65 73           Nth res
25a30 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68  ult column of th
25a40 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
25a50 65 6d 65 6e 74 5d 20 53 20 69 73 20 65 78 74 72  ement] S is extr
25a60 61 63 74 65 64 2c 0a 2a 2a 20 20 20 20 20 20 20  acted,.**       
25a70 20 20 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68     or NULL if th
25a80 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20  e Nth column of 
25a90 53 20 69 73 20 61 20 67 65 6e 65 72 61 6c 20 65  S is a general e
25aa0 78 70 72 65 73 73 69 6f 6e 0a 2a 2a 20 20 20 20  xpression.**    
25ab0 20 20 20 20 20 20 6f 72 20 69 66 20 75 6e 61 62        or if unab
25ac0 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d  le to allocate m
25ad0 65 6d 6f 72 79 20 74 6f 20 73 74 6f 72 65 20 74  emory to store t
25ae0 68 65 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20 7b  he name..**.** {
25af0 48 31 33 37 34 36 7d 20 54 68 65 20 5b 73 71 6c  H13746} The [sql
25b00 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67  ite3_column_orig
25b10 69 6e 5f 6e 61 6d 65 31 36 28 53 2c 4e 29 5d 20  in_name16(S,N)] 
25b20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
25b30 73 20 65 69 74 68 65 72 0a 2a 2a 20 20 20 20 20  s either.**     
25b40 20 20 20 20 20 74 68 65 20 55 54 46 2d 31 36 20       the UTF-16 
25b50 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
25b60 72 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  r zero-terminate
25b70 64 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 74 61  d name of the ta
25b80 62 6c 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ble.**          
25b90 63 6f 6c 75 6d 6e 20 66 72 6f 6d 20 77 68 69 63  column from whic
25ba0 68 20 74 68 65 20 4e 74 68 20 72 65 73 75 6c 74  h the Nth result
25bb0 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 0a 2a   column of the.*
25bc0 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70  *          [prep
25bd0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
25be0 53 20 69 73 20 65 78 74 72 61 63 74 65 64 2c 20  S is extracted, 
25bf0 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 65 20 4e  or NULL if the N
25c00 74 68 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 20 20 20  th column.**    
25c10 20 20 20 20 20 20 6f 66 20 53 20 69 73 20 61 20        of S is a 
25c20 67 65 6e 65 72 61 6c 20 65 78 70 72 65 73 73 69  general expressi
25c30 6f 6e 20 6f 72 20 69 66 20 75 6e 61 62 6c 65 20  on or if unable 
25c40 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f  to allocate memo
25c50 72 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  ry.**          t
25c60 6f 20 73 74 6f 72 65 20 74 68 65 20 6e 61 6d 65  o store the name
25c70 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 34 38 7d  ..**.** {H13748}
25c80 20 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   The return valu
25c90 65 73 20 66 72 6f 6d 0a 2a 2a 20 20 20 20 20 20  es from.**      
25ca0 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c      [sqlite3_col
25cb0 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d  umn_database_nam
25cc0 65 20 7c 20 63 6f 6c 75 6d 6e 20 6d 65 74 61 64  e | column metad
25cd0 61 74 61 20 69 6e 74 65 72 66 61 63 65 73 5d 0a  ata interfaces].
25ce0 2a 2a 20 20 20 20 20 20 20 20 20 20 61 72 65 20  **          are 
25cf0 76 61 6c 69 64 20 66 6f 72 20 74 68 65 20 6c 69  valid for the li
25d00 66 65 74 69 6d 65 20 6f 66 20 74 68 65 20 5b 70  fetime of the [p
25d10 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
25d20 74 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  t].**          o
25d30 72 20 75 6e 74 69 6c 20 74 68 65 20 65 6e 63 6f  r until the enco
25d40 64 69 6e 67 20 69 73 20 63 68 61 6e 67 65 64 20  ding is changed 
25d50 62 79 20 61 6e 6f 74 68 65 72 20 6d 65 74 61 64  by another metad
25d60 61 74 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ata.**          
25d70 69 6e 74 65 72 66 61 63 65 20 63 61 6c 6c 20 66  interface call f
25d80 6f 72 20 74 68 65 20 73 61 6d 65 20 70 72 65 70  or the same prep
25d90 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61  ared statement a
25da0 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a  nd column..**.**
25db0 20 41 53 53 55 4d 50 54 49 4f 4e 53 3a 0a 2a 2a   ASSUMPTIONS:.**
25dc0 0a 2a 2a 20 7b 41 31 33 37 35 31 7d 20 49 66 20  .** {A13751} If 
25dd0 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65  two or more thre
25de0 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20  ads call one or 
25df0 6d 6f 72 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  more.**         
25e00 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
25e10 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 20 7c  _database_name |
25e20 20 63 6f 6c 75 6d 6e 20 6d 65 74 61 64 61 74 61   column metadata
25e30 20 69 6e 74 65 72 66 61 63 65 73 5d 0a 2a 2a 20   interfaces].** 
25e40 20 20 20 20 20 20 20 20 20 66 6f 72 20 74 68 65           for the
25e50 20 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20   same [prepared 
25e60 73 74 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20 72  statement] and r
25e70 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20  esult column.** 
25e80 20 20 20 20 20 20 20 20 20 61 74 20 74 68 65 20           at the 
25e90 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74  same time then t
25ea0 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75  he results are u
25eb0 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 63 6f 6e  ndefined..*/.con
25ec0 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
25ed0 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65  _column_database
25ee0 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74  _name(sqlite3_st
25ef0 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20  mt*,int);.const 
25f00 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
25f10 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61  lumn_database_na
25f20 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  me16(sqlite3_stm
25f30 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63  t*,int);.const c
25f40 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  har *sqlite3_col
25f50 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 28 73  umn_table_name(s
25f60 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
25f70 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
25f80 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61  qlite3_column_ta
25f90 62 6c 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74  ble_name16(sqlit
25fa0 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63  e3_stmt*,int);.c
25fb0 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
25fc0 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e  e3_column_origin
25fd0 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74  _name(sqlite3_st
25fe0 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20  mt*,int);.const 
25ff0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
26000 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65  lumn_origin_name
26010 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
26020 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ,int);../*.** CA
26030 50 49 33 52 45 46 3a 20 44 65 63 6c 61 72 65 64  PI3REF: Declared
26040 20 44 61 74 61 74 79 70 65 20 4f 66 20 41 20 51   Datatype Of A Q
26050 75 65 72 79 20 52 65 73 75 6c 74 20 7b 48 31 33  uery Result {H13
26060 37 36 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 2a  760} <S10700>.**
26070 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 61  .** The first pa
26080 72 61 6d 65 74 65 72 20 69 73 20 61 20 5b 70 72  rameter is a [pr
26090 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
260a0 5d 2e 0a 2a 2a 20 49 66 20 74 68 69 73 20 73 74  ]..** If this st
260b0 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 53 45  atement is a [SE
260c0 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20  LECT] statement 
260d0 61 6e 64 20 74 68 65 20 4e 74 68 20 63 6f 6c 75  and the Nth colu
260e0 6d 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65 74  mn of the.** ret
260f0 75 72 6e 65 64 20 72 65 73 75 6c 74 20 73 65 74  urned result set
26100 20 6f 66 20 74 68 61 74 20 5b 53 45 4c 45 43 54   of that [SELECT
26110 5d 20 69 73 20 61 20 74 61 62 6c 65 20 63 6f 6c  ] is a table col
26120 75 6d 6e 20 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65  umn (not an.** e
26130 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62  xpression or sub
26140 71 75 65 72 79 29 20 74 68 65 6e 20 74 68 65 20  query) then the 
26150 64 65 63 6c 61 72 65 64 20 74 79 70 65 20 6f 66  declared type of
26160 20 74 68 65 20 74 61 62 6c 65 0a 2a 2a 20 63 6f   the table.** co
26170 6c 75 6d 6e 20 69 73 20 72 65 74 75 72 6e 65 64  lumn is returned
26180 2e 20 20 49 66 20 74 68 65 20 4e 74 68 20 63 6f  .  If the Nth co
26190 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75  lumn of the resu
261a0 6c 74 20 73 65 74 20 69 73 20 61 6e 0a 2a 2a 20  lt set is an.** 
261b0 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75  expression or su
261c0 62 71 75 65 72 79 2c 20 74 68 65 6e 20 61 20 4e  bquery, then a N
261d0 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72  ULL pointer is r
261e0 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 54 68 65 20  eturned..** The 
261f0 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20  returned string 
26200 69 73 20 61 6c 77 61 79 73 20 55 54 46 2d 38 20  is always UTF-8 
26210 65 6e 63 6f 64 65 64 2e 20 7b 45 4e 44 7d 0a 2a  encoded. {END}.*
26220 2a 0a 2a 2a 20 46 6f 72 20 65 78 61 6d 70 6c 65  *.** For example
26230 2c 20 67 69 76 65 6e 20 74 68 65 20 64 61 74 61  , given the data
26240 62 61 73 65 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a  base schema:.**.
26250 2a 2a 20 43 52 45 41 54 45 20 54 41 42 4c 45 20  ** CREATE TABLE 
26260 74 31 28 63 31 20 56 41 52 49 41 4e 54 29 3b 0a  t1(c1 VARIANT);.
26270 2a 2a 0a 2a 2a 20 61 6e 64 20 74 68 65 20 66 6f  **.** and the fo
26280 6c 6c 6f 77 69 6e 67 20 73 74 61 74 65 6d 65 6e  llowing statemen
26290 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64  t to be compiled
262a0 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c 45 43 54 20 63  :.**.** SELECT c
262b0 31 20 2b 20 31 2c 20 63 31 20 46 52 4f 4d 20 74  1 + 1, c1 FROM t
262c0 31 3b 0a 2a 2a 0a 2a 2a 20 74 68 69 73 20 72 6f  1;.**.** this ro
262d0 75 74 69 6e 65 20 77 6f 75 6c 64 20 72 65 74 75  utine would retu
262e0 72 6e 20 74 68 65 20 73 74 72 69 6e 67 20 22 56  rn the string "V
262f0 41 52 49 41 4e 54 22 20 66 6f 72 20 74 68 65 20  ARIANT" for the 
26300 73 65 63 6f 6e 64 20 72 65 73 75 6c 74 0a 2a 2a  second result.**
26310 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c 20   column (i==1), 
26320 61 6e 64 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  and a NULL point
26330 65 72 20 66 6f 72 20 74 68 65 20 66 69 72 73 74  er for the first
26340 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 28   result column (
26350 69 3d 3d 30 29 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c  i==0)..**.** SQL
26360 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63  ite uses dynamic
26370 20 72 75 6e 2d 74 69 6d 65 20 74 79 70 69 6e 67   run-time typing
26380 2e 20 20 53 6f 20 6a 75 73 74 20 62 65 63 61 75  .  So just becau
26390 73 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69  se a column.** i
263a0 73 20 64 65 63 6c 61 72 65 64 20 74 6f 20 63 6f  s declared to co
263b0 6e 74 61 69 6e 20 61 20 70 61 72 74 69 63 75 6c  ntain a particul
263c0 61 72 20 74 79 70 65 20 64 6f 65 73 20 6e 6f 74  ar type does not
263d0 20 6d 65 61 6e 20 74 68 61 74 20 74 68 65 0a 2a   mean that the.*
263e0 2a 20 64 61 74 61 20 73 74 6f 72 65 64 20 69 6e  * data stored in
263f0 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20   that column is 
26400 6f 66 20 74 68 65 20 64 65 63 6c 61 72 65 64 20  of the declared 
26410 74 79 70 65 2e 20 20 53 51 4c 69 74 65 20 69 73  type.  SQLite is
26420 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79 20 74 79 70  .** strongly typ
26430 65 64 2c 20 62 75 74 20 74 68 65 20 74 79 70 69  ed, but the typi
26440 6e 67 20 69 73 20 64 79 6e 61 6d 69 63 20 6e 6f  ng is dynamic no
26450 74 20 73 74 61 74 69 63 2e 20 20 54 79 70 65 0a  t static.  Type.
26460 2a 2a 20 69 73 20 61 73 73 6f 63 69 61 74 65 64  ** is associated
26470 20 77 69 74 68 20 69 6e 64 69 76 69 64 75 61 6c   with individual
26480 20 76 61 6c 75 65 73 2c 20 6e 6f 74 20 77 69 74   values, not wit
26490 68 20 74 68 65 20 63 6f 6e 74 61 69 6e 65 72 73  h the containers
264a0 0a 2a 2a 20 75 73 65 64 20 74 6f 20 68 6f 6c 64  .** used to hold
264b0 20 74 68 6f 73 65 20 76 61 6c 75 65 73 2e 0a 2a   those values..*
264c0 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
264d0 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 36 31 7d 20  .**.** {H13761} 
264e0 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 63 61   A successful ca
264f0 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ll to [sqlite3_c
26500 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 28 53  olumn_decltype(S
26510 2c 4e 29 5d 20 72 65 74 75 72 6e 73 20 61 0a 2a  ,N)] returns a.*
26520 2a 20 20 20 20 20 20 20 20 20 20 20 7a 65 72 6f  *           zero
26530 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d  -terminated UTF-
26540 38 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e  8 string contain
26550 69 6e 67 20 74 68 65 20 64 65 63 6c 61 72 65 64  ing the declared
26560 20 64 61 74 61 74 79 70 65 0a 2a 2a 20 20 20 20   datatype.**    
26570 20 20 20 20 20 20 20 6f 66 20 74 68 65 20 74 61         of the ta
26580 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20  ble column that 
26590 61 70 70 65 61 72 73 20 61 73 20 74 68 65 20 4e  appears as the N
265a0 74 68 20 63 6f 6c 75 6d 6e 20 28 6e 75 6d 62 65  th column (numbe
265b0 72 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  red.**          
265c0 20 66 72 6f 6d 20 30 29 20 6f 66 20 74 68 65 20   from 0) of the 
265d0 72 65 73 75 6c 74 20 73 65 74 20 74 6f 20 74 68  result set to th
265e0 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
265f0 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2a 0a 2a 2a 20  ement] S..**.** 
26600 7b 48 31 33 37 36 32 7d 20 20 41 20 73 75 63 63  {H13762}  A succ
26610 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b  essful call to [
26620 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
26630 65 63 6c 74 79 70 65 31 36 28 53 2c 4e 29 5d 0a  ecltype16(S,N)].
26640 2a 2a 20 20 20 20 20 20 20 20 20 20 20 72 65 74  **           ret
26650 75 72 6e 73 20 61 20 7a 65 72 6f 2d 74 65 72 6d  urns a zero-term
26660 69 6e 61 74 65 64 20 55 54 46 2d 31 36 20 6e 61  inated UTF-16 na
26670 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20  tive byte order 
26680 73 74 72 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20  string.**       
26690 20 20 20 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74      containing t
266a0 68 65 20 64 65 63 6c 61 72 65 64 20 64 61 74 61  he declared data
266b0 74 79 70 65 20 6f 66 20 74 68 65 20 74 61 62 6c  type of the tabl
266c0 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 61 70  e column that ap
266d0 70 65 61 72 73 0a 2a 2a 20 20 20 20 20 20 20 20  pears.**        
266e0 20 20 20 61 73 20 74 68 65 20 4e 74 68 20 63 6f     as the Nth co
266f0 6c 75 6d 6e 20 28 6e 75 6d 62 65 72 65 64 20 66  lumn (numbered f
26700 72 6f 6d 20 30 29 20 6f 66 20 74 68 65 20 72 65  rom 0) of the re
26710 73 75 6c 74 20 73 65 74 20 74 6f 20 74 68 65 0a  sult set to the.
26720 2a 2a 20 20 20 20 20 20 20 20 20 20 20 5b 70 72  **           [pr
26730 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
26740 5d 20 53 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37  ] S..**.** {H137
26750 36 33 7d 20 20 49 66 20 4e 20 69 73 20 6c 65 73  63}  If N is les
26760 73 20 74 68 61 6e 20 30 20 6f 72 20 4e 20 69 73  s than 0 or N is
26770 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 6f 72   greater than or
26780 20 65 71 75 61 6c 20 74 6f 0a 2a 2a 20 20 20 20   equal to.**    
26790 20 20 20 20 20 20 20 74 68 65 20 6e 75 6d 62 65         the numbe
267a0 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20  r of columns in 
267b0 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
267c0 61 74 65 6d 65 6e 74 5d 20 53 2c 0a 2a 2a 20 20  atement] S,.**  
267d0 20 20 20 20 20 20 20 20 20 6f 72 20 69 66 20 74           or if t
267e0 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66  he Nth column of
267f0 20 53 20 69 73 20 61 6e 20 65 78 70 72 65 73 73   S is an express
26800 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79 20  ion or subquery 
26810 72 61 74 68 65 72 0a 2a 2a 20 20 20 20 20 20 20  rather.**       
26820 20 20 20 20 74 68 61 6e 20 61 20 74 61 62 6c 65      than a table
26830 20 63 6f 6c 75 6d 6e 2c 20 6f 72 20 69 66 20 61   column, or if a
26840 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
26850 6f 6e 20 66 61 69 6c 75 72 65 0a 2a 2a 20 20 20  on failure.**   
26860 20 20 20 20 20 20 20 20 6f 63 63 75 72 73 20 64          occurs d
26870 75 72 69 6e 67 20 65 6e 63 6f 64 69 6e 67 20 63  uring encoding c
26880 6f 6e 76 65 72 73 69 6f 6e 73 2c 20 74 68 65 6e  onversions, then
26890 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 63 61  .**           ca
268a0 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
268b0 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 28  column_decltype(
268c0 53 2c 4e 29 5d 20 6f 72 0a 2a 2a 20 20 20 20 20  S,N)] or.**     
268d0 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63        [sqlite3_c
268e0 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31 36  olumn_decltype16
268f0 28 53 2c 4e 29 5d 20 72 65 74 75 72 6e 20 4e 55  (S,N)] return NU
26900 4c 4c 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61  LL..*/.const cha
26910 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  r *sqlite3_colum
26920 6e 5f 64 65 63 6c 74 79 70 65 28 73 71 6c 69 74  n_decltype(sqlit
26930 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63  e3_stmt*,int);.c
26940 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
26950 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79  e3_column_declty
26960 70 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  pe16(sqlite3_stm
26970 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  t*,int);../*.** 
26980 43 41 50 49 33 52 45 46 3a 20 45 76 61 6c 75 61  CAPI3REF: Evalua
26990 74 65 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d  te An SQL Statem
269a0 65 6e 74 20 7b 48 31 33 32 30 30 7d 20 3c 53 31  ent {H13200} <S1
269b0 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 41 66 74 65  0000>.**.** Afte
269c0 72 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  r a [prepared st
269d0 61 74 65 6d 65 6e 74 5d 20 68 61 73 20 62 65 65  atement] has bee
269e0 6e 20 70 72 65 70 61 72 65 64 20 75 73 69 6e 67  n prepared using
269f0 20 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69   either.** [sqli
26a00 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
26a10 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72  ] or [sqlite3_pr
26a20 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72  epare16_v2()] or
26a30 20 6f 6e 65 20 6f 66 20 74 68 65 20 6c 65 67 61   one of the lega
26a40 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73  cy.** interfaces
26a50 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
26a60 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  e()] or [sqlite3
26a70 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2c 20 74  _prepare16()], t
26a80 68 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20  his function.** 
26a90 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 6f  must be called o
26aa0 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73  ne or more times
26ab0 20 74 6f 20 65 76 61 6c 75 61 74 65 20 74 68 65   to evaluate the
26ac0 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a   statement..**.*
26ad0 2a 20 54 68 65 20 64 65 74 61 69 6c 73 20 6f 66  * The details of
26ae0 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66   the behavior of
26af0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74 65   the sqlite3_ste
26b00 70 28 29 20 69 6e 74 65 72 66 61 63 65 20 64 65  p() interface de
26b10 70 65 6e 64 0a 2a 2a 20 6f 6e 20 77 68 65 74 68  pend.** on wheth
26b20 65 72 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  er the statement
26b30 20 77 61 73 20 70 72 65 70 61 72 65 64 20 75 73   was prepared us
26b40 69 6e 67 20 74 68 65 20 6e 65 77 65 72 20 22 76  ing the newer "v
26b50 32 22 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  2" interface.** 
26b60 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
26b70 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  _v2()] and [sqli
26b80 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
26b90 28 29 5d 20 6f 72 20 74 68 65 20 6f 6c 64 65 72  ()] or the older
26ba0 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72   legacy.** inter
26bb0 66 61 63 65 20 5b 73 71 6c 69 74 65 33 5f 70 72  face [sqlite3_pr
26bc0 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71  epare()] and [sq
26bd0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
26be0 29 5d 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20  )].  The use of 
26bf0 74 68 65 0a 2a 2a 20 6e 65 77 20 22 76 32 22 20  the.** new "v2" 
26c00 69 6e 74 65 72 66 61 63 65 20 69 73 20 72 65 63  interface is rec
26c10 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6e 65 77  ommended for new
26c20 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 62 75   applications bu
26c30 74 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20  t the legacy.** 
26c40 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 63  interface will c
26c50 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 20 73 75  ontinue to be su
26c60 70 70 6f 72 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49  pported..**.** I
26c70 6e 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74  n the legacy int
26c80 65 72 66 61 63 65 2c 20 74 68 65 20 72 65 74 75  erface, the retu
26c90 72 6e 20 76 61 6c 75 65 20 77 69 6c 6c 20 62 65  rn value will be
26ca0 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f   either [SQLITE_
26cb0 42 55 53 59 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54  BUSY],.** [SQLIT
26cc0 45 5f 44 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45  E_DONE], [SQLITE
26cd0 5f 52 4f 57 5d 2c 20 5b 53 51 4c 49 54 45 5f 45  _ROW], [SQLITE_E
26ce0 52 52 4f 52 5d 2c 20 6f 72 20 5b 53 51 4c 49 54  RROR], or [SQLIT
26cf0 45 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2a 20 57 69  E_MISUSE]..** Wi
26d00 74 68 20 74 68 65 20 22 76 32 22 20 69 6e 74 65  th the "v2" inte
26d10 72 66 61 63 65 2c 20 61 6e 79 20 6f 66 20 74 68  rface, any of th
26d20 65 20 6f 74 68 65 72 20 5b 72 65 73 75 6c 74 20  e other [result 
26d30 63 6f 64 65 73 5d 20 6f 72 0a 2a 2a 20 5b 65 78  codes] or.** [ex
26d40 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
26d50 64 65 73 5d 20 6d 69 67 68 74 20 62 65 20 72 65  des] might be re
26d60 74 75 72 6e 65 64 20 61 73 20 77 65 6c 6c 2e 0a  turned as well..
26d70 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55  **.** [SQLITE_BU
26d80 53 59 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74  SY] means that t
26d90 68 65 20 64 61 74 61 62 61 73 65 20 65 6e 67 69  he database engi
26da0 6e 65 20 77 61 73 20 75 6e 61 62 6c 65 20 74 6f  ne was unable to
26db0 20 61 63 71 75 69 72 65 20 74 68 65 0a 2a 2a 20   acquire the.** 
26dc0 64 61 74 61 62 61 73 65 20 6c 6f 63 6b 73 20 69  database locks i
26dd0 74 20 6e 65 65 64 73 20 74 6f 20 64 6f 20 69 74  t needs to do it
26de0 73 20 6a 6f 62 2e 20 20 49 66 20 74 68 65 20 73  s job.  If the s
26df0 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 43  tatement is a [C
26e00 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 72 20 6f 63 63  OMMIT].** or occ
26e10 75 72 73 20 6f 75 74 73 69 64 65 20 6f 66 20 61  urs outside of a
26e20 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73  n explicit trans
26e30 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 79 6f 75  action, then you
26e40 20 63 61 6e 20 72 65 74 72 79 20 74 68 65 0a 2a   can retry the.*
26e50 2a 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 49 66  * statement.  If
26e60 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
26e70 73 20 6e 6f 74 20 61 20 5b 43 4f 4d 4d 49 54 5d  s not a [COMMIT]
26e80 20 61 6e 64 20 6f 63 63 75 72 73 20 77 69 74 68   and occurs with
26e90 69 6e 20 61 0a 2a 2a 20 65 78 70 6c 69 63 69 74  in a.** explicit
26ea0 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 68 65   transaction the
26eb0 6e 20 79 6f 75 20 73 68 6f 75 6c 64 20 72 6f 6c  n you should rol
26ec0 6c 62 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61  lback the transa
26ed0 63 74 69 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a 20  ction before.** 
26ee0 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a  continuing..**.*
26ef0 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 20  * [SQLITE_DONE] 
26f00 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 73  means that the s
26f10 74 61 74 65 6d 65 6e 74 20 68 61 73 20 66 69 6e  tatement has fin
26f20 69 73 68 65 64 20 65 78 65 63 75 74 69 6e 67 0a  ished executing.
26f30 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2e  ** successfully.
26f40 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29    sqlite3_step()
26f50 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63   should not be c
26f60 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 20 74  alled again on t
26f70 68 69 73 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d  his virtual.** m
26f80 61 63 68 69 6e 65 20 77 69 74 68 6f 75 74 20 66  achine without f
26f90 69 72 73 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71  irst calling [sq
26fa0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74  lite3_reset()] t
26fb0 6f 20 72 65 73 65 74 20 74 68 65 20 76 69 72 74  o reset the virt
26fc0 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 62  ual.** machine b
26fd0 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69  ack to its initi
26fe0 61 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20  al state..**.** 
26ff0 49 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  If the SQL state
27000 6d 65 6e 74 20 62 65 69 6e 67 20 65 78 65 63 75  ment being execu
27010 74 65 64 20 72 65 74 75 72 6e 73 20 61 6e 79 20  ted returns any 
27020 64 61 74 61 2c 20 74 68 65 6e 20 5b 53 51 4c 49  data, then [SQLI
27030 54 45 5f 52 4f 57 5d 0a 2a 2a 20 69 73 20 72 65  TE_ROW].** is re
27040 74 75 72 6e 65 64 20 65 61 63 68 20 74 69 6d 65  turned each time
27050 20 61 20 6e 65 77 20 72 6f 77 20 6f 66 20 64 61   a new row of da
27060 74 61 20 69 73 20 72 65 61 64 79 20 66 6f 72 20  ta is ready for 
27070 70 72 6f 63 65 73 73 69 6e 67 20 62 79 20 74 68  processing by th
27080 65 0a 2a 2a 20 63 61 6c 6c 65 72 2e 20 54 68 65  e.** caller. The
27090 20 76 61 6c 75 65 73 20 6d 61 79 20 62 65 20 61   values may be a
270a0 63 63 65 73 73 65 64 20 75 73 69 6e 67 20 74 68  ccessed using th
270b0 65 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73  e [column access
270c0 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20   functions]..** 
270d0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69  sqlite3_step() i
270e0 73 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 74  s called again t
270f0 6f 20 72 65 74 72 69 65 76 65 20 74 68 65 20 6e  o retrieve the n
27100 65 78 74 20 72 6f 77 20 6f 66 20 64 61 74 61 2e  ext row of data.
27110 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45  .**.** [SQLITE_E
27120 52 52 4f 52 5d 20 6d 65 61 6e 73 20 74 68 61 74  RROR] means that
27130 20 61 20 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f   a run-time erro
27140 72 20 28 73 75 63 68 20 61 73 20 61 20 63 6f 6e  r (such as a con
27150 73 74 72 61 69 6e 74 0a 2a 2a 20 76 69 6f 6c 61  straint.** viola
27160 74 69 6f 6e 29 20 68 61 73 20 6f 63 63 75 72 72  tion) has occurr
27170 65 64 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65  ed.  sqlite3_ste
27180 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62  p() should not b
27190 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f  e called again o
271a0 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e 20 4d 6f 72  n.** the VM. Mor
271b0 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6d 61  e information ma
271c0 79 20 62 65 20 66 6f 75 6e 64 20 62 79 20 63 61  y be found by ca
271d0 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65  lling [sqlite3_e
271e0 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20 57 69 74  rrmsg()]..** Wit
271f0 68 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74  h the legacy int
27200 65 72 66 61 63 65 2c 20 61 20 6d 6f 72 65 20 73  erface, a more s
27210 70 65 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f  pecific error co
27220 64 65 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 2c  de (for example,
27230 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45  .** [SQLITE_INTE
27240 52 52 55 50 54 5d 2c 20 5b 53 51 4c 49 54 45 5f  RRUPT], [SQLITE_
27250 53 43 48 45 4d 41 5d 2c 20 5b 53 51 4c 49 54 45  SCHEMA], [SQLITE
27260 5f 43 4f 52 52 55 50 54 5d 2c 20 61 6e 64 20 73  _CORRUPT], and s
27270 6f 20 66 6f 72 74 68 29 0a 2a 2a 20 63 61 6e 20  o forth).** can 
27280 62 65 20 6f 62 74 61 69 6e 65 64 20 62 79 20 63  be obtained by c
27290 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
272a0 72 65 73 65 74 28 29 5d 20 6f 6e 20 74 68 65 0a  reset()] on the.
272b0 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ** [prepared sta
272c0 74 65 6d 65 6e 74 5d 2e 20 20 49 6e 20 74 68 65  tement].  In the
272d0 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c   "v2" interface,
272e0 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73 70 65  .** the more spe
272f0 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64 65  cific error code
27300 20 69 73 20 72 65 74 75 72 6e 65 64 20 64 69 72   is returned dir
27310 65 63 74 6c 79 20 62 79 20 73 71 6c 69 74 65 33  ectly by sqlite3
27320 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a 2a 2a 20 5b  _step()..**.** [
27330 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 6d  SQLITE_MISUSE] m
27340 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 74 68  eans that the th
27350 69 73 20 72 6f 75 74 69 6e 65 20 77 61 73 20 63  is routine was c
27360 61 6c 6c 65 64 20 69 6e 61 70 70 72 6f 70 72 69  alled inappropri
27370 61 74 65 6c 79 2e 0a 2a 2a 20 50 65 72 68 61 70  ately..** Perhap
27380 73 20 69 74 20 77 61 73 20 63 61 6c 6c 65 64 20  s it was called 
27390 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  on a [prepared s
273a0 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 68  tatement] that h
273b0 61 73 0a 2a 2a 20 61 6c 72 65 61 64 79 20 62 65  as.** already be
273c0 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  en [sqlite3_fina
273d0 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65 64  lize | finalized
273e0 5d 20 6f 72 20 6f 6e 20 6f 6e 65 20 74 68 61 74  ] or on one that
273f0 20 68 61 64 0a 2a 2a 20 70 72 65 76 69 6f 75 73   had.** previous
27400 6c 79 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c  ly returned [SQL
27410 49 54 45 5f 45 52 52 4f 52 5d 20 6f 72 20 5b 53  ITE_ERROR] or [S
27420 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 4f 72  QLITE_DONE].  Or
27430 20 69 74 20 63 6f 75 6c 64 0a 2a 2a 20 62 65 20   it could.** be 
27440 74 68 65 20 63 61 73 65 20 74 68 61 74 20 74 68  the case that th
27450 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20  e same database 
27460 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 62 65  connection is be
27470 69 6e 67 20 75 73 65 64 20 62 79 20 74 77 6f 20  ing used by two 
27480 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74 68 72 65 61  or.** more threa
27490 64 73 20 61 74 20 74 68 65 20 73 61 6d 65 20 6d  ds at the same m
274a0 6f 6d 65 6e 74 20 69 6e 20 74 69 6d 65 2e 0a 2a  oment in time..*
274b0 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f 66 79 20 49 6e  *.** <b>Goofy In
274c0 74 65 72 66 61 63 65 20 41 6c 65 72 74 3a 3c 2f  terface Alert:</
274d0 62 3e 20 49 6e 20 74 68 65 20 6c 65 67 61 63 79  b> In the legacy
274e0 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20   interface, the 
274f0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 0a 2a  sqlite3_step().*
27500 2a 20 41 50 49 20 61 6c 77 61 79 73 20 72 65 74  * API always ret
27510 75 72 6e 73 20 61 20 67 65 6e 65 72 69 63 20 65  urns a generic e
27520 72 72 6f 72 20 63 6f 64 65 2c 20 5b 53 51 4c 49  rror code, [SQLI
27530 54 45 5f 45 52 52 4f 52 5d 2c 20 66 6f 6c 6c 6f  TE_ERROR], follo
27540 77 69 6e 67 20 61 6e 79 0a 2a 2a 20 65 72 72 6f  wing any.** erro
27550 72 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51  r other than [SQ
27560 4c 49 54 45 5f 42 55 53 59 5d 20 61 6e 64 20 5b  LITE_BUSY] and [
27570 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20  SQLITE_MISUSE]. 
27580 20 59 6f 75 20 6d 75 73 74 20 63 61 6c 6c 0a 2a   You must call.*
27590 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  * [sqlite3_reset
275a0 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
275b0 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 6e 20 6f  finalize()] in o
275c0 72 64 65 72 20 74 6f 20 66 69 6e 64 20 6f 6e 65  rder to find one
275d0 20 6f 66 20 74 68 65 0a 2a 2a 20 73 70 65 63 69   of the.** speci
275e0 66 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 73  fic [error codes
275f0 5d 20 74 68 61 74 20 62 65 74 74 65 72 20 64 65  ] that better de
27600 73 63 72 69 62 65 73 20 74 68 65 20 65 72 72 6f  scribes the erro
27610 72 2e 0a 2a 2a 20 57 65 20 61 64 6d 69 74 20 74  r..** We admit t
27620 68 61 74 20 74 68 69 73 20 69 73 20 61 20 67 6f  hat this is a go
27630 6f 66 79 20 64 65 73 69 67 6e 2e 20 20 54 68 65  ofy design.  The
27640 20 70 72 6f 62 6c 65 6d 20 68 61 73 20 62 65 65   problem has bee
27650 6e 20 66 69 78 65 64 0a 2a 2a 20 77 69 74 68 20  n fixed.** with 
27660 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61  the "v2" interfa
27670 63 65 2e 20 20 49 66 20 79 6f 75 20 70 72 65 70  ce.  If you prep
27680 61 72 65 20 61 6c 6c 20 6f 66 20 79 6f 75 72 20  are all of your 
27690 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a  SQL statements.*
276a0 2a 20 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b  * using either [
276b0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
276c0 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  v2()] or [sqlite
276d0 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
276e0 5d 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20  ] instead.** of 
276f0 74 68 65 20 6c 65 67 61 63 79 20 5b 73 71 6c 69  the legacy [sqli
27700 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61  te3_prepare()] a
27710 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  nd [sqlite3_prep
27720 61 72 65 31 36 28 29 5d 20 69 6e 74 65 72 66 61  are16()] interfa
27730 63 65 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ces,.** then the
27740 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 5b   more specific [
27750 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 61 72 65  error codes] are
27760 20 72 65 74 75 72 6e 65 64 20 64 69 72 65 63 74   returned direct
27770 6c 79 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33  ly.** by sqlite3
27780 5f 73 74 65 70 28 29 2e 20 20 54 68 65 20 75 73  _step().  The us
27790 65 20 6f 66 20 74 68 65 20 22 76 32 22 20 69 6e  e of the "v2" in
277a0 74 65 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d  terface is recom
277b0 6d 65 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e  mended..**.** IN
277c0 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
277d0 7b 48 31 33 32 30 32 7d 20 20 49 66 20 74 68 65  {H13202}  If the
277e0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
277f0 6d 65 6e 74 5d 20 53 20 69 73 20 72 65 61 64 79  ment] S is ready
27800 20 74 6f 20 62 65 20 72 75 6e 2c 20 74 68 65 6e   to be run, then
27810 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 5b 73  .**           [s
27820 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20  qlite3_step(S)] 
27830 61 64 76 61 6e 63 65 73 20 74 68 61 74 20 70 72  advances that pr
27840 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
27850 20 75 6e 74 69 6c 0a 2a 2a 20 20 20 20 20 20 20   until.**       
27860 20 20 20 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 6f      completion o
27870 72 20 75 6e 74 69 6c 20 69 74 20 69 73 20 72 65  r until it is re
27880 61 64 79 20 74 6f 20 72 65 74 75 72 6e 20 61 6e  ady to return an
27890 6f 74 68 65 72 20 72 6f 77 20 6f 66 20 74 68 65  other row of the
278a0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 72 65  .**           re
278b0 73 75 6c 74 20 73 65 74 2c 20 6f 72 20 75 6e 74  sult set, or unt
278c0 69 6c 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69  il an [sqlite3_i
278d0 6e 74 65 72 72 75 70 74 20 7c 20 69 6e 74 65 72  nterrupt | inter
278e0 72 75 70 74 5d 0a 2a 2a 20 20 20 20 20 20 20 20  rupt].**        
278f0 20 20 20 6f 72 20 61 20 72 75 6e 2d 74 69 6d 65     or a run-time
27900 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 0a 2a   error occurs..*
27910 2a 0a 2a 2a 20 7b 48 31 35 33 30 34 7d 20 20 57  *.** {H15304}  W
27920 68 65 6e 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73  hen a call to [s
27930 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20  qlite3_step(S)] 
27940 63 61 75 73 65 73 20 74 68 65 20 5b 70 72 65 70  causes the [prep
27950 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a  ared statement].
27960 2a 2a 20 20 20 20 20 20 20 20 20 20 20 53 20 74  **           S t
27970 6f 20 72 75 6e 20 74 6f 20 63 6f 6d 70 6c 65 74  o run to complet
27980 69 6f 6e 2c 20 74 68 65 20 66 75 6e 63 74 69 6f  ion, the functio
27990 6e 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  n returns [SQLIT
279a0 45 5f 44 4f 4e 45 5d 2e 0a 2a 2a 0a 2a 2a 20 7b  E_DONE]..**.** {
279b0 48 31 35 33 30 36 7d 20 20 57 68 65 6e 20 61 20  H15306}  When a 
279c0 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
279d0 5f 73 74 65 70 28 53 29 5d 20 73 74 6f 70 73 20  _step(S)] stops 
279e0 62 65 63 61 75 73 65 20 69 74 20 69 73 20 72 65  because it is re
279f0 61 64 79 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20  ady to.**       
27a00 20 20 20 20 72 65 74 75 72 6e 20 61 6e 6f 74 68      return anoth
27a10 65 72 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65  er row of the re
27a20 73 75 6c 74 20 73 65 74 2c 20 69 74 20 72 65 74  sult set, it ret
27a30 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 52 4f 57  urns [SQLITE_ROW
27a40 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 33 30 38  ]..**.** {H15308
27a50 7d 20 20 49 66 20 61 20 63 61 6c 6c 20 74 6f 20  }  If a call to 
27a60 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29  [sqlite3_step(S)
27a70 5d 20 65 6e 63 6f 75 6e 74 65 72 73 20 61 6e 0a  ] encounters an.
27a80 2a 2a 20 20 20 20 20 20 20 20 20 20 20 5b 73 71  **           [sq
27a90 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 20  lite3_interrupt 
27aa0 7c 20 69 6e 74 65 72 72 75 70 74 5d 20 6f 72 20  | interrupt] or 
27ab0 61 20 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72  a run-time error
27ac0 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 69  ,.**           i
27ad0 74 20 72 65 74 75 72 6e 73 20 61 6e 20 61 70 70  t returns an app
27ae0 72 6f 70 72 69 61 74 65 20 65 72 72 6f 72 20 63  ropriate error c
27af0 6f 64 65 20 74 68 61 74 20 69 73 20 6e 6f 74 20  ode that is not 
27b00 6f 6e 65 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20  one of.**       
27b10 20 20 20 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c      [SQLITE_OK],
27b20 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 6f   [SQLITE_ROW], o
27b30 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e  r [SQLITE_DONE].
27b40 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 33 31 30 7d 20  .**.** {H15310} 
27b50 20 49 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f   If an [sqlite3_
27b60 69 6e 74 65 72 72 75 70 74 20 7c 20 69 6e 74 65  interrupt | inte
27b70 72 72 75 70 74 5d 20 6f 72 20 61 20 72 75 6e 2d  rrupt] or a run-
27b80 74 69 6d 65 20 65 72 72 6f 72 0a 2a 2a 20 20 20  time error.**   
27b90 20 20 20 20 20 20 20 20 6f 63 63 75 72 73 20 64          occurs d
27ba0 75 72 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20  uring a call to 
27bb0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29  [sqlite3_step(S)
27bc0 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 66  ].**           f
27bd0 6f 72 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  or a [prepared s
27be0 74 61 74 65 6d 65 6e 74 5d 20 53 20 63 72 65 61  tatement] S crea
27bf0 74 65 64 20 75 73 69 6e 67 0a 2a 2a 20 20 20 20  ted using.**    
27c00 20 20 20 20 20 20 20 6c 65 67 61 63 79 20 69 6e         legacy in
27c10 74 65 72 66 61 63 65 73 20 5b 73 71 6c 69 74 65  terfaces [sqlite
27c20 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 0a  3_prepare()] or.
27c30 2a 2a 20 20 20 20 20 20 20 20 20 20 20 5b 73 71  **           [sq
27c40 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
27c50 29 5d 2c 20 74 68 65 6e 20 74 68 65 20 66 75 6e  )], then the fun
27c60 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 65 69  ction returns ei
27c70 74 68 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  ther.**         
27c80 20 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d    [SQLITE_ERROR]
27c90 2c 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c  , [SQLITE_BUSY],
27ca0 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55   or [SQLITE_MISU
27cb0 53 45 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  SE]..*/.int sqli
27cc0 74 65 33 5f 73 74 65 70 28 73 71 6c 69 74 65 33  te3_step(sqlite3
27cd0 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  _stmt*);../*.** 
27ce0 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72  CAPI3REF: Number
27cf0 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61   of columns in a
27d00 20 72 65 73 75 6c 74 20 73 65 74 20 7b 48 31 33   result set {H13
27d10 37 37 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 2a  770} <S10700>.**
27d20 0a 2a 2a 20 52 65 74 75 72 6e 73 20 74 68 65 20  .** Returns the 
27d30 6e 75 6d 62 65 72 20 6f 66 20 76 61 6c 75 65 73  number of values
27d40 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20   in the current 
27d50 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c  row of the resul
27d60 74 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56  t set..**.** INV
27d70 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
27d80 48 31 33 37 37 31 7d 20 20 41 66 74 65 72 20 61  H13771}  After a
27d90 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
27da0 33 5f 73 74 65 70 28 53 29 5d 20 74 68 61 74 20  3_step(S)] that 
27db0 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
27dc0 52 4f 57 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20  ROW],.**        
27dd0 20 20 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f     the [sqlite3_
27de0 64 61 74 61 5f 63 6f 75 6e 74 28 53 29 5d 20 72  data_count(S)] r
27df0 6f 75 74 69 6e 65 20 77 69 6c 6c 20 72 65 74 75  outine will retu
27e00 72 6e 20 74 68 65 20 73 61 6d 65 20 76 61 6c 75  rn the same valu
27e10 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 61  e.**           a
27e20 73 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  s the [sqlite3_c
27e30 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 53 29 5d 20  olumn_count(S)] 
27e40 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  function..**.** 
27e50 7b 48 31 33 37 37 32 7d 20 20 41 66 74 65 72 20  {H13772}  After 
27e60 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29  [sqlite3_step(S)
27e70 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64 20 61  ] has returned a
27e80 6e 79 20 76 61 6c 75 65 20 6f 74 68 65 72 20 74  ny value other t
27e90 68 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  han.**          
27ea0 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 6f 72   [SQLITE_ROW] or
27eb0 20 62 65 66 6f 72 65 20 5b 73 71 6c 69 74 65 33   before [sqlite3
27ec0 5f 73 74 65 70 28 53 29 5d 20 68 61 73 20 62 65  _step(S)] has be
27ed0 65 6e 20 63 61 6c 6c 65 64 20 6f 6e 20 74 68 65  en called on the
27ee0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 5b 70  .**           [p
27ef0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
27f00 74 5d 20 66 6f 72 20 74 68 65 20 66 69 72 73 74  t] for the first
27f10 20 74 69 6d 65 20 73 69 6e 63 65 20 69 74 20 77   time since it w
27f20 61 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  as.**           
27f30 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
27f40 20 7c 20 70 72 65 70 61 72 65 64 5d 20 6f 72 20   | prepared] or 
27f50 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 20 7c  [sqlite3_reset |
27f60 20 72 65 73 65 74 5d 2c 0a 2a 2a 20 20 20 20 20   reset],.**     
27f70 20 20 20 20 20 20 74 68 65 20 5b 73 71 6c 69 74        the [sqlit
27f80 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 53 29  e3_data_count(S)
27f90 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ] routine return
27fa0 73 20 7a 65 72 6f 2e 0a 2a 2f 0a 69 6e 74 20 73  s zero..*/.int s
27fb0 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e  qlite3_data_coun
27fc0 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  t(sqlite3_stmt *
27fd0 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pStmt);../*.** C
27fe0 41 50 49 33 52 45 46 3a 20 46 75 6e 64 61 6d 65  API3REF: Fundame
27ff0 6e 74 61 6c 20 44 61 74 61 74 79 70 65 73 20 7b  ntal Datatypes {
28000 48 31 30 32 36 35 7d 20 3c 53 31 30 31 31 30 3e  H10265} <S10110>
28010 3c 53 31 30 31 32 30 3e 0a 2a 2a 20 4b 45 59 57  <S10120>.** KEYW
28020 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 54 45 58  ORDS: SQLITE_TEX
28030 54 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 32 36 36 7d  T.**.** {H10266}
28040 20 45 76 65 72 79 20 76 61 6c 75 65 20 69 6e 20   Every value in 
28050 53 51 4c 69 74 65 20 68 61 73 20 6f 6e 65 20 6f  SQLite has one o
28060 66 20 66 69 76 65 20 66 75 6e 64 61 6d 65 6e 74  f five fundament
28070 61 6c 20 64 61 74 61 74 79 70 65 73 3a 0a 2a 2a  al datatypes:.**
28080 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
28090 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69   64-bit signed i
280a0 6e 74 65 67 65 72 0a 2a 2a 20 3c 6c 69 3e 20 36  nteger.** <li> 6
280b0 34 2d 62 69 74 20 49 45 45 45 20 66 6c 6f 61 74  4-bit IEEE float
280c0 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72  ing point number
280d0 0a 2a 2a 20 3c 6c 69 3e 20 73 74 72 69 6e 67 0a  .** <li> string.
280e0 2a 2a 20 3c 6c 69 3e 20 42 4c 4f 42 0a 2a 2a 20  ** <li> BLOB.** 
280f0 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75  <li> NULL.** </u
28100 6c 3e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54  l> {END}.**.** T
28110 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61  hese constants a
28120 72 65 20 63 6f 64 65 73 20 66 6f 72 20 65 61 63  re codes for eac
28130 68 20 6f 66 20 74 68 6f 73 65 20 74 79 70 65 73  h of those types
28140 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ..**.** Note tha
28150 74 20 74 68 65 20 53 51 4c 49 54 45 5f 54 45 58  t the SQLITE_TEX
28160 54 20 63 6f 6e 73 74 61 6e 74 20 77 61 73 20 61  T constant was a
28170 6c 73 6f 20 75 73 65 64 20 69 6e 20 53 51 4c 69  lso used in SQLi
28180 74 65 20 76 65 72 73 69 6f 6e 20 32 0a 2a 2a 20  te version 2.** 
28190 66 6f 72 20 61 20 63 6f 6d 70 6c 65 74 65 6c 79  for a completely
281a0 20 64 69 66 66 65 72 65 6e 74 20 6d 65 61 6e 69   different meani
281b0 6e 67 2e 20 20 53 6f 66 74 77 61 72 65 20 74 68  ng.  Software th
281c0 61 74 20 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74  at links against
281d0 20 62 6f 74 68 0a 2a 2a 20 53 51 4c 69 74 65 20   both.** SQLite 
281e0 76 65 72 73 69 6f 6e 20 32 20 61 6e 64 20 53 51  version 2 and SQ
281f0 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 20 73  Lite version 3 s
28200 68 6f 75 6c 64 20 75 73 65 20 53 51 4c 49 54 45  hould use SQLITE
28210 33 5f 54 45 58 54 2c 20 6e 6f 74 0a 2a 2a 20 53  3_TEXT, not.** S
28220 51 4c 49 54 45 5f 54 45 58 54 2e 0a 2a 2f 0a 23  QLITE_TEXT..*/.#
28230 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e  define SQLITE_IN
28240 54 45 47 45 52 20 20 31 0a 23 64 65 66 69 6e 65  TEGER  1.#define
28250 20 53 51 4c 49 54 45 5f 46 4c 4f 41 54 20 20 20   SQLITE_FLOAT   
28260 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   2.#define SQLIT
28270 45 5f 42 4c 4f 42 20 20 20 20 20 34 0a 23 64 65  E_BLOB     4.#de
28280 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 55 4c 4c  fine SQLITE_NULL
28290 20 20 20 20 20 35 0a 23 69 66 64 65 66 20 53 51       5.#ifdef SQ
282a0 4c 49 54 45 5f 54 45 58 54 0a 23 20 75 6e 64 65  LITE_TEXT.# unde
282b0 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 65  f SQLITE_TEXT.#e
282c0 6c 73 65 0a 23 20 64 65 66 69 6e 65 20 53 51 4c  lse.# define SQL
282d0 49 54 45 5f 54 45 58 54 20 20 20 20 20 33 0a 23  ITE_TEXT     3.#
282e0 65 6e 64 69 66 0a 23 64 65 66 69 6e 65 20 53 51  endif.#define SQ
282f0 4c 49 54 45 33 5f 54 45 58 54 20 20 20 20 20 33  LITE3_TEXT     3
28300 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
28310 3a 20 52 65 73 75 6c 74 20 56 61 6c 75 65 73 20  : Result Values 
28320 46 72 6f 6d 20 41 20 51 75 65 72 79 20 7b 48 31  From A Query {H1
28330 33 38 30 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a  3800} <S10700>.*
28340 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6c  * KEYWORDS: {col
28350 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74  umn access funct
28360 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ions}.**.** Thes
28370 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 6d 20  e routines form 
28380 74 68 65 20 22 72 65 73 75 6c 74 20 73 65 74 20  the "result set 
28390 71 75 65 72 79 22 20 69 6e 74 65 72 66 61 63 65  query" interface
283a0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  ..**.** These ro
283b0 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 69 6e  utines return in
283c0 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20  formation about 
283d0 61 20 73 69 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20  a single column 
283e0 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a  of the current.*
283f0 2a 20 72 65 73 75 6c 74 20 72 6f 77 20 6f 66 20  * result row of 
28400 61 20 71 75 65 72 79 2e 20 20 49 6e 20 65 76 65  a query.  In eve
28410 72 79 20 63 61 73 65 20 74 68 65 20 66 69 72 73  ry case the firs
28420 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20  t argument is a 
28430 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68  pointer.** to th
28440 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
28450 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 73 20 62  ement] that is b
28460 65 69 6e 67 20 65 76 61 6c 75 61 74 65 64 20 28  eing evaluated (
28470 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d  the [sqlite3_stm
28480 74 2a 5d 0a 2a 2a 20 74 68 61 74 20 77 61 73 20  t*].** that was 
28490 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 5b 73  returned from [s
284a0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
284b0 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 69  2()] or one of i
284c0 74 73 20 76 61 72 69 61 6e 74 73 29 0a 2a 2a 20  ts variants).** 
284d0 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 61  and the second a
284e0 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69  rgument is the i
284f0 6e 64 65 78 20 6f 66 20 74 68 65 20 63 6f 6c 75  ndex of the colu
28500 6d 6e 20 66 6f 72 20 77 68 69 63 68 20 69 6e 66  mn for which inf
28510 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75  ormation.** shou
28520 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20  ld be returned. 
28530 20 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f   The leftmost co
28540 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75  lumn of the resu
28550 6c 74 20 73 65 74 20 68 61 73 20 74 68 65 20 69  lt set has the i
28560 6e 64 65 78 20 30 2e 0a 2a 2a 0a 2a 2a 20 49 66  ndex 0..**.** If
28570 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
28580 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63 75 72 72  nt does not curr
28590 65 6e 74 6c 79 20 70 6f 69 6e 74 20 74 6f 20 61  ently point to a
285a0 20 76 61 6c 69 64 20 72 6f 77 2c 20 6f 72 20 69   valid row, or i
285b0 66 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20  f the.** column 
285c0 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20  index is out of 
285d0 72 61 6e 67 65 2c 20 74 68 65 20 72 65 73 75 6c  range, the resul
285e0 74 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  t is undefined..
285f0 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
28600 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 63 61  s may only be ca
28610 6c 6c 65 64 20 77 68 65 6e 20 74 68 65 20 6d 6f  lled when the mo
28620 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74  st recent call t
28630 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74  o.** [sqlite3_st
28640 65 70 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e  ep()] has return
28650 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20  ed [SQLITE_ROW] 
28660 61 6e 64 20 6e 65 69 74 68 65 72 0a 2a 2a 20 5b  and neither.** [
28670 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
28680 20 6e 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69   nor [sqlite3_fi
28690 6e 61 6c 69 7a 65 28 29 5d 20 68 61 76 65 20 62  nalize()] have b
286a0 65 65 6e 20 63 61 6c 6c 65 64 20 73 75 62 73 65  een called subse
286b0 71 75 65 6e 74 6c 79 2e 0a 2a 2a 20 49 66 20 61  quently..** If a
286c0 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  ny of these rout
286d0 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20  ines are called 
286e0 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 72  after [sqlite3_r
286f0 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73  eset()] or.** [s
28700 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
28710 29 5d 20 6f 72 20 61 66 74 65 72 20 5b 73 71 6c  )] or after [sql
28720 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73  ite3_step()] has
28730 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 73 6f 6d   returned.** som
28740 65 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61  ething other tha
28750 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20  n [SQLITE_ROW], 
28760 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20  the results are 
28770 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66  undefined..** If
28780 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
28790 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  ] or [sqlite3_re
287a0 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  set()] or [sqlit
287b0 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a  e3_finalize()].*
287c0 2a 20 61 72 65 20 63 61 6c 6c 65 64 20 66 72 6f  * are called fro
287d0 6d 20 61 20 64 69 66 66 65 72 65 6e 74 20 74 68  m a different th
287e0 72 65 61 64 20 77 68 69 6c 65 20 61 6e 79 20 6f  read while any o
287f0 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
28800 0a 2a 2a 20 61 72 65 20 70 65 6e 64 69 6e 67 2c  .** are pending,
28810 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74   then the result
28820 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e  s are undefined.
28830 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
28840 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29  e3_column_type()
28850 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
28860 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
28870 49 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74 79  INTEGER | dataty
28880 70 65 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 65  pe code] for the
28890 20 69 6e 69 74 69 61 6c 20 64 61 74 61 20 74 79   initial data ty
288a0 70 65 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65 73  pe.** of the res
288b0 75 6c 74 20 63 6f 6c 75 6d 6e 2e 20 20 54 68 65  ult column.  The
288c0 20 72 65 74 75 72 6e 65 64 20 76 61 6c 75 65 20   returned value 
288d0 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54  is one of [SQLIT
288e0 45 5f 49 4e 54 45 47 45 52 5d 2c 0a 2a 2a 20 5b  E_INTEGER],.** [
288f0 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b  SQLITE_FLOAT], [
28900 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20 5b 53  SQLITE_TEXT], [S
28910 51 4c 49 54 45 5f 42 4c 4f 42 5d 2c 20 6f 72 20  QLITE_BLOB], or 
28920 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2e 20 20  [SQLITE_NULL].  
28930 54 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74  The value.** ret
28940 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
28950 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69  _column_type() i
28960 73 20 6f 6e 6c 79 20 6d 65 61 6e 69 6e 67 66 75  s only meaningfu
28970 6c 20 69 66 20 6e 6f 20 74 79 70 65 0a 2a 2a 20  l if no type.** 
28980 63 6f 6e 76 65 72 73 69 6f 6e 73 20 68 61 76 65  conversions have
28990 20 6f 63 63 75 72 72 65 64 20 61 73 20 64 65 73   occurred as des
289a0 63 72 69 62 65 64 20 62 65 6c 6f 77 2e 20 20 41  cribed below.  A
289b0 66 74 65 72 20 61 20 74 79 70 65 20 63 6f 6e 76  fter a type conv
289c0 65 72 73 69 6f 6e 2c 0a 2a 2a 20 74 68 65 20 76  ersion,.** the v
289d0 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79  alue returned by
289e0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
289f0 74 79 70 65 28 29 20 69 73 20 75 6e 64 65 66 69  type() is undefi
28a00 6e 65 64 2e 20 20 46 75 74 75 72 65 0a 2a 2a 20  ned.  Future.** 
28a10 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
28a20 74 65 20 6d 61 79 20 63 68 61 6e 67 65 20 74 68  te may change th
28a30 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 73 71  e behavior of sq
28a40 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70  lite3_column_typ
28a50 65 28 29 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67  e().** following
28a60 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69   a type conversi
28a70 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  on..**.** If the
28a80 20 72 65 73 75 6c 74 20 69 73 20 61 20 42 4c 4f   result is a BLO
28a90 42 20 6f 72 20 55 54 46 2d 38 20 73 74 72 69 6e  B or UTF-8 strin
28aa0 67 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74  g then the sqlit
28ab0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
28ac0 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74  ).** routine ret
28ad0 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
28ae0 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74  of bytes in that
28af0 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e   BLOB or string.
28b00 0a 2a 2a 20 49 66 20 74 68 65 20 72 65 73 75 6c  .** If the resul
28b10 74 20 69 73 20 61 20 55 54 46 2d 31 36 20 73 74  t is a UTF-16 st
28b20 72 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74  ring, then sqlit
28b30 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
28b40 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68  ) converts.** th
28b50 65 20 73 74 72 69 6e 67 20 74 6f 20 55 54 46 2d  e string to UTF-
28b60 38 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72  8 and then retur
28b70 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
28b80 20 62 79 74 65 73 2e 0a 2a 2a 20 49 66 20 74 68   bytes..** If th
28b90 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 6e 75  e result is a nu
28ba0 6d 65 72 69 63 20 76 61 6c 75 65 20 74 68 65 6e  meric value then
28bb0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
28bc0 62 79 74 65 73 28 29 20 75 73 65 73 0a 2a 2a 20  bytes() uses.** 
28bd0 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74  [sqlite3_snprint
28be0 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20  f()] to convert 
28bf0 74 68 61 74 20 76 61 6c 75 65 20 74 6f 20 61 20  that value to a 
28c00 55 54 46 2d 38 20 73 74 72 69 6e 67 20 61 6e 64  UTF-8 string and
28c10 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20   returns.** the 
28c20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
28c30 69 6e 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a  in that string..
28c40 2a 2a 20 54 68 65 20 76 61 6c 75 65 20 72 65 74  ** The value ret
28c50 75 72 6e 65 64 20 64 6f 65 73 20 6e 6f 74 20 69  urned does not i
28c60 6e 63 6c 75 64 65 20 74 68 65 20 7a 65 72 6f 20  nclude the zero 
28c70 74 65 72 6d 69 6e 61 74 6f 72 20 61 74 20 74 68  terminator at th
28c80 65 20 65 6e 64 0a 2a 2a 20 6f 66 20 74 68 65 20  e end.** of the 
28c90 73 74 72 69 6e 67 2e 20 20 46 6f 72 20 63 6c 61  string.  For cla
28ca0 72 69 74 79 3a 20 74 68 65 20 76 61 6c 75 65 20  rity: the value 
28cb0 72 65 74 75 72 6e 65 64 20 69 73 20 74 68 65 20  returned is the 
28cc0 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 62 79 74  number of.** byt
28cd0 65 73 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67  es in the string
28ce0 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72  , not the number
28cf0 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e 0a   of characters..
28d00 2a 2a 0a 2a 2a 20 53 74 72 69 6e 67 73 20 72 65  **.** Strings re
28d10 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65  turned by sqlite
28d20 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20  3_column_text() 
28d30 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  and sqlite3_colu
28d40 6d 6e 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20  mn_text16(),.** 
28d50 65 76 65 6e 20 65 6d 70 74 79 20 73 74 72 69 6e  even empty strin
28d60 67 73 2c 20 61 72 65 20 61 6c 77 61 79 73 20 7a  gs, are always z
28d70 65 72 6f 20 74 65 72 6d 69 6e 61 74 65 64 2e 20  ero terminated. 
28d80 20 54 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20 76   The return.** v
28d90 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65  alue from sqlite
28da0 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20  3_column_blob() 
28db0 66 6f 72 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74  for a zero-lengt
28dc0 68 20 42 4c 4f 42 20 69 73 20 61 6e 20 61 72 62  h BLOB is an arb
28dd0 69 74 72 61 72 79 0a 2a 2a 20 70 6f 69 6e 74 65  itrary.** pointe
28de0 72 2c 20 70 6f 73 73 69 62 6c 79 20 65 76 65 6e  r, possibly even
28df0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
28e00 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
28e10 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
28e20 36 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 73  6() routine is s
28e30 69 6d 69 6c 61 72 20 74 6f 20 73 71 6c 69 74 65  imilar to sqlite
28e40 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
28e50 0a 2a 2a 20 62 75 74 20 6c 65 61 76 65 73 20 74  .** but leaves t
28e60 68 65 20 72 65 73 75 6c 74 20 69 6e 20 55 54 46  he result in UTF
28e70 2d 31 36 20 69 6e 20 6e 61 74 69 76 65 20 62 79  -16 in native by
28e80 74 65 20 6f 72 64 65 72 20 69 6e 73 74 65 61 64  te order instead
28e90 20 6f 66 20 55 54 46 2d 38 2e 0a 2a 2a 20 54 68   of UTF-8..** Th
28ea0 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f  e zero terminato
28eb0 72 20 69 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65  r is not include
28ec0 64 20 69 6e 20 74 68 69 73 20 63 6f 75 6e 74 2e  d in this count.
28ed0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6f 62 6a 65 63  .**.** The objec
28ee0 74 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73  t returned by [s
28ef0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61  qlite3_column_va
28f00 6c 75 65 28 29 5d 20 69 73 20 61 6e 0a 2a 2a 20  lue()] is an.** 
28f10 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c  [unprotected sql
28f20 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
28f30 63 74 2e 20 20 41 6e 20 75 6e 70 72 6f 74 65 63  ct.  An unprotec
28f40 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
28f50 65 20 6f 62 6a 65 63 74 0a 2a 2a 20 6d 61 79 20  e object.** may 
28f60 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 77 69 74  only be used wit
28f70 68 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  h [sqlite3_bind_
28f80 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71  value()] and [sq
28f90 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c  lite3_result_val
28fa0 75 65 28 29 5d 2e 0a 2a 2a 20 49 66 20 74 68 65  ue()]..** If the
28fb0 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71   [unprotected sq
28fc0 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
28fd0 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a  ect returned by.
28fe0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ** [sqlite3_colu
28ff0 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75  mn_value()] is u
29000 73 65 64 20 69 6e 20 61 6e 79 20 6f 74 68 65 72  sed in any other
29010 20 77 61 79 2c 20 69 6e 63 6c 75 64 69 6e 67 20   way, including 
29020 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f 75 74  calls.** to rout
29030 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74  ines like [sqlit
29040 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 29 5d 2c  e3_value_int()],
29050 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
29060 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b  text()],.** or [
29070 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79  sqlite3_value_by
29080 74 65 73 28 29 5d 2c 20 74 68 65 6e 20 74 68 65  tes()], then the
29090 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64   behavior is und
290a0 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  efined..**.** Th
290b0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 74 74  ese routines att
290c0 65 6d 70 74 20 74 6f 20 63 6f 6e 76 65 72 74 20  empt to convert 
290d0 74 68 65 20 76 61 6c 75 65 20 77 68 65 72 65 20  the value where 
290e0 61 70 70 72 6f 70 72 69 61 74 65 2e 20 20 46 6f  appropriate.  Fo
290f0 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 69 66  r.** example, if
29100 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 65   the internal re
29110 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 69 73 20  presentation is 
29120 46 4c 4f 41 54 20 61 6e 64 20 61 20 74 65 78 74  FLOAT and a text
29130 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 72 65   result.** is re
29140 71 75 65 73 74 65 64 2c 20 5b 73 71 6c 69 74 65  quested, [sqlite
29150 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 69 73  3_snprintf()] is
29160 20 75 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79   used internally
29170 20 74 6f 20 70 65 72 66 6f 72 6d 20 74 68 65 0a   to perform the.
29180 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 75  ** conversion au
29190 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 54 68  tomatically.  Th
291a0 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 61 62 6c  e following tabl
291b0 65 20 64 65 74 61 69 6c 73 20 74 68 65 20 63 6f  e details the co
291c0 6e 76 65 72 73 69 6f 6e 73 0a 2a 2a 20 74 68 61  nversions.** tha
291d0 74 20 61 72 65 20 61 70 70 6c 69 65 64 3a 0a 2a  t are applied:.*
291e0 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
291f0 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64  >.** <table bord
29200 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c  er="1">.** <tr><
29210 74 68 3e 20 49 6e 74 65 72 6e 61 6c 3c 62 72 3e  th> Internal<br>
29220 54 79 70 65 20 3c 74 68 3e 20 52 65 71 75 65 73  Type <th> Reques
29230 74 65 64 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e  ted<br>Type <th>
29240 20 20 43 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a 0a    Conversion.**.
29250 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c  ** <tr><td>  NUL
29260 4c 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45  L    <td> INTEGE
29270 52 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20  R   <td> Result 
29280 69 73 20 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  is 0.** <tr><td>
29290 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20    NULL    <td>  
292a0 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 52 65  FLOAT    <td> Re
292b0 73 75 6c 74 20 69 73 20 30 2e 30 0a 2a 2a 20 3c  sult is 0.0.** <
292c0 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20  tr><td>  NULL   
292d0 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20   <td>   TEXT    
292e0 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 4e  <td> Result is N
292f0 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c  ULL pointer.** <
29300 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20  tr><td>  NULL   
29310 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20   <td>   BLOB    
29320 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 4e  <td> Result is N
29330 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c  ULL pointer.** <
29340 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20  tr><td> INTEGER 
29350 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20   <td>  FLOAT    
29360 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f  <td> Convert fro
29370 6d 20 69 6e 74 65 67 65 72 20 74 6f 20 66 6c 6f  m integer to flo
29380 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49  at.** <tr><td> I
29390 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20 54  NTEGER  <td>   T
293a0 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49  EXT    <td> ASCI
293b0 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74  I rendering of t
293c0 68 65 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74  he integer.** <t
293d0 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20  r><td> INTEGER  
293e0 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c  <td>   BLOB    <
293f0 74 64 3e 20 53 61 6d 65 20 61 73 20 49 4e 54 45  td> Same as INTE
29400 47 45 52 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72  GER->TEXT.** <tr
29410 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c  ><td>  FLOAT   <
29420 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74  td> INTEGER   <t
29430 64 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20  d> Convert from 
29440 66 6c 6f 61 74 20 74 6f 20 69 6e 74 65 67 65 72  float to integer
29450 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c  .** <tr><td>  FL
29460 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 54 45 58  OAT   <td>   TEX
29470 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20  T    <td> ASCII 
29480 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65  rendering of the
29490 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74   float.** <tr><t
294a0 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e  d>  FLOAT   <td>
294b0 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20     BLOB    <td> 
294c0 53 61 6d 65 20 61 73 20 46 4c 4f 41 54 2d 3e 54  Same as FLOAT->T
294d0 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  EXT.** <tr><td> 
294e0 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 49 4e   TEXT    <td> IN
294f0 54 45 47 45 52 20 20 20 3c 74 64 3e 20 55 73 65  TEGER   <td> Use
29500 20 61 74 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c   atoi().** <tr><
29510 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64  td>  TEXT    <td
29520 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e  >  FLOAT    <td>
29530 20 55 73 65 20 61 74 6f 66 28 29 0a 2a 2a 20 3c   Use atof().** <
29540 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20  tr><td>  TEXT   
29550 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20   <td>   BLOB    
29560 3c 74 64 3e 20 4e 6f 20 63 68 61 6e 67 65 0a 2a  <td> No change.*
29570 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42  * <tr><td>  BLOB
29580 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52      <td> INTEGER
29590 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20     <td> Convert 
295a0 74 6f 20 54 45 58 54 20 74 68 65 6e 20 75 73 65  to TEXT then use
295b0 20 61 74 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c   atoi().** <tr><
295c0 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  td>  BLOB    <td
295d0 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e  >  FLOAT    <td>
295e0 20 43 6f 6e 76 65 72 74 20 74 6f 20 54 45 58 54   Convert to TEXT
295f0 20 74 68 65 6e 20 75 73 65 20 61 74 6f 66 28 29   then use atof()
29600 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c  .** <tr><td>  BL
29610 4f 42 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58  OB    <td>   TEX
29620 54 20 20 20 20 3c 74 64 3e 20 41 64 64 20 61 20  T    <td> Add a 
29630 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20  zero terminator 
29640 69 66 20 6e 65 65 64 65 64 0a 2a 2a 20 3c 2f 74  if needed.** </t
29650 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b  able>.** </block
29660 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  quote>.**.** The
29670 20 74 61 62 6c 65 20 61 62 6f 76 65 20 6d 61 6b   table above mak
29680 65 73 20 72 65 66 65 72 65 6e 63 65 20 74 6f 20  es reference to 
29690 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61  standard C libra
296a0 72 79 20 66 75 6e 63 74 69 6f 6e 73 20 61 74 6f  ry functions ato
296b0 69 28 29 0a 2a 2a 20 61 6e 64 20 61 74 6f 66 28  i().** and atof(
296c0 29 2e 20 20 53 51 4c 69 74 65 20 64 6f 65 73 20  ).  SQLite does 
296d0 6e 6f 74 20 72 65 61 6c 6c 79 20 75 73 65 20 74  not really use t
296e0 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20  hese functions. 
296f0 20 49 74 20 68 61 73 20 69 74 73 0a 2a 2a 20 6f   It has its.** o
29700 77 6e 20 65 71 75 69 76 61 6c 65 6e 74 20 69 6e  wn equivalent in
29710 74 65 72 6e 61 6c 20 72 6f 75 74 69 6e 65 73 2e  ternal routines.
29720 20 20 54 68 65 20 61 74 6f 69 28 29 20 61 6e 64    The atoi() and
29730 20 61 74 6f 66 28 29 20 6e 61 6d 65 73 20 61 72   atof() names ar
29740 65 0a 2a 2a 20 75 73 65 64 20 69 6e 20 74 68 65  e.** used in the
29750 20 74 61 62 6c 65 20 66 6f 72 20 62 72 65 76 69   table for brevi
29760 74 79 20 61 6e 64 20 62 65 63 61 75 73 65 20 74  ty and because t
29770 68 65 79 20 61 72 65 20 66 61 6d 69 6c 69 61 72  hey are familiar
29780 20 74 6f 20 6d 6f 73 74 0a 2a 2a 20 43 20 70 72   to most.** C pr
29790 6f 67 72 61 6d 6d 65 72 73 2e 0a 2a 2a 0a 2a 2a  ogrammers..**.**
297a0 20 4e 6f 74 65 20 74 68 61 74 20 77 68 65 6e 20   Note that when 
297b0 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73  type conversions
297c0 20 6f 63 63 75 72 2c 20 70 6f 69 6e 74 65 72 73   occur, pointers
297d0 20 72 65 74 75 72 6e 65 64 20 62 79 20 70 72 69   returned by pri
297e0 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73  or.** calls to s
297f0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
29800 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 5f 63 6f  ob(), sqlite3_co
29810 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 20 61 6e 64  lumn_text(), and
29820 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63  /or.** sqlite3_c
29830 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 6d  olumn_text16() m
29840 61 79 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65  ay be invalidate
29850 64 2e 0a 2a 2a 20 54 79 70 65 20 63 6f 6e 76 65  d..** Type conve
29860 72 73 69 6f 6e 73 20 61 6e 64 20 70 6f 69 6e 74  rsions and point
29870 65 72 20 69 6e 76 61 6c 69 64 61 74 69 6f 6e 73  er invalidations
29880 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20   might occur.** 
29890 69 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  in the following
298a0 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75   cases:.**.** <u
298b0 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69  l>.** <li> The i
298c0 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69  nitial content i
298d0 73 20 61 20 42 4c 4f 42 20 61 6e 64 20 73 71 6c  s a BLOB and sql
298e0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
298f0 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71  () or.**      sq
29900 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
29910 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e  t16() is called.
29920 20 20 41 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61    A zero-termina
29930 74 6f 72 20 6d 69 67 68 74 0a 2a 2a 20 20 20 20  tor might.**    
29940 20 20 6e 65 65 64 20 74 6f 20 62 65 20 61 64 64    need to be add
29950 65 64 20 74 6f 20 74 68 65 20 73 74 72 69 6e 67  ed to the string
29960 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54  .</li>.** <li> T
29970 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65  he initial conte
29980 6e 74 20 69 73 20 55 54 46 2d 38 20 74 65 78 74  nt is UTF-8 text
29990 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c   and sqlite3_col
299a0 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 6f 72  umn_bytes16() or
299b0 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33  .**      sqlite3
299c0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
299d0 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65   is called.  The
299e0 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65   content must be
299f0 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20   converted.**   
29a00 20 20 20 74 6f 20 55 54 46 2d 31 36 2e 3c 2f 6c     to UTF-16.</l
29a10 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69  i>.** <li> The i
29a20 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69  nitial content i
29a30 73 20 55 54 46 2d 31 36 20 74 65 78 74 20 61 6e  s UTF-16 text an
29a40 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  d sqlite3_column
29a50 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 20  _bytes() or.**  
29a60 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75      sqlite3_colu
29a70 6d 6e 5f 74 65 78 74 28 29 20 69 73 20 63 61 6c  mn_text() is cal
29a80 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e  led.  The conten
29a90 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72  t must be conver
29aa0 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55  ted.**      to U
29ab0 54 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f  TF-8.</li>.** </
29ac0 75 6c 3e 0a 2a 2a 0a 2a 2a 20 43 6f 6e 76 65 72  ul>.**.** Conver
29ad0 73 69 6f 6e 73 20 62 65 74 77 65 65 6e 20 55 54  sions between UT
29ae0 46 2d 31 36 62 65 20 61 6e 64 20 55 54 46 2d 31  F-16be and UTF-1
29af0 36 6c 65 20 61 72 65 20 61 6c 77 61 79 73 20 64  6le are always d
29b00 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 61 6e 64  one in place and
29b10 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69 6e 76 61 6c   do.** not inval
29b20 69 64 61 74 65 20 61 20 70 72 69 6f 72 20 70 6f  idate a prior po
29b30 69 6e 74 65 72 2c 20 74 68 6f 75 67 68 20 6f 66  inter, though of
29b40 20 63 6f 75 72 73 65 20 74 68 65 20 63 6f 6e 74   course the cont
29b50 65 6e 74 20 6f 66 20 74 68 65 20 62 75 66 66 65  ent of the buffe
29b60 72 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 70 72  r.** that the pr
29b70 69 6f 72 20 70 6f 69 6e 74 65 72 20 70 6f 69 6e  ior pointer poin
29b80 74 73 20 74 6f 20 77 69 6c 6c 20 68 61 76 65 20  ts to will have 
29b90 62 65 65 6e 20 6d 6f 64 69 66 69 65 64 2e 20 20  been modified.  
29ba0 4f 74 68 65 72 20 6b 69 6e 64 73 0a 2a 2a 20 6f  Other kinds.** o
29bb0 66 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 72 65  f conversion are
29bc0 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 77   done in place w
29bd0 68 65 6e 20 69 74 20 69 73 20 70 6f 73 73 69 62  hen it is possib
29be0 6c 65 2c 20 62 75 74 20 73 6f 6d 65 74 69 6d 65  le, but sometime
29bf0 73 20 74 68 65 79 0a 2a 2a 20 61 72 65 20 6e 6f  s they.** are no
29c00 74 20 70 6f 73 73 69 62 6c 65 20 61 6e 64 20 69  t possible and i
29c10 6e 20 74 68 6f 73 65 20 63 61 73 65 73 20 70 72  n those cases pr
29c20 69 6f 72 20 70 6f 69 6e 74 65 72 73 20 61 72 65  ior pointers are
29c30 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a   invalidated..**
29c40 0a 2a 2a 20 54 68 65 20 73 61 66 65 73 74 20 61  .** The safest a
29c50 6e 64 20 65 61 73 69 65 73 74 20 74 6f 20 72 65  nd easiest to re
29c60 6d 65 6d 62 65 72 20 70 6f 6c 69 63 79 20 69 73  member policy is
29c70 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65 73 65   to invoke these
29c80 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 69 6e 20   routines.** in 
29c90 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f  one of the follo
29ca0 77 69 6e 67 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a  wing ways:.**.**
29cb0 20 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71   <ul>.**  <li>sq
29cc0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
29cd0 74 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20  t() followed by 
29ce0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
29cf0 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20  ytes()</li>.**  
29d00 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75  <li>sqlite3_colu
29d10 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 6c 6c 6f 77  mn_blob() follow
29d20 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f  ed by sqlite3_co
29d30 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69  lumn_bytes()</li
29d40 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65  >.**  <li>sqlite
29d50 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
29d60 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71  ) followed by sq
29d70 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
29d80 65 73 31 36 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c  es16()</li>.** <
29d90 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f 74  /ul>.**.** In ot
29da0 68 65 72 20 77 6f 72 64 73 2c 20 79 6f 75 20 73  her words, you s
29db0 68 6f 75 6c 64 20 63 61 6c 6c 20 73 71 6c 69 74  hould call sqlit
29dc0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
29dd0 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c  ,.** sqlite3_col
29de0 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 6f 72 20 73  umn_blob(), or s
29df0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
29e00 78 74 31 36 28 29 20 66 69 72 73 74 20 74 6f 20  xt16() first to 
29e10 66 6f 72 63 65 20 74 68 65 20 72 65 73 75 6c 74  force the result
29e20 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 64 65 73  .** into the des
29e30 69 72 65 64 20 66 6f 72 6d 61 74 2c 20 74 68 65  ired format, the
29e40 6e 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33  n invoke sqlite3
29e50 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20  _column_bytes() 
29e60 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  or.** sqlite3_co
29e70 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 74  lumn_bytes16() t
29e80 6f 20 66 69 6e 64 20 74 68 65 20 73 69 7a 65 20  o find the size 
29e90 6f 66 20 74 68 65 20 72 65 73 75 6c 74 2e 20 20  of the result.  
29ea0 44 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73  Do not mix calls
29eb0 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  .** to sqlite3_c
29ec0 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 20  olumn_text() or 
29ed0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
29ee0 6c 6f 62 28 29 20 77 69 74 68 20 63 61 6c 6c 73  lob() with calls
29ef0 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63   to.** sqlite3_c
29f00 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 2c  olumn_bytes16(),
29f10 20 61 6e 64 20 64 6f 20 6e 6f 74 20 6d 69 78 20   and do not mix 
29f20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
29f30 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
29f40 0a 2a 2a 20 77 69 74 68 20 63 61 6c 6c 73 20 74  .** with calls t
29f50 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  o sqlite3_column
29f60 5f 62 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a 2a 20  _bytes()..**.** 
29f70 54 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74  The pointers ret
29f80 75 72 6e 65 64 20 61 72 65 20 76 61 6c 69 64 20  urned are valid 
29f90 75 6e 74 69 6c 20 61 20 74 79 70 65 20 63 6f 6e  until a type con
29fa0 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 20 61  version occurs a
29fb0 73 0a 2a 2a 20 64 65 73 63 72 69 62 65 64 20 61  s.** described a
29fc0 62 6f 76 65 2c 20 6f 72 20 75 6e 74 69 6c 20 5b  bove, or until [
29fd0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
29fe0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  or [sqlite3_rese
29ff0 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  t()] or.** [sqli
2a000 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
2a010 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20  is called.  The 
2a020 6d 65 6d 6f 72 79 20 73 70 61 63 65 20 75 73 65  memory space use
2a030 64 20 74 6f 20 68 6f 6c 64 20 73 74 72 69 6e 67  d to hold string
2a040 73 0a 2a 2a 20 61 6e 64 20 42 4c 4f 42 73 20 69  s.** and BLOBs i
2a050 73 20 66 72 65 65 64 20 61 75 74 6f 6d 61 74 69  s freed automati
2a060 63 61 6c 6c 79 2e 20 20 44 6f 20 3c 62 3e 6e 6f  cally.  Do <b>no
2a070 74 3c 2f 62 3e 20 70 61 73 73 20 74 68 65 20 70  t</b> pass the p
2a080 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64  ointers returned
2a090 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  .** [sqlite3_col
2a0a0 75 6d 6e 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71  umn_blob()], [sq
2a0b0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
2a0c0 74 28 29 5d 2c 20 65 74 63 2e 20 69 6e 74 6f 0a  t()], etc. into.
2a0d0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ** [sqlite3_free
2a0e0 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20  ()]..**.** If a 
2a0f0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
2a100 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 64  n error occurs d
2a110 75 72 69 6e 67 20 74 68 65 20 65 76 61 6c 75 61  uring the evalua
2a120 74 69 6f 6e 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f  tion of any.** o
2a130 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
2a140 2c 20 61 20 64 65 66 61 75 6c 74 20 76 61 6c 75  , a default valu
2a150 65 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20  e is returned.  
2a160 54 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75  The default valu
2a170 65 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 20 74  e.** is either t
2a180 68 65 20 69 6e 74 65 67 65 72 20 30 2c 20 74 68  he integer 0, th
2a190 65 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74  e floating point
2a1a0 20 6e 75 6d 62 65 72 20 30 2e 30 2c 20 6f 72 20   number 0.0, or 
2a1b0 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65  a NULL.** pointe
2a1c0 72 2e 20 20 53 75 62 73 65 71 75 65 6e 74 20 63  r.  Subsequent c
2a1d0 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
2a1e0 5f 65 72 72 63 6f 64 65 28 29 5d 20 77 69 6c 6c  _errcode()] will
2a1f0 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49   return.** [SQLI
2a200 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a  TE_NOMEM]..**.**
2a210 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
2a220 2a 2a 20 7b 48 31 33 38 30 33 7d 20 54 68 65 20  ** {H13803} The 
2a230 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
2a240 62 6c 6f 62 28 53 2c 4e 29 5d 20 69 6e 74 65 72  blob(S,N)] inter
2a250 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68  face converts th
2a260 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 74  e.**          Nt
2a270 68 20 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 20  h column in the 
2a280 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74  current row of t
2a290 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 66 6f  he result set fo
2a2a0 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  r.**          th
2a2b0 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
2a2c0 65 6d 65 6e 74 5d 20 53 20 69 6e 74 6f 20 61 20  ement] S into a 
2a2d0 42 4c 4f 42 20 61 6e 64 20 74 68 65 6e 20 72 65  BLOB and then re
2a2e0 74 75 72 6e 73 20 61 0a 2a 2a 20 20 20 20 20 20  turns a.**      
2a2f0 20 20 20 20 70 6f 69 6e 74 65 72 20 74 6f 20 74      pointer to t
2a300 68 65 20 63 6f 6e 76 65 72 74 65 64 20 76 61 6c  he converted val
2a310 75 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 38 30  ue..**.** {H1380
2a320 36 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  6} The [sqlite3_
2a330 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 53 2c 4e  column_bytes(S,N
2a340 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  )] interface ret
2a350 75 72 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20 20  urns the.**     
2a360 20 20 20 20 20 6e 75 6d 62 65 72 20 6f 66 20 62       number of b
2a370 79 74 65 73 20 69 6e 20 74 68 65 20 42 4c 4f 42  ytes in the BLOB
2a380 20 6f 72 20 73 74 72 69 6e 67 20 28 65 78 63 6c   or string (excl
2a390 75 73 69 76 65 20 6f 66 20 74 68 65 0a 2a 2a 20  usive of the.** 
2a3a0 20 20 20 20 20 20 20 20 20 7a 65 72 6f 20 74 65           zero te
2a3b0 72 6d 69 6e 61 74 6f 72 20 6f 6e 20 74 68 65 20  rminator on the 
2a3c0 73 74 72 69 6e 67 29 20 74 68 61 74 20 77 61 73  string) that was
2a3d0 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65   returned by the
2a3e0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 6f 73  .**          mos
2a3f0 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f  t recent call to
2a400 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
2a410 5f 62 6c 6f 62 28 53 2c 4e 29 5d 20 6f 72 0a 2a  _blob(S,N)] or.*
2a420 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
2a430 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
2a440 53 2c 4e 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  S,N)]..**.** {H1
2a450 33 38 30 39 7d 20 54 68 65 20 5b 73 71 6c 69 74  3809} The [sqlit
2a460 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
2a470 36 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63  6(S,N)] interfac
2a480 65 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a  e returns the.**
2a490 20 20 20 20 20 20 20 20 20 20 6e 75 6d 62 65 72            number
2a4a0 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65   of bytes in the
2a4b0 20 73 74 72 69 6e 67 20 28 65 78 63 6c 75 73 69   string (exclusi
2a4c0 76 65 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20  ve of the.**    
2a4d0 20 20 20 20 20 20 7a 65 72 6f 20 74 65 72 6d 69        zero termi
2a4e0 6e 61 74 6f 72 20 6f 6e 20 74 68 65 20 73 74 72  nator on the str
2a4f0 69 6e 67 29 20 74 68 61 74 20 77 61 73 20 72 65  ing) that was re
2a500 74 75 72 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a  turned by the.**
2a510 20 20 20 20 20 20 20 20 20 20 6d 6f 73 74 20 72            most r
2a520 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73  ecent call to [s
2a530 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
2a540 78 74 31 36 28 53 2c 4e 29 5d 2e 0a 2a 2a 0a 2a  xt16(S,N)]..**.*
2a550 2a 20 7b 48 31 33 38 31 32 7d 20 54 68 65 20 5b  * {H13812} The [
2a560 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
2a570 6f 75 62 6c 65 28 53 2c 4e 29 5d 20 69 6e 74 65  ouble(S,N)] inte
2a580 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74  rface converts t
2a590 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4e  he.**          N
2a5a0 74 68 20 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 65  th column in the
2a5b0 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20   current row of 
2a5c0 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 66  the result set f
2a5d0 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  or the.**       
2a5e0 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61     [prepared sta
2a5f0 74 65 6d 65 6e 74 5d 20 53 20 69 6e 74 6f 20 61  tement] S into a
2a600 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20   floating point 
2a610 76 61 6c 75 65 20 61 6e 64 0a 2a 2a 20 20 20 20  value and.**    
2a620 20 20 20 20 20 20 72 65 74 75 72 6e 73 20 61 20        returns a 
2a630 63 6f 70 79 20 6f 66 20 74 68 61 74 20 76 61 6c  copy of that val
2a640 75 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 38 31  ue..**.** {H1381
2a650 35 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  5} The [sqlite3_
2a660 63 6f 6c 75 6d 6e 5f 69 6e 74 28 53 2c 4e 29 5d  column_int(S,N)]
2a670 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65   interface conve
2a680 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  rts the.**      
2a690 20 20 20 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 69      Nth column i
2a6a0 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 72 6f  n the current ro
2a6b0 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  w of the result 
2a6c0 73 65 74 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20  set for the.**  
2a6d0 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65          [prepare
2a6e0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69  d statement] S i
2a6f0 6e 74 6f 20 61 20 36 34 2d 62 69 74 20 73 69 67  nto a 64-bit sig
2a700 6e 65 64 20 69 6e 74 65 67 65 72 20 61 6e 64 0a  ned integer and.
2a710 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75  **          retu
2a720 72 6e 73 20 74 68 65 20 6c 6f 77 65 72 20 33 32  rns the lower 32
2a730 20 62 69 74 73 20 6f 66 20 74 68 61 74 20 69 6e   bits of that in
2a740 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  teger..**.** {H1
2a750 33 38 31 38 7d 20 54 68 65 20 5b 73 71 6c 69 74  3818} The [sqlit
2a760 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34 28  e3_column_int64(
2a770 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20  S,N)] interface 
2a780 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20  converts the.** 
2a790 20 20 20 20 20 20 20 20 20 4e 74 68 20 63 6f 6c           Nth col
2a7a0 75 6d 6e 20 69 6e 20 74 68 65 20 63 75 72 72 65  umn in the curre
2a7b0 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65  nt row of the re
2a7c0 73 75 6c 74 20 73 65 74 20 66 6f 72 20 74 68 65  sult set for the
2a7d0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72  .**          [pr
2a7e0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2a7f0 5d 20 53 20 69 6e 74 6f 20 61 20 36 34 2d 62 69  ] S into a 64-bi
2a800 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  t signed integer
2a810 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20   and.**         
2a820 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20   returns a copy 
2a830 6f 66 20 74 68 61 74 20 69 6e 74 65 67 65 72 2e  of that integer.
2a840 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 38 32 31 7d 20  .**.** {H13821} 
2a850 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  The [sqlite3_col
2a860 75 6d 6e 5f 74 65 78 74 28 53 2c 4e 29 5d 20 69  umn_text(S,N)] i
2a870 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74  nterface convert
2a880 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  s the.**        
2a890 20 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 69 6e 20    Nth column in 
2a8a0 74 68 65 20 63 75 72 72 65 6e 74 20 72 6f 77 20  the current row 
2a8b0 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  of the result se
2a8c0 74 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20  t for.**        
2a8d0 20 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20    the [prepared 
2a8e0 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 74  statement] S int
2a8f0 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  o a zero-termina
2a900 74 65 64 20 55 54 46 2d 38 0a 2a 2a 20 20 20 20  ted UTF-8.**    
2a910 20 20 20 20 20 20 73 74 72 69 6e 67 20 61 6e 64        string and
2a920 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
2a930 65 72 20 74 6f 20 74 68 61 74 20 73 74 72 69 6e  er to that strin
2a940 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 38 32 34  g..**.** {H13824
2a950 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  } The [sqlite3_c
2a960 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 53 2c 4e  olumn_text16(S,N
2a970 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e  )] interface con
2a980 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20  verts the.**    
2a990 20 20 20 20 20 20 4e 74 68 20 63 6f 6c 75 6d 6e        Nth column
2a9a0 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20   in the current 
2a9b0 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c  row of the resul
2a9c0 74 20 73 65 74 20 66 6f 72 20 74 68 65 0a 2a 2a  t set for the.**
2a9d0 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 61            [prepa
2a9e0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
2a9f0 20 69 6e 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72   into a zero-ter
2aa00 6d 69 6e 61 74 65 64 20 32 2d 62 79 74 65 0a 2a  minated 2-byte.*
2aa10 2a 20 20 20 20 20 20 20 20 20 20 61 6c 69 67 6e  *          align
2aa20 65 64 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65  ed UTF-16 native
2aa30 20 62 79 74 65 20 6f 72 64 65 72 20 73 74 72 69   byte order stri
2aa40 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a  ng and returns.*
2aa50 2a 20 20 20 20 20 20 20 20 20 20 61 20 70 6f 69  *          a poi
2aa60 6e 74 65 72 20 74 6f 20 74 68 61 74 20 73 74 72  nter to that str
2aa70 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 38  ing..**.** {H138
2aa80 32 37 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  27} The [sqlite3
2aa90 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 53 2c 4e  _column_type(S,N
2aaa0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  )] interface ret
2aab0 75 72 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  urns.**         
2aac0 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f   one of [SQLITE_
2aad0 4e 55 4c 4c 5d 2c 20 5b 53 51 4c 49 54 45 5f 49  NULL], [SQLITE_I
2aae0 4e 54 45 47 45 52 5d 2c 20 5b 53 51 4c 49 54 45  NTEGER], [SQLITE
2aaf0 5f 46 4c 4f 41 54 5d 2c 0a 2a 2a 20 20 20 20 20  _FLOAT],.**     
2ab00 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 54 45 58       [SQLITE_TEX
2ab10 54 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 42  T], or [SQLITE_B
2ab20 4c 4f 42 5d 20 61 73 20 61 70 70 72 6f 70 72 69  LOB] as appropri
2ab30 61 74 65 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20  ate for.**      
2ab40 20 20 20 20 74 68 65 20 4e 74 68 20 63 6f 6c 75      the Nth colu
2ab50 6d 6e 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e  mn in the curren
2ab60 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73  t row of the res
2ab70 75 6c 74 20 73 65 74 20 66 6f 72 0a 2a 2a 20 20  ult set for.**  
2ab80 20 20 20 20 20 20 20 20 74 68 65 20 5b 70 72 65          the [pre
2ab90 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2aba0 20 53 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 38 33   S..**.** {H1383
2abb0 30 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  0} The [sqlite3_
2abc0 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 53 2c 4e  column_value(S,N
2abd0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  )] interface ret
2abe0 75 72 6e 73 20 61 0a 2a 2a 20 20 20 20 20 20 20  urns a.**       
2abf0 20 20 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e     pointer to an
2ac00 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71   [unprotected sq
2ac10 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
2ac20 65 63 74 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20  ect for the.**  
2ac30 20 20 20 20 20 20 20 20 4e 74 68 20 63 6f 6c 75          Nth colu
2ac40 6d 6e 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e  mn in the curren
2ac50 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73  t row of the res
2ac60 75 6c 74 20 73 65 74 20 66 6f 72 0a 2a 2a 20 20  ult set for.**  
2ac70 20 20 20 20 20 20 20 20 74 68 65 20 5b 70 72 65          the [pre
2ac80 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2ac90 20 53 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69   S..*/.const voi
2aca0 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
2acb0 6e 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73  n_blob(sqlite3_s
2acc0 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
2acd0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c  .int sqlite3_col
2ace0 75 6d 6e 5f 62 79 74 65 73 28 73 71 6c 69 74 65  umn_bytes(sqlite
2acf0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
2ad00 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  l);.int sqlite3_
2ad10 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 73  column_bytes16(s
2ad20 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
2ad30 74 20 69 43 6f 6c 29 3b 0a 64 6f 75 62 6c 65 20  t iCol);.double 
2ad40 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
2ad50 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74  ouble(sqlite3_st
2ad60 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
2ad70 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  int sqlite3_colu
2ad80 6d 6e 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73  mn_int(sqlite3_s
2ad90 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
2ada0 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73  .sqlite3_int64 s
2adb0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e  qlite3_column_in
2adc0 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  t64(sqlite3_stmt
2add0 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f  *, int iCol);.co
2ade0 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61  nst unsigned cha
2adf0 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  r *sqlite3_colum
2ae00 6e 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73  n_text(sqlite3_s
2ae10 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
2ae20 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
2ae30 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
2ae40 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
2ae50 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74  , int iCol);.int
2ae60 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2ae70 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  type(sqlite3_stm
2ae80 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73  t*, int iCol);.s
2ae90 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 73 71  qlite3_value *sq
2aea0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c  lite3_column_val
2aeb0 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ue(sqlite3_stmt*
2aec0 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 0a 2f 2a  , int iCol);../*
2aed0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
2aee0 73 74 72 6f 79 20 41 20 50 72 65 70 61 72 65 64  stroy A Prepared
2aef0 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63   Statement Objec
2af00 74 20 7b 48 31 33 33 30 30 7d 20 3c 53 37 30 33  t {H13300} <S703
2af10 30 30 3e 3c 53 33 30 31 30 30 3e 0a 2a 2a 0a 2a  00><S30100>.**.*
2af20 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 66 69  * The sqlite3_fi
2af30 6e 61 6c 69 7a 65 28 29 20 66 75 6e 63 74 69 6f  nalize() functio
2af40 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 64  n is called to d
2af50 65 6c 65 74 65 20 61 20 5b 70 72 65 70 61 72 65  elete a [prepare
2af60 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a  d statement]..**
2af70 20 49 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e   If the statemen
2af80 74 20 77 61 73 20 65 78 65 63 75 74 65 64 20 73  t was executed s
2af90 75 63 63 65 73 73 66 75 6c 6c 79 20 6f 72 20 6e  uccessfully or n
2afa0 6f 74 20 65 78 65 63 75 74 65 64 20 61 74 20 61  ot executed at a
2afb0 6c 6c 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 49  ll, then.** SQLI
2afc0 54 45 5f 4f 4b 20 69 73 20 72 65 74 75 72 6e 65  TE_OK is returne
2afd0 64 2e 20 49 66 20 65 78 65 63 75 74 69 6f 6e 20  d. If execution 
2afe0 6f 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  of the statement
2aff0 20 66 61 69 6c 65 64 20 74 68 65 6e 20 61 6e 0a   failed then an.
2b000 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  ** [error code] 
2b010 6f 72 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72  or [extended err
2b020 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75  or code] is retu
2b030 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  rned..**.** This
2b040 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20   routine can be 
2b050 63 61 6c 6c 65 64 20 61 74 20 61 6e 79 20 70 6f  called at any po
2b060 69 6e 74 20 64 75 72 69 6e 67 20 74 68 65 20 65  int during the e
2b070 78 65 63 75 74 69 6f 6e 20 6f 66 20 74 68 65 0a  xecution of the.
2b080 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ** [prepared sta
2b090 74 65 6d 65 6e 74 5d 2e 20 20 49 66 20 74 68 65  tement].  If the
2b0a0 20 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65   virtual machine
2b0b0 20 68 61 73 20 6e 6f 74 0a 2a 2a 20 63 6f 6d 70   has not.** comp
2b0c0 6c 65 74 65 64 20 65 78 65 63 75 74 69 6f 6e 20  leted execution 
2b0d0 77 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e  when this routin
2b0e0 65 20 69 73 20 63 61 6c 6c 65 64 2c 20 74 68 61  e is called, tha
2b0f0 74 20 69 73 20 6c 69 6b 65 0a 2a 2a 20 65 6e 63  t is like.** enc
2b100 6f 75 6e 74 65 72 69 6e 67 20 61 6e 20 65 72 72  ountering an err
2b110 6f 72 20 6f 72 20 61 6e 20 5b 73 71 6c 69 74 65  or or an [sqlite
2b120 33 5f 69 6e 74 65 72 72 75 70 74 20 7c 20 69 6e  3_interrupt | in
2b130 74 65 72 72 75 70 74 5d 2e 0a 2a 2a 20 49 6e 63  terrupt]..** Inc
2b140 6f 6d 70 6c 65 74 65 20 75 70 64 61 74 65 73 20  omplete updates 
2b150 6d 61 79 20 62 65 20 72 6f 6c 6c 65 64 20 62 61  may be rolled ba
2b160 63 6b 20 61 6e 64 20 74 72 61 6e 73 61 63 74 69  ck and transacti
2b170 6f 6e 73 20 63 61 6e 63 65 6c 65 64 2c 0a 2a 2a  ons canceled,.**
2b180 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68   depending on th
2b190 65 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73 2c  e circumstances,
2b1a0 20 61 6e 64 20 74 68 65 0a 2a 2a 20 5b 65 72 72   and the.** [err
2b1b0 6f 72 20 63 6f 64 65 5d 20 72 65 74 75 72 6e 65  or code] returne
2b1c0 64 20 77 69 6c 6c 20 62 65 20 5b 53 51 4c 49 54  d will be [SQLIT
2b1d0 45 5f 41 42 4f 52 54 5d 2e 0a 2a 2a 0a 2a 2a 20  E_ABORT]..**.** 
2b1e0 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
2b1f0 2a 20 7b 48 31 31 33 30 32 7d 20 54 68 65 20 5b  * {H11302} The [
2b200 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
2b210 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 64  (S)] interface d
2b220 65 73 74 72 6f 79 73 20 74 68 65 0a 2a 2a 20 20  estroys the.**  
2b230 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65          [prepare
2b240 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 61  d statement] S a
2b250 6e 64 20 72 65 6c 65 61 73 65 73 20 61 6c 6c 0a  nd releases all.
2b260 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 65 6d 6f  **          memo
2b270 72 79 20 61 6e 64 20 66 69 6c 65 20 72 65 73 6f  ry and file reso
2b280 75 72 63 65 73 20 68 65 6c 64 20 62 79 20 74 68  urces held by th
2b290 61 74 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a  at object..**.**
2b2a0 20 7b 48 31 31 33 30 34 7d 20 49 66 20 74 68 65   {H11304} If the
2b2b0 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c   most recent cal
2b2c0 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74  l to [sqlite3_st
2b2d0 65 70 28 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a  ep(S)] for the.*
2b2e0 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70  *          [prep
2b2f0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2b300 53 20 72 65 74 75 72 6e 65 64 20 61 6e 20 65 72  S returned an er
2b310 72 6f 72 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  ror,.**         
2b320 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66   then [sqlite3_f
2b330 69 6e 61 6c 69 7a 65 28 53 29 5d 20 72 65 74 75  inalize(S)] retu
2b340 72 6e 73 20 74 68 61 74 20 73 61 6d 65 20 65 72  rns that same er
2b350 72 6f 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ror..*/.int sqli
2b360 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 73 71 6c  te3_finalize(sql
2b370 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
2b380 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2b390 45 46 3a 20 52 65 73 65 74 20 41 20 50 72 65 70  EF: Reset A Prep
2b3a0 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f  ared Statement O
2b3b0 62 6a 65 63 74 20 7b 48 31 33 33 33 30 7d 20 3c  bject {H13330} <
2b3c0 53 37 30 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68  S70300>.**.** Th
2b3d0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28  e sqlite3_reset(
2b3e0 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61  ) function is ca
2b3f0 6c 6c 65 64 20 74 6f 20 72 65 73 65 74 20 61 20  lled to reset a 
2b400 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2b410 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 62  ent].** object b
2b420 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69  ack to its initi
2b430 61 6c 20 73 74 61 74 65 2c 20 72 65 61 64 79 20  al state, ready 
2b440 74 6f 20 62 65 20 72 65 2d 65 78 65 63 75 74 65  to be re-execute
2b450 64 2e 0a 2a 2a 20 41 6e 79 20 53 51 4c 20 73 74  d..** Any SQL st
2b460 61 74 65 6d 65 6e 74 20 76 61 72 69 61 62 6c 65  atement variable
2b470 73 20 74 68 61 74 20 68 61 64 20 76 61 6c 75 65  s that had value
2b480 73 20 62 6f 75 6e 64 20 74 6f 20 74 68 65 6d 20  s bound to them 
2b490 75 73 69 6e 67 0a 2a 2a 20 74 68 65 20 5b 73 71  using.** the [sq
2b4a0 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20  lite3_bind_blob 
2b4b0 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  | sqlite3_bind_*
2b4c0 28 29 20 41 50 49 5d 20 72 65 74 61 69 6e 20 74  () API] retain t
2b4d0 68 65 69 72 20 76 61 6c 75 65 73 2e 0a 2a 2a 20  heir values..** 
2b4e0 55 73 65 20 5b 73 71 6c 69 74 65 33 5f 63 6c 65  Use [sqlite3_cle
2b4f0 61 72 5f 62 69 6e 64 69 6e 67 73 28 29 5d 20 74  ar_bindings()] t
2b500 6f 20 72 65 73 65 74 20 74 68 65 20 62 69 6e 64  o reset the bind
2b510 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31  ings..**.** {H11
2b520 33 33 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  332} The [sqlite
2b530 33 5f 72 65 73 65 74 28 53 29 5d 20 69 6e 74 65  3_reset(S)] inte
2b540 72 66 61 63 65 20 72 65 73 65 74 73 20 74 68 65  rface resets the
2b550 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2b560 6d 65 6e 74 5d 20 53 0a 2a 2a 20 20 20 20 20 20  ment] S.**      
2b570 20 20 20 20 62 61 63 6b 20 74 6f 20 74 68 65 20      back to the 
2b580 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 69 74 73  beginning of its
2b590 20 70 72 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20   program..**.** 
2b5a0 7b 48 31 31 33 33 34 7d 20 49 66 20 74 68 65 20  {H11334} If the 
2b5b0 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c  most recent call
2b5c0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   to [sqlite3_ste
2b5d0 70 28 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a  p(S)] for the.**
2b5e0 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 61            [prepa
2b5f0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
2b600 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54   returned [SQLIT
2b610 45 5f 52 4f 57 5d 20 6f 72 20 5b 53 51 4c 49 54  E_ROW] or [SQLIT
2b620 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20 20 20 20 20  E_DONE],.**     
2b630 20 20 20 20 20 6f 72 20 69 66 20 5b 73 71 6c 69       or if [sqli
2b640 74 65 33 5f 73 74 65 70 28 53 29 5d 20 68 61 73  te3_step(S)] has
2b650 20 6e 65 76 65 72 20 62 65 66 6f 72 65 20 62 65   never before be
2b660 65 6e 20 63 61 6c 6c 65 64 20 6f 6e 20 53 2c 0a  en called on S,.
2b670 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 6e  **          then
2b680 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
2b690 53 29 5d 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  S)] returns [SQL
2b6a0 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 7b  ITE_OK]..**.** {
2b6b0 48 31 31 33 33 36 7d 20 49 66 20 74 68 65 20 6d  H11336} If the m
2b6c0 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20  ost recent call 
2b6d0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  to [sqlite3_step
2b6e0 28 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20  (S)] for the.** 
2b6f0 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72           [prepar
2b700 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20  ed statement] S 
2b710 69 6e 64 69 63 61 74 65 64 20 61 6e 20 65 72 72  indicated an err
2b720 6f 72 2c 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20  or, then.**     
2b730 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 72 65       [sqlite3_re
2b740 73 65 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20  set(S)] returns 
2b750 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b  an appropriate [
2b760 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a  error code]..**.
2b770 2a 2a 20 7b 48 31 31 33 33 38 7d 20 54 68 65 20  ** {H11338} The 
2b780 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53  [sqlite3_reset(S
2b790 29 5d 20 69 6e 74 65 72 66 61 63 65 20 64 6f 65  )] interface doe
2b7a0 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65  s not change the
2b7b0 20 76 61 6c 75 65 73 0a 2a 2a 20 20 20 20 20 20   values.**      
2b7c0 20 20 20 20 6f 66 20 61 6e 79 20 5b 73 71 6c 69      of any [sqli
2b7d0 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 62 69  te3_bind_blob|bi
2b7e0 6e 64 69 6e 67 73 5d 20 6f 6e 20 74 68 65 20 5b  ndings] on the [
2b7f0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2b800 6e 74 5d 20 53 2e 0a 2a 2f 0a 69 6e 74 20 73 71  nt] S..*/.int sq
2b810 6c 69 74 65 33 5f 72 65 73 65 74 28 73 71 6c 69  lite3_reset(sqli
2b820 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29  te3_stmt *pStmt)
2b830 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2b840 46 3a 20 43 72 65 61 74 65 20 4f 72 20 52 65 64  F: Create Or Red
2b850 65 66 69 6e 65 20 53 51 4c 20 46 75 6e 63 74 69  efine SQL Functi
2b860 6f 6e 73 20 7b 48 31 36 31 30 30 7d 20 3c 53 32  ons {H16100} <S2
2b870 30 32 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44  0200>.** KEYWORD
2b880 53 3a 20 7b 66 75 6e 63 74 69 6f 6e 20 63 72 65  S: {function cre
2b890 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 7d 0a  ation routines}.
2b8a0 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70  ** KEYWORDS: {ap
2b8b0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
2b8c0 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 7d 0a  d SQL function}.
2b8d0 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70  ** KEYWORDS: {ap
2b8e0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
2b8f0 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 7d  d SQL functions}
2b900 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 74 77 6f  .**.** These two
2b910 20 66 75 6e 63 74 69 6f 6e 73 20 28 63 6f 6c 6c   functions (coll
2b920 65 63 74 69 76 65 6c 79 20 6b 6e 6f 77 6e 20 61  ectively known a
2b930 73 20 22 66 75 6e 63 74 69 6f 6e 20 63 72 65 61  s "function crea
2b940 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 22 29 0a  tion routines").
2b950 2a 2a 20 61 72 65 20 75 73 65 64 20 74 6f 20 61  ** are used to a
2b960 64 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  dd SQL functions
2b970 20 6f 72 20 61 67 67 72 65 67 61 74 65 73 20 6f   or aggregates o
2b980 72 20 74 6f 20 72 65 64 65 66 69 6e 65 20 74 68  r to redefine th
2b990 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f 66  e behavior.** of
2b9a0 20 65 78 69 73 74 69 6e 67 20 53 51 4c 20 66 75   existing SQL fu
2b9b0 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65  nctions or aggre
2b9c0 67 61 74 65 73 2e 20 20 54 68 65 20 6f 6e 6c 79  gates.  The only
2b9d0 20 64 69 66 66 65 72 65 6e 63 65 20 62 65 74 77   difference betw
2b9e0 65 65 6e 20 74 68 65 0a 2a 2a 20 74 77 6f 20 69  een the.** two i
2b9f0 73 20 74 68 61 74 20 74 68 65 20 73 65 63 6f 6e  s that the secon
2ba00 64 20 70 61 72 61 6d 65 74 65 72 2c 20 74 68 65  d parameter, the
2ba10 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 28 73 63   name of the (sc
2ba20 61 6c 61 72 29 20 66 75 6e 63 74 69 6f 6e 20 6f  alar) function o
2ba30 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 2c 20  r.** aggregate, 
2ba40 69 73 20 65 6e 63 6f 64 65 64 20 69 6e 20 55 54  is encoded in UT
2ba50 46 2d 38 20 66 6f 72 20 73 71 6c 69 74 65 33 5f  F-8 for sqlite3_
2ba60 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
2ba70 29 20 61 6e 64 20 55 54 46 2d 31 36 0a 2a 2a 20  ) and UTF-16.** 
2ba80 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61  for sqlite3_crea
2ba90 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 2e  te_function16().
2baa0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  .**.** The first
2bab0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
2bac0 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
2bad0 65 63 74 69 6f 6e 5d 20 74 6f 20 77 68 69 63 68  ection] to which
2bae0 20 74 68 65 20 53 51 4c 0a 2a 2a 20 66 75 6e 63   the SQL.** func
2baf0 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 20 61 64  tion is to be ad
2bb00 64 65 64 2e 20 20 49 66 20 61 20 73 69 6e 67 6c  ded.  If a singl
2bb10 65 20 70 72 6f 67 72 61 6d 20 75 73 65 73 20 6d  e program uses m
2bb20 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 64 61 74  ore than one dat
2bb30 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74  abase.** connect
2bb40 69 6f 6e 20 69 6e 74 65 72 6e 61 6c 6c 79 2c 20  ion internally, 
2bb50 74 68 65 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f  then SQL functio
2bb60 6e 73 20 6d 75 73 74 20 62 65 20 61 64 64 65 64  ns must be added
2bb70 20 69 6e 64 69 76 69 64 75 61 6c 6c 79 20 74 6f   individually to
2bb80 0a 2a 2a 20 65 61 63 68 20 64 61 74 61 62 61 73  .** each databas
2bb90 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 0a 2a 2a  e connection..**
2bba0 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70  .** The second p
2bbb0 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20  arameter is the 
2bbc0 6e 61 6d 65 20 6f 66 20 74 68 65 20 53 51 4c 20  name of the SQL 
2bbd0 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 63  function to be c
2bbe0 72 65 61 74 65 64 20 6f 72 0a 2a 2a 20 72 65 64  reated or.** red
2bbf0 65 66 69 6e 65 64 2e 20 20 54 68 65 20 6c 65 6e  efined.  The len
2bc00 67 74 68 20 6f 66 20 74 68 65 20 6e 61 6d 65 20  gth of the name 
2bc10 69 73 20 6c 69 6d 69 74 65 64 20 74 6f 20 32 35  is limited to 25
2bc20 35 20 62 79 74 65 73 2c 20 65 78 63 6c 75 73 69  5 bytes, exclusi
2bc30 76 65 20 6f 66 0a 2a 2a 20 74 68 65 20 7a 65 72  ve of.** the zer
2bc40 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 4e  o-terminator.  N
2bc50 6f 74 65 20 74 68 61 74 20 74 68 65 20 6e 61 6d  ote that the nam
2bc60 65 20 6c 65 6e 67 74 68 20 6c 69 6d 69 74 20 69  e length limit i
2bc70 73 20 69 6e 20 62 79 74 65 73 2c 20 6e 6f 74 0a  s in bytes, not.
2bc80 2a 2a 20 63 68 61 72 61 63 74 65 72 73 2e 20 20  ** characters.  
2bc90 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 63  Any attempt to c
2bca0 72 65 61 74 65 20 61 20 66 75 6e 63 74 69 6f 6e  reate a function
2bcb0 20 77 69 74 68 20 61 20 6c 6f 6e 67 65 72 20 6e   with a longer n
2bcc0 61 6d 65 0a 2a 2a 20 77 69 6c 6c 20 72 65 73 75  ame.** will resu
2bcd0 6c 74 20 69 6e 20 5b 53 51 4c 49 54 45 5f 45 52  lt in [SQLITE_ER
2bce0 52 4f 52 5d 20 62 65 69 6e 67 20 72 65 74 75 72  ROR] being retur
2bcf0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74  ned..**.** The t
2bd00 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 69  hird parameter i
2bd10 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
2bd20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 74  arguments that t
2bd30 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
2bd40 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20  or.** aggregate 
2bd50 74 61 6b 65 73 2e 20 49 66 20 74 68 69 73 20 70  takes. If this p
2bd60 61 72 61 6d 65 74 65 72 20 69 73 20 6e 65 67 61  arameter is nega
2bd70 74 69 76 65 2c 20 74 68 65 6e 20 74 68 65 20 53  tive, then the S
2bd80 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a  QL function or.*
2bd90 2a 20 61 67 67 72 65 67 61 74 65 20 6d 61 79 20  * aggregate may 
2bda0 74 61 6b 65 20 61 6e 79 20 6e 75 6d 62 65 72 20  take any number 
2bdb0 6f 66 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a  of arguments..**
2bdc0 0a 2a 2a 20 54 68 65 20 66 6f 75 72 74 68 20 70  .** The fourth p
2bdd0 61 72 61 6d 65 74 65 72 2c 20 65 54 65 78 74 52  arameter, eTextR
2bde0 65 70 2c 20 73 70 65 63 69 66 69 65 73 20 77 68  ep, specifies wh
2bdf0 61 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54  at.** [SQLITE_UT
2be00 46 38 20 7c 20 74 65 78 74 20 65 6e 63 6f 64 69  F8 | text encodi
2be10 6e 67 5d 20 74 68 69 73 20 53 51 4c 20 66 75 6e  ng] this SQL fun
2be20 63 74 69 6f 6e 20 70 72 65 66 65 72 73 20 66 6f  ction prefers fo
2be30 72 0a 2a 2a 20 69 74 73 20 70 61 72 61 6d 65 74  r.** its paramet
2be40 65 72 73 2e 20 20 41 6e 79 20 53 51 4c 20 66 75  ers.  Any SQL fu
2be50 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74  nction implement
2be60 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 62 65 20  ation should be 
2be70 61 62 6c 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20  able to work.** 
2be80 77 6f 72 6b 20 77 69 74 68 20 55 54 46 2d 38 2c  work with UTF-8,
2be90 20 55 54 46 2d 31 36 6c 65 2c 20 6f 72 20 55 54   UTF-16le, or UT
2bea0 46 2d 31 36 62 65 2e 20 20 42 75 74 20 73 6f 6d  F-16be.  But som
2beb0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
2bec0 73 20 6d 61 79 20 62 65 0a 2a 2a 20 6d 6f 72 65  s may be.** more
2bed0 20 65 66 66 69 63 69 65 6e 74 20 77 69 74 68 20   efficient with 
2bee0 6f 6e 65 20 65 6e 63 6f 64 69 6e 67 20 74 68 61  one encoding tha
2bef0 6e 20 61 6e 6f 74 68 65 72 2e 20 20 49 74 20 69  n another.  It i
2bf00 73 20 61 6c 6c 6f 77 65 64 20 74 6f 0a 2a 2a 20  s allowed to.** 
2bf10 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63  invoke sqlite3_c
2bf20 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29  reate_function()
2bf30 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61   or sqlite3_crea
2bf40 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 20  te_function16() 
2bf50 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 74 69 6d 65  multiple.** time
2bf60 73 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20  s with the same 
2bf70 66 75 6e 63 74 69 6f 6e 20 62 75 74 20 77 69 74  function but wit
2bf80 68 20 64 69 66 66 65 72 65 6e 74 20 76 61 6c 75  h different valu
2bf90 65 73 20 6f 66 20 65 54 65 78 74 52 65 70 2e 0a  es of eTextRep..
2bfa0 2a 2a 20 57 68 65 6e 20 6d 75 6c 74 69 70 6c 65  ** When multiple
2bfb0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
2bfc0 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e   of the same fun
2bfd0 63 74 69 6f 6e 20 61 72 65 20 61 76 61 69 6c 61  ction are availa
2bfe0 62 6c 65 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 77  ble, SQLite.** w
2bff0 69 6c 6c 20 70 69 63 6b 20 74 68 65 20 6f 6e 65  ill pick the one
2c000 20 74 68 61 74 20 69 6e 76 6f 6c 76 65 73 20 74   that involves t
2c010 68 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20  he least amount 
2c020 6f 66 20 64 61 74 61 20 63 6f 6e 76 65 72 73 69  of data conversi
2c030 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 72 65 20  on..** If there 
2c040 69 73 20 6f 6e 6c 79 20 61 20 73 69 6e 67 6c 65  is only a single
2c050 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
2c060 77 68 69 63 68 20 64 6f 65 73 20 6e 6f 74 20 63  which does not c
2c070 61 72 65 20 77 68 61 74 20 74 65 78 74 0a 2a 2a  are what text.**
2c080 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 75 73 65   encoding is use
2c090 64 2c 20 74 68 65 6e 20 74 68 65 20 66 6f 75 72  d, then the four
2c0a0 74 68 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75  th argument shou
2c0b0 6c 64 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 4e  ld be [SQLITE_AN
2c0c0 59 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  Y]..**.** The fi
2c0d0 66 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73  fth parameter is
2c0e0 20 61 6e 20 61 72 62 69 74 72 61 72 79 20 70 6f   an arbitrary po
2c0f0 69 6e 74 65 72 2e 20 20 54 68 65 20 69 6d 70 6c  inter.  The impl
2c100 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68  ementation of th
2c110 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 63 61  e.** function ca
2c120 6e 20 67 61 69 6e 20 61 63 63 65 73 73 20 74 6f  n gain access to
2c130 20 74 68 69 73 20 70 6f 69 6e 74 65 72 20 75 73   this pointer us
2c140 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 75 73 65  ing [sqlite3_use
2c150 72 5f 64 61 74 61 28 29 5d 2e 0a 2a 2a 0a 2a 2a  r_data()]..**.**
2c160 20 54 68 65 20 73 65 76 65 6e 74 68 2c 20 65 69   The seventh, ei
2c170 67 68 74 68 20 61 6e 64 20 6e 69 6e 74 68 20 70  ghth and ninth p
2c180 61 72 61 6d 65 74 65 72 73 2c 20 78 46 75 6e 63  arameters, xFunc
2c190 2c 20 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e  , xStep and xFin
2c1a0 61 6c 2c 20 61 72 65 0a 2a 2a 20 70 6f 69 6e 74  al, are.** point
2c1b0 65 72 73 20 74 6f 20 43 2d 6c 61 6e 67 75 61 67  ers to C-languag
2c1c0 65 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74  e functions that
2c1d0 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53   implement the S
2c1e0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a  QL function or.*
2c1f0 2a 20 61 67 67 72 65 67 61 74 65 2e 20 41 20 73  * aggregate. A s
2c200 63 61 6c 61 72 20 53 51 4c 20 66 75 6e 63 74 69  calar SQL functi
2c210 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20 69  on requires an i
2c220 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
2c230 20 74 68 65 20 78 46 75 6e 63 0a 2a 2a 20 63 61   the xFunc.** ca
2c240 6c 6c 62 61 63 6b 20 6f 6e 6c 79 2c 20 4e 55 4c  llback only, NUL
2c250 4c 20 70 6f 69 6e 74 65 72 73 20 73 68 6f 75 6c  L pointers shoul
2c260 64 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74  d be passed as t
2c270 68 65 20 78 53 74 65 70 20 61 6e 64 20 78 46 69  he xStep and xFi
2c280 6e 61 6c 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  nal.** parameter
2c290 73 2e 20 41 6e 20 61 67 67 72 65 67 61 74 65 20  s. An aggregate 
2c2a0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71  SQL function req
2c2b0 75 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65  uires an impleme
2c2c0 6e 74 61 74 69 6f 6e 20 6f 66 20 78 53 74 65 70  ntation of xStep
2c2d0 0a 2a 2a 20 61 6e 64 20 78 46 69 6e 61 6c 20 61  .** and xFinal a
2c2e0 6e 64 20 4e 55 4c 4c 20 73 68 6f 75 6c 64 20 62  nd NULL should b
2c2f0 65 20 70 61 73 73 65 64 20 66 6f 72 20 78 46 75  e passed for xFu
2c300 6e 63 2e 20 54 6f 20 64 65 6c 65 74 65 20 61 6e  nc. To delete an
2c310 20 65 78 69 73 74 69 6e 67 0a 2a 2a 20 53 51 4c   existing.** SQL
2c320 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67   function or agg
2c330 72 65 67 61 74 65 2c 20 70 61 73 73 20 4e 55 4c  regate, pass NUL
2c340 4c 20 66 6f 72 20 61 6c 6c 20 74 68 72 65 65 20  L for all three 
2c350 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 62 61 63  function callbac
2c360 6b 73 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73 20  ks..**.** It is 
2c370 70 65 72 6d 69 74 74 65 64 20 74 6f 20 72 65 67  permitted to reg
2c380 69 73 74 65 72 20 6d 75 6c 74 69 70 6c 65 20 69  ister multiple i
2c390 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f  mplementations o
2c3a0 66 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 66 75  f the same.** fu
2c3b0 6e 63 74 69 6f 6e 73 20 77 69 74 68 20 74 68 65  nctions with the
2c3c0 20 73 61 6d 65 20 6e 61 6d 65 20 62 75 74 20 77   same name but w
2c3d0 69 74 68 20 65 69 74 68 65 72 20 64 69 66 66 65  ith either diffe
2c3e0 72 69 6e 67 20 6e 75 6d 62 65 72 73 20 6f 66 0a  ring numbers of.
2c3f0 2a 2a 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20  ** arguments or 
2c400 64 69 66 66 65 72 69 6e 67 20 70 72 65 66 65 72  differing prefer
2c410 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e  red text encodin
2c420 67 73 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c  gs.  SQLite will
2c430 20 75 73 65 0a 2a 2a 20 74 68 65 20 69 6d 70 6c   use.** the impl
2c440 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 6f 73 74 20  ementation most 
2c450 63 6c 6f 73 65 6c 79 20 6d 61 74 63 68 65 73 20  closely matches 
2c460 74 68 65 20 77 61 79 20 69 6e 20 77 68 69 63 68  the way in which
2c470 20 74 68 65 0a 2a 2a 20 53 51 4c 20 66 75 6e 63   the.** SQL func
2c480 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 0a 2a 2a  tion is used..**
2c490 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
2c4a0 2a 2a 0a 2a 2a 20 7b 48 31 36 31 30 33 7d 20 54  **.** {H16103} T
2c4b0 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  he [sqlite3_crea
2c4c0 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d  te_function16()]
2c4d0 20 69 6e 74 65 72 66 61 63 65 20 62 65 68 61 76   interface behav
2c4e0 65 73 20 65 78 61 63 74 6c 79 0a 2a 2a 20 20 20  es exactly.**   
2c4f0 20 20 20 20 20 20 20 6c 69 6b 65 20 5b 73 71 6c         like [sql
2c500 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
2c510 74 69 6f 6e 28 29 5d 20 69 6e 20 65 76 65 72 79  tion()] in every
2c520 20 77 61 79 20 65 78 63 65 70 74 20 74 68 61 74   way except that
2c530 20 69 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   it.**          
2c540 69 6e 74 65 72 70 72 65 74 73 20 74 68 65 20 7a  interprets the z
2c550 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 20 61 72 67  FunctionName arg
2c560 75 6d 65 6e 74 20 61 73 20 7a 65 72 6f 2d 74 65  ument as zero-te
2c570 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 31 36 0a  rminated UTF-16.
2c580 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 61 74 69  **          nati
2c590 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 69 6e  ve byte order in
2c5a0 73 74 65 61 64 20 6f 66 20 61 73 20 7a 65 72 6f  stead of as zero
2c5b0 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d  -terminated UTF-
2c5c0 38 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 31 30 36  8..**.** {H16106
2c5d0 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 69  } A successful i
2c5e0 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20  nvocation of.** 
2c5f0 20 20 20 20 20 20 20 20 20 74 68 65 20 5b 73 71           the [sq
2c600 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
2c610 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 45 2c 2e 2e  ction(D,X,N,E,..
2c620 2e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  .)] interface re
2c630 67 69 73 74 65 72 73 0a 2a 2a 20 20 20 20 20 20  gisters.**      
2c640 20 20 20 20 6f 72 20 72 65 70 6c 61 63 65 73 20      or replaces 
2c650 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
2c660 6e 73 20 69 6e 20 74 68 65 20 5b 64 61 74 61 62  ns in the [datab
2c670 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
2c680 44 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 75 73  D.**          us
2c690 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20  ed to implement 
2c6a0 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
2c6b0 20 6e 61 6d 65 64 20 58 20 77 69 74 68 20 4e 20   named X with N 
2c6c0 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 20 20  parameters.**   
2c6d0 20 20 20 20 20 20 20 61 6e 64 20 68 61 76 69 6e         and havin
2c6e0 67 20 61 20 70 72 65 66 65 72 72 65 64 20 74 65  g a preferred te
2c6f0 78 74 20 65 6e 63 6f 64 69 6e 67 20 6f 66 20 45  xt encoding of E
2c700 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 31 30 39 7d  ..**.** {H16109}
2c710 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 63 61   A successful ca
2c720 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ll to [sqlite3_c
2c730 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44  reate_function(D
2c740 2c 58 2c 4e 2c 45 2c 50 2c 46 2c 53 2c 4c 29 5d  ,X,N,E,P,F,S,L)]
2c750 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 70  .**          rep
2c760 6c 61 63 65 73 20 74 68 65 20 50 2c 20 46 2c 20  laces the P, F, 
2c770 53 2c 20 61 6e 64 20 4c 20 76 61 6c 75 65 73 20  S, and L values 
2c780 66 72 6f 6d 20 61 6e 79 20 70 72 69 6f 72 20 63  from any prior c
2c790 61 6c 6c 73 20 77 69 74 68 0a 2a 2a 20 20 20 20  alls with.**    
2c7a0 20 20 20 20 20 20 74 68 65 20 73 61 6d 65 20 44        the same D
2c7b0 2c 20 58 2c 20 4e 2c 20 61 6e 64 20 45 20 76 61  , X, N, and E va
2c7c0 6c 75 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36  lues..**.** {H16
2c7d0 31 31 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  112} The [sqlite
2c7e0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
2c7f0 6e 28 44 2c 58 2c 2e 2e 2e 29 5d 20 69 6e 74 65  n(D,X,...)] inte
2c800 72 66 61 63 65 20 66 61 69 6c 73 20 77 69 74 68  rface fails with
2c810 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20 72  .**          a r
2c820 65 74 75 72 6e 20 63 6f 64 65 20 6f 66 20 5b 53  eturn code of [S
2c830 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20  QLITE_ERROR] if 
2c840 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
2c850 20 6e 61 6d 65 20 58 20 69 73 0a 2a 2a 20 20 20   name X is.**   
2c860 20 20 20 20 20 20 20 6c 6f 6e 67 65 72 20 74 68         longer th
2c870 61 6e 20 32 35 35 20 62 79 74 65 73 20 65 78 63  an 255 bytes exc
2c880 6c 75 73 69 76 65 20 6f 66 20 74 68 65 20 7a 65  lusive of the ze
2c890 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a  ro terminator..*
2c8a0 2a 0a 2a 2a 20 7b 48 31 36 31 31 38 7d 20 45 69  *.** {H16118} Ei
2c8b0 74 68 65 72 20 46 20 6d 75 73 74 20 62 65 20 4e  ther F must be N
2c8c0 55 4c 4c 20 61 6e 64 20 53 20 61 6e 64 20 4c 20  ULL and S and L 
2c8d0 61 72 65 20 6e 6f 6e 2d 4e 55 4c 4c 20 6f 72 20  are non-NULL or 
2c8e0 65 6c 73 65 20 46 0a 2a 2a 20 20 20 20 20 20 20  else F.**       
2c8f0 20 20 20 69 73 20 6e 6f 6e 2d 4e 55 4c 4c 20 61     is non-NULL a
2c900 6e 64 20 53 20 61 6e 64 20 4c 20 61 72 65 20 4e  nd S and L are N
2c910 55 4c 4c 2c 20 6f 74 68 65 72 77 69 73 65 0a 2a  ULL, otherwise.*
2c920 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
2c930 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
2c940 69 6f 6e 28 44 2c 58 2c 4e 2c 45 2c 50 2c 46 2c  ion(D,X,N,E,P,F,
2c950 53 2c 4c 29 5d 20 72 65 74 75 72 6e 73 20 5b 53  S,L)] returns [S
2c960 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 0a 2a 2a  QLITE_ERROR]..**
2c970 0a 2a 2a 20 7b 48 31 36 31 32 31 7d 20 54 68 65  .** {H16121} The
2c980 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
2c990 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 2e 2e 2e 29  _function(D,...)
2c9a0 5d 20 69 6e 74 65 72 66 61 63 65 20 66 61 69 6c  ] interface fail
2c9b0 73 20 77 69 74 68 20 61 6e 0a 2a 2a 20 20 20 20  s with an.**    
2c9c0 20 20 20 20 20 20 65 72 72 6f 72 20 63 6f 64 65        error code
2c9d0 20 6f 66 20 5b 53 51 4c 49 54 45 5f 42 55 53 59   of [SQLITE_BUSY
2c9e0 5d 20 69 66 20 74 68 65 72 65 20 65 78 69 73 74  ] if there exist
2c9f0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2ca00 6d 65 6e 74 73 5d 0a 2a 2a 20 20 20 20 20 20 20  ments].**       
2ca10 20 20 20 61 73 73 6f 63 69 61 74 65 64 20 77 69     associated wi
2ca20 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  th the [database
2ca30 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2e 0a   connection] D..
2ca40 2a 2a 0a 2a 2a 20 7b 48 31 36 31 32 34 7d 20 54  **.** {H16124} T
2ca50 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  he [sqlite3_crea
2ca60 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c  te_function(D,X,
2ca70 4e 2c 2e 2e 2e 29 5d 20 69 6e 74 65 72 66 61 63  N,...)] interfac
2ca80 65 20 66 61 69 6c 73 20 77 69 74 68 20 61 6e 0a  e fails with an.
2ca90 2a 2a 20 20 20 20 20 20 20 20 20 20 65 72 72 6f  **          erro
2caa0 72 20 63 6f 64 65 20 6f 66 20 5b 53 51 4c 49 54  r code of [SQLIT
2cab0 45 5f 45 52 52 4f 52 5d 20 69 66 20 70 61 72 61  E_ERROR] if para
2cac0 6d 65 74 65 72 20 4e 20 28 73 70 65 63 69 66 79  meter N (specify
2cad0 69 6e 67 20 74 68 65 20 6e 75 6d 62 65 72 0a 2a  ing the number.*
2cae0 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20 61 72  *          of ar
2caf0 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 65 20 53  guments to the S
2cb00 51 4c 20 66 75 6e 63 74 69 6f 6e 20 62 65 69 6e  QL function bein
2cb10 67 20 72 65 67 69 73 74 65 72 65 64 29 20 69 73  g registered) is
2cb20 20 6c 65 73 73 0a 2a 2a 20 20 20 20 20 20 20 20   less.**        
2cb30 20 20 74 68 61 6e 20 2d 31 20 6f 72 20 67 72 65    than -1 or gre
2cb40 61 74 65 72 20 74 68 61 6e 20 31 32 37 2e 0a 2a  ater than 127..*
2cb50 2a 0a 2a 2a 20 7b 48 31 36 31 32 37 7d 20 57 68  *.** {H16127} Wh
2cb60 65 6e 20 4e 20 69 73 20 6e 6f 6e 2d 6e 65 67 61  en N is non-nega
2cb70 74 69 76 65 2c 20 74 68 65 20 5b 73 71 6c 69 74  tive, the [sqlit
2cb80 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
2cb90 6f 6e 28 44 2c 58 2c 4e 2c 2e 2e 2e 29 5d 0a 2a  on(D,X,N,...)].*
2cba0 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74 65 72  *          inter
2cbb0 66 61 63 65 20 63 61 75 73 65 73 20 63 61 6c 6c  face causes call
2cbc0 62 61 63 6b 73 20 74 6f 20 62 65 20 69 6e 76 6f  backs to be invo
2cbd0 6b 65 64 20 66 6f 72 20 74 68 65 20 53 51 4c 20  ked for the SQL 
2cbe0 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20  function.**     
2cbf0 20 20 20 20 20 6e 61 6d 65 64 20 58 20 77 68 65       named X whe
2cc00 6e 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  n the number of 
2cc10 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 65  arguments to the
2cc20 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73   SQL function is
2cc30 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 65 78 61  .**          exa
2cc40 63 74 6c 79 20 4e 2e 0a 2a 2a 0a 2a 2a 20 7b 48  ctly N..**.** {H
2cc50 31 36 31 33 30 7d 20 57 68 65 6e 20 4e 20 69 73  16130} When N is
2cc60 20 2d 31 2c 20 74 68 65 20 5b 73 71 6c 69 74 65   -1, the [sqlite
2cc70 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
2cc80 6e 28 44 2c 58 2c 4e 2c 2e 2e 2e 29 5d 0a 2a 2a  n(D,X,N,...)].**
2cc90 20 20 20 20 20 20 20 20 20 20 69 6e 74 65 72 66            interf
2cca0 61 63 65 20 63 61 75 73 65 73 20 63 61 6c 6c 62  ace causes callb
2ccb0 61 63 6b 73 20 74 6f 20 62 65 20 69 6e 76 6f 6b  acks to be invok
2ccc0 65 64 20 66 6f 72 20 74 68 65 20 53 51 4c 20 66  ed for the SQL f
2ccd0 75 6e 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20  unction.**      
2cce0 20 20 20 20 6e 61 6d 65 64 20 58 20 77 69 74 68      named X with
2ccf0 20 61 6e 79 20 6e 75 6d 62 65 72 20 6f 66 20 61   any number of a
2cd00 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20  rguments..**.** 
2cd10 7b 48 31 36 31 33 33 7d 20 57 68 65 6e 20 63 61  {H16133} When ca
2cd20 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
2cd30 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
2cd40 44 2c 58 2c 4e 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20  D,X,N,...)].**  
2cd50 20 20 20 20 20 20 20 20 73 70 65 63 69 66 79 20          specify 
2cd60 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65  multiple impleme
2cd70 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20  ntations of the 
2cd80 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 58 0a  same function X.
2cd90 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6e 64 20  **          and 
2cda0 77 68 65 6e 20 6f 6e 65 20 69 6d 70 6c 65 6d 65  when one impleme
2cdb0 6e 74 61 74 69 6f 6e 20 68 61 73 20 4e 3e 3d 30  ntation has N>=0
2cdc0 20 61 6e 64 20 74 68 65 20 6f 74 68 65 72 20 68   and the other h
2cdd0 61 73 20 4e 3d 28 2d 31 29 0a 2a 2a 20 20 20 20  as N=(-1).**    
2cde0 20 20 20 20 20 20 74 68 65 20 69 6d 70 6c 65 6d        the implem
2cdf0 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 20 61 20  entation with a 
2ce00 6e 6f 6e 2d 7a 65 72 6f 20 4e 20 69 73 20 70 72  non-zero N is pr
2ce10 65 66 65 72 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b  eferred..**.** {
2ce20 48 31 36 31 33 36 7d 20 57 68 65 6e 20 63 61 6c  H16136} When cal
2ce30 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ls to [sqlite3_c
2ce40 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44  reate_function(D
2ce50 2c 58 2c 4e 2c 45 2c 2e 2e 2e 29 5d 0a 2a 2a 20  ,X,N,E,...)].** 
2ce60 20 20 20 20 20 20 20 20 20 73 70 65 63 69 66 79           specify
2ce70 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d   multiple implem
2ce80 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65  entations of the
2ce90 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 58   same function X
2cea0 20 77 69 74 68 0a 2a 2a 20 20 20 20 20 20 20 20   with.**        
2ceb0 20 20 74 68 65 20 73 61 6d 65 20 6e 75 6d 62 65    the same numbe
2cec0 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 4e  r of arguments N
2ced0 20 62 75 74 20 77 69 74 68 20 64 69 66 66 65 72   but with differ
2cee0 65 6e 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ent.**          
2cef0 65 6e 63 6f 64 69 6e 67 73 20 45 2c 20 74 68 65  encodings E, the
2cf00 6e 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  n the implementa
2cf10 74 69 6f 6e 20 77 68 65 72 65 20 45 20 6d 61 74  tion where E mat
2cf20 63 68 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 20  ches the.**     
2cf30 20 20 20 20 20 64 61 74 61 62 61 73 65 20 65 6e       database en
2cf40 63 6f 64 69 6e 67 20 69 73 20 70 72 65 66 65 72  coding is prefer
2cf50 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 31  red..**.** {H161
2cf60 33 39 7d 20 46 6f 72 20 61 6e 20 61 67 67 72 65  39} For an aggre
2cf70 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f  gate SQL functio
2cf80 6e 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 0a  n created using.
2cf90 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
2cfa0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
2cfb0 74 69 6f 6e 28 44 2c 58 2c 4e 2c 45 2c 50 2c 30  tion(D,X,N,E,P,0
2cfc0 2c 53 2c 4c 29 5d 20 74 68 65 20 66 69 6e 61 6c  ,S,L)] the final
2cfd0 69 7a 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  izer.**         
2cfe0 20 66 75 6e 63 74 69 6f 6e 20 4c 20 77 69 6c 6c   function L will
2cff0 20 61 6c 77 61 79 73 20 62 65 20 69 6e 76 6f 6b   always be invok
2d000 65 64 20 65 78 61 63 74 6c 79 20 6f 6e 63 65 20  ed exactly once 
2d010 69 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  if the.**       
2d020 20 20 20 73 74 65 70 20 66 75 6e 63 74 69 6f 6e     step function
2d030 20 53 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 65   S is called one
2d040 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a   or more times..
2d050 2a 2a 0a 2a 2a 20 7b 48 31 36 31 34 32 7d 20 57  **.** {H16142} W
2d060 68 65 6e 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b  hen SQLite invok
2d070 65 73 20 65 69 74 68 65 72 20 74 68 65 20 78 46  es either the xF
2d080 75 6e 63 20 6f 72 20 78 53 74 65 70 20 66 75 6e  unc or xStep fun
2d090 63 74 69 6f 6e 20 6f 66 0a 2a 2a 20 20 20 20 20  ction of.**     
2d0a0 20 20 20 20 20 61 6e 20 61 70 70 6c 69 63 61 74       an applicat
2d0b0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20  ion-defined SQL 
2d0c0 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72  function or aggr
2d0d0 65 67 61 74 65 20 63 72 65 61 74 65 64 0a 2a 2a  egate created.**
2d0e0 20 20 20 20 20 20 20 20 20 20 62 79 20 5b 73 71            by [sq
2d0f0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
2d100 63 74 69 6f 6e 28 29 5d 20 6f 72 20 5b 73 71 6c  ction()] or [sql
2d110 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
2d120 74 69 6f 6e 31 36 28 29 5d 2c 0a 2a 2a 20 20 20  tion16()],.**   
2d130 20 20 20 20 20 20 20 74 68 65 6e 20 74 68 65 20         then the 
2d140 61 72 72 61 79 20 6f 66 20 5b 73 71 6c 69 74 65  array of [sqlite
2d150 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73  3_value] objects
2d160 20 70 61 73 73 65 64 20 61 73 20 74 68 65 0a 2a   passed as the.*
2d170 2a 20 20 20 20 20 20 20 20 20 20 74 68 69 72 64  *          third
2d180 20 70 61 72 61 6d 65 74 65 72 20 61 72 65 20 61   parameter are a
2d190 6c 77 61 79 73 20 5b 70 72 6f 74 65 63 74 65 64  lways [protected
2d1a0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
2d1b0 6f 62 6a 65 63 74 73 2e 0a 2a 2f 0a 69 6e 74 20  objects..*/.int 
2d1c0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
2d1d0 75 6e 63 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74  unction(.  sqlit
2d1e0 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20  e3 *db,.  const 
2d1f0 63 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e  char *zFunctionN
2d200 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c  ame,.  int nArg,
2d210 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c  .  int eTextRep,
2d220 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20  .  void *pApp,. 
2d230 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73   void (*xFunc)(s
2d240 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
2d250 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75  int,sqlite3_valu
2d260 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78  e**),.  void (*x
2d270 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f  Step)(sqlite3_co
2d280 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74  ntext*,int,sqlit
2d290 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76  e3_value**),.  v
2d2a0 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71  oid (*xFinal)(sq
2d2b0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a  lite3_context*).
2d2c0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
2d2d0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36  reate_function16
2d2e0 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
2d2f0 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a  .  const void *z
2d300 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20  FunctionName,.  
2d310 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20  int nArg,.  int 
2d320 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64  eTextRep,.  void
2d330 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28   *pApp,.  void (
2d340 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f  *xFunc)(sqlite3_
2d350 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c  context*,int,sql
2d360 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20  ite3_value**),. 
2d370 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73   void (*xStep)(s
2d380 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
2d390 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75  int,sqlite3_valu
2d3a0 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78  e**),.  void (*x
2d3b0 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63  Final)(sqlite3_c
2d3c0 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 0a 2f 2a 0a  ontext*).);../*.
2d3d0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 65 78  ** CAPI3REF: Tex
2d3e0 74 20 45 6e 63 6f 64 69 6e 67 73 20 7b 48 31 30  t Encodings {H10
2d3f0 32 36 37 7d 20 3c 53 35 30 32 30 30 3e 20 3c 48  267} <S50200> <H
2d400 31 36 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  16100>.**.** The
2d410 73 65 20 63 6f 6e 73 74 61 6e 74 20 64 65 66 69  se constant defi
2d420 6e 65 20 69 6e 74 65 67 65 72 20 63 6f 64 65 73  ne integer codes
2d430 20 74 68 61 74 20 72 65 70 72 65 73 65 6e 74 20   that represent 
2d440 74 68 65 20 76 61 72 69 6f 75 73 0a 2a 2a 20 74  the various.** t
2d450 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 20 73 75  ext encodings su
2d460 70 70 6f 72 74 65 64 20 62 79 20 53 51 4c 69 74  pported by SQLit
2d470 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  e..*/.#define SQ
2d480 4c 49 54 45 5f 55 54 46 38 20 20 20 20 20 20 20  LITE_UTF8       
2d490 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51      1.#define SQ
2d4a0 4c 49 54 45 5f 55 54 46 31 36 4c 45 20 20 20 20  LITE_UTF16LE    
2d4b0 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51      2.#define SQ
2d4c0 4c 49 54 45 5f 55 54 46 31 36 42 45 20 20 20 20  LITE_UTF16BE    
2d4d0 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51      3.#define SQ
2d4e0 4c 49 54 45 5f 55 54 46 31 36 20 20 20 20 20 20  LITE_UTF16      
2d4f0 20 20 20 20 34 20 20 20 20 2f 2a 20 55 73 65 20      4    /* Use 
2d500 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
2d510 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  r */.#define SQL
2d520 49 54 45 5f 41 4e 59 20 20 20 20 20 20 20 20 20  ITE_ANY         
2d530 20 20 20 35 20 20 20 20 2f 2a 20 73 71 6c 69 74     5    /* sqlit
2d540 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
2d550 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  on only */.#defi
2d560 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 5f  ne SQLITE_UTF16_
2d570 41 4c 49 47 4e 45 44 20 20 38 20 20 20 20 2f 2a  ALIGNED  8    /*
2d580 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
2d590 63 6f 6c 6c 61 74 69 6f 6e 20 6f 6e 6c 79 20 2a  collation only *
2d5a0 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  /../*.** CAPI3RE
2d5b0 46 3a 20 44 65 70 72 65 63 61 74 65 64 20 46 75  F: Deprecated Fu
2d5c0 6e 63 74 69 6f 6e 73 0a 2a 2a 20 44 45 50 52 45  nctions.** DEPRE
2d5d0 43 41 54 45 44 0a 2a 2a 0a 2a 2a 20 54 68 65 73  CATED.**.** Thes
2d5e0 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20  e functions are 
2d5f0 5b 64 65 70 72 65 63 61 74 65 64 5d 2e 20 20 49  [deprecated].  I
2d600 6e 20 6f 72 64 65 72 20 74 6f 20 6d 61 69 6e 74  n order to maint
2d610 61 69 6e 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73  ain.** backwards
2d620 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 77   compatibility w
2d630 69 74 68 20 6f 6c 64 65 72 20 63 6f 64 65 2c 20  ith older code, 
2d640 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20  these functions 
2d650 63 6f 6e 74 69 6e 75 65 20 0a 2a 2a 20 74 6f 20  continue .** to 
2d660 62 65 20 73 75 70 70 6f 72 74 65 64 2e 20 20 48  be supported.  H
2d670 6f 77 65 76 65 72 2c 20 6e 65 77 20 61 70 70 6c  owever, new appl
2d680 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20  ications should 
2d690 61 76 6f 69 64 0a 2a 2a 20 74 68 65 20 75 73 65  avoid.** the use
2d6a0 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74 69   of these functi
2d6b0 6f 6e 73 2e 20 20 54 6f 20 68 65 6c 70 20 65 6e  ons.  To help en
2d6c0 63 6f 75 72 61 67 65 20 70 65 6f 70 6c 65 20 74  courage people t
2d6d0 6f 20 61 76 6f 69 64 0a 2a 2a 20 75 73 69 6e 67  o avoid.** using
2d6e0 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   these functions
2d6f0 2c 20 77 65 20 61 72 65 20 6e 6f 74 20 67 6f 69  , we are not goi
2d700 6e 67 20 74 6f 20 74 65 6c 6c 20 79 6f 75 20 77  ng to tell you w
2d710 61 6e 74 20 74 68 65 79 20 64 6f 2e 0a 2a 2f 0a  ant they do..*/.
2d720 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45  SQLITE_DEPRECATE
2d730 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 61 67  D int sqlite3_ag
2d740 67 72 65 67 61 74 65 5f 63 6f 75 6e 74 28 73 71  gregate_count(sq
2d750 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b  lite3_context*);
2d760 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54  .SQLITE_DEPRECAT
2d770 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 65  ED int sqlite3_e
2d780 78 70 69 72 65 64 28 73 71 6c 69 74 65 33 5f 73  xpired(sqlite3_s
2d790 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45  tmt*);.SQLITE_DE
2d7a0 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c  PRECATED int sql
2d7b0 69 74 65 33 5f 74 72 61 6e 73 66 65 72 5f 62 69  ite3_transfer_bi
2d7c0 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73  ndings(sqlite3_s
2d7d0 74 6d 74 2a 2c 20 73 71 6c 69 74 65 33 5f 73 74  tmt*, sqlite3_st
2d7e0 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50  mt*);.SQLITE_DEP
2d7f0 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69  RECATED int sqli
2d800 74 65 33 5f 67 6c 6f 62 61 6c 5f 72 65 63 6f 76  te3_global_recov
2d810 65 72 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45  er(void);.SQLITE
2d820 5f 44 45 50 52 45 43 41 54 45 44 20 76 6f 69 64  _DEPRECATED void
2d830 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 5f   sqlite3_thread_
2d840 63 6c 65 61 6e 75 70 28 76 6f 69 64 29 3b 0a 53  cleanup(void);.S
2d850 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44  QLITE_DEPRECATED
2d860 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d   int sqlite3_mem
2d870 6f 72 79 5f 61 6c 61 72 6d 28 76 6f 69 64 28 2a  ory_alarm(void(*
2d880 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f  )(void*,sqlite3_
2d890 69 6e 74 36 34 2c 69 6e 74 29 2c 76 6f 69 64 2a  int64,int),void*
2d8a0 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b  ,sqlite3_int64);
2d8b0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2d8c0 3a 20 4f 62 74 61 69 6e 69 6e 67 20 53 51 4c 20  : Obtaining SQL 
2d8d0 46 75 6e 63 74 69 6f 6e 20 50 61 72 61 6d 65 74  Function Paramet
2d8e0 65 72 20 56 61 6c 75 65 73 20 7b 48 31 35 31 30  er Values {H1510
2d8f0 30 7d 20 3c 53 32 30 32 30 30 3e 0a 2a 2a 0a 2a  0} <S20200>.**.*
2d900 2a 20 54 68 65 20 43 2d 6c 61 6e 67 75 61 67 65  * The C-language
2d910 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
2d920 6f 66 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  of SQL functions
2d930 20 61 6e 64 20 61 67 67 72 65 67 61 74 65 73 20   and aggregates 
2d940 75 73 65 73 0a 2a 2a 20 74 68 69 73 20 73 65 74  uses.** this set
2d950 20 6f 66 20 69 6e 74 65 72 66 61 63 65 20 72 6f   of interface ro
2d960 75 74 69 6e 65 73 20 74 6f 20 61 63 63 65 73 73  utines to access
2d970 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 76   the parameter v
2d980 61 6c 75 65 73 20 6f 6e 0a 2a 2a 20 74 68 65 20  alues on.** the 
2d990 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72  function or aggr
2d9a0 65 67 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  egate..**.** The
2d9b0 20 78 46 75 6e 63 20 28 66 6f 72 20 73 63 61 6c   xFunc (for scal
2d9c0 61 72 20 66 75 6e 63 74 69 6f 6e 73 29 20 6f 72  ar functions) or
2d9d0 20 78 53 74 65 70 20 28 66 6f 72 20 61 67 67 72   xStep (for aggr
2d9e0 65 67 61 74 65 73 29 20 70 61 72 61 6d 65 74 65  egates) paramete
2d9f0 72 73 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65  rs.** to [sqlite
2da00 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
2da10 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  n()] and [sqlite
2da20 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
2da30 6e 31 36 28 29 5d 0a 2a 2a 20 64 65 66 69 6e 65  n16()].** define
2da40 20 63 61 6c 6c 62 61 63 6b 73 20 74 68 61 74 20   callbacks that 
2da50 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 51  implement the SQ
2da60 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20  L functions and 
2da70 61 67 67 72 65 67 61 74 65 73 2e 0a 2a 2a 20 54  aggregates..** T
2da80 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72  he 4th parameter
2da90 20 74 6f 20 74 68 65 73 65 20 63 61 6c 6c 62 61   to these callba
2daa0 63 6b 73 20 69 73 20 61 6e 20 61 72 72 61 79 20  cks is an array 
2dab0 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 0a 2a  of pointers to.*
2dac0 2a 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c  * [protected sql
2dad0 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
2dae0 63 74 73 2e 20 20 54 68 65 72 65 20 69 73 20 6f  cts.  There is o
2daf0 6e 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ne [sqlite3_valu
2db00 65 5d 20 6f 62 6a 65 63 74 20 66 6f 72 0a 2a 2a  e] object for.**
2db10 20 65 61 63 68 20 70 61 72 61 6d 65 74 65 72 20   each parameter 
2db20 74 6f 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  to the SQL funct
2db30 69 6f 6e 2e 20 20 54 68 65 73 65 20 72 6f 75 74  ion.  These rout
2db40 69 6e 65 73 20 61 72 65 20 75 73 65 64 20 74 6f  ines are used to
2db50 0a 2a 2a 20 65 78 74 72 61 63 74 20 76 61 6c 75  .** extract valu
2db60 65 73 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c  es from the [sql
2db70 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
2db80 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  cts..**.** These
2db90 20 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20 6f   routines work o
2dba0 6e 6c 79 20 77 69 74 68 20 5b 70 72 6f 74 65 63  nly with [protec
2dbb0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
2dbc0 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 41  e] objects..** A
2dbd0 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 75 73  ny attempt to us
2dbe0 65 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  e these routines
2dbf0 20 6f 6e 20 61 6e 20 5b 75 6e 70 72 6f 74 65 63   on an [unprotec
2dc00 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
2dc10 65 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 73  e].** object res
2dc20 75 6c 74 73 20 69 6e 20 75 6e 64 65 66 69 6e 65  ults in undefine
2dc30 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a  d behavior..**.*
2dc40 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
2dc50 20 77 6f 72 6b 20 6a 75 73 74 20 6c 69 6b 65 20   work just like 
2dc60 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  the correspondin
2dc70 67 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73  g [column access
2dc80 20 66 75 6e 63 74 69 6f 6e 73 5d 0a 2a 2a 20 65   functions].** e
2dc90 78 63 65 70 74 20 74 68 61 74 20 20 74 68 65 73  xcept that  thes
2dca0 65 20 72 6f 75 74 69 6e 65 73 20 74 61 6b 65 20  e routines take 
2dcb0 61 20 73 69 6e 67 6c 65 20 5b 70 72 6f 74 65 63  a single [protec
2dcc0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
2dcd0 65 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 70 6f 69  e] object.** poi
2dce0 6e 74 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20  nter instead of 
2dcf0 61 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  a [sqlite3_stmt*
2dd00 5d 20 70 6f 69 6e 74 65 72 20 61 6e 64 20 61 6e  ] pointer and an
2dd10 20 69 6e 74 65 67 65 72 20 63 6f 6c 75 6d 6e 20   integer column 
2dd20 6e 75 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68  number..**.** Th
2dd30 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  e sqlite3_value_
2dd40 74 65 78 74 31 36 28 29 20 69 6e 74 65 72 66 61  text16() interfa
2dd50 63 65 20 65 78 74 72 61 63 74 73 20 61 20 55 54  ce extracts a UT
2dd60 46 2d 31 36 20 73 74 72 69 6e 67 0a 2a 2a 20 69  F-16 string.** i
2dd70 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74  n the native byt
2dd80 65 2d 6f 72 64 65 72 20 6f 66 20 74 68 65 20 68  e-order of the h
2dd90 6f 73 74 20 6d 61 63 68 69 6e 65 2e 20 20 54 68  ost machine.  Th
2dda0 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c  e.** sqlite3_val
2ddb0 75 65 5f 74 65 78 74 31 36 62 65 28 29 20 61 6e  ue_text16be() an
2ddc0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  d sqlite3_value_
2ddd0 74 65 78 74 31 36 6c 65 28 29 20 69 6e 74 65 72  text16le() inter
2dde0 66 61 63 65 73 0a 2a 2a 20 65 78 74 72 61 63 74  faces.** extract
2ddf0 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 73 20   UTF-16 strings 
2de00 61 73 20 62 69 67 2d 65 6e 64 69 61 6e 20 61 6e  as big-endian an
2de10 64 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e 20  d little-endian 
2de20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a  respectively..**
2de30 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
2de40 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79  value_numeric_ty
2de50 70 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 61  pe() interface a
2de60 74 74 65 6d 70 74 73 20 74 6f 20 61 70 70 6c 79  ttempts to apply
2de70 0a 2a 2a 20 6e 75 6d 65 72 69 63 20 61 66 66 69  .** numeric affi
2de80 6e 69 74 79 20 74 6f 20 74 68 65 20 76 61 6c 75  nity to the valu
2de90 65 2e 20 20 54 68 69 73 20 6d 65 61 6e 73 20 74  e.  This means t
2dea0 68 61 74 20 61 6e 20 61 74 74 65 6d 70 74 20 69  hat an attempt i
2deb0 73 0a 2a 2a 20 6d 61 64 65 20 74 6f 20 63 6f 6e  s.** made to con
2dec0 76 65 72 74 20 74 68 65 20 76 61 6c 75 65 20 74  vert the value t
2ded0 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 6f 72 20  o an integer or 
2dee0 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 2e 20  floating point. 
2def0 20 49 66 0a 2a 2a 20 73 75 63 68 20 61 20 63 6f   If.** such a co
2df00 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 6f 73 73  nversion is poss
2df10 69 62 6c 65 20 77 69 74 68 6f 75 74 20 6c 6f 73  ible without los
2df20 73 20 6f 66 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  s of information
2df30 20 28 69 6e 20 6f 74 68 65 72 0a 2a 2a 20 77 6f   (in other.** wo
2df40 72 64 73 2c 20 69 66 20 74 68 65 20 76 61 6c 75  rds, if the valu
2df50 65 20 69 73 20 61 20 73 74 72 69 6e 67 20 74 68  e is a string th
2df60 61 74 20 6c 6f 6f 6b 73 20 6c 69 6b 65 20 61 20  at looks like a 
2df70 6e 75 6d 62 65 72 29 0a 2a 2a 20 74 68 65 6e 20  number).** then 
2df80 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69  the conversion i
2df90 73 20 70 65 72 66 6f 72 6d 65 64 2e 20 20 4f 74  s performed.  Ot
2dfa0 68 65 72 77 69 73 65 20 6e 6f 20 63 6f 6e 76 65  herwise no conve
2dfb0 72 73 69 6f 6e 20 6f 63 63 75 72 73 2e 0a 2a 2a  rsion occurs..**
2dfc0 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 4e 54   The [SQLITE_INT
2dfd0 45 47 45 52 20 7c 20 64 61 74 61 74 79 70 65 5d  EGER | datatype]
2dfe0 20 61 66 74 65 72 20 63 6f 6e 76 65 72 73 69 6f   after conversio
2dff0 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  n is returned..*
2e000 2a 0a 2a 2a 20 50 6c 65 61 73 65 20 70 61 79 20  *.** Please pay 
2e010 70 61 72 74 69 63 75 6c 61 72 20 61 74 74 65 6e  particular atten
2e020 74 69 6f 6e 20 74 6f 20 74 68 65 20 66 61 63 74  tion to the fact
2e030 20 74 68 61 74 20 74 68 65 20 70 6f 69 6e 74 65   that the pointe
2e040 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 66 72  r returned.** fr
2e050 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  om [sqlite3_valu
2e060 65 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69  e_blob()], [sqli
2e070 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29  te3_value_text()
2e080 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  ], or.** [sqlite
2e090 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29  3_value_text16()
2e0a0 5d 20 63 61 6e 20 62 65 20 69 6e 76 61 6c 69 64  ] can be invalid
2e0b0 61 74 65 64 20 62 79 20 61 20 73 75 62 73 65 71  ated by a subseq
2e0c0 75 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20  uent call to.** 
2e0d0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62  [sqlite3_value_b
2e0e0 79 74 65 73 28 29 5d 2c 20 5b 73 71 6c 69 74 65  ytes()], [sqlite
2e0f0 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28  3_value_bytes16(
2e100 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  )], [sqlite3_val
2e110 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f  ue_text()],.** o
2e120 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  r [sqlite3_value
2e130 5f 74 65 78 74 31 36 28 29 5d 2e 0a 2a 2a 0a 2a  _text16()]..**.*
2e140 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
2e150 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20   must be called 
2e160 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68  from the same th
2e170 72 65 61 64 20 61 73 0a 2a 2a 20 74 68 65 20 53  read as.** the S
2e180 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74  QL function that
2e190 20 73 75 70 70 6c 69 65 64 20 74 68 65 20 5b 73   supplied the [s
2e1a0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 5d 20 70  qlite3_value*] p
2e1b0 61 72 61 6d 65 74 65 72 73 2e 0a 2a 2a 0a 2a 2a  arameters..**.**
2e1c0 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
2e1d0 2a 2a 20 7b 48 31 35 31 30 33 7d 20 54 68 65 20  ** {H15103} The 
2e1e0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62  [sqlite3_value_b
2e1f0 6c 6f 62 28 56 29 5d 20 69 6e 74 65 72 66 61 63  lob(V)] interfac
2e200 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a  e converts the.*
2e210 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 6f 74  *          [prot
2e220 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
2e230 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56 20 69 6e  lue] object V in
2e240 74 6f 20 61 20 42 4c 4f 42 20 61 6e 64 20 74 68  to a BLOB and th
2e250 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72  en.**          r
2e260 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
2e270 20 74 6f 20 74 68 65 20 63 6f 6e 76 65 72 74 65   to the converte
2e280 64 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 7b  d value..**.** {
2e290 48 31 35 31 30 36 7d 20 54 68 65 20 5b 73 71 6c  H15106} The [sql
2e2a0 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73  ite3_value_bytes
2e2b0 28 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  (V)] interface r
2e2c0 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 20 20  eturns the.**   
2e2d0 20 20 20 20 20 20 20 6e 75 6d 62 65 72 20 6f 66         number of
2e2e0 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 42 4c   bytes in the BL
2e2f0 4f 42 20 6f 72 20 73 74 72 69 6e 67 20 28 65 78  OB or string (ex
2e300 63 6c 75 73 69 76 65 20 6f 66 20 74 68 65 0a 2a  clusive of the.*
2e310 2a 20 20 20 20 20 20 20 20 20 20 7a 65 72 6f 20  *          zero 
2e320 74 65 72 6d 69 6e 61 74 6f 72 20 6f 6e 20 74 68  terminator on th
2e330 65 20 73 74 72 69 6e 67 29 20 74 68 61 74 20 77  e string) that w
2e340 61 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74  as returned by t
2e350 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d  he.**          m
2e360 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20  ost recent call 
2e370 74 6f 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  to [sqlite3_valu
2e380 65 5f 62 6c 6f 62 28 56 29 5d 20 6f 72 0a 2a 2a  e_blob(V)] or.**
2e390 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
2e3a0 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 56 29  e3_value_text(V)
2e3b0 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 31 30 39  ]..**.** {H15109
2e3c0 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  } The [sqlite3_v
2e3d0 61 6c 75 65 5f 62 79 74 65 73 31 36 28 56 29 5d  alue_bytes16(V)]
2e3e0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
2e3f0 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  ns the.**       
2e400 20 20 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74     number of byt
2e410 65 73 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67  es in the string
2e420 20 28 65 78 63 6c 75 73 69 76 65 20 6f 66 20 74   (exclusive of t
2e430 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 7a  he.**          z
2e440 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 6f  ero terminator o
2e450 6e 20 74 68 65 20 73 74 72 69 6e 67 29 20 74 68  n the string) th
2e460 61 74 20 77 61 73 20 72 65 74 75 72 6e 65 64 20  at was returned 
2e470 62 79 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  by the.**       
2e480 20 20 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63     most recent c
2e490 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
2e4a0 76 61 6c 75 65 5f 74 65 78 74 31 36 28 56 29 5d  value_text16(V)]
2e4b0 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  ,.**          [s
2e4c0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
2e4d0 74 31 36 62 65 28 56 29 5d 2c 20 6f 72 20 5b 73  t16be(V)], or [s
2e4e0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
2e4f0 74 31 36 6c 65 28 56 29 5d 2e 0a 2a 2a 0a 2a 2a  t16le(V)]..**.**
2e500 20 7b 48 31 35 31 31 32 7d 20 54 68 65 20 5b 73   {H15112} The [s
2e510 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 6f 75  qlite3_value_dou
2e520 62 6c 65 28 56 29 5d 20 69 6e 74 65 72 66 61 63  ble(V)] interfac
2e530 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a  e converts the.*
2e540 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 6f 74  *          [prot
2e550 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
2e560 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56 20 69 6e  lue] object V in
2e570 74 6f 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f  to a floating po
2e580 69 6e 74 20 76 61 6c 75 65 20 61 6e 64 0a 2a 2a  int value and.**
2e590 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e            return
2e5a0 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 61 74  s a copy of that
2e5b0 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48   value..**.** {H
2e5c0 31 35 31 31 35 7d 20 54 68 65 20 5b 73 71 6c 69  15115} The [sqli
2e5d0 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 56 29  te3_value_int(V)
2e5e0 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76  ] interface conv
2e5f0 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20  erts the.**     
2e600 20 20 20 20 20 5b 70 72 6f 74 65 63 74 65 64 20       [protected 
2e610 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
2e620 62 6a 65 63 74 20 56 20 69 6e 74 6f 20 61 20 36  bject V into a 6
2e630 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74  4-bit signed int
2e640 65 67 65 72 20 61 6e 64 0a 2a 2a 20 20 20 20 20  eger and.**     
2e650 20 20 20 20 20 72 65 74 75 72 6e 73 20 74 68 65       returns the
2e660 20 6c 6f 77 65 72 20 33 32 20 62 69 74 73 20 6f   lower 32 bits o
2e670 66 20 74 68 61 74 20 69 6e 74 65 67 65 72 2e 0a  f that integer..
2e680 2a 2a 0a 2a 2a 20 7b 48 31 35 31 31 38 7d 20 54  **.** {H15118} T
2e690 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  he [sqlite3_valu
2e6a0 65 5f 69 6e 74 36 34 28 56 29 5d 20 69 6e 74 65  e_int64(V)] inte
2e6b0 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74  rface converts t
2e6c0 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  he.**          [
2e6d0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
2e6e0 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
2e6f0 56 20 69 6e 74 6f 20 61 20 36 34 2d 62 69 74 20  V into a 64-bit 
2e700 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20 61  signed integer a
2e710 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72  nd.**          r
2e720 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66  eturns a copy of
2e730 20 74 68 61 74 20 69 6e 74 65 67 65 72 2e 0a 2a   that integer..*
2e740 2a 0a 2a 2a 20 7b 48 31 35 31 32 31 7d 20 54 68  *.** {H15121} Th
2e750 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
2e760 5f 74 65 78 74 28 56 29 5d 20 69 6e 74 65 72 66  _text(V)] interf
2e770 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65  ace converts the
2e780 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72  .**          [pr
2e790 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
2e7a0 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56 20  value] object V 
2e7b0 69 6e 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d  into a zero-term
2e7c0 69 6e 61 74 65 64 20 55 54 46 2d 38 0a 2a 2a 20  inated UTF-8.** 
2e7d0 20 20 20 20 20 20 20 20 20 73 74 72 69 6e 67 20           string 
2e7e0 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f  and returns a po
2e7f0 69 6e 74 65 72 20 74 6f 20 74 68 61 74 20 73 74  inter to that st
2e800 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35  ring..**.** {H15
2e810 31 32 34 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  124} The [sqlite
2e820 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 56  3_value_text16(V
2e830 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e  )] interface con
2e840 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20  verts the.**    
2e850 20 20 20 20 20 20 5b 70 72 6f 74 65 63 74 65 64        [protected
2e860 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
2e870 6f 62 6a 65 63 74 20 56 20 69 6e 74 6f 20 61 20  object V into a 
2e880 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
2e890 32 2d 62 79 74 65 0a 2a 2a 20 20 20 20 20 20 20  2-byte.**       
2e8a0 20 20 20 61 6c 69 67 6e 65 64 20 55 54 46 2d 31     aligned UTF-1
2e8b0 36 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  6 native byte or
2e8c0 64 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  der.**          
2e8d0 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72  string and retur
2e8e0 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
2e8f0 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a  that string..**.
2e900 2a 2a 20 7b 48 31 35 31 32 37 7d 20 54 68 65 20  ** {H15127} The 
2e910 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
2e920 65 78 74 31 36 62 65 28 56 29 5d 20 69 6e 74 65  ext16be(V)] inte
2e930 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74  rface converts t
2e940 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  he.**          [
2e950 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
2e960 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
2e970 56 20 69 6e 74 6f 20 61 20 7a 65 72 6f 2d 74 65  V into a zero-te
2e980 72 6d 69 6e 61 74 65 64 20 32 2d 62 79 74 65 0a  rminated 2-byte.
2e990 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6c 69 67  **          alig
2e9a0 6e 65 64 20 55 54 46 2d 31 36 20 62 69 67 2d 65  ned UTF-16 big-e
2e9b0 6e 64 69 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20  ndian.**        
2e9c0 20 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74    string and ret
2e9d0 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
2e9e0 6f 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a  o that string..*
2e9f0 2a 0a 2a 2a 20 7b 48 31 35 31 33 30 7d 20 54 68  *.** {H15130} Th
2ea00 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
2ea10 5f 74 65 78 74 31 36 6c 65 28 56 29 5d 20 69 6e  _text16le(V)] in
2ea20 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73  terface converts
2ea30 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
2ea40 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69   [protected sqli
2ea50 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
2ea60 74 20 56 20 69 6e 74 6f 20 61 20 7a 65 72 6f 2d  t V into a zero-
2ea70 74 65 72 6d 69 6e 61 74 65 64 20 32 2d 62 79 74  terminated 2-byt
2ea80 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6c  e.**          al
2ea90 69 67 6e 65 64 20 55 54 46 2d 31 36 20 6c 69 74  igned UTF-16 lit
2eaa0 74 6c 65 2d 65 6e 64 69 61 6e 0a 2a 2a 20 20 20  tle-endian.**   
2eab0 20 20 20 20 20 20 20 73 74 72 69 6e 67 20 61 6e         string an
2eac0 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  d returns a poin
2ead0 74 65 72 20 74 6f 20 74 68 61 74 20 73 74 72 69  ter to that stri
2eae0 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 31 33  ng..**.** {H1513
2eaf0 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  3} The [sqlite3_
2eb00 76 61 6c 75 65 5f 74 79 70 65 28 56 29 5d 20 69  value_type(V)] i
2eb10 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
2eb20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 6e 65  .**          one
2eb30 20 6f 66 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c   of [SQLITE_NULL
2eb40 5d 2c 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47  ], [SQLITE_INTEG
2eb50 45 52 5d 2c 20 5b 53 51 4c 49 54 45 5f 46 4c 4f  ER], [SQLITE_FLO
2eb60 41 54 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  AT],.**         
2eb70 20 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20   [SQLITE_TEXT], 
2eb80 6f 72 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d  or [SQLITE_BLOB]
2eb90 20 61 73 20 61 70 70 72 6f 70 72 69 61 74 65 20   as appropriate 
2eba0 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  for.**          
2ebb0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  the [sqlite3_val
2ebc0 75 65 5d 20 6f 62 6a 65 63 74 20 56 2e 0a 2a 2a  ue] object V..**
2ebd0 0a 2a 2a 20 7b 48 31 35 31 33 36 7d 20 54 68 65  .** {H15136} The
2ebe0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
2ebf0 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 56 29 5d  numeric_type(V)]
2ec00 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65   interface conve
2ec10 72 74 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  rts.**          
2ec20 74 68 65 20 5b 70 72 6f 74 65 63 74 65 64 20 73  the [protected s
2ec30 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
2ec40 6a 65 63 74 20 56 20 69 6e 74 6f 20 65 69 74 68  ject V into eith
2ec50 65 72 20 61 6e 20 69 6e 74 65 67 65 72 20 6f 72  er an integer or
2ec60 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20 66  .**          a f
2ec70 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61  loating point va
2ec80 6c 75 65 20 69 66 20 69 74 20 63 61 6e 20 64 6f  lue if it can do
2ec90 20 73 6f 20 77 69 74 68 6f 75 74 20 6c 6f 73 73   so without loss
2eca0 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   of.**          
2ecb0 69 6e 66 6f 72 6d 61 74 69 6f 6e 2c 20 61 6e 64  information, and
2ecc0 20 72 65 74 75 72 6e 73 20 6f 6e 65 20 6f 66 20   returns one of 
2ecd0 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2c 0a 2a  [SQLITE_NULL],.*
2ece0 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49  *          [SQLI
2ecf0 54 45 5f 49 4e 54 45 47 45 52 5d 2c 20 5b 53 51  TE_INTEGER], [SQ
2ed00 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51  LITE_FLOAT], [SQ
2ed10 4c 49 54 45 5f 54 45 58 54 5d 2c 20 6f 72 0a 2a  LITE_TEXT], or.*
2ed20 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49  *          [SQLI
2ed30 54 45 5f 42 4c 4f 42 5d 20 61 73 20 61 70 70 72  TE_BLOB] as appr
2ed40 6f 70 72 69 61 74 65 20 66 6f 72 20 74 68 65 0a  opriate for the.
2ed50 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 6f  **          [pro
2ed60 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
2ed70 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56 20 61  alue] object V a
2ed80 66 74 65 72 20 74 68 65 20 63 6f 6e 76 65 72 73  fter the convers
2ed90 69 6f 6e 20 61 74 74 65 6d 70 74 2e 0a 2a 2f 0a  ion attempt..*/.
2eda0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
2edb0 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 73  te3_value_blob(s
2edc0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
2edd0 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  int sqlite3_valu
2ede0 65 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f  e_bytes(sqlite3_
2edf0 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c  value*);.int sql
2ee00 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73  ite3_value_bytes
2ee10 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  16(sqlite3_value
2ee20 2a 29 3b 0a 64 6f 75 62 6c 65 20 73 71 6c 69 74  *);.double sqlit
2ee30 65 33 5f 76 61 6c 75 65 5f 64 6f 75 62 6c 65 28  e3_value_double(
2ee40 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
2ee50 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c  .int sqlite3_val
2ee60 75 65 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 76  ue_int(sqlite3_v
2ee70 61 6c 75 65 2a 29 3b 0a 73 71 6c 69 74 65 33 5f  alue*);.sqlite3_
2ee80 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 76 61  int64 sqlite3_va
2ee90 6c 75 65 5f 69 6e 74 36 34 28 73 71 6c 69 74 65  lue_int64(sqlite
2eea0 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74  3_value*);.const
2eeb0 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a   unsigned char *
2eec0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
2eed0 78 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  xt(sqlite3_value
2eee0 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  *);.const void *
2eef0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
2ef00 78 74 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c  xt16(sqlite3_val
2ef10 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  ue*);.const void
2ef20 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   *sqlite3_value_
2ef30 74 65 78 74 31 36 6c 65 28 73 71 6c 69 74 65 33  text16le(sqlite3
2ef40 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20  _value*);.const 
2ef50 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61  void *sqlite3_va
2ef60 6c 75 65 5f 74 65 78 74 31 36 62 65 28 73 71 6c  lue_text16be(sql
2ef70 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e  ite3_value*);.in
2ef80 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  t sqlite3_value_
2ef90 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c  type(sqlite3_val
2efa0 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  ue*);.int sqlite
2efb0 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f  3_value_numeric_
2efc0 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c  type(sqlite3_val
2efd0 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ue*);../*.** CAP
2efe0 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 20 41 67  I3REF: Obtain Ag
2eff0 67 72 65 67 61 74 65 20 46 75 6e 63 74 69 6f 6e  gregate Function
2f000 20 43 6f 6e 74 65 78 74 20 7b 48 31 36 32 31 30   Context {H16210
2f010 7d 20 3c 53 32 30 32 30 30 3e 0a 2a 2a 0a 2a 2a  } <S20200>.**.**
2f020 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   The implementat
2f030 69 6f 6e 20 6f 66 20 61 67 67 72 65 67 61 74 65  ion of aggregate
2f040 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 75   SQL functions u
2f050 73 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  se this routine 
2f060 74 6f 20 61 6c 6c 6f 63 61 74 65 0a 2a 2a 20 61  to allocate.** a
2f070 20 73 74 72 75 63 74 75 72 65 20 66 6f 72 20 73   structure for s
2f080 74 6f 72 69 6e 67 20 74 68 65 69 72 20 73 74 61  toring their sta
2f090 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  te..**.** The fi
2f0a0 72 73 74 20 74 69 6d 65 20 74 68 65 20 73 71 6c  rst time the sql
2f0b0 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
2f0c0 6f 6e 74 65 78 74 28 29 20 72 6f 75 74 69 6e 65  ontext() routine
2f0d0 20 69 73 20 63 61 6c 6c 65 64 20 66 6f 72 20 61   is called for a
2f0e0 0a 2a 2a 20 70 61 72 74 69 63 75 6c 61 72 20 61  .** particular a
2f0f0 67 67 72 65 67 61 74 65 2c 20 53 51 4c 69 74 65  ggregate, SQLite
2f100 20 61 6c 6c 6f 63 61 74 65 73 20 6e 42 79 74 65   allocates nByte
2f110 73 20 6f 66 20 6d 65 6d 6f 72 79 2c 20 7a 65 72  s of memory, zer
2f120 6f 65 73 20 6f 75 74 20 74 68 61 74 0a 2a 2a 20  oes out that.** 
2f130 6d 65 6d 6f 72 79 2c 20 61 6e 64 20 72 65 74 75  memory, and retu
2f140 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
2f150 20 69 74 2e 20 4f 6e 20 73 65 63 6f 6e 64 20 61   it. On second a
2f160 6e 64 20 73 75 62 73 65 71 75 65 6e 74 20 63 61  nd subsequent ca
2f170 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  lls to.** sqlite
2f180 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
2f190 65 78 74 28 29 20 66 6f 72 20 74 68 65 20 73 61  ext() for the sa
2f1a0 6d 65 20 61 67 67 72 65 67 61 74 65 20 66 75 6e  me aggregate fun
2f1b0 63 74 69 6f 6e 20 69 6e 64 65 78 2c 0a 2a 2a 20  ction index,.** 
2f1c0 74 68 65 20 73 61 6d 65 20 62 75 66 66 65 72 20  the same buffer 
2f1d0 69 73 20 72 65 74 75 72 6e 65 64 2e 20 54 68 65  is returned. The
2f1e0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
2f1f0 6f 66 20 74 68 65 20 61 67 67 72 65 67 61 74 65  of the aggregate
2f200 20 63 61 6e 20 75 73 65 0a 2a 2a 20 74 68 65 20   can use.** the 
2f210 72 65 74 75 72 6e 65 64 20 62 75 66 66 65 72 20  returned buffer 
2f220 74 6f 20 61 63 63 75 6d 75 6c 61 74 65 20 64 61  to accumulate da
2f230 74 61 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  ta..**.** SQLite
2f240 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 66   automatically f
2f250 72 65 65 73 20 74 68 65 20 61 6c 6c 6f 63 61 74  rees the allocat
2f260 65 64 20 62 75 66 66 65 72 20 77 68 65 6e 20 74  ed buffer when t
2f270 68 65 20 61 67 67 72 65 67 61 74 65 0a 2a 2a 20  he aggregate.** 
2f280 71 75 65 72 79 20 63 6f 6e 63 6c 75 64 65 73 2e  query concludes.
2f290 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  .**.** The first
2f2a0 20 70 61 72 61 6d 65 74 65 72 20 73 68 6f 75 6c   parameter shoul
2f2b0 64 20 62 65 20 61 20 63 6f 70 79 20 6f 66 20 74  d be a copy of t
2f2c0 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  he.** [sqlite3_c
2f2d0 6f 6e 74 65 78 74 20 7c 20 53 51 4c 20 66 75 6e  ontext | SQL fun
2f2e0 63 74 69 6f 6e 20 63 6f 6e 74 65 78 74 5d 20 74  ction context] t
2f2f0 68 61 74 20 69 73 20 74 68 65 20 66 69 72 73 74  hat is the first
2f300 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f   parameter.** to
2f310 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 6f   the callback ro
2f320 75 74 69 6e 65 20 74 68 61 74 20 69 6d 70 6c 65  utine that imple
2f330 6d 65 6e 74 73 20 74 68 65 20 61 67 67 72 65 67  ments the aggreg
2f340 61 74 65 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a  ate function..**
2f350 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65  .** This routine
2f360 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20   must be called 
2f370 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68  from the same th
2f380 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a  read in which.**
2f390 20 74 68 65 20 61 67 67 72 65 67 61 74 65 20 53   the aggregate S
2f3a0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72  QL function is r
2f3b0 75 6e 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 49 4e  unning..**.** IN
2f3c0 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
2f3d0 7b 48 31 36 32 31 31 7d 20 54 68 65 20 66 69 72  {H16211} The fir
2f3e0 73 74 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66  st invocation of
2f3f0 20 5b 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67   [sqlite3_aggreg
2f400 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29  ate_context(C,N)
2f410 5d 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20  ] for.**        
2f420 20 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 69    a particular i
2f430 6e 73 74 61 6e 63 65 20 6f 66 20 61 6e 20 61 67  nstance of an ag
2f440 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e  gregate function
2f450 20 28 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c   (for a particul
2f460 61 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63  ar.**          c
2f470 6f 6e 74 65 78 74 20 43 29 20 63 61 75 73 65 73  ontext C) causes
2f480 20 53 51 4c 69 74 65 20 74 6f 20 61 6c 6c 6f 63   SQLite to alloc
2f490 61 74 65 20 4e 20 62 79 74 65 73 20 6f 66 20 6d  ate N bytes of m
2f4a0 65 6d 6f 72 79 2c 0a 2a 2a 20 20 20 20 20 20 20  emory,.**       
2f4b0 20 20 20 7a 65 72 6f 20 74 68 61 74 20 6d 65 6d     zero that mem
2f4c0 6f 72 79 2c 20 61 6e 64 20 72 65 74 75 72 6e 20  ory, and return 
2f4d0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
2f4e0 20 61 6c 6c 6f 63 61 74 65 64 20 6d 65 6d 6f 72   allocated memor
2f4f0 79 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 32 31 33  y..**.** {H16213
2f500 7d 20 49 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c  } If a memory al
2f510 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f  location error o
2f520 63 63 75 72 73 20 64 75 72 69 6e 67 0a 2a 2a 20  ccurs during.** 
2f530 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
2f540 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
2f550 65 78 74 28 43 2c 4e 29 5d 20 74 68 65 6e 20 74  ext(C,N)] then t
2f560 68 65 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  he function retu
2f570 72 6e 73 20 30 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  rns 0..**.** {H1
2f580 36 32 31 35 7d 20 53 65 63 6f 6e 64 20 61 6e 64  6215} Second and
2f590 20 73 75 62 73 65 71 75 65 6e 74 20 69 6e 76 6f   subsequent invo
2f5a0 63 61 74 69 6f 6e 73 20 6f 66 0a 2a 2a 20 20 20  cations of.**   
2f5b0 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
2f5c0 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
2f5d0 74 28 43 2c 4e 29 5d 20 66 6f 72 20 74 68 65 20  t(C,N)] for the 
2f5e0 73 61 6d 65 20 63 6f 6e 74 65 78 74 20 70 6f 69  same context poi
2f5f0 6e 74 65 72 20 43 0a 2a 2a 20 20 20 20 20 20 20  nter C.**       
2f600 20 20 20 69 67 6e 6f 72 65 20 74 68 65 20 4e 20     ignore the N 
2f610 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20 72 65  parameter and re
2f620 74 75 72 6e 20 61 20 70 6f 69 6e 74 65 72 20 74  turn a pointer t
2f630 6f 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 20 20  o the same.**   
2f640 20 20 20 20 20 20 20 62 6c 6f 63 6b 20 6f 66 20         block of 
2f650 6d 65 6d 6f 72 79 20 72 65 74 75 72 6e 65 64 20  memory returned 
2f660 62 79 20 74 68 65 20 66 69 72 73 74 20 69 6e 76  by the first inv
2f670 6f 63 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 7b  ocation..**.** {
2f680 48 31 36 32 31 37 7d 20 54 68 65 20 6d 65 6d 6f  H16217} The memo
2f690 72 79 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20  ry allocated by 
2f6a0 5b 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61  [sqlite3_aggrega
2f6b0 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 5d  te_context(C,N)]
2f6c0 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   is.**          
2f6d0 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 66 72  automatically fr
2f6e0 65 65 64 20 6f 6e 20 74 68 65 20 6e 65 78 74 20  eed on the next 
2f6f0 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
2f700 5f 72 65 73 65 74 28 29 5d 0a 2a 2a 20 20 20 20  _reset()].**    
2f710 20 20 20 20 20 20 6f 72 20 5b 73 71 6c 69 74 65        or [sqlite
2f720 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 66 6f  3_finalize()] fo
2f730 72 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  r the [prepared 
2f740 73 74 61 74 65 6d 65 6e 74 5d 20 63 6f 6e 74 61  statement] conta
2f750 69 6e 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20  ining.**        
2f760 20 20 74 68 65 20 61 67 67 72 65 67 61 74 65 20    the aggregate 
2f770 66 75 6e 63 74 69 6f 6e 20 61 73 73 6f 63 69 61  function associa
2f780 74 65 64 20 77 69 74 68 20 63 6f 6e 74 65 78 74  ted with context
2f790 20 43 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c   C..*/.void *sql
2f7a0 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
2f7b0 6f 6e 74 65 78 74 28 73 71 6c 69 74 65 33 5f 63  ontext(sqlite3_c
2f7c0 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e 42 79  ontext*, int nBy
2f7d0 74 65 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tes);../*.** CAP
2f7e0 49 33 52 45 46 3a 20 55 73 65 72 20 44 61 74 61  I3REF: User Data
2f7f0 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73 20 7b   For Functions {
2f800 48 31 36 32 34 30 7d 20 3c 53 32 30 32 30 30 3e  H16240} <S20200>
2f810 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
2f820 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29 20 69  e3_user_data() i
2f830 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
2f840 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68   a copy of.** th
2f850 65 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 77  e pointer that w
2f860 61 73 20 74 68 65 20 70 55 73 65 72 44 61 74 61  as the pUserData
2f870 20 70 61 72 61 6d 65 74 65 72 20 28 74 68 65 20   parameter (the 
2f880 35 74 68 20 70 61 72 61 6d 65 74 65 72 29 0a 2a  5th parameter).*
2f890 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  * of the [sqlite
2f8a0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
2f8b0 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c  n()].** and [sql
2f8c0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
2f8d0 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e  tion16()] routin
2f8e0 65 73 20 74 68 61 74 20 6f 72 69 67 69 6e 61 6c  es that original
2f8f0 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64  ly.** registered
2f900 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
2f910 20 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f   defined functio
2f920 6e 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54  n. {END}.**.** T
2f930 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74  his routine must
2f940 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20   be called from 
2f950 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20  the same thread 
2f960 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20  in which.** the 
2f970 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
2f980 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  ned function is 
2f990 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 49  running..**.** I
2f9a0 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
2f9b0 20 7b 48 31 36 32 34 33 7d 20 54 68 65 20 5b 73   {H16243} The [s
2f9c0 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61  qlite3_user_data
2f9d0 28 43 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  (C)] interface r
2f9e0 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66  eturns a copy of
2f9f0 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
2fa00 20 50 20 70 6f 69 6e 74 65 72 20 66 72 6f 6d 20   P pointer from 
2fa10 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  the [sqlite3_cre
2fa20 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58  ate_function(D,X
2fa30 2c 4e 2c 45 2c 50 2c 46 2c 53 2c 4c 29 5d 0a 2a  ,N,E,P,F,S,L)].*
2fa40 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 5b 73  *          or [s
2fa50 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
2fa60 6e 63 74 69 6f 6e 31 36 28 44 2c 58 2c 4e 2c 45  nction16(D,X,N,E
2fa70 2c 50 2c 46 2c 53 2c 4c 29 5d 20 63 61 6c 6c 20  ,P,F,S,L)] call 
2fa80 74 68 61 74 0a 2a 2a 20 20 20 20 20 20 20 20 20  that.**         
2fa90 20 72 65 67 69 73 74 65 72 65 64 20 74 68 65 20   registered the 
2faa0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 61 73 73  SQL function ass
2fab0 6f 63 69 61 74 65 64 20 77 69 74 68 20 5b 73 71  ociated with [sq
2fac0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5d 20 43  lite3_context] C
2fad0 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74  ..*/.void *sqlit
2fae0 65 33 5f 75 73 65 72 5f 64 61 74 61 28 73 71 6c  e3_user_data(sql
2faf0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a  ite3_context*);.
2fb00 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2fb10 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63   Database Connec
2fb20 74 69 6f 6e 20 46 6f 72 20 46 75 6e 63 74 69 6f  tion For Functio
2fb30 6e 73 20 7b 48 31 36 32 35 30 7d 20 3c 53 36 30  ns {H16250} <S60
2fb40 36 30 30 3e 3c 53 32 30 32 30 30 3e 0a 2a 2a 0a  600><S20200>.**.
2fb50 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63  ** The sqlite3_c
2fb60 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65  ontext_db_handle
2fb70 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  () interface ret
2fb80 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a  urns a copy of.*
2fb90 2a 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74 6f  * the pointer to
2fba0 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
2fbb0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 74 68 65 20  onnection] (the 
2fbc0 31 73 74 20 70 61 72 61 6d 65 74 65 72 29 0a 2a  1st parameter).*
2fbd0 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  * of the [sqlite
2fbe0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
2fbf0 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c  n()].** and [sql
2fc00 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
2fc10 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e  tion16()] routin
2fc20 65 73 20 74 68 61 74 20 6f 72 69 67 69 6e 61 6c  es that original
2fc30 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64  ly.** registered
2fc40 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
2fc50 20 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f   defined functio
2fc60 6e 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  n..**.** INVARIA
2fc70 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 32  NTS:.**.** {H162
2fc80 35 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  53} The [sqlite3
2fc90 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64  _context_db_hand
2fca0 6c 65 28 43 29 5d 20 69 6e 74 65 72 66 61 63 65  le(C)] interface
2fcb0 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20   returns a copy 
2fcc0 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  of the.**       
2fcd0 20 20 20 44 20 70 6f 69 6e 74 65 72 20 66 72 6f     D pointer fro
2fce0 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  m the [sqlite3_c
2fcf0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44  reate_function(D
2fd00 2c 58 2c 4e 2c 45 2c 50 2c 46 2c 53 2c 4c 29 5d  ,X,N,E,P,F,S,L)]
2fd10 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20  .**          or 
2fd20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
2fd30 66 75 6e 63 74 69 6f 6e 31 36 28 44 2c 58 2c 4e  function16(D,X,N
2fd40 2c 45 2c 50 2c 46 2c 53 2c 4c 29 5d 20 63 61 6c  ,E,P,F,S,L)] cal
2fd50 6c 20 74 68 61 74 0a 2a 2a 20 20 20 20 20 20 20  l that.**       
2fd60 20 20 20 72 65 67 69 73 74 65 72 65 64 20 74 68     registered th
2fd70 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 61  e SQL function a
2fd80 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 5b  ssociated with [
2fd90 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5d  sqlite3_context]
2fda0 20 43 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 20 2a   C..*/.sqlite3 *
2fdb0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f  sqlite3_context_
2fdc0 64 62 5f 68 61 6e 64 6c 65 28 73 71 6c 69 74 65  db_handle(sqlite
2fdd0 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a  3_context*);../*
2fde0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75  .** CAPI3REF: Fu
2fdf0 6e 63 74 69 6f 6e 20 41 75 78 69 6c 69 61 72 79  nction Auxiliary
2fe00 20 44 61 74 61 20 7b 48 31 36 32 37 30 7d 20 3c   Data {H16270} <
2fe10 53 32 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68  S20200>.**.** Th
2fe20 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 77 6f 20  e following two 
2fe30 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62 65  functions may be
2fe40 20 75 73 65 64 20 62 79 20 73 63 61 6c 61 72 20   used by scalar 
2fe50 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f  SQL functions to
2fe60 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 20 6d 65  .** associate me
2fe70 74 61 64 61 74 61 20 77 69 74 68 20 61 72 67 75  tadata with argu
2fe80 6d 65 6e 74 20 76 61 6c 75 65 73 2e 20 49 66 20  ment values. If 
2fe90 74 68 65 20 73 61 6d 65 20 76 61 6c 75 65 20 69  the same value i
2fea0 73 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20 6d  s passed to.** m
2feb0 75 6c 74 69 70 6c 65 20 69 6e 76 6f 63 61 74 69  ultiple invocati
2fec0 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20  ons of the same 
2fed0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 64 75 72  SQL function dur
2fee0 69 6e 67 20 71 75 65 72 79 20 65 78 65 63 75 74  ing query execut
2fef0 69 6f 6e 2c 20 75 6e 64 65 72 0a 2a 2a 20 73 6f  ion, under.** so
2ff00 6d 65 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73  me circumstances
2ff10 20 74 68 65 20 61 73 73 6f 63 69 61 74 65 64 20   the associated 
2ff20 6d 65 74 61 64 61 74 61 20 6d 61 79 20 62 65 20  metadata may be 
2ff30 70 72 65 73 65 72 76 65 64 2e 20 54 68 69 73 20  preserved. This 
2ff40 6d 61 79 0a 2a 2a 20 62 65 20 75 73 65 64 2c 20  may.** be used, 
2ff50 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 74 6f 20  for example, to 
2ff60 61 64 64 20 61 20 72 65 67 75 6c 61 72 2d 65 78  add a regular-ex
2ff70 70 72 65 73 73 69 6f 6e 20 6d 61 74 63 68 69 6e  pression matchin
2ff80 67 20 73 63 61 6c 61 72 0a 2a 2a 20 66 75 6e 63  g scalar.** func
2ff90 74 69 6f 6e 2e 20 54 68 65 20 63 6f 6d 70 69 6c  tion. The compil
2ffa0 65 64 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68  ed version of th
2ffb0 65 20 72 65 67 75 6c 61 72 20 65 78 70 72 65 73  e regular expres
2ffc0 73 69 6f 6e 20 69 73 20 73 74 6f 72 65 64 20 61  sion is stored a
2ffd0 73 0a 2a 2a 20 6d 65 74 61 64 61 74 61 20 61 73  s.** metadata as
2ffe0 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68  sociated with th
2fff0 65 20 53 51 4c 20 76 61 6c 75 65 20 70 61 73 73  e SQL value pass
30000 65 64 20 61 73 20 74 68 65 20 72 65 67 75 6c 61  ed as the regula
30010 72 20 65 78 70 72 65 73 73 69 6f 6e 0a 2a 2a 20  r expression.** 
30020 70 61 74 74 65 72 6e 2e 20 20 54 68 65 20 63 6f  pattern.  The co
30030 6d 70 69 6c 65 64 20 72 65 67 75 6c 61 72 20 65  mpiled regular e
30040 78 70 72 65 73 73 69 6f 6e 20 63 61 6e 20 62 65  xpression can be
30050 20 72 65 75 73 65 64 20 6f 6e 20 6d 75 6c 74 69   reused on multi
30060 70 6c 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f  ple.** invocatio
30070 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66  ns of the same f
30080 75 6e 63 74 69 6f 6e 20 73 6f 20 74 68 61 74 20  unction so that 
30090 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 70 61 74  the original pat
300a0 74 65 72 6e 20 73 74 72 69 6e 67 0a 2a 2a 20 64  tern string.** d
300b0 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20  oes not need to 
300c0 62 65 20 72 65 63 6f 6d 70 69 6c 65 64 20 6f 6e  be recompiled on
300d0 20 65 61 63 68 20 69 6e 76 6f 63 61 74 69 6f 6e   each invocation
300e0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
300f0 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28  te3_get_auxdata(
30100 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
30110 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
30120 20 74 68 65 20 6d 65 74 61 64 61 74 61 0a 2a 2a   the metadata.**
30130 20 61 73 73 6f 63 69 61 74 65 64 20 62 79 20 74   associated by t
30140 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  he sqlite3_set_a
30150 75 78 64 61 74 61 28 29 20 66 75 6e 63 74 69 6f  uxdata() functio
30160 6e 20 77 69 74 68 20 74 68 65 20 4e 74 68 20 61  n with the Nth a
30170 72 67 75 6d 65 6e 74 0a 2a 2a 20 76 61 6c 75 65  rgument.** value
30180 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74   to the applicat
30190 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
301a0 74 69 6f 6e 2e 20 49 66 20 6e 6f 20 6d 65 74 61  tion. If no meta
301b0 64 61 74 61 20 68 61 73 20 62 65 65 6e 20 65 76  data has been ev
301c0 65 72 0a 2a 2a 20 62 65 65 6e 20 73 65 74 20 66  er.** been set f
301d0 6f 72 20 74 68 65 20 4e 74 68 20 61 72 67 75 6d  or the Nth argum
301e0 65 6e 74 20 6f 66 20 74 68 65 20 66 75 6e 63 74  ent of the funct
301f0 69 6f 6e 2c 20 6f 72 20 69 66 20 74 68 65 20 63  ion, or if the c
30200 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20  orresponding.** 
30210 66 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65 74  function paramet
30220 65 72 20 68 61 73 20 63 68 61 6e 67 65 64 20 73  er has changed s
30230 69 6e 63 65 20 74 68 65 20 6d 65 74 61 2d 64 61  ince the meta-da
30240 74 61 20 77 61 73 20 73 65 74 2c 0a 2a 2a 20 74  ta was set,.** t
30250 68 65 6e 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  hen sqlite3_get_
30260 61 75 78 64 61 74 61 28 29 20 72 65 74 75 72 6e  auxdata() return
30270 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
30280 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
30290 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28  te3_set_auxdata(
302a0 29 20 69 6e 74 65 72 66 61 63 65 20 73 61 76 65  ) interface save
302b0 73 20 74 68 65 20 6d 65 74 61 64 61 74 61 0a 2a  s the metadata.*
302c0 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20  * pointed to by 
302d0 69 74 73 20 33 72 64 20 70 61 72 61 6d 65 74 65  its 3rd paramete
302e0 72 20 61 73 20 74 68 65 20 6d 65 74 61 64 61 74  r as the metadat
302f0 61 20 66 6f 72 20 74 68 65 20 4e 2d 74 68 0a 2a  a for the N-th.*
30300 2a 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 68  * argument of th
30310 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
30320 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20  fined function. 
30330 20 53 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 63   Subsequent.** c
30340 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
30350 67 65 74 5f 61 75 78 64 61 74 61 28 29 20 6d 69  get_auxdata() mi
30360 67 68 74 20 72 65 74 75 72 6e 20 74 68 69 73 20  ght return this 
30370 64 61 74 61 2c 20 69 66 20 69 74 20 68 61 73 0a  data, if it has.
30380 2a 2a 20 6e 6f 74 20 62 65 65 6e 20 64 65 73 74  ** not been dest
30390 72 6f 79 65 64 2e 0a 2a 2a 20 49 66 20 69 74 20  royed..** If it 
303a0 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 53 51 4c  is not NULL, SQL
303b0 69 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20  ite will invoke 
303c0 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 0a 2a  the destructor.*
303d0 2a 20 66 75 6e 63 74 69 6f 6e 20 67 69 76 65 6e  * function given
303e0 20 62 79 20 74 68 65 20 34 74 68 20 70 61 72 61   by the 4th para
303f0 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
30400 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 6f  _set_auxdata() o
30410 6e 0a 2a 2a 20 74 68 65 20 6d 65 74 61 64 61 74  n.** the metadat
30420 61 20 77 68 65 6e 20 74 68 65 20 63 6f 72 72 65  a when the corre
30430 73 70 6f 6e 64 69 6e 67 20 66 75 6e 63 74 69 6f  sponding functio
30440 6e 20 70 61 72 61 6d 65 74 65 72 20 63 68 61 6e  n parameter chan
30450 67 65 73 0a 2a 2a 20 6f 72 20 77 68 65 6e 20 74  ges.** or when t
30460 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
30470 20 63 6f 6d 70 6c 65 74 65 73 2c 20 77 68 69 63   completes, whic
30480 68 65 76 65 72 20 63 6f 6d 65 73 20 66 69 72 73  hever comes firs
30490 74 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  t..**.** SQLite 
304a0 69 73 20 66 72 65 65 20 74 6f 20 63 61 6c 6c 20  is free to call 
304b0 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 61  the destructor a
304c0 6e 64 20 64 72 6f 70 20 6d 65 74 61 64 61 74 61  nd drop metadata
304d0 20 6f 6e 20 61 6e 79 0a 2a 2a 20 70 61 72 61 6d   on any.** param
304e0 65 74 65 72 20 6f 66 20 61 6e 79 20 66 75 6e 63  eter of any func
304f0 74 69 6f 6e 20 61 74 20 61 6e 79 20 74 69 6d 65  tion at any time
30500 2e 20 20 54 68 65 20 6f 6e 6c 79 20 67 75 61 72  .  The only guar
30510 61 6e 74 65 65 20 69 73 20 74 68 61 74 0a 2a 2a  antee is that.**
30520 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20   the destructor 
30530 77 69 6c 6c 20 62 65 20 63 61 6c 6c 65 64 20 62  will be called b
30540 65 66 6f 72 65 20 74 68 65 20 6d 65 74 61 64 61  efore the metada
30550 74 61 20 69 73 20 64 72 6f 70 70 65 64 2e 0a 2a  ta is dropped..*
30560 2a 0a 2a 2a 20 49 6e 20 70 72 61 63 74 69 63 65  *.** In practice
30570 2c 20 6d 65 74 61 64 61 74 61 20 69 73 20 70 72  , metadata is pr
30580 65 73 65 72 76 65 64 20 62 65 74 77 65 65 6e 20  eserved between 
30590 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 73 20 66  function calls f
305a0 6f 72 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e  or.** expression
305b0 73 20 74 68 61 74 20 61 72 65 20 63 6f 6e 73 74  s that are const
305c0 61 6e 74 20 61 74 20 63 6f 6d 70 69 6c 65 20 74  ant at compile t
305d0 69 6d 65 2e 20 54 68 69 73 20 69 6e 63 6c 75 64  ime. This includ
305e0 65 73 20 6c 69 74 65 72 61 6c 0a 2a 2a 20 76 61  es literal.** va
305f0 6c 75 65 73 20 61 6e 64 20 53 51 4c 20 76 61 72  lues and SQL var
30600 69 61 62 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  iables..**.** Th
30610 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 75 73  ese routines mus
30620 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d  t be called from
30630 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64   the same thread
30640 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65   in which.** the
30650 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73   SQL function is
30660 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20   running..**.** 
30670 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
30680 2a 20 7b 48 31 36 32 37 32 7d 20 54 68 65 20 5b  * {H16272} The [
30690 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64  sqlite3_get_auxd
306a0 61 74 61 28 43 2c 4e 29 5d 20 69 6e 74 65 72 66  ata(C,N)] interf
306b0 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f  ace returns a po
306c0 69 6e 74 65 72 0a 2a 2a 20 20 20 20 20 20 20 20  inter.**        
306d0 20 20 74 6f 20 6d 65 74 61 64 61 74 61 20 61 73    to metadata as
306e0 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68  sociated with th
306f0 65 20 4e 74 68 20 70 61 72 61 6d 65 74 65 72 20  e Nth parameter 
30700 6f 66 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  of the SQL funct
30710 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ion.**          
30720 77 68 6f 73 65 20 63 6f 6e 74 65 78 74 20 69 73  whose context is
30730 20 43 2c 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74   C, or NULL if t
30740 68 65 72 65 20 69 73 20 6e 6f 20 6d 65 74 61 64  here is no metad
30750 61 74 61 20 61 73 73 6f 63 69 61 74 65 64 0a 2a  ata associated.*
30760 2a 20 20 20 20 20 20 20 20 20 20 77 69 74 68 20  *          with 
30770 74 68 61 74 20 70 61 72 61 6d 65 74 65 72 2e 0a  that parameter..
30780 2a 2a 0a 2a 2a 20 7b 48 31 36 32 37 34 7d 20 54  **.** {H16274} T
30790 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f  he [sqlite3_set_
307a0 61 75 78 64 61 74 61 28 43 2c 4e 2c 50 2c 44 29  auxdata(C,N,P,D)
307b0 5d 20 69 6e 74 65 72 66 61 63 65 20 61 73 73 69  ] interface assi
307c0 67 6e 73 20 61 20 6d 65 74 61 64 61 74 61 0a 2a  gns a metadata.*
307d0 2a 20 20 20 20 20 20 20 20 20 20 70 6f 69 6e 74  *          point
307e0 65 72 20 50 20 74 6f 20 74 68 65 20 4e 74 68 20  er P to the Nth 
307f0 70 61 72 61 6d 65 74 65 72 20 6f 66 20 74 68 65  parameter of the
30800 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 77 69   SQL function wi
30810 74 68 20 63 6f 6e 74 65 78 74 20 43 2e 0a 2a 2a  th context C..**
30820 0a 2a 2a 20 7b 48 31 36 32 37 36 7d 20 53 51 4c  .** {H16276} SQL
30830 69 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20  ite will invoke 
30840 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 44  the destructor D
30850 20 77 69 74 68 20 61 20 73 69 6e 67 6c 65 20 61   with a single a
30860 72 67 75 6d 65 6e 74 0a 2a 2a 20 20 20 20 20 20  rgument.**      
30870 20 20 20 20 77 68 69 63 68 20 69 73 20 74 68 65      which is the
30880 20 6d 65 74 61 64 61 74 61 20 70 6f 69 6e 74 65   metadata pointe
30890 72 20 50 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20  r P following a 
308a0 63 61 6c 6c 20 74 6f 0a 2a 2a 20 20 20 20 20 20  call to.**      
308b0 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 73 65 74      [sqlite3_set
308c0 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c 50 2c 44  _auxdata(C,N,P,D
308d0 29 5d 20 77 68 65 6e 20 53 51 4c 69 74 65 20 63  )] when SQLite c
308e0 65 61 73 65 73 20 74 6f 20 68 6f 6c 64 0a 2a 2a  eases to hold.**
308f0 20 20 20 20 20 20 20 20 20 20 74 68 65 20 6d 65            the me
30900 74 61 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 7b 48  tadata..**.** {H
30910 31 36 32 37 37 7d 20 53 51 4c 69 74 65 20 63 65  16277} SQLite ce
30920 61 73 65 73 20 74 6f 20 68 6f 6c 64 20 6d 65 74  ases to hold met
30930 61 64 61 74 61 20 66 6f 72 20 61 6e 20 53 51 4c  adata for an SQL
30940 20 66 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65   function parame
30950 74 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ter.**          
30960 77 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20 6f  when the value o
30970 66 20 74 68 61 74 20 70 61 72 61 6d 65 74 65 72  f that parameter
30980 20 63 68 61 6e 67 65 73 2e 0a 2a 2a 0a 2a 2a 20   changes..**.** 
30990 7b 48 31 36 32 37 38 7d 20 57 68 65 6e 20 5b 73  {H16278} When [s
309a0 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61  qlite3_set_auxda
309b0 74 61 28 43 2c 4e 2c 50 2c 44 29 5d 20 69 73 20  ta(C,N,P,D)] is 
309c0 69 6e 76 6f 6b 65 64 2c 20 74 68 65 20 64 65 73  invoked, the des
309d0 74 72 75 63 74 6f 72 0a 2a 2a 20 20 20 20 20 20  tructor.**      
309e0 20 20 20 20 69 73 20 63 61 6c 6c 65 64 20 66 6f      is called fo
309f0 72 20 61 6e 79 20 70 72 69 6f 72 20 6d 65 74 61  r any prior meta
30a00 64 61 74 61 20 61 73 73 6f 63 69 61 74 65 64 20  data associated 
30a10 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 66 75  with the same fu
30a20 6e 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20  nction.**       
30a30 20 20 20 63 6f 6e 74 65 78 74 20 43 20 61 6e 64     context C and
30a40 20 70 61 72 61 6d 65 74 65 72 20 4e 2e 0a 2a 2a   parameter N..**
30a50 0a 2a 2a 20 7b 48 31 36 32 37 39 7d 20 53 51 4c  .** {H16279} SQL
30a60 69 74 65 20 77 69 6c 6c 20 63 61 6c 6c 20 64 65  ite will call de
30a70 73 74 72 75 63 74 6f 72 73 20 66 6f 72 20 61 6e  structors for an
30a80 79 20 6d 65 74 61 64 61 74 61 20 69 74 20 69 73  y metadata it is
30a90 20 68 6f 6c 64 69 6e 67 0a 2a 2a 20 20 20 20 20   holding.**     
30aa0 20 20 20 20 20 69 6e 20 61 20 70 61 72 74 69 63       in a partic
30ab0 75 6c 61 72 20 5b 70 72 65 70 61 72 65 64 20 73  ular [prepared s
30ac0 74 61 74 65 6d 65 6e 74 5d 20 53 20 77 68 65 6e  tatement] S when
30ad0 20 65 69 74 68 65 72 0a 2a 2a 20 20 20 20 20 20   either.**      
30ae0 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73      [sqlite3_res
30af0 65 74 28 53 29 5d 20 6f 72 20 5b 73 71 6c 69 74  et(S)] or [sqlit
30b00 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 5d 20  e3_finalize(S)] 
30b10 69 73 20 63 61 6c 6c 65 64 2e 0a 2a 2f 0a 76 6f  is called..*/.vo
30b20 69 64 20 2a 73 71 6c 69 74 65 33 5f 67 65 74 5f  id *sqlite3_get_
30b30 61 75 78 64 61 74 61 28 73 71 6c 69 74 65 33 5f  auxdata(sqlite3_
30b40 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e 29  context*, int N)
30b50 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 73  ;.void sqlite3_s
30b60 65 74 5f 61 75 78 64 61 74 61 28 73 71 6c 69 74  et_auxdata(sqlit
30b70 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74  e3_context*, int
30b80 20 4e 2c 20 76 6f 69 64 2a 2c 20 76 6f 69 64 20   N, void*, void 
30b90 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 0a 0a 2f  (*)(void*));.../
30ba0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
30bb0 6f 6e 73 74 61 6e 74 73 20 44 65 66 69 6e 69 6e  onstants Definin
30bc0 67 20 53 70 65 63 69 61 6c 20 44 65 73 74 72 75  g Special Destru
30bd0 63 74 6f 72 20 42 65 68 61 76 69 6f 72 20 7b 48  ctor Behavior {H
30be0 31 30 32 38 30 7d 20 3c 53 33 30 31 30 30 3e 0a  10280} <S30100>.
30bf0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72 65 20  **.** These are 
30c00 73 70 65 63 69 61 6c 20 76 61 6c 75 65 73 20 66  special values f
30c10 6f 72 20 74 68 65 20 64 65 73 74 72 75 63 74 6f  or the destructo
30c20 72 20 74 68 61 74 20 69 73 20 70 61 73 73 65 64  r that is passed
30c30 20 69 6e 20 61 73 20 74 68 65 0a 2a 2a 20 66 69   in as the.** fi
30c40 6e 61 6c 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  nal argument to 
30c50 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73  routines like [s
30c60 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c  qlite3_result_bl
30c70 6f 62 28 29 5d 2e 20 20 49 66 20 74 68 65 20 64  ob()].  If the d
30c80 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20 61 72 67  estructor.** arg
30c90 75 6d 65 6e 74 20 69 73 20 53 51 4c 49 54 45 5f  ument is SQLITE_
30ca0 53 54 41 54 49 43 2c 20 69 74 20 6d 65 61 6e 73  STATIC, it means
30cb0 20 74 68 61 74 20 74 68 65 20 63 6f 6e 74 65 6e   that the conten
30cc0 74 20 70 6f 69 6e 74 65 72 20 69 73 20 63 6f 6e  t pointer is con
30cd0 73 74 61 6e 74 0a 2a 2a 20 61 6e 64 20 77 69 6c  stant.** and wil
30ce0 6c 20 6e 65 76 65 72 20 63 68 61 6e 67 65 2e 20  l never change. 
30cf0 20 49 74 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65   It does not nee
30d00 64 20 74 6f 20 62 65 20 64 65 73 74 72 6f 79 65  d to be destroye
30d10 64 2e 20 20 54 68 65 0a 2a 2a 20 53 51 4c 49 54  d.  The.** SQLIT
30d20 45 5f 54 52 41 4e 53 49 45 4e 54 20 76 61 6c 75  E_TRANSIENT valu
30d30 65 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  e means that the
30d40 20 63 6f 6e 74 65 6e 74 20 77 69 6c 6c 20 6c 69   content will li
30d50 6b 65 6c 79 20 63 68 61 6e 67 65 20 69 6e 0a 2a  kely change in.*
30d60 2a 20 74 68 65 20 6e 65 61 72 20 66 75 74 75 72  * the near futur
30d70 65 20 61 6e 64 20 74 68 61 74 20 53 51 4c 69 74  e and that SQLit
30d80 65 20 73 68 6f 75 6c 64 20 6d 61 6b 65 20 69 74  e should make it
30d90 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f  s own private co
30da0 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 63 6f 6e  py of.** the con
30db0 74 65 6e 74 20 62 65 66 6f 72 65 20 72 65 74 75  tent before retu
30dc0 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  rning..**.** The
30dd0 20 74 79 70 65 64 65 66 20 69 73 20 6e 65 63 65   typedef is nece
30de0 73 73 61 72 79 20 74 6f 20 77 6f 72 6b 20 61 72  ssary to work ar
30df0 6f 75 6e 64 20 70 72 6f 62 6c 65 6d 73 20 69 6e  ound problems in
30e00 20 63 65 72 74 61 69 6e 0a 2a 2a 20 43 2b 2b 20   certain.** C++ 
30e10 63 6f 6d 70 69 6c 65 72 73 2e 20 20 53 65 65 20  compilers.  See 
30e20 74 69 63 6b 65 74 20 23 32 31 39 31 2e 0a 2a 2f  ticket #2191..*/
30e30 0a 74 79 70 65 64 65 66 20 76 6f 69 64 20 28 2a  .typedef void (*
30e40 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74  sqlite3_destruct
30e50 6f 72 5f 74 79 70 65 29 28 76 6f 69 64 2a 29 3b  or_type)(void*);
30e60 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
30e70 53 54 41 54 49 43 20 20 20 20 20 20 28 28 73 71  STATIC      ((sq
30e80 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72  lite3_destructor
30e90 5f 74 79 70 65 29 30 29 0a 23 64 65 66 69 6e 65  _type)0).#define
30ea0 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e   SQLITE_TRANSIEN
30eb0 54 20 20 20 28 28 73 71 6c 69 74 65 33 5f 64 65  T   ((sqlite3_de
30ec0 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29 2d 31  structor_type)-1
30ed0 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  )../*.** CAPI3RE
30ee0 46 3a 20 53 65 74 74 69 6e 67 20 54 68 65 20 52  F: Setting The R
30ef0 65 73 75 6c 74 20 4f 66 20 41 6e 20 53 51 4c 20  esult Of An SQL 
30f00 46 75 6e 63 74 69 6f 6e 20 7b 48 31 36 34 30 30  Function {H16400
30f10 7d 20 3c 53 32 30 32 30 30 3e 0a 2a 2a 0a 2a 2a  } <S20200>.**.**
30f20 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
30f30 61 72 65 20 75 73 65 64 20 62 79 20 74 68 65 20  are used by the 
30f40 78 46 75 6e 63 20 6f 72 20 78 46 69 6e 61 6c 20  xFunc or xFinal 
30f50 63 61 6c 6c 62 61 63 6b 73 20 74 68 61 74 0a 2a  callbacks that.*
30f60 2a 20 69 6d 70 6c 65 6d 65 6e 74 20 53 51 4c 20  * implement SQL 
30f70 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67  functions and ag
30f80 67 72 65 67 61 74 65 73 2e 20 20 53 65 65 0a 2a  gregates.  See.*
30f90 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  * [sqlite3_creat
30fa0 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e  e_function()] an
30fb0 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  d [sqlite3_creat
30fc0 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a  e_function16()].
30fd0 2a 2a 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61  ** for additiona
30fe0 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  l information..*
30ff0 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74  *.** These funct
31000 69 6f 6e 73 20 77 6f 72 6b 20 76 65 72 79 20 6d  ions work very m
31010 75 63 68 20 6c 69 6b 65 20 74 68 65 20 5b 70 61  uch like the [pa
31020 72 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 5d  rameter binding]
31030 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 66 75   family of.** fu
31040 6e 63 74 69 6f 6e 73 20 75 73 65 64 20 74 6f 20  nctions used to 
31050 62 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 68  bind values to h
31060 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 20 69  ost parameters i
31070 6e 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  n prepared state
31080 6d 65 6e 74 73 2e 0a 2a 2a 20 52 65 66 65 72 20  ments..** Refer 
31090 74 6f 20 74 68 65 20 5b 53 51 4c 20 70 61 72 61  to the [SQL para
310a0 6d 65 74 65 72 5d 20 64 6f 63 75 6d 65 6e 74 61  meter] documenta
310b0 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69 6f  tion for additio
310c0 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e  nal information.
310d0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
310e0 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29  e3_result_blob()
310f0 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20   interface sets 
31100 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a  the result from.
31110 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  ** an applicatio
31120 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
31130 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 42 4c 4f  on to be the BLO
31140 42 20 77 68 6f 73 65 20 63 6f 6e 74 65 6e 74 20  B whose content 
31150 69 73 20 70 6f 69 6e 74 65 64 0a 2a 2a 20 74 6f  is pointed.** to
31160 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 70   by the second p
31170 61 72 61 6d 65 74 65 72 20 61 6e 64 20 77 68 69  arameter and whi
31180 63 68 20 69 73 20 4e 20 62 79 74 65 73 20 6c 6f  ch is N bytes lo
31190 6e 67 20 77 68 65 72 65 20 4e 20 69 73 20 74 68  ng where N is th
311a0 65 0a 2a 2a 20 74 68 69 72 64 20 70 61 72 61 6d  e.** third param
311b0 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  eter..**.** The 
311c0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a  sqlite3_result_z
311d0 65 72 6f 62 6c 6f 62 28 29 20 69 6e 74 65 72 66  eroblob() interf
311e0 61 63 65 73 20 73 65 74 20 74 68 65 20 72 65 73  aces set the res
311f0 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70  ult of.** the ap
31200 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
31210 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  d function to be
31220 20 61 20 42 4c 4f 42 20 63 6f 6e 74 61 69 6e 69   a BLOB containi
31230 6e 67 20 61 6c 6c 20 7a 65 72 6f 0a 2a 2a 20 62  ng all zero.** b
31240 79 74 65 73 20 61 6e 64 20 4e 20 62 79 74 65 73  ytes and N bytes
31250 20 69 6e 20 73 69 7a 65 2c 20 77 68 65 72 65 20   in size, where 
31260 4e 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f  N is the value o
31270 66 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65  f the 2nd parame
31280 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ter..**.** The s
31290 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f  qlite3_result_do
312a0 75 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65  uble() interface
312b0 20 73 65 74 73 20 74 68 65 20 72 65 73 75 6c 74   sets the result
312c0 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c   from.** an appl
312d0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
312e0 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61  function to be a
312f0 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20   floating point 
31300 76 61 6c 75 65 20 73 70 65 63 69 66 69 65 64 0a  value specified.
31310 2a 2a 20 62 79 20 69 74 73 20 32 6e 64 20 61 72  ** by its 2nd ar
31320 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68  gument..**.** Th
31330 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
31340 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 73 71 6c  _error() and sql
31350 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
31360 72 31 36 28 29 20 66 75 6e 63 74 69 6f 6e 73 0a  r16() functions.
31370 2a 2a 20 63 61 75 73 65 20 74 68 65 20 69 6d 70  ** cause the imp
31380 6c 65 6d 65 6e 74 65 64 20 53 51 4c 20 66 75 6e  lemented SQL fun
31390 63 74 69 6f 6e 20 74 6f 20 74 68 72 6f 77 20 61  ction to throw a
313a0 6e 20 65 78 63 65 70 74 69 6f 6e 2e 0a 2a 2a 20  n exception..** 
313b0 53 51 4c 69 74 65 20 75 73 65 73 20 74 68 65 20  SQLite uses the 
313c0 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 64 20 74  string pointed t
313d0 6f 20 62 79 20 74 68 65 0a 2a 2a 20 32 6e 64 20  o by the.** 2nd 
313e0 70 61 72 61 6d 65 74 65 72 20 6f 66 20 73 71 6c  parameter of sql
313f0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
31400 72 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72  r() or sqlite3_r
31410 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a  esult_error16().
31420 2a 2a 20 61 73 20 74 68 65 20 74 65 78 74 20 6f  ** as the text o
31430 66 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61  f an error messa
31440 67 65 2e 20 20 53 51 4c 69 74 65 20 69 6e 74 65  ge.  SQLite inte
31450 72 70 72 65 74 73 20 74 68 65 20 65 72 72 6f 72  rprets the error
31460 0a 2a 2a 20 6d 65 73 73 61 67 65 20 73 74 72 69  .** message stri
31470 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ng from sqlite3_
31480 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61  result_error() a
31490 73 20 55 54 46 2d 38 2e 20 53 51 4c 69 74 65 0a  s UTF-8. SQLite.
314a0 2a 2a 20 69 6e 74 65 72 70 72 65 74 73 20 74 68  ** interprets th
314b0 65 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 73 71  e string from sq
314c0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
314d0 6f 72 31 36 28 29 20 61 73 20 55 54 46 2d 31 36  or16() as UTF-16
314e0 20 69 6e 20 6e 61 74 69 76 65 0a 2a 2a 20 62 79   in native.** by
314f0 74 65 20 6f 72 64 65 72 2e 20 20 49 66 20 74 68  te order.  If th
31500 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
31510 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73  r to sqlite3_res
31520 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f  ult_error().** o
31530 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  r sqlite3_result
31540 5f 65 72 72 6f 72 31 36 28 29 20 69 73 20 6e 65  _error16() is ne
31550 67 61 74 69 76 65 20 74 68 65 6e 20 53 51 4c 69  gative then SQLi
31560 74 65 20 74 61 6b 65 73 20 61 73 20 74 68 65 20  te takes as the 
31570 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65  error.** message
31580 20 61 6c 6c 20 74 65 78 74 20 75 70 20 74 68 72   all text up thr
31590 6f 75 67 68 20 74 68 65 20 66 69 72 73 74 20 7a  ough the first z
315a0 65 72 6f 20 63 68 61 72 61 63 74 65 72 2e 0a 2a  ero character..*
315b0 2a 20 49 66 20 74 68 65 20 74 68 69 72 64 20 70  * If the third p
315c0 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
315d0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
315e0 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  () or.** sqlite3
315f0 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
31600 29 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76  ) is non-negativ
31610 65 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61  e then SQLite ta
31620 6b 65 73 20 74 68 61 74 20 6d 61 6e 79 0a 2a 2a  kes that many.**
31630 20 62 79 74 65 73 20 28 6e 6f 74 20 63 68 61 72   bytes (not char
31640 61 63 74 65 72 73 29 20 66 72 6f 6d 20 74 68 65  acters) from the
31650 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61   2nd parameter a
31660 73 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73  s the error mess
31670 61 67 65 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69  age..** The sqli
31680 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
31690 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72  () and sqlite3_r
316a0 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a  esult_error16().
316b0 2a 2a 20 72 6f 75 74 69 6e 65 73 20 6d 61 6b 65  ** routines make
316c0 20 61 20 70 72 69 76 61 74 65 20 63 6f 70 79 20   a private copy 
316d0 6f 66 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73  of the error mes
316e0 73 61 67 65 20 74 65 78 74 20 62 65 66 6f 72 65  sage text before
316f0 0a 2a 2a 20 74 68 65 79 20 72 65 74 75 72 6e 2e  .** they return.
31700 20 20 48 65 6e 63 65 2c 20 74 68 65 20 63 61 6c    Hence, the cal
31710 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 61  ling function ca
31720 6e 20 64 65 61 6c 6c 6f 63 61 74 65 20 6f 72 0a  n deallocate or.
31730 2a 2a 20 6d 6f 64 69 66 79 20 74 68 65 20 74 65  ** modify the te
31740 78 74 20 61 66 74 65 72 20 74 68 65 79 20 72 65  xt after they re
31750 74 75 72 6e 20 77 69 74 68 6f 75 74 20 68 61 72  turn without har
31760 6d 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  m..** The sqlite
31770 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63  3_result_error_c
31780 6f 64 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 63  ode() function c
31790 68 61 6e 67 65 73 20 74 68 65 20 65 72 72 6f 72  hanges the error
317a0 20 63 6f 64 65 0a 2a 2a 20 72 65 74 75 72 6e 65   code.** returne
317b0 64 20 62 79 20 53 51 4c 69 74 65 20 61 73 20 61  d by SQLite as a
317c0 20 72 65 73 75 6c 74 20 6f 66 20 61 6e 20 65 72   result of an er
317d0 72 6f 72 20 69 6e 20 61 20 66 75 6e 63 74 69 6f  ror in a functio
317e0 6e 2e 20 20 42 79 20 64 65 66 61 75 6c 74 2c 0a  n.  By default,.
317f0 2a 2a 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64  ** the error cod
31800 65 20 69 73 20 53 51 4c 49 54 45 5f 45 52 52 4f  e is SQLITE_ERRO
31810 52 2e 20 20 41 20 73 75 62 73 65 71 75 65 6e 74  R.  A subsequent
31820 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
31830 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 0a  _result_error().
31840 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65  ** or sqlite3_re
31850 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 72  sult_error16() r
31860 65 73 65 74 73 20 74 68 65 20 65 72 72 6f 72 20  esets the error 
31870 63 6f 64 65 20 74 6f 20 53 51 4c 49 54 45 5f 45  code to SQLITE_E
31880 52 52 4f 52 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  RROR..**.** The 
31890 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
318a0 6f 6f 62 69 67 28 29 20 69 6e 74 65 72 66 61 63  oobig() interfac
318b0 65 20 63 61 75 73 65 73 20 53 51 4c 69 74 65 20  e causes SQLite 
318c0 74 6f 20 74 68 72 6f 77 20 61 6e 20 65 72 72 6f  to throw an erro
318d0 72 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67 20  r.** indicating 
318e0 74 68 61 74 20 61 20 73 74 72 69 6e 67 20 6f 72  that a string or
318f0 20 42 4c 4f 42 20 69 73 20 74 6f 20 6c 6f 6e 67   BLOB is to long
31900 20 74 6f 20 72 65 70 72 65 73 65 6e 74 2e 0a 2a   to represent..*
31910 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
31920 5f 72 65 73 75 6c 74 5f 6e 6f 6d 65 6d 28 29 20  _result_nomem() 
31930 69 6e 74 65 72 66 61 63 65 20 63 61 75 73 65 73  interface causes
31940 20 53 51 4c 69 74 65 20 74 6f 20 74 68 72 6f 77   SQLite to throw
31950 20 61 6e 20 65 72 72 6f 72 0a 2a 2a 20 69 6e 64   an error.** ind
31960 69 63 61 74 69 6e 67 20 74 68 61 74 20 61 20 6d  icating that a m
31970 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
31980 20 66 61 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 54   failed..**.** T
31990 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
319a0 74 5f 69 6e 74 28 29 20 69 6e 74 65 72 66 61 63  t_int() interfac
319b0 65 20 73 65 74 73 20 74 68 65 20 72 65 74 75 72  e sets the retur
319c0 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68  n value.** of th
319d0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
319e0 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74  fined function t
319f0 6f 20 62 65 20 74 68 65 20 33 32 2d 62 69 74 20  o be the 32-bit 
31a00 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a  signed integer.*
31a10 2a 20 76 61 6c 75 65 20 67 69 76 65 6e 20 69 6e  * value given in
31a20 20 74 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e   the 2nd argumen
31a30 74 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  t..** The sqlite
31a40 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 28 29  3_result_int64()
31a50 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20   interface sets 
31a60 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
31a70 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69  .** of the appli
31a80 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
31a90 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68  unction to be th
31aa0 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20  e 64-bit signed 
31ab0 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65  integer.** value
31ac0 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20 32 6e   given in the 2n
31ad0 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a  d argument..**.*
31ae0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65  * The sqlite3_re
31af0 73 75 6c 74 5f 6e 75 6c 6c 28 29 20 69 6e 74 65  sult_null() inte
31b00 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72  rface sets the r
31b10 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f  eturn value.** o
31b20 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  f the applicatio
31b30 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
31b40 6f 6e 20 74 6f 20 62 65 20 4e 55 4c 4c 2e 0a 2a  on to be NULL..*
31b50 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
31b60 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 29 2c 20  _result_text(), 
31b70 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
31b80 65 78 74 31 36 28 29 2c 0a 2a 2a 20 73 71 6c 69  ext16(),.** sqli
31b90 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31  te3_result_text1
31ba0 36 6c 65 28 29 2c 20 61 6e 64 20 73 71 6c 69 74  6le(), and sqlit
31bb0 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
31bc0 62 65 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a  be() interfaces.
31bd0 2a 2a 20 73 65 74 20 74 68 65 20 72 65 74 75 72  ** set the retur
31be0 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 61  n value of the a
31bf0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
31c00 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
31c10 65 0a 2a 2a 20 61 20 74 65 78 74 20 73 74 72 69  e.** a text stri
31c20 6e 67 20 77 68 69 63 68 20 69 73 20 72 65 70 72  ng which is repr
31c30 65 73 65 6e 74 65 64 20 61 73 20 55 54 46 2d 38  esented as UTF-8
31c40 2c 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20  , UTF-16 native 
31c50 62 79 74 65 20 6f 72 64 65 72 2c 0a 2a 2a 20 55  byte order,.** U
31c60 54 46 2d 31 36 20 6c 69 74 74 6c 65 20 65 6e 64  TF-16 little end
31c70 69 61 6e 2c 20 6f 72 20 55 54 46 2d 31 36 20 62  ian, or UTF-16 b
31c80 69 67 20 65 6e 64 69 61 6e 2c 20 72 65 73 70 65  ig endian, respe
31c90 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 53 51 4c 69  ctively..** SQLi
31ca0 74 65 20 74 61 6b 65 73 20 74 68 65 20 74 65 78  te takes the tex
31cb0 74 20 72 65 73 75 6c 74 20 66 72 6f 6d 20 74 68  t result from th
31cc0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 66 72  e application fr
31cd0 6f 6d 0a 2a 2a 20 74 68 65 20 32 6e 64 20 70 61  om.** the 2nd pa
31ce0 72 61 6d 65 74 65 72 20 6f 66 20 74 68 65 20 73  rameter of the s
31cf0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
31d00 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 2e 0a  xt* interfaces..
31d10 2a 2a 20 49 66 20 74 68 65 20 33 72 64 20 70 61  ** If the 3rd pa
31d20 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73  rameter to the s
31d30 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
31d40 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  xt* interfaces.*
31d50 2a 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74  * is negative, t
31d60 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73  hen SQLite takes
31d70 20 72 65 73 75 6c 74 20 74 65 78 74 20 66 72 6f   result text fro
31d80 6d 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65  m the 2nd parame
31d90 74 65 72 0a 2a 2a 20 74 68 72 6f 75 67 68 20 74  ter.** through t
31da0 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 63 68  he first zero ch
31db0 61 72 61 63 74 65 72 2e 0a 2a 2a 20 49 66 20 74  aracter..** If t
31dc0 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72  he 3rd parameter
31dd0 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
31de0 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74  result_text* int
31df0 65 72 66 61 63 65 73 0a 2a 2a 20 69 73 20 6e 6f  erfaces.** is no
31e00 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e  n-negative, then
31e10 20 61 73 20 6d 61 6e 79 20 62 79 74 65 73 20 28   as many bytes (
31e20 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73 29 20  not characters) 
31e30 6f 66 20 74 68 65 20 74 65 78 74 0a 2a 2a 20 70  of the text.** p
31e40 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65  ointed to by the
31e50 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61   2nd parameter a
31e60 72 65 20 74 61 6b 65 6e 20 61 73 20 74 68 65 20  re taken as the 
31e70 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
31e80 6e 65 64 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ned.** function 
31e90 72 65 73 75 6c 74 2e 0a 2a 2a 20 49 66 20 74 68  result..** If th
31ea0 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 4th parameter 
31eb0 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72  to the sqlite3_r
31ec0 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65  esult_text* inte
31ed0 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c  rfaces.** or sql
31ee0 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62  ite3_result_blob
31ef0 20 69 73 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70   is a non-NULL p
31f00 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 53 51 4c  ointer, then SQL
31f10 69 74 65 20 63 61 6c 6c 73 20 74 68 61 74 0a 2a  ite calls that.*
31f20 2a 20 66 75 6e 63 74 69 6f 6e 20 61 73 20 74 68  * function as th
31f30 65 20 64 65 73 74 72 75 63 74 6f 72 20 6f 6e 20  e destructor on 
31f40 74 68 65 20 74 65 78 74 20 6f 72 20 42 4c 4f 42  the text or BLOB
31f50 20 72 65 73 75 6c 74 20 77 68 65 6e 20 69 74 20   result when it 
31f60 68 61 73 0a 2a 2a 20 66 69 6e 69 73 68 65 64 20  has.** finished 
31f70 75 73 69 6e 67 20 74 68 61 74 20 72 65 73 75 6c  using that resul
31f80 74 2e 0a 2a 2a 20 49 66 20 74 68 65 20 34 74 68  t..** If the 4th
31f90 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
31fa0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
31fb0 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65  _text* interface
31fc0 73 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  s or.** sqlite3_
31fd0 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74  result_blob is t
31fe0 68 65 20 73 70 65 63 69 61 6c 20 63 6f 6e 73 74  he special const
31ff0 61 6e 74 20 53 51 4c 49 54 45 5f 53 54 41 54 49  ant SQLITE_STATI
32000 43 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 0a 2a  C, then SQLite.*
32010 2a 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74  * assumes that t
32020 68 65 20 74 65 78 74 20 6f 72 20 42 4c 4f 42 20  he text or BLOB 
32030 72 65 73 75 6c 74 20 69 73 20 69 6e 20 63 6f 6e  result is in con
32040 73 74 61 6e 74 20 73 70 61 63 65 20 61 6e 64 20  stant space and 
32050 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 63 6f 70 79  does not.** copy
32060 20 74 68 65 20 69 74 20 6f 72 20 63 61 6c 6c 20   the it or call 
32070 61 20 64 65 73 74 72 75 63 74 6f 72 20 77 68 65  a destructor whe
32080 6e 20 69 74 20 68 61 73 20 66 69 6e 69 73 68 65  n it has finishe
32090 64 20 75 73 69 6e 67 20 74 68 61 74 20 72 65 73  d using that res
320a0 75 6c 74 2e 0a 2a 2a 20 49 66 20 74 68 65 20 34  ult..** If the 4
320b0 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
320c0 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  the sqlite3_resu
320d0 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61  lt_text* interfa
320e0 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65  ces.** or sqlite
320f0 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73  3_result_blob is
32100 20 74 68 65 20 73 70 65 63 69 61 6c 20 63 6f 6e   the special con
32110 73 74 61 6e 74 20 53 51 4c 49 54 45 5f 54 52 41  stant SQLITE_TRA
32120 4e 53 49 45 4e 54 0a 2a 2a 20 74 68 65 6e 20 53  NSIENT.** then S
32130 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f  QLite makes a co
32140 70 79 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  py of the result
32150 20 69 6e 74 6f 20 73 70 61 63 65 20 6f 62 74 61   into space obta
32160 69 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 66 72 6f  ined from.** fro
32170 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  m [sqlite3_mallo
32180 63 28 29 5d 20 62 65 66 6f 72 65 20 69 74 20 72  c()] before it r
32190 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  eturns..**.** Th
321a0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
321b0 5f 76 61 6c 75 65 28 29 20 69 6e 74 65 72 66 61  _value() interfa
321c0 63 65 20 73 65 74 73 20 74 68 65 20 72 65 73 75  ce sets the resu
321d0 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70  lt of.** the app
321e0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
321f0 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
32200 61 20 63 6f 70 79 20 74 68 65 0a 2a 2a 20 5b 75  a copy the.** [u
32210 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
32220 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
32230 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68   specified by th
32240 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 2e  e 2nd parameter.
32250 20 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33    The.** sqlite3
32260 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20  _result_value() 
32270 69 6e 74 65 72 66 61 63 65 20 6d 61 6b 65 73 20  interface makes 
32280 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 5b 73  a copy of the [s
32290 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a  qlite3_value].**
322a0 20 73 6f 20 74 68 61 74 20 74 68 65 20 5b 73 71   so that the [sq
322b0 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 73 70 65  lite3_value] spe
322c0 63 69 66 69 65 64 20 69 6e 20 74 68 65 20 70 61  cified in the pa
322d0 72 61 6d 65 74 65 72 20 6d 61 79 20 63 68 61 6e  rameter may chan
322e0 67 65 20 6f 72 0a 2a 2a 20 62 65 20 64 65 61 6c  ge or.** be deal
322f0 6c 6f 63 61 74 65 64 20 61 66 74 65 72 20 73 71  located after sq
32300 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c  lite3_result_val
32310 75 65 28 29 20 72 65 74 75 72 6e 73 20 77 69 74  ue() returns wit
32320 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 41 20  hout harm..** A 
32330 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  [protected sqlit
32340 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
32350 20 6d 61 79 20 61 6c 77 61 79 73 20 62 65 20 75   may always be u
32360 73 65 64 20 77 68 65 72 65 20 61 6e 0a 2a 2a 20  sed where an.** 
32370 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c  [unprotected sql
32380 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
32390 63 74 20 69 73 20 72 65 71 75 69 72 65 64 2c 20  ct is required, 
323a0 73 6f 20 65 69 74 68 65 72 0a 2a 2a 20 6b 69 6e  so either.** kin
323b0 64 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 76 61  d of [sqlite3_va
323c0 6c 75 65 5d 20 6f 62 6a 65 63 74 20 63 61 6e 20  lue] object can 
323d0 62 65 20 75 73 65 64 20 77 69 74 68 20 74 68 69  be used with thi
323e0 73 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a  s interface..**.
323f0 2a 2a 20 49 66 20 74 68 65 73 65 20 72 6f 75 74  ** If these rout
32400 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20  ines are called 
32410 66 72 6f 6d 20 77 69 74 68 69 6e 20 74 68 65 20  from within the 
32420 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64  different thread
32430 0a 2a 2a 20 74 68 61 6e 20 74 68 65 20 6f 6e 65  .** than the one
32440 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20   containing the 
32450 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
32460 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 68 61  ned function tha
32470 74 20 72 65 63 65 69 76 65 64 0a 2a 2a 20 74 68  t received.** th
32480 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  e [sqlite3_conte
32490 78 74 5d 20 70 6f 69 6e 74 65 72 2c 20 74 68 65  xt] pointer, the
324a0 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64   results are und
324b0 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e  efined..**.** IN
324c0 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
324d0 7b 48 31 36 34 30 33 7d 20 54 68 65 20 64 65 66  {H16403} The def
324e0 61 75 6c 74 20 72 65 74 75 72 6e 20 76 61 6c 75  ault return valu
324f0 65 20 66 72 6f 6d 20 61 6e 79 20 53 51 4c 20 66  e from any SQL f
32500 75 6e 63 74 69 6f 6e 20 69 73 20 4e 55 4c 4c 2e  unction is NULL.
32510 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 30 36 7d 20  .**.** {H16406} 
32520 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  The [sqlite3_res
32530 75 6c 74 5f 62 6c 6f 62 28 43 2c 56 2c 4e 2c 44  ult_blob(C,V,N,D
32540 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68 61  )] interface cha
32550 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 20  nges the.**     
32560 20 20 20 20 20 72 65 74 75 72 6e 20 76 61 6c 75       return valu
32570 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 20  e of function C 
32580 74 6f 20 62 65 20 61 20 42 4c 4f 42 20 74 68 61  to be a BLOB tha
32590 74 20 69 73 20 4e 20 62 79 74 65 73 0a 2a 2a 20  t is N bytes.** 
325a0 20 20 20 20 20 20 20 20 20 69 6e 20 6c 65 6e 67           in leng
325b0 74 68 20 61 6e 64 20 77 69 74 68 20 63 6f 6e 74  th and with cont
325c0 65 6e 74 20 70 6f 69 6e 74 65 64 20 74 6f 20 62  ent pointed to b
325d0 79 20 56 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34  y V..**.** {H164
325e0 30 39 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  09} The [sqlite3
325f0 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28 43  _result_double(C
32600 2c 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63  ,V)] interface c
32610 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20 20  hanges the.**   
32620 20 20 20 20 20 20 20 72 65 74 75 72 6e 20 76 61         return va
32630 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20  lue of function 
32640 43 20 74 6f 20 62 65 20 74 68 65 20 66 6c 6f 61  C to be the floa
32650 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65  ting point value
32660 20 56 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 31   V..**.** {H1641
32670 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  2} The [sqlite3_
32680 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 43 2c 56  result_error(C,V
32690 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63  ,N)] interface c
326a0 68 61 6e 67 65 73 20 74 68 65 20 72 65 74 75 72  hanges the retur
326b0 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 76 61  n.**          va
326c0 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20  lue of function 
326d0 43 20 74 6f 20 62 65 20 61 6e 20 65 78 63 65 70  C to be an excep
326e0 74 69 6f 6e 20 77 69 74 68 20 65 72 72 6f 72 20  tion with error 
326f0 63 6f 64 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  code.**         
32700 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
32710 61 6e 64 20 61 20 55 54 46 2d 38 20 65 72 72 6f  and a UTF-8 erro
32720 72 20 6d 65 73 73 61 67 65 20 63 6f 70 69 65 64  r message copied
32730 20 66 72 6f 6d 20 56 20 75 70 20 74 6f 20 74 68   from V up to th
32740 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69  e.**          fi
32750 72 73 74 20 7a 65 72 6f 20 62 79 74 65 20 6f 72  rst zero byte or
32760 20 75 6e 74 69 6c 20 4e 20 62 79 74 65 73 20 61   until N bytes a
32770 72 65 20 72 65 61 64 20 69 66 20 4e 20 69 73 20  re read if N is 
32780 70 6f 73 69 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20  positive..**.** 
32790 7b 48 31 36 34 31 35 7d 20 54 68 65 20 5b 73 71  {H16415} The [sq
327a0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
327b0 6f 72 31 36 28 43 2c 56 2c 4e 29 5d 20 69 6e 74  or16(C,V,N)] int
327c0 65 72 66 61 63 65 20 63 68 61 6e 67 65 73 20 74  erface changes t
327d0 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20 20 20 20  he return.**    
327e0 20 20 20 20 20 20 76 61 6c 75 65 20 6f 66 20 66        value of f
327f0 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20  unction C to be 
32800 61 6e 20 65 78 63 65 70 74 69 6f 6e 20 77 69 74  an exception wit
32810 68 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20  h error code.** 
32820 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45           [SQLITE
32830 5f 45 52 52 4f 52 5d 20 61 6e 64 20 61 20 55 54  _ERROR] and a UT
32840 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74 65  F-16 native byte
32850 20 6f 72 64 65 72 20 65 72 72 6f 72 20 6d 65 73   order error mes
32860 73 61 67 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  sage.**         
32870 20 63 6f 70 69 65 64 20 66 72 6f 6d 20 56 20 75   copied from V u
32880 70 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 7a  p to the first z
32890 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 6f  ero terminator o
328a0 72 20 75 6e 74 69 6c 20 4e 20 62 79 74 65 73 0a  r until N bytes.
328b0 2a 2a 20 20 20 20 20 20 20 20 20 20 61 72 65 20  **          are 
328c0 72 65 61 64 20 69 66 20 4e 20 69 73 20 70 6f 73  read if N is pos
328d0 69 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  itive..**.** {H1
328e0 36 34 31 38 7d 20 54 68 65 20 5b 73 71 6c 69 74  6418} The [sqlit
328f0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f  e3_result_error_
32900 74 6f 6f 62 69 67 28 43 29 5d 20 69 6e 74 65 72  toobig(C)] inter
32910 66 61 63 65 20 63 68 61 6e 67 65 73 20 74 68 65  face changes the
32920 20 72 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20 20   return.**      
32930 20 20 20 20 76 61 6c 75 65 20 6f 66 20 74 68 65      value of the
32940 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62   function C to b
32950 65 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 20 77  e an exception w
32960 69 74 68 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a  ith error code.*
32970 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49  *          [SQLI
32980 54 45 5f 54 4f 4f 42 49 47 5d 20 61 6e 64 20 61  TE_TOOBIG] and a
32990 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20 65 72  n appropriate er
329a0 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a  ror message..**.
329b0 2a 2a 20 7b 48 31 36 34 32 31 7d 20 54 68 65 20  ** {H16421} The 
329c0 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
329d0 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28 43 29 5d 20  error_nomem(C)] 
329e0 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67 65  interface change
329f0 73 20 74 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20  s the return.** 
32a00 20 20 20 20 20 20 20 20 20 76 61 6c 75 65 20 6f           value o
32a10 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 43  f the function C
32a20 20 74 6f 20 62 65 20 61 6e 20 65 78 63 65 70 74   to be an except
32a30 69 6f 6e 20 77 69 74 68 20 65 72 72 6f 72 20 63  ion with error c
32a40 6f 64 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ode.**          
32a50 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20 61  [SQLITE_NOMEM] a
32a60 6e 64 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74  nd an appropriat
32a70 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e  e error message.
32a80 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 32 34 7d 20  .**.** {H16424} 
32a90 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  The [sqlite3_res
32aa0 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28 43  ult_error_code(C
32ab0 2c 45 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63  ,E)] interface c
32ac0 68 61 6e 67 65 73 20 74 68 65 20 72 65 74 75 72  hanges the retur
32ad0 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 76 61  n.**          va
32ae0 6c 75 65 20 6f 66 20 74 68 65 20 66 75 6e 63 74  lue of the funct
32af0 69 6f 6e 20 43 20 74 6f 20 62 65 20 61 6e 20 65  ion C to be an e
32b00 78 63 65 70 74 69 6f 6e 20 77 69 74 68 20 65 72  xception with er
32b10 72 6f 72 20 63 6f 64 65 20 45 2e 0a 2a 2a 20 20  ror code E..**  
32b20 20 20 20 20 20 20 20 20 54 68 65 20 65 72 72 6f          The erro
32b30 72 20 6d 65 73 73 61 67 65 20 74 65 78 74 20 69  r message text i
32b40 73 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 0a  s unchanged..**.
32b50 2a 2a 20 7b 48 31 36 34 32 37 7d 20 54 68 65 20  ** {H16427} The 
32b60 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
32b70 69 6e 74 28 43 2c 56 29 5d 20 69 6e 74 65 72 66  int(C,V)] interf
32b80 61 63 65 20 63 68 61 6e 67 65 73 20 74 68 65 0a  ace changes the.
32b90 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75  **          retu
32ba0 72 6e 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63  rn value of func
32bb0 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 74 68 65  tion C to be the
32bc0 20 33 32 2d 62 69 74 20 69 6e 74 65 67 65 72 20   32-bit integer 
32bd0 76 61 6c 75 65 20 56 2e 0a 2a 2a 0a 2a 2a 20 7b  value V..**.** {
32be0 48 31 36 34 33 30 7d 20 54 68 65 20 5b 73 71 6c  H16430} The [sql
32bf0 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36  ite3_result_int6
32c00 34 28 43 2c 56 29 5d 20 69 6e 74 65 72 66 61 63  4(C,V)] interfac
32c10 65 20 63 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a  e changes the.**
32c20 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e            return
32c30 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 69   value of functi
32c40 6f 6e 20 43 20 74 6f 20 62 65 20 74 68 65 20 36  on C to be the 6
32c50 34 2d 62 69 74 20 69 6e 74 65 67 65 72 20 76 61  4-bit integer va
32c60 6c 75 65 20 56 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  lue V..**.** {H1
32c70 36 34 33 33 7d 20 54 68 65 20 5b 73 71 6c 69 74  6433} The [sqlit
32c80 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 43  e3_result_null(C
32c90 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68 61  )] interface cha
32ca0 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 20  nges the.**     
32cb0 20 20 20 20 20 72 65 74 75 72 6e 20 76 61 6c 75       return valu
32cc0 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 20  e of function C 
32cd0 74 6f 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  to be NULL..**.*
32ce0 2a 20 7b 48 31 36 34 33 36 7d 20 54 68 65 20 5b  * {H16436} The [
32cf0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
32d00 65 78 74 28 43 2c 56 2c 4e 2c 44 29 5d 20 69 6e  ext(C,V,N,D)] in
32d10 74 65 72 66 61 63 65 20 63 68 61 6e 67 65 73 20  terface changes 
32d20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
32d30 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20  return value of 
32d40 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65  function C to be
32d50 20 74 68 65 20 55 54 46 2d 38 20 73 74 72 69 6e   the UTF-8 strin
32d60 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 56 20  g.**          V 
32d70 75 70 20 74 6f 20 74 68 65 20 66 69 72 73 74 20  up to the first 
32d80 7a 65 72 6f 20 69 66 20 4e 20 69 73 20 6e 65 67  zero if N is neg
32d90 61 74 69 76 65 0a 2a 2a 20 20 20 20 20 20 20 20  ative.**        
32da0 20 20 6f 72 20 74 68 65 20 66 69 72 73 74 20 4e    or the first N
32db0 20 62 79 74 65 73 20 6f 66 20 56 20 69 66 20 4e   bytes of V if N
32dc0 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65   is non-negative
32dd0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 33 39 7d  ..**.** {H16439}
32de0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65   The [sqlite3_re
32df0 73 75 6c 74 5f 74 65 78 74 31 36 28 43 2c 56 2c  sult_text16(C,V,
32e00 4e 2c 44 29 5d 20 69 6e 74 65 72 66 61 63 65 20  N,D)] interface 
32e10 63 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20  changes the.**  
32e20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 20 76          return v
32e30 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e  alue of function
32e40 20 43 20 74 6f 20 62 65 20 74 68 65 20 55 54 46   C to be the UTF
32e50 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74 65 20  -16 native byte 
32e60 6f 72 64 65 72 0a 2a 2a 20 20 20 20 20 20 20 20  order.**        
32e70 20 20 73 74 72 69 6e 67 20 56 20 75 70 20 74 6f    string V up to
32e80 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20   the first zero 
32e90 69 66 20 4e 20 69 73 20 6e 65 67 61 74 69 76 65  if N is negative
32ea0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20  .**          or 
32eb0 74 68 65 20 66 69 72 73 74 20 4e 20 62 79 74 65  the first N byte
32ec0 73 20 6f 66 20 56 20 69 66 20 4e 20 69 73 20 6e  s of V if N is n
32ed0 6f 6e 2d 6e 65 67 61 74 69 76 65 2e 0a 2a 2a 0a  on-negative..**.
32ee0 2a 2a 20 7b 48 31 36 34 34 32 7d 20 54 68 65 20  ** {H16442} The 
32ef0 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
32f00 74 65 78 74 31 36 62 65 28 43 2c 56 2c 4e 2c 44  text16be(C,V,N,D
32f10 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68 61  )] interface cha
32f20 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 20  nges the.**     
32f30 20 20 20 20 20 72 65 74 75 72 6e 20 76 61 6c 75       return valu
32f40 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 20  e of function C 
32f50 74 6f 20 62 65 20 74 68 65 20 55 54 46 2d 31 36  to be the UTF-16
32f60 20 62 69 67 2d 65 6e 64 69 61 6e 0a 2a 2a 20 20   big-endian.**  
32f70 20 20 20 20 20 20 20 20 73 74 72 69 6e 67 20 56          string V
32f80 20 75 70 20 74 6f 20 74 68 65 20 66 69 72 73 74   up to the first
32f90 20 7a 65 72 6f 20 69 66 20 4e 20 69 73 20 6e 65   zero if N is ne
32fa0 67 61 74 69 76 65 0a 2a 2a 20 20 20 20 20 20 20  gative.**       
32fb0 20 20 20 6f 72 20 74 68 65 20 66 69 72 73 74 20     or the first 
32fc0 4e 20 62 79 74 65 73 20 6f 72 20 56 20 69 66 20  N bytes or V if 
32fd0 4e 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76  N is non-negativ
32fe0 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 34 35  e..**.** {H16445
32ff0 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72  } The [sqlite3_r
33000 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 43  esult_text16le(C
33010 2c 56 2c 4e 2c 44 29 5d 20 69 6e 74 65 72 66 61  ,V,N,D)] interfa
33020 63 65 20 63 68 61 6e 67 65 73 20 74 68 65 0a 2a  ce changes the.*
33030 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72  *          retur
33040 6e 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 74  n value of funct
33050 69 6f 6e 20 43 20 74 6f 20 62 65 20 74 68 65 20  ion C to be the 
33060 55 54 46 2d 31 36 20 6c 69 74 74 6c 65 2d 65 6e  UTF-16 little-en
33070 64 69 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  dian.**         
33080 20 73 74 72 69 6e 67 20 56 20 75 70 20 74 6f 20   string V up to 
33090 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 69  the first zero i
330a0 66 20 4e 20 69 73 20 6e 65 67 61 74 69 76 65 0a  f N is negative.
330b0 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 74  **          or t
330c0 68 65 20 66 69 72 73 74 20 4e 20 62 79 74 65 73  he first N bytes
330d0 20 6f 66 20 56 20 69 66 20 4e 20 69 73 20 6e 6f   of V if N is no
330e0 6e 2d 6e 65 67 61 74 69 76 65 2e 0a 2a 2a 0a 2a  n-negative..**.*
330f0 2a 20 7b 48 31 36 34 34 38 7d 20 54 68 65 20 5b  * {H16448} The [
33100 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76  sqlite3_result_v
33110 61 6c 75 65 28 43 2c 56 29 5d 20 69 6e 74 65 72  alue(C,V)] inter
33120 66 61 63 65 20 63 68 61 6e 67 65 73 20 74 68 65  face changes the
33130 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74  .**          ret
33140 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 66 75 6e  urn value of fun
33150 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 74 68  ction C to be th
33160 65 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73  e [unprotected s
33170 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a  qlite3_value].**
33180 20 20 20 20 20 20 20 20 20 20 6f 62 6a 65 63 74            object
33190 20 56 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 35   V..**.** {H1645
331a0 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  1} The [sqlite3_
331b0 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28  result_zeroblob(
331c0 43 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20  C,N)] interface 
331d0 63 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20  changes the.**  
331e0 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 20 76          return v
331f0 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e  alue of function
33200 20 43 20 74 6f 20 62 65 20 61 6e 20 4e 2d 62 79   C to be an N-by
33210 74 65 20 42 4c 4f 42 20 6f 66 20 61 6c 6c 20 7a  te BLOB of all z
33220 65 72 6f 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36  eros..**.** {H16
33230 34 35 34 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  454} The [sqlite
33240 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29  3_result_error()
33250 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72  ] and [sqlite3_r
33260 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 5d  esult_error16()]
33270 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74  .**          int
33280 65 72 66 61 63 65 73 20 6d 61 6b 65 20 61 20 63  erfaces make a c
33290 6f 70 79 20 6f 66 20 74 68 65 69 72 20 65 72 72  opy of their err
332a0 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e  or message strin
332b0 67 73 20 62 65 66 6f 72 65 0a 2a 2a 20 20 20 20  gs before.**    
332c0 20 20 20 20 20 20 72 65 74 75 72 6e 69 6e 67 2e        returning.
332d0 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 35 37 7d 20  .**.** {H16457} 
332e0 49 66 20 74 68 65 20 44 20 64 65 73 74 72 75 63  If the D destruc
332f0 74 6f 72 20 70 61 72 61 6d 65 74 65 72 20 74 6f  tor parameter to
33300 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
33310 5f 62 6c 6f 62 28 43 2c 56 2c 4e 2c 44 29 5d 2c  _blob(C,V,N,D)],
33320 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
33330 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
33340 74 28 43 2c 56 2c 4e 2c 44 29 5d 2c 20 5b 73 71  t(C,V,N,D)], [sq
33350 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
33360 74 31 36 28 43 2c 56 2c 4e 2c 44 29 5d 2c 0a 2a  t16(C,V,N,D)],.*
33370 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
33380 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31  te3_result_text1
33390 36 62 65 28 43 2c 56 2c 4e 2c 44 29 5d 2c 20 6f  6be(C,V,N,D)], o
333a0 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  r.**          [s
333b0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
333c0 78 74 31 36 6c 65 28 43 2c 56 2c 4e 2c 44 29 5d  xt16le(C,V,N,D)]
333d0 20 69 73 20 74 68 65 20 63 6f 6e 73 74 61 6e 74   is the constant
333e0 20 5b 53 51 4c 49 54 45 5f 53 54 41 54 49 43 5d   [SQLITE_STATIC]
333f0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
33400 6e 20 6e 6f 20 64 65 73 74 72 75 63 74 6f 72 20  n no destructor 
33410 69 73 20 65 76 65 72 20 63 61 6c 6c 65 64 20 6f  is ever called o
33420 6e 20 74 68 65 20 70 6f 69 6e 74 65 72 20 56 20  n the pointer V 
33430 61 6e 64 20 53 51 4c 69 74 65 0a 2a 2a 20 20 20  and SQLite.**   
33440 20 20 20 20 20 20 20 61 73 73 75 6d 65 73 20 74         assumes t
33450 68 61 74 20 56 20 69 73 20 69 6d 6d 75 74 61 62  hat V is immutab
33460 6c 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 36  le..**.** {H1646
33470 30 7d 20 49 66 20 74 68 65 20 44 20 64 65 73 74  0} If the D dest
33480 72 75 63 74 6f 72 20 70 61 72 61 6d 65 74 65 72  ructor parameter
33490 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73   to [sqlite3_res
334a0 75 6c 74 5f 62 6c 6f 62 28 43 2c 56 2c 4e 2c 44  ult_blob(C,V,N,D
334b0 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  )],.**          
334c0 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
334d0 74 65 78 74 28 43 2c 56 2c 4e 2c 44 29 5d 2c 20  text(C,V,N,D)], 
334e0 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
334f0 74 65 78 74 31 36 28 43 2c 56 2c 4e 2c 44 29 5d  text16(C,V,N,D)]
33500 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  ,.**          [s
33510 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
33520 78 74 31 36 62 65 28 43 2c 56 2c 4e 2c 44 29 5d  xt16be(C,V,N,D)]
33530 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  , or.**         
33540 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
33550 5f 74 65 78 74 31 36 6c 65 28 43 2c 56 2c 4e 2c  _text16le(C,V,N,
33560 44 29 5d 20 69 73 20 74 68 65 20 63 6f 6e 73 74  D)] is the const
33570 61 6e 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ant.**          
33580 5b 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e  [SQLITE_TRANSIEN
33590 54 5d 20 74 68 65 6e 20 74 68 65 20 69 6e 74 65  T] then the inte
335a0 72 66 61 63 65 73 20 6d 61 6b 65 73 20 61 20 63  rfaces makes a c
335b0 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20  opy of the.**   
335c0 20 20 20 20 20 20 20 63 6f 6e 74 65 6e 74 20 6f         content o
335d0 66 20 56 20 61 6e 64 20 72 65 74 61 69 6e 73 20  f V and retains 
335e0 74 68 65 20 63 6f 70 79 2e 0a 2a 2a 0a 2a 2a 20  the copy..**.** 
335f0 7b 48 31 36 34 36 33 7d 20 49 66 20 74 68 65 20  {H16463} If the 
33600 44 20 64 65 73 74 72 75 63 74 6f 72 20 70 61 72  D destructor par
33610 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74  ameter to [sqlit
33620 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 43  e3_result_blob(C
33630 2c 56 2c 4e 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20  ,V,N,D)],.**    
33640 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 72        [sqlite3_r
33650 65 73 75 6c 74 5f 74 65 78 74 28 43 2c 56 2c 4e  esult_text(C,V,N
33660 2c 44 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 72  ,D)], [sqlite3_r
33670 65 73 75 6c 74 5f 74 65 78 74 31 36 28 43 2c 56  esult_text16(C,V
33680 2c 4e 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20  ,N,D)],.**      
33690 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73      [sqlite3_res
336a0 75 6c 74 5f 74 65 78 74 31 36 62 65 28 43 2c 56  ult_text16be(C,V
336b0 2c 4e 2c 44 29 5d 2c 20 6f 72 0a 2a 2a 20 20 20  ,N,D)], or.**   
336c0 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
336d0 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28  result_text16le(
336e0 43 2c 56 2c 4e 2c 44 29 5d 20 69 73 20 73 6f 6d  C,V,N,D)] is som
336f0 65 20 76 61 6c 75 65 20 6f 74 68 65 72 20 74 68  e value other th
33700 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  an.**          t
33710 68 65 20 63 6f 6e 73 74 61 6e 74 73 20 5b 53 51  he constants [SQ
33720 4c 49 54 45 5f 53 54 41 54 49 43 5d 20 61 6e 64  LITE_STATIC] and
33730 20 5b 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45   [SQLITE_TRANSIE
33740 4e 54 5d 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20  NT] then.**     
33750 20 20 20 20 20 53 51 4c 69 74 65 20 77 69 6c 6c       SQLite will
33760 20 69 6e 76 6f 6b 65 20 74 68 65 20 64 65 73 74   invoke the dest
33770 72 75 63 74 6f 72 20 44 20 77 69 74 68 20 56 20  ructor D with V 
33780 61 73 20 69 74 73 20 6f 6e 6c 79 20 61 72 67 75  as its only argu
33790 6d 65 6e 74 0a 2a 2a 20 20 20 20 20 20 20 20 20  ment.**         
337a0 20 77 68 65 6e 20 69 74 20 68 61 73 20 66 69 6e   when it has fin
337b0 69 73 68 65 64 20 77 69 74 68 20 74 68 65 20 56  ished with the V
337c0 20 76 61 6c 75 65 2e 0a 2a 2f 0a 76 6f 69 64 20   value..*/.void 
337d0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62  sqlite3_result_b
337e0 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  lob(sqlite3_cont
337f0 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64  ext*, const void
33800 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28  *, int, void(*)(
33810 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71  void*));.void sq
33820 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75  lite3_result_dou
33830 62 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ble(sqlite3_cont
33840 65 78 74 2a 2c 20 64 6f 75 62 6c 65 29 3b 0a 76  ext*, double);.v
33850 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
33860 6c 74 5f 65 72 72 6f 72 28 73 71 6c 69 74 65 33  lt_error(sqlite3
33870 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74  _context*, const
33880 20 63 68 61 72 2a 2c 20 69 6e 74 29 3b 0a 76 6f   char*, int);.vo
33890 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
338a0 74 5f 65 72 72 6f 72 31 36 28 73 71 6c 69 74 65  t_error16(sqlite
338b0 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73  3_context*, cons
338c0 74 20 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 76  t void*, int);.v
338d0 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
338e0 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f 62 69 67 28  lt_error_toobig(
338f0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
33900 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
33910 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f 6d  result_error_nom
33920 65 6d 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  em(sqlite3_conte
33930 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  xt*);.void sqlit
33940 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f  e3_result_error_
33950 63 6f 64 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e  code(sqlite3_con
33960 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69  text*, int);.voi
33970 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
33980 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e  _int(sqlite3_con
33990 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69  text*, int);.voi
339a0 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
339b0 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 63  _int64(sqlite3_c
339c0 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74 65 33  ontext*, sqlite3
339d0 5f 69 6e 74 36 34 29 3b 0a 76 6f 69 64 20 73 71  _int64);.void sq
339e0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c  lite3_result_nul
339f0 6c 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  l(sqlite3_contex
33a00 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  t*);.void sqlite
33a10 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 73 71  3_result_text(sq
33a20 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
33a30 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74  const char*, int
33a40 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  , void(*)(void*)
33a50 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
33a60 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28 73 71  result_text16(sq
33a70 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
33a80 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
33a90 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  , void(*)(void*)
33aa0 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
33ab0 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28  result_text16le(
33ac0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
33ad0 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
33ae0 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  nt,void(*)(void*
33af0 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  ));.void sqlite3
33b00 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65  _result_text16be
33b10 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
33b20 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  *, const void*, 
33b30 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64  int,void(*)(void
33b40 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  *));.void sqlite
33b50 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 73  3_result_value(s
33b60 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
33b70 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29   sqlite3_value*)
33b80 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
33b90 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 73  esult_zeroblob(s
33ba0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
33bb0 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20   int n);../*.** 
33bc0 43 41 50 49 33 52 45 46 3a 20 44 65 66 69 6e 65  CAPI3REF: Define
33bd0 20 4e 65 77 20 43 6f 6c 6c 61 74 69 6e 67 20 53   New Collating S
33be0 65 71 75 65 6e 63 65 73 20 7b 48 31 36 36 30 30  equences {H16600
33bf0 7d 20 3c 53 32 30 33 30 30 3e 0a 2a 2a 0a 2a 2a  } <S20300>.**.**
33c00 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   These functions
33c10 20 61 72 65 20 75 73 65 64 20 74 6f 20 61 64 64   are used to add
33c20 20 6e 65 77 20 63 6f 6c 6c 61 74 69 6f 6e 20 73   new collation s
33c30 65 71 75 65 6e 63 65 73 20 74 6f 20 74 68 65 0a  equences to the.
33c40 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
33c50 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 69  nection] specifi
33c60 65 64 20 61 73 20 74 68 65 20 66 69 72 73 74 20  ed as the first 
33c70 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  argument..**.** 
33c80 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  The name of the 
33c90 6e 65 77 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65  new collation se
33ca0 71 75 65 6e 63 65 20 69 73 20 73 70 65 63 69 66  quence is specif
33cb0 69 65 64 20 61 73 20 61 20 55 54 46 2d 38 20 73  ied as a UTF-8 s
33cc0 74 72 69 6e 67 0a 2a 2a 20 66 6f 72 20 73 71 6c  tring.** for sql
33cd0 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
33ce0 61 74 69 6f 6e 28 29 20 61 6e 64 20 73 71 6c 69  ation() and sqli
33cf0 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
33d00 74 69 6f 6e 5f 76 32 28 29 0a 2a 2a 20 61 6e 64  tion_v2().** and
33d10 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67   a UTF-16 string
33d20 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65   for sqlite3_cre
33d30 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28  ate_collation16(
33d40 29 2e 20 49 6e 20 61 6c 6c 20 63 61 73 65 73 0a  ). In all cases.
33d50 2a 2a 20 74 68 65 20 6e 61 6d 65 20 69 73 20 70  ** the name is p
33d60 61 73 73 65 64 20 61 73 20 74 68 65 20 73 65 63  assed as the sec
33d70 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61 72 67  ond function arg
33d80 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ument..**.** The
33d90 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20   third argument 
33da0 6d 61 79 20 62 65 20 6f 6e 65 20 6f 66 20 74 68  may be one of th
33db0 65 20 63 6f 6e 73 74 61 6e 74 73 20 5b 53 51 4c  e constants [SQL
33dc0 49 54 45 5f 55 54 46 38 5d 2c 0a 2a 2a 20 5b 53  ITE_UTF8],.** [S
33dd0 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 20 6f  QLITE_UTF16LE] o
33de0 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42  r [SQLITE_UTF16B
33df0 45 5d 2c 20 69 6e 64 69 63 61 74 69 6e 67 20 74  E], indicating t
33e00 68 61 74 20 74 68 65 20 75 73 65 72 2d 73 75 70  hat the user-sup
33e10 70 6c 69 65 64 0a 2a 2a 20 72 6f 75 74 69 6e 65  plied.** routine
33e20 20 65 78 70 65 63 74 73 20 74 6f 20 62 65 20 70   expects to be p
33e30 61 73 73 65 64 20 70 6f 69 6e 74 65 72 73 20 74  assed pointers t
33e40 6f 20 73 74 72 69 6e 67 73 20 65 6e 63 6f 64 65  o strings encode
33e50 64 20 75 73 69 6e 67 20 55 54 46 2d 38 2c 0a 2a  d using UTF-8,.*
33e60 2a 20 55 54 46 2d 31 36 20 6c 69 74 74 6c 65 2d  * UTF-16 little-
33e70 65 6e 64 69 61 6e 2c 20 6f 72 20 55 54 46 2d 31  endian, or UTF-1
33e80 36 20 62 69 67 2d 65 6e 64 69 61 6e 2c 20 72 65  6 big-endian, re
33e90 73 70 65 63 74 69 76 65 6c 79 2e 20 54 68 65 0a  spectively. The.
33ea0 2a 2a 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  ** third argumen
33eb0 74 20 6d 69 67 68 74 20 61 6c 73 6f 20 62 65 20  t might also be 
33ec0 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c  [SQLITE_UTF16_AL
33ed0 49 47 4e 45 44 5d 20 74 6f 20 69 6e 64 69 63 61  IGNED] to indica
33ee0 74 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 72  te that.** the r
33ef0 6f 75 74 69 6e 65 20 65 78 70 65 63 74 73 20 70  outine expects p
33f00 6f 69 6e 74 65 72 73 20 74 6f 20 31 36 2d 62 69  ointers to 16-bi
33f10 74 20 77 6f 72 64 20 61 6c 69 67 6e 65 64 20 73  t word aligned s
33f20 74 72 69 6e 67 73 0a 2a 2a 20 6f 66 20 55 54 46  trings.** of UTF
33f30 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76  -16 in the nativ
33f40 65 20 62 79 74 65 20 6f 72 64 65 72 20 6f 66 20  e byte order of 
33f50 74 68 65 20 68 6f 73 74 20 63 6f 6d 70 75 74 65  the host compute
33f60 72 2e 0a 2a 2a 0a 2a 2a 20 41 20 70 6f 69 6e 74  r..**.** A point
33f70 65 72 20 74 6f 20 74 68 65 20 75 73 65 72 20 73  er to the user s
33f80 75 70 70 6c 69 65 64 20 72 6f 75 74 69 6e 65 20  upplied routine 
33f90 6d 75 73 74 20 62 65 20 70 61 73 73 65 64 20 61  must be passed a
33fa0 73 20 74 68 65 20 66 69 66 74 68 0a 2a 2a 20 61  s the fifth.** a
33fb0 72 67 75 6d 65 6e 74 2e 20 20 49 66 20 69 74 20  rgument.  If it 
33fc0 69 73 20 4e 55 4c 4c 2c 20 74 68 69 73 20 69 73  is NULL, this is
33fd0 20 74 68 65 20 73 61 6d 65 20 61 73 20 64 65 6c   the same as del
33fe0 65 74 69 6e 67 20 74 68 65 20 63 6f 6c 6c 61 74  eting the collat
33ff0 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20  ion.** sequence 
34000 28 73 6f 20 74 68 61 74 20 53 51 4c 69 74 65 20  (so that SQLite 
34010 63 61 6e 6e 6f 74 20 63 61 6c 6c 20 69 74 20 61  cannot call it a
34020 6e 79 6d 6f 72 65 29 2e 0a 2a 2a 20 45 61 63 68  nymore)..** Each
34030 20 74 69 6d 65 20 74 68 65 20 61 70 70 6c 69 63   time the applic
34040 61 74 69 6f 6e 20 73 75 70 70 6c 69 65 64 20 66  ation supplied f
34050 75 6e 63 74 69 6f 6e 20 69 73 20 69 6e 76 6f 6b  unction is invok
34060 65 64 2c 20 69 74 20 69 73 20 70 61 73 73 65 64  ed, it is passed
34070 0a 2a 2a 20 61 73 20 69 74 73 20 66 69 72 73 74  .** as its first
34080 20 70 61 72 61 6d 65 74 65 72 20 61 20 63 6f 70   parameter a cop
34090 79 20 6f 66 20 74 68 65 20 76 6f 69 64 2a 20 70  y of the void* p
340a0 61 73 73 65 64 20 61 73 20 74 68 65 20 66 6f 75  assed as the fou
340b0 72 74 68 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  rth argument.** 
340c0 74 6f 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  to sqlite3_creat
340d0 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 20 6f 72  e_collation() or
340e0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
340f0 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 2e 0a 2a  collation16()..*
34100 2a 0a 2a 2a 20 54 68 65 20 72 65 6d 61 69 6e 69  *.** The remaini
34110 6e 67 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20  ng arguments to 
34120 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
34130 73 75 70 70 6c 69 65 64 20 72 6f 75 74 69 6e 65  supplied routine
34140 20 61 72 65 20 74 77 6f 20 73 74 72 69 6e 67 73   are two strings
34150 2c 0a 2a 2a 20 65 61 63 68 20 72 65 70 72 65 73  ,.** each repres
34160 65 6e 74 65 64 20 62 79 20 61 20 28 6c 65 6e 67  ented by a (leng
34170 74 68 2c 20 64 61 74 61 29 20 70 61 69 72 20 61  th, data) pair a
34180 6e 64 20 65 6e 63 6f 64 65 64 20 69 6e 20 74 68  nd encoded in th
34190 65 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20 74 68  e encoding.** th
341a0 61 74 20 77 61 73 20 70 61 73 73 65 64 20 61 73  at was passed as
341b0 20 74 68 65 20 74 68 69 72 64 20 61 72 67 75 6d   the third argum
341c0 65 6e 74 20 77 68 65 6e 20 74 68 65 20 63 6f 6c  ent when the col
341d0 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 20  lation sequence 
341e0 77 61 73 0a 2a 2a 20 72 65 67 69 73 74 65 72 65  was.** registere
341f0 64 2e 20 7b 45 4e 44 7d 20 20 54 68 65 20 61 70  d. {END}  The ap
34200 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65  plication define
34210 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 72 6f 75 74  d collation rout
34220 69 6e 65 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65  ine should.** re
34230 74 75 72 6e 20 6e 65 67 61 74 69 76 65 2c 20 7a  turn negative, z
34240 65 72 6f 20 6f 72 20 70 6f 73 69 74 69 76 65 20  ero or positive 
34250 69 66 20 74 68 65 20 66 69 72 73 74 20 73 74 72  if the first str
34260 69 6e 67 20 69 73 20 6c 65 73 73 20 74 68 61 6e  ing is less than
34270 2c 0a 2a 2a 20 65 71 75 61 6c 20 74 6f 2c 20 6f  ,.** equal to, o
34280 72 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 74  r greater than t
34290 68 65 20 73 65 63 6f 6e 64 20 73 74 72 69 6e 67  he second string
342a0 2e 20 69 2e 65 2e 20 28 53 54 52 49 4e 47 31 20  . i.e. (STRING1 
342b0 2d 20 53 54 52 49 4e 47 32 29 2e 0a 2a 2a 0a 2a  - STRING2)..**.*
342c0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 72  * The sqlite3_cr
342d0 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76  eate_collation_v
342e0 32 28 29 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73  2() works like s
342f0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
34300 6c 6c 61 74 69 6f 6e 28 29 0a 2a 2a 20 65 78 63  llation().** exc
34310 65 70 74 20 74 68 61 74 20 69 74 20 74 61 6b 65  ept that it take
34320 73 20 61 6e 20 65 78 74 72 61 20 61 72 67 75 6d  s an extra argum
34330 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 64  ent which is a d
34340 65 73 74 72 75 63 74 6f 72 20 66 6f 72 0a 2a 2a  estructor for.**
34350 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 2e 20   the collation. 
34360 20 54 68 65 20 64 65 73 74 72 75 63 74 6f 72 20   The destructor 
34370 69 73 20 63 61 6c 6c 65 64 20 77 68 65 6e 20 74  is called when t
34380 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 69 73 0a  he collation is.
34390 2a 2a 20 64 65 73 74 72 6f 79 65 64 20 61 6e 64  ** destroyed and
343a0 20 69 73 20 70 61 73 73 65 64 20 61 20 63 6f 70   is passed a cop
343b0 79 20 6f 66 20 74 68 65 20 66 6f 75 72 74 68 20  y of the fourth 
343c0 70 61 72 61 6d 65 74 65 72 20 76 6f 69 64 2a 20  parameter void* 
343d0 70 6f 69 6e 74 65 72 0a 2a 2a 20 6f 66 20 74 68  pointer.** of th
343e0 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  e sqlite3_create
343f0 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 2e  _collation_v2().
34400 0a 2a 2a 20 43 6f 6c 6c 61 74 69 6f 6e 73 20 61  .** Collations a
34410 72 65 20 64 65 73 74 72 6f 79 65 64 20 77 68 65  re destroyed whe
34420 6e 20 74 68 65 79 20 61 72 65 20 6f 76 65 72 72  n they are overr
34430 69 64 64 65 6e 20 62 79 20 6c 61 74 65 72 20 63  idden by later c
34440 61 6c 6c 73 20 74 6f 20 74 68 65 0a 2a 2a 20 63  alls to the.** c
34450 6f 6c 6c 61 74 69 6f 6e 20 63 72 65 61 74 69 6f  ollation creatio
34460 6e 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 77  n functions or w
34470 68 65 6e 20 74 68 65 20 5b 64 61 74 61 62 61 73  hen the [databas
34480 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73  e connection] is
34490 20 63 6c 6f 73 65 64 0a 2a 2a 20 75 73 69 6e 67   closed.** using
344a0 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28   [sqlite3_close(
344b0 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  )]..**.** INVARI
344c0 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 36  ANTS:.**.** {H16
344d0 36 30 33 7d 20 41 20 73 75 63 63 65 73 73 66 75  603} A successfu
344e0 6c 20 63 61 6c 6c 20 74 6f 20 74 68 65 0a 2a 2a  l call to the.**
344f0 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
34500 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
34510 69 6f 6e 5f 76 32 28 42 2c 58 2c 45 2c 50 2c 46  ion_v2(B,X,E,P,F
34520 2c 44 29 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a  ,D)] interface.*
34530 2a 20 20 20 20 20 20 20 20 20 20 72 65 67 69 73  *          regis
34540 74 65 72 73 20 66 75 6e 63 74 69 6f 6e 20 46 20  ters function F 
34550 61 73 20 74 68 65 20 63 6f 6d 70 61 72 69 73 6f  as the compariso
34560 6e 20 66 75 6e 63 74 69 6f 6e 20 75 73 65 64 20  n function used 
34570 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  to.**          i
34580 6d 70 6c 65 6d 65 6e 74 20 63 6f 6c 6c 61 74 69  mplement collati
34590 6f 6e 20 58 20 6f 6e 20 74 68 65 20 5b 64 61 74  on X on the [dat
345a0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
345b0 5d 20 42 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20  ] B for.**      
345c0 20 20 20 20 64 61 74 61 62 61 73 65 73 20 68 61      databases ha
345d0 76 69 6e 67 20 65 6e 63 6f 64 69 6e 67 20 45 2e  ving encoding E.
345e0 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 36 30 34 7d 20  .**.** {H16604} 
345f0 53 51 4c 69 74 65 20 75 6e 64 65 72 73 74 61 6e  SQLite understan
34600 64 73 20 74 68 65 20 58 20 70 61 72 61 6d 65 74  ds the X paramet
34610 65 72 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20  er to.**        
34620 20 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74    [sqlite3_creat
34630 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 42  e_collation_v2(B
34640 2c 58 2c 45 2c 50 2c 46 2c 44 29 5d 20 61 73 20  ,X,E,P,F,D)] as 
34650 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  a zero-terminate
34660 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 55 54  d.**          UT
34670 46 2d 38 20 73 74 72 69 6e 67 20 69 6e 20 77 68  F-8 string in wh
34680 69 63 68 20 63 61 73 65 20 69 73 20 69 67 6e 6f  ich case is igno
34690 72 65 64 20 66 6f 72 20 41 53 43 49 49 20 63 68  red for ASCII ch
346a0 61 72 61 63 74 65 72 73 20 61 6e 64 0a 2a 2a 20  aracters and.** 
346b0 20 20 20 20 20 20 20 20 20 69 73 20 73 69 67 6e           is sign
346c0 69 66 69 63 61 6e 74 20 66 6f 72 20 6e 6f 6e 2d  ificant for non-
346d0 41 53 43 49 49 20 63 68 61 72 61 63 74 65 72 73  ASCII characters
346e0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 36 30 36 7d  ..**.** {H16606}
346f0 20 53 75 63 63 65 73 73 69 76 65 20 63 61 6c 6c   Successive call
34700 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72  s to [sqlite3_cr
34710 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76  eate_collation_v
34720 32 28 42 2c 58 2c 45 2c 50 2c 46 2c 44 29 5d 0a  2(B,X,E,P,F,D)].
34730 2a 2a 20 20 20 20 20 20 20 20 20 20 77 69 74 68  **          with
34740 20 74 68 65 20 73 61 6d 65 20 76 61 6c 75 65 73   the same values
34750 20 66 6f 72 20 42 2c 20 58 2c 20 61 6e 64 20 45   for B, X, and E
34760 2c 20 6f 76 65 72 72 69 64 65 20 70 72 69 6f 72  , override prior
34770 20 76 61 6c 75 65 73 0a 2a 2a 20 20 20 20 20 20   values.**      
34780 20 20 20 20 6f 66 20 50 2c 20 46 2c 20 61 6e 64      of P, F, and
34790 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 36 30   D..**.** {H1660
347a0 39 7d 20 49 66 20 74 68 65 20 64 65 73 74 72 75  9} If the destru
347b0 63 74 6f 72 20 44 20 69 6e 20 5b 73 71 6c 69 74  ctor D in [sqlit
347c0 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
347d0 69 6f 6e 5f 76 32 28 42 2c 58 2c 45 2c 50 2c 46  ion_v2(B,X,E,P,F
347e0 2c 44 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  ,D)].**         
347f0 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65   is not NULL the
34800 6e 20 69 74 20 69 73 20 63 61 6c 6c 65 64 20 77  n it is called w
34810 69 74 68 20 61 72 67 75 6d 65 6e 74 20 50 20 77  ith argument P w
34820 68 65 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  hen the.**      
34830 20 20 20 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75      collating fu
34840 6e 63 74 69 6f 6e 20 69 73 20 64 72 6f 70 70 65  nction is droppe
34850 64 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a  d by SQLite..**.
34860 2a 2a 20 7b 48 31 36 36 31 32 7d 20 41 20 63 6f  ** {H16612} A co
34870 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e  llating function
34880 20 69 73 20 64 72 6f 70 70 65 64 20 77 68 65 6e   is dropped when
34890 20 69 74 20 69 73 20 6f 76 65 72 6c 6f 61 64 65   it is overloade
348a0 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 36 31 35  d..**.** {H16615
348b0 7d 20 41 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75  } A collating fu
348c0 6e 63 74 69 6f 6e 20 69 73 20 64 72 6f 70 70 65  nction is droppe
348d0 64 20 77 68 65 6e 20 74 68 65 20 64 61 74 61 62  d when the datab
348e0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase connection.*
348f0 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 63 6c  *          is cl
34900 6f 73 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69  osed using [sqli
34910 74 65 33 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2a  te3_close()]..**
34920 0a 2a 2a 20 7b 48 31 36 36 31 38 7d 20 54 68 65  .** {H16618} The
34930 20 70 6f 69 6e 74 65 72 20 50 20 69 6e 20 5b 73   pointer P in [s
34940 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
34950 6c 6c 61 74 69 6f 6e 5f 76 32 28 42 2c 58 2c 45  llation_v2(B,X,E
34960 2c 50 2c 46 2c 44 29 5d 0a 2a 2a 20 20 20 20 20  ,P,F,D)].**     
34970 20 20 20 20 20 69 73 20 70 61 73 73 65 64 20 74       is passed t
34980 68 72 6f 75 67 68 20 61 73 20 74 68 65 20 66 69  hrough as the fi
34990 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rst parameter to
349a0 20 74 68 65 20 63 6f 6d 70 61 72 69 73 6f 6e 0a   the comparison.
349b0 2a 2a 20 20 20 20 20 20 20 20 20 20 66 75 6e 63  **          func
349c0 74 69 6f 6e 20 46 20 66 6f 72 20 61 6c 6c 20 73  tion F for all s
349d0 75 62 73 65 71 75 65 6e 74 20 69 6e 76 6f 63 61  ubsequent invoca
349e0 74 69 6f 6e 73 20 6f 66 20 46 2e 0a 2a 2a 0a 2a  tions of F..**.*
349f0 2a 20 7b 48 31 36 36 32 31 7d 20 41 20 63 61 6c  * {H16621} A cal
34a00 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72  l to [sqlite3_cr
34a10 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 42  eate_collation(B
34a20 2c 58 2c 45 2c 50 2c 46 29 5d 20 69 73 20 65 78  ,X,E,P,F)] is ex
34a30 61 63 74 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20  actly.**        
34a40 20 20 74 68 65 20 73 61 6d 65 20 61 73 20 61 20    the same as a 
34a50 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
34a60 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
34a70 6e 5f 76 32 28 29 5d 20 77 69 74 68 0a 2a 2a 20  n_v2()] with.** 
34a80 20 20 20 20 20 20 20 20 20 74 68 65 20 73 61 6d           the sam
34a90 65 20 70 61 72 61 6d 65 74 65 72 73 20 61 6e 64  e parameters and
34aa0 20 61 20 4e 55 4c 4c 20 64 65 73 74 72 75 63 74   a NULL destruct
34ab0 6f 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 36 32  or..**.** {H1662
34ac0 34 7d 20 46 6f 6c 6c 6f 77 69 6e 67 20 61 20 5b  4} Following a [
34ad0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
34ae0 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 42 2c 58 2c  ollation_v2(B,X,
34af0 45 2c 50 2c 46 2c 44 29 5d 2c 0a 2a 2a 20 20 20  E,P,F,D)],.**   
34b00 20 20 20 20 20 20 20 53 51 4c 69 74 65 20 75 73         SQLite us
34b10 65 73 20 74 68 65 20 63 6f 6d 70 61 72 69 73 6f  es the compariso
34b20 6e 20 66 75 6e 63 74 69 6f 6e 20 46 20 66 6f 72  n function F for
34b30 20 61 6c 6c 20 74 65 78 74 20 63 6f 6d 70 61 72   all text compar
34b40 69 73 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  ison.**         
34b50 20 6f 70 65 72 61 74 69 6f 6e 73 20 6f 6e 20 74   operations on t
34b60 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
34b70 6e 65 63 74 69 6f 6e 5d 20 42 20 6f 6e 20 74 65  nection] B on te
34b80 78 74 20 76 61 6c 75 65 73 20 74 68 61 74 0a 2a  xt values that.*
34b90 2a 20 20 20 20 20 20 20 20 20 20 75 73 65 20 74  *          use t
34ba0 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 73 65 71  he collating seq
34bb0 75 65 6e 63 65 20 6e 61 6d 65 64 20 58 2e 0a 2a  uence named X..*
34bc0 2a 0a 2a 2a 20 7b 48 31 36 36 32 37 7d 20 54 68  *.** {H16627} Th
34bd0 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  e [sqlite3_creat
34be0 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 42 2c  e_collation16(B,
34bf0 58 2c 45 2c 50 2c 46 29 5d 20 77 6f 72 6b 73 20  X,E,P,F)] works 
34c00 74 68 65 20 73 61 6d 65 0a 2a 2a 20 20 20 20 20  the same.**     
34c10 20 20 20 20 20 61 73 20 5b 73 71 6c 69 74 65 33       as [sqlite3
34c20 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
34c30 6e 28 42 2c 58 2c 45 2c 50 2c 46 29 5d 20 65 78  n(B,X,E,P,F)] ex
34c40 63 65 70 74 20 74 68 61 74 20 74 68 65 0a 2a 2a  cept that the.**
34c50 20 20 20 20 20 20 20 20 20 20 63 6f 6c 6c 61 74            collat
34c60 69 6f 6e 20 6e 61 6d 65 20 58 20 69 73 20 75 6e  ion name X is un
34c70 64 65 72 73 74 6f 6f 64 20 61 73 20 55 54 46 2d  derstood as UTF-
34c80 31 36 20 69 6e 20 6e 61 74 69 76 65 20 62 79 74  16 in native byt
34c90 65 20 6f 72 64 65 72 0a 2a 2a 20 20 20 20 20 20  e order.**      
34ca0 20 20 20 20 69 6e 73 74 65 61 64 20 6f 66 20 55      instead of U
34cb0 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36  TF-8..**.** {H16
34cc0 36 33 30 7d 20 57 68 65 6e 20 6d 75 6c 74 69 70  630} When multip
34cd0 6c 65 20 63 6f 6d 70 61 72 69 73 6f 6e 20 66 75  le comparison fu
34ce0 6e 63 74 69 6f 6e 73 20 61 72 65 20 61 76 61 69  nctions are avai
34cf0 6c 61 62 6c 65 20 66 6f 72 20 74 68 65 20 73 61  lable for the sa
34d00 6d 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63  me.**          c
34d10 6f 6c 6c 61 74 69 6e 67 20 73 65 71 75 65 6e 63  ollating sequenc
34d20 65 2c 20 53 51 4c 69 74 65 20 63 68 6f 6f 73 65  e, SQLite choose
34d30 73 20 74 68 65 20 6f 6e 65 20 77 68 6f 73 65 20  s the one whose 
34d40 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a  text encoding.**
34d50 20 20 20 20 20 20 20 20 20 20 72 65 71 75 69 72            requir
34d60 65 73 20 74 68 65 20 6c 65 61 73 74 20 61 6d 6f  es the least amo
34d70 75 6e 74 20 6f 66 20 63 6f 6e 76 65 72 73 69 6f  unt of conversio
34d80 6e 20 66 72 6f 6d 20 74 68 65 20 64 65 66 61 75  n from the defau
34d90 6c 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  lt.**          t
34da0 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 6f 66 20  ext encoding of 
34db0 74 68 65 20 64 61 74 61 62 61 73 65 2e 0a 2a 2f  the database..*/
34dc0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65  .int sqlite3_cre
34dd0 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 0a 20  ate_collation(. 
34de0 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f   sqlite3*, .  co
34df0 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
34e00 20 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70   .  int eTextRep
34e10 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 69 6e  , .  void*,.  in
34e20 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69  t(*xCompare)(voi
34e30 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69  d*,int,const voi
34e40 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69  d*,int,const voi
34e50 64 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  d*).);.int sqlit
34e60 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
34e70 69 6f 6e 5f 76 32 28 0a 20 20 73 71 6c 69 74 65  ion_v2(.  sqlite
34e80 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68 61  3*, .  const cha
34e90 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74  r *zName, .  int
34ea0 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f   eTextRep, .  vo
34eb0 69 64 2a 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d  id*,.  int(*xCom
34ec0 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c  pare)(void*,int,
34ed0 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c  const void*,int,
34ee0 63 6f 6e 73 74 20 76 6f 69 64 2a 29 2c 0a 20 20  const void*),.  
34ef0 76 6f 69 64 28 2a 78 44 65 73 74 72 6f 79 29 28  void(*xDestroy)(
34f00 76 6f 69 64 2a 29 0a 29 3b 0a 69 6e 74 20 73 71  void*).);.int sq
34f10 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
34f20 6c 61 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69  lation16(.  sqli
34f30 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 76  te3*, .  const v
34f40 6f 69 64 20 2a 7a 4e 61 6d 65 2c 0a 20 20 69 6e  oid *zName,.  in
34f50 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76  t eTextRep, .  v
34f60 6f 69 64 2a 2c 0a 20 20 69 6e 74 28 2a 78 43 6f  oid*,.  int(*xCo
34f70 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74  mpare)(void*,int
34f80 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74  ,const void*,int
34f90 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b  ,const void*).);
34fa0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
34fb0 3a 20 43 6f 6c 6c 61 74 69 6f 6e 20 4e 65 65 64  : Collation Need
34fc0 65 64 20 43 61 6c 6c 62 61 63 6b 73 20 7b 48 31  ed Callbacks {H1
34fd0 36 37 30 30 7d 20 3c 53 32 30 33 30 30 3e 0a 2a  6700} <S20300>.*
34fe0 2a 0a 2a 2a 20 54 6f 20 61 76 6f 69 64 20 68 61  *.** To avoid ha
34ff0 76 69 6e 67 20 74 6f 20 72 65 67 69 73 74 65 72  ving to register
35000 20 61 6c 6c 20 63 6f 6c 6c 61 74 69 6f 6e 20 73   all collation s
35010 65 71 75 65 6e 63 65 73 20 62 65 66 6f 72 65 20  equences before 
35020 61 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 61  a database.** ca
35030 6e 20 62 65 20 75 73 65 64 2c 20 61 20 73 69 6e  n be used, a sin
35040 67 6c 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  gle callback fun
35050 63 74 69 6f 6e 20 6d 61 79 20 62 65 20 72 65 67  ction may be reg
35060 69 73 74 65 72 65 64 20 77 69 74 68 20 74 68 65  istered with the
35070 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
35080 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 62 65 20  nnection] to be 
35090 63 61 6c 6c 65 64 20 77 68 65 6e 65 76 65 72 20  called whenever 
350a0 61 6e 20 75 6e 64 65 66 69 6e 65 64 20 63 6f 6c  an undefined col
350b0 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e  lation.** sequen
350c0 63 65 20 69 73 20 72 65 71 75 69 72 65 64 2e 0a  ce is required..
350d0 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 66 75 6e  **.** If the fun
350e0 63 74 69 6f 6e 20 69 73 20 72 65 67 69 73 74 65  ction is registe
350f0 72 65 64 20 75 73 69 6e 67 20 74 68 65 20 73 71  red using the sq
35100 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  lite3_collation_
35110 6e 65 65 64 65 64 28 29 20 41 50 49 2c 0a 2a 2a  needed() API,.**
35120 20 74 68 65 6e 20 69 74 20 69 73 20 70 61 73 73   then it is pass
35130 65 64 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20  ed the names of 
35140 75 6e 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74  undefined collat
35150 69 6f 6e 20 73 65 71 75 65 6e 63 65 73 20 61 73  ion sequences as
35160 20 73 74 72 69 6e 67 73 0a 2a 2a 20 65 6e 63 6f   strings.** enco
35170 64 65 64 20 69 6e 20 55 54 46 2d 38 2e 20 7b 48  ded in UTF-8. {H
35180 31 36 37 30 33 7d 20 49 66 20 73 71 6c 69 74 65  16703} If sqlite
35190 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64  3_collation_need
351a0 65 64 31 36 28 29 20 69 73 20 75 73 65 64 2c 0a  ed16() is used,.
351b0 2a 2a 20 74 68 65 20 6e 61 6d 65 73 20 61 72 65  ** the names are
351c0 20 70 61 73 73 65 64 20 61 73 20 55 54 46 2d 31   passed as UTF-1
351d0 36 20 69 6e 20 6d 61 63 68 69 6e 65 20 6e 61 74  6 in machine nat
351e0 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a  ive byte order..
351f0 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 65 69 74  ** A call to eit
35200 68 65 72 20 66 75 6e 63 74 69 6f 6e 20 72 65 70  her function rep
35210 6c 61 63 65 73 20 61 6e 79 20 65 78 69 73 74 69  laces any existi
35220 6e 67 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a  ng callback..**.
35230 2a 2a 20 57 68 65 6e 20 74 68 65 20 63 61 6c 6c  ** When the call
35240 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2c  back is invoked,
35250 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
35260 65 6e 74 20 70 61 73 73 65 64 20 69 73 20 61 20  ent passed is a 
35270 63 6f 70 79 0a 2a 2a 20 6f 66 20 74 68 65 20 73  copy.** of the s
35280 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74  econd argument t
35290 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74  o sqlite3_collat
352a0 69 6f 6e 5f 6e 65 65 64 65 64 28 29 20 6f 72 0a  ion_needed() or.
352b0 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61  ** sqlite3_colla
352c0 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 2e  tion_needed16().
352d0 20 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67    The second arg
352e0 75 6d 65 6e 74 20 69 73 20 74 68 65 20 64 61 74  ument is the dat
352f0 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74  abase.** connect
35300 69 6f 6e 2e 20 20 54 68 65 20 74 68 69 72 64 20  ion.  The third 
35310 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20  argument is one 
35320 6f 66 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d  of [SQLITE_UTF8]
35330 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42  , [SQLITE_UTF16B
35340 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54  E],.** or [SQLIT
35350 45 5f 55 54 46 31 36 4c 45 5d 2c 20 69 6e 64 69  E_UTF16LE], indi
35360 63 61 74 69 6e 67 20 74 68 65 20 6d 6f 73 74 20  cating the most 
35370 64 65 73 69 72 61 62 6c 65 20 66 6f 72 6d 20 6f  desirable form o
35380 66 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 0a  f the collation.
35390 2a 2a 20 73 65 71 75 65 6e 63 65 20 66 75 6e 63  ** sequence func
353a0 74 69 6f 6e 20 72 65 71 75 69 72 65 64 2e 20 20  tion required.  
353b0 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  The fourth param
353c0 65 74 65 72 20 69 73 20 74 68 65 20 6e 61 6d 65  eter is the name
353d0 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65 71 75 69   of the.** requi
353e0 72 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65  red collation se
353f0 71 75 65 6e 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  quence..**.** Th
35400 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  e callback funct
35410 69 6f 6e 20 73 68 6f 75 6c 64 20 72 65 67 69 73  ion should regis
35420 74 65 72 20 74 68 65 20 64 65 73 69 72 65 64 20  ter the desired 
35430 63 6f 6c 6c 61 74 69 6f 6e 20 75 73 69 6e 67 0a  collation using.
35440 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  ** [sqlite3_crea
35450 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 5d 2c  te_collation()],
35460 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
35470 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 5d 2c  _collation16()],
35480 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
35490 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
354a0 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e  _v2()]..**.** IN
354b0 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
354c0 7b 48 31 36 37 30 32 7d 20 41 20 73 75 63 63 65  {H16702} A succe
354d0 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73  ssful call to [s
354e0 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e  qlite3_collation
354f0 5f 6e 65 65 64 65 64 28 44 2c 50 2c 46 29 5d 0a  _needed(D,P,F)].
35500 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 5b  **          or [
35510 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f  sqlite3_collatio
35520 6e 5f 6e 65 65 64 65 64 31 36 28 44 2c 50 2c 46  n_needed16(D,P,F
35530 29 5d 20 63 61 75 73 65 73 0a 2a 2a 20 20 20 20  )] causes.**    
35540 20 20 20 20 20 20 74 68 65 20 5b 64 61 74 61 62        the [datab
35550 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
35560 44 20 74 6f 20 69 6e 76 6f 6b 65 20 63 61 6c 6c  D to invoke call
35570 62 61 63 6b 20 46 20 77 69 74 68 20 66 69 72 73  back F with firs
35580 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70 61  t.**          pa
35590 72 61 6d 65 74 65 72 20 50 20 77 68 65 6e 65 76  rameter P whenev
355a0 65 72 20 69 74 20 6e 65 65 64 73 20 61 20 63 6f  er it needs a co
355b0 6d 70 61 72 69 73 6f 6e 20 66 75 6e 63 74 69 6f  mparison functio
355c0 6e 20 66 6f 72 20 61 0a 2a 2a 20 20 20 20 20 20  n for a.**      
355d0 20 20 20 20 63 6f 6c 6c 61 74 69 6e 67 20 73 65      collating se
355e0 71 75 65 6e 63 65 20 74 68 61 74 20 69 74 20 64  quence that it d
355f0 6f 65 73 20 6e 6f 74 20 6b 6e 6f 77 20 61 62 6f  oes not know abo
35600 75 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 37 30  ut..**.** {H1670
35610 34 7d 20 45 61 63 68 20 73 75 63 63 65 73 73 66  4} Each successf
35620 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  ul call to [sqli
35630 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65  te3_collation_ne
35640 65 64 65 64 28 29 5d 20 6f 72 0a 2a 2a 20 20 20  eded()] or.**   
35650 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
35660 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64  collation_needed
35670 31 36 28 29 5d 20 6f 76 65 72 72 69 64 65 73 20  16()] overrides 
35680 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 67  the callback reg
35690 69 73 74 65 72 65 64 0a 2a 2a 20 20 20 20 20 20  istered.**      
356a0 20 20 20 20 6f 6e 20 74 68 65 20 73 61 6d 65 20      on the same 
356b0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
356c0 74 69 6f 6e 5d 20 62 79 20 70 72 69 6f 72 20 63  tion] by prior c
356d0 61 6c 6c 73 20 74 6f 20 65 69 74 68 65 72 0a 2a  alls to either.*
356e0 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74 65 72  *          inter
356f0 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36  face..**.** {H16
35700 37 30 36 7d 20 54 68 65 20 6e 61 6d 65 20 6f 66  706} The name of
35710 20 74 68 65 20 72 65 71 75 65 73 74 65 64 20 63   the requested c
35720 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f  ollating functio
35730 6e 20 70 61 73 73 65 64 20 69 6e 20 74 68 65 0a  n passed in the.
35740 2a 2a 20 20 20 20 20 20 20 20 20 20 34 74 68 20  **          4th 
35750 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
35760 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 20   callback is in 
35770 55 54 46 2d 38 20 69 66 20 74 68 65 20 63 61 6c  UTF-8 if the cal
35780 6c 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 20 20  lback.**        
35790 20 20 77 61 73 20 72 65 67 69 73 74 65 72 65 64    was registered
357a0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
357b0 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64  collation_needed
357c0 28 29 5d 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20  ()] and.**      
357d0 20 20 20 20 69 73 20 69 6e 20 55 54 46 2d 31 36      is in UTF-16
357e0 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
357f0 65 72 20 69 66 20 74 68 65 20 63 61 6c 6c 62 61  er if the callba
35800 63 6b 20 77 61 73 0a 2a 2a 20 20 20 20 20 20 20  ck was.**       
35810 20 20 20 72 65 67 69 73 74 65 72 65 64 20 75 73     registered us
35820 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  ing [sqlite3_col
35830 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28  lation_needed16(
35840 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  )]..*/.int sqlit
35850 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65  e3_collation_nee
35860 64 65 64 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c  ded(.  sqlite3*,
35870 20 0a 20 20 76 6f 69 64 2a 2c 20 0a 20 20 76 6f   .  void*, .  vo
35880 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69  id(*)(void*,sqli
35890 74 65 33 2a 2c 69 6e 74 20 65 54 65 78 74 52 65  te3*,int eTextRe
358a0 70 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 0a 29  p,const char*).)
358b0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  ;.int sqlite3_co
358c0 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36  llation_needed16
358d0 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20  (.  sqlite3*, . 
358e0 20 76 6f 69 64 2a 2c 0a 20 20 76 6f 69 64 28 2a   void*,.  void(*
358f0 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a  )(void*,sqlite3*
35900 2c 69 6e 74 20 65 54 65 78 74 52 65 70 2c 63 6f  ,int eTextRep,co
35910 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f  nst void*).);../
35920 2a 0a 2a 2a 20 53 70 65 63 69 66 79 20 74 68 65  *.** Specify the
35930 20 6b 65 79 20 66 6f 72 20 61 6e 20 65 6e 63 72   key for an encr
35940 79 70 74 65 64 20 64 61 74 61 62 61 73 65 2e 20  ypted database. 
35950 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73 68   This routine sh
35960 6f 75 6c 64 20 62 65 0a 2a 2a 20 63 61 6c 6c 65  ould be.** calle
35970 64 20 72 69 67 68 74 20 61 66 74 65 72 20 73 71  d right after sq
35980 6c 69 74 65 33 5f 6f 70 65 6e 28 29 2e 0a 2a 2a  lite3_open()..**
35990 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 74 6f 20  .** The code to 
359a0 69 6d 70 6c 65 6d 65 6e 74 20 74 68 69 73 20 41  implement this A
359b0 50 49 20 69 73 20 6e 6f 74 20 61 76 61 69 6c 61  PI is not availa
359c0 62 6c 65 20 69 6e 20 74 68 65 20 70 75 62 6c 69  ble in the publi
359d0 63 20 72 65 6c 65 61 73 65 0a 2a 2a 20 6f 66 20  c release.** of 
359e0 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73  SQLite..*/.int s
359f0 71 6c 69 74 65 33 5f 6b 65 79 28 0a 20 20 73 71  qlite3_key(.  sq
35a00 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
35a10 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
35a20 44 61 74 61 62 61 73 65 20 74 6f 20 62 65 20 72  Database to be r
35a30 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73  ekeyed */.  cons
35a40 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e  t void *pKey, in
35a50 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54 68  t nKey     /* Th
35a60 65 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a  e key */.);../*.
35a70 2a 2a 20 43 68 61 6e 67 65 20 74 68 65 20 6b 65  ** Change the ke
35a80 79 20 6f 6e 20 61 6e 20 6f 70 65 6e 20 64 61 74  y on an open dat
35a90 61 62 61 73 65 2e 20 20 49 66 20 74 68 65 20 63  abase.  If the c
35aa0 75 72 72 65 6e 74 20 64 61 74 61 62 61 73 65 20  urrent database 
35ab0 69 73 20 6e 6f 74 0a 2a 2a 20 65 6e 63 72 79 70  is not.** encryp
35ac0 74 65 64 2c 20 74 68 69 73 20 72 6f 75 74 69 6e  ted, this routin
35ad0 65 20 77 69 6c 6c 20 65 6e 63 72 79 70 74 20 69  e will encrypt i
35ae0 74 2e 20 20 49 66 20 70 4e 65 77 3d 3d 30 20 6f  t.  If pNew==0 o
35af0 72 20 6e 4e 65 77 3d 3d 30 2c 20 74 68 65 0a 2a  r nNew==0, the.*
35b00 2a 20 64 61 74 61 62 61 73 65 20 69 73 20 64 65  * database is de
35b10 63 72 79 70 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  crypted..**.** T
35b20 68 65 20 63 6f 64 65 20 74 6f 20 69 6d 70 6c 65  he code to imple
35b30 6d 65 6e 74 20 74 68 69 73 20 41 50 49 20 69 73  ment this API is
35b40 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c 65 20 69   not available i
35b50 6e 20 74 68 65 20 70 75 62 6c 69 63 20 72 65 6c  n the public rel
35b60 65 61 73 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 74  ease.** of SQLit
35b70 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  e..*/.int sqlite
35b80 33 5f 72 65 6b 65 79 28 0a 20 20 73 71 6c 69 74  3_rekey(.  sqlit
35b90 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
35ba0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74            /* Dat
35bb0 61 62 61 73 65 20 74 6f 20 62 65 20 72 65 6b 65  abase to be reke
35bc0 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76  yed */.  const v
35bd0 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e  oid *pKey, int n
35be0 4b 65 79 20 20 20 20 20 2f 2a 20 54 68 65 20 6e  Key     /* The n
35bf0 65 77 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a  ew key */.);../*
35c00 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 75  .** CAPI3REF: Su
35c10 73 70 65 6e 64 20 45 78 65 63 75 74 69 6f 6e 20  spend Execution 
35c20 46 6f 72 20 41 20 53 68 6f 72 74 20 54 69 6d 65  For A Short Time
35c30 20 7b 48 31 30 35 33 30 7d 20 3c 53 34 30 34 31   {H10530} <S4041
35c40 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  0>.**.** The sql
35c50 69 74 65 33 5f 73 6c 65 65 70 28 29 20 66 75 6e  ite3_sleep() fun
35c60 63 74 69 6f 6e 20 63 61 75 73 65 73 20 74 68 65  ction causes the
35c70 20 63 75 72 72 65 6e 74 20 74 68 72 65 61 64 20   current thread 
35c80 74 6f 20 73 75 73 70 65 6e 64 20 65 78 65 63 75  to suspend execu
35c90 74 69 6f 6e 0a 2a 2a 20 66 6f 72 20 61 74 20 6c  tion.** for at l
35ca0 65 61 73 74 20 61 20 6e 75 6d 62 65 72 20 6f 66  east a number of
35cb0 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 73 70   milliseconds sp
35cc0 65 63 69 66 69 65 64 20 69 6e 20 69 74 73 20 70  ecified in its p
35cd0 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  arameter..**.** 
35ce0 49 66 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67  If the operating
35cf0 20 73 79 73 74 65 6d 20 64 6f 65 73 20 6e 6f 74   system does not
35d00 20 73 75 70 70 6f 72 74 20 73 6c 65 65 70 20 72   support sleep r
35d10 65 71 75 65 73 74 73 20 77 69 74 68 0a 2a 2a 20  equests with.** 
35d20 6d 69 6c 6c 69 73 65 63 6f 6e 64 20 74 69 6d 65  millisecond time
35d30 20 72 65 73 6f 6c 75 74 69 6f 6e 2c 20 74 68 65   resolution, the
35d40 6e 20 74 68 65 20 74 69 6d 65 20 77 69 6c 6c 20  n the time will 
35d50 62 65 20 72 6f 75 6e 64 65 64 20 75 70 20 74 6f  be rounded up to
35d60 0a 2a 2a 20 74 68 65 20 6e 65 61 72 65 73 74 20  .** the nearest 
35d70 73 65 63 6f 6e 64 2e 20 54 68 65 20 6e 75 6d 62  second. The numb
35d80 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e  er of millisecon
35d90 64 73 20 6f 66 20 73 6c 65 65 70 20 61 63 74 75  ds of sleep actu
35da0 61 6c 6c 79 0a 2a 2a 20 72 65 71 75 65 73 74 65  ally.** requeste
35db0 64 20 66 72 6f 6d 20 74 68 65 20 6f 70 65 72 61  d from the opera
35dc0 74 69 6e 67 20 73 79 73 74 65 6d 20 69 73 20 72  ting system is r
35dd0 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 53  eturned..**.** S
35de0 51 4c 69 74 65 20 69 6d 70 6c 65 6d 65 6e 74 73  QLite implements
35df0 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   this interface 
35e00 62 79 20 63 61 6c 6c 69 6e 67 20 74 68 65 20 78  by calling the x
35e10 53 6c 65 65 70 28 29 0a 2a 2a 20 6d 65 74 68 6f  Sleep().** metho
35e20 64 20 6f 66 20 74 68 65 20 64 65 66 61 75 6c 74  d of the default
35e30 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f   [sqlite3_vfs] o
35e40 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56  bject..**.** INV
35e50 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
35e60 48 31 30 35 33 33 7d 20 54 68 65 20 5b 73 71 6c  H10533} The [sql
35e70 69 74 65 33 5f 73 6c 65 65 70 28 4d 29 5d 20 69  ite3_sleep(M)] i
35e80 6e 74 65 72 66 61 63 65 20 69 6e 76 6f 6b 65 73  nterface invokes
35e90 20 74 68 65 20 78 53 6c 65 65 70 0a 2a 2a 20 20   the xSleep.**  
35ea0 20 20 20 20 20 20 20 20 6d 65 74 68 6f 64 20 6f          method o
35eb0 66 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73  f the default [s
35ec0 71 6c 69 74 65 33 5f 76 66 73 7c 56 46 53 5d 20  qlite3_vfs|VFS] 
35ed0 69 6e 20 6f 72 64 65 72 20 74 6f 0a 2a 2a 20 20  in order to.**  
35ee0 20 20 20 20 20 20 20 20 73 75 73 70 65 6e 64 20          suspend 
35ef0 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 74 68 65  execution of the
35f00 20 63 75 72 72 65 6e 74 20 74 68 72 65 61 64 20   current thread 
35f10 66 6f 72 20 61 74 20 6c 65 61 73 74 0a 2a 2a 20  for at least.** 
35f20 20 20 20 20 20 20 20 20 20 4d 20 6d 69 6c 6c 69           M milli
35f30 73 65 63 6f 6e 64 73 2e 0a 2a 2a 0a 2a 2a 20 7b  seconds..**.** {
35f40 48 31 30 35 33 36 7d 20 54 68 65 20 5b 73 71 6c  H10536} The [sql
35f50 69 74 65 33 5f 73 6c 65 65 70 28 4d 29 5d 20 69  ite3_sleep(M)] i
35f60 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
35f70 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a   the number of.*
35f80 2a 20 20 20 20 20 20 20 20 20 20 6d 69 6c 6c 69  *          milli
35f90 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70  seconds of sleep
35fa0 20 61 63 74 75 61 6c 6c 79 20 72 65 71 75 65 73   actually reques
35fb0 74 65 64 20 6f 66 20 74 68 65 20 6f 70 65 72 61  ted of the opera
35fc0 74 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20  ting.**         
35fd0 20 73 79 73 74 65 6d 2c 20 77 68 69 63 68 20 6d   system, which m
35fe0 69 67 68 74 20 62 65 20 6c 61 72 67 65 72 20 74  ight be larger t
35ff0 68 61 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65  han the paramete
36000 72 20 4d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  r M..*/.int sqli
36010 74 65 33 5f 73 6c 65 65 70 28 69 6e 74 29 3b 0a  te3_sleep(int);.
36020 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
36030 20 4e 61 6d 65 20 4f 66 20 54 68 65 20 46 6f 6c   Name Of The Fol
36040 64 65 72 20 48 6f 6c 64 69 6e 67 20 54 65 6d 70  der Holding Temp
36050 6f 72 61 72 79 20 46 69 6c 65 73 20 7b 48 31 30  orary Files {H10
36060 33 31 30 7d 20 3c 53 32 30 30 30 30 3e 0a 2a 2a  310} <S20000>.**
36070 0a 2a 2a 20 49 66 20 74 68 69 73 20 67 6c 6f 62  .** If this glob
36080 61 6c 20 76 61 72 69 61 62 6c 65 20 69 73 20 6d  al variable is m
36090 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20  ade to point to 
360a0 61 20 73 74 72 69 6e 67 20 77 68 69 63 68 20 69  a string which i
360b0 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66  s.** the name of
360c0 20 61 20 66 6f 6c 64 65 72 20 28 61 2e 6b 2e 61   a folder (a.k.a
360d0 2e 20 64 69 72 65 63 74 6f 72 79 29 2c 20 74 68  . directory), th
360e0 65 6e 20 61 6c 6c 20 74 65 6d 70 6f 72 61 72 79  en all temporary
360f0 20 66 69 6c 65 73 0a 2a 2a 20 63 72 65 61 74 65   files.** create
36100 64 20 62 79 20 53 51 4c 69 74 65 20 77 69 6c 6c  d by SQLite will
36110 20 62 65 20 70 6c 61 63 65 64 20 69 6e 20 74 68   be placed in th
36120 61 74 20 64 69 72 65 63 74 6f 72 79 2e 20 20 49  at directory.  I
36130 66 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 0a  f this variable.
36140 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  ** is a NULL poi
36150 6e 74 65 72 2c 20 74 68 65 6e 20 53 51 4c 69 74  nter, then SQLit
36160 65 20 70 65 72 66 6f 72 6d 73 20 61 20 73 65 61  e performs a sea
36170 72 63 68 20 66 6f 72 20 61 6e 20 61 70 70 72 6f  rch for an appro
36180 70 72 69 61 74 65 0a 2a 2a 20 74 65 6d 70 6f 72  priate.** tempor
36190 61 72 79 20 66 69 6c 65 20 64 69 72 65 63 74 6f  ary file directo
361a0 72 79 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73 20  ry..**.** It is 
361b0 6e 6f 74 20 73 61 66 65 20 74 6f 20 6d 6f 64 69  not safe to modi
361c0 66 79 20 74 68 69 73 20 76 61 72 69 61 62 6c 65  fy this variable
361d0 20 6f 6e 63 65 20 61 20 5b 64 61 74 61 62 61 73   once a [databas
361e0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a  e connection].**
361f0 20 68 61 73 20 62 65 65 6e 20 6f 70 65 6e 65 64   has been opened
36200 2e 20 20 49 74 20 69 73 20 69 6e 74 65 6e 64 65  .  It is intende
36210 64 20 74 68 61 74 20 74 68 69 73 20 76 61 72 69  d that this vari
36220 61 62 6c 65 20 62 65 20 73 65 74 20 6f 6e 63 65  able be set once
36230 0a 2a 2a 20 61 73 20 70 61 72 74 20 6f 66 20 70  .** as part of p
36240 72 6f 63 65 73 73 20 69 6e 69 74 69 61 6c 69 7a  rocess initializ
36250 61 74 69 6f 6e 20 61 6e 64 20 62 65 66 6f 72 65  ation and before
36260 20 61 6e 79 20 53 51 4c 69 74 65 20 69 6e 74 65   any SQLite inte
36270 72 66 61 63 65 0a 2a 2a 20 72 6f 75 74 69 6e 65  rface.** routine
36280 73 20 68 61 76 65 20 62 65 65 6e 20 63 61 6c 6c  s have been call
36290 20 61 6e 64 20 72 65 6d 61 69 6e 20 75 6e 63 68   and remain unch
362a0 61 6e 67 65 64 20 74 68 65 72 65 61 66 74 65 72  anged thereafter
362b0 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 54 45  ..*/.SQLITE_EXTE
362c0 52 4e 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  RN char *sqlite3
362d0 5f 74 65 6d 70 5f 64 69 72 65 63 74 6f 72 79 3b  _temp_directory;
362e0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
362f0 3a 20 54 65 73 74 20 46 6f 72 20 41 75 74 6f 2d  : Test For Auto-
36300 43 6f 6d 6d 69 74 20 4d 6f 64 65 20 7b 48 31 32  Commit Mode {H12
36310 39 33 30 7d 20 3c 53 36 30 32 30 30 3e 0a 2a 2a  930} <S60200>.**
36320 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 75 74 6f   KEYWORDS: {auto
36330 63 6f 6d 6d 69 74 20 6d 6f 64 65 7d 0a 2a 2a 0a  commit mode}.**.
36340 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67  ** The sqlite3_g
36350 65 74 5f 61 75 74 6f 63 6f 6d 6d 69 74 28 29 20  et_autocommit() 
36360 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
36370 73 20 6e 6f 6e 2d 7a 65 72 6f 20 6f 72 0a 2a 2a  s non-zero or.**
36380 20 7a 65 72 6f 20 69 66 20 74 68 65 20 67 69 76   zero if the giv
36390 65 6e 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  en database conn
363a0 65 63 74 69 6f 6e 20 69 73 20 6f 72 20 69 73 20  ection is or is 
363b0 6e 6f 74 20 69 6e 20 61 75 74 6f 63 6f 6d 6d 69  not in autocommi
363c0 74 20 6d 6f 64 65 2c 0a 2a 2a 20 72 65 73 70 65  t mode,.** respe
363d0 63 74 69 76 65 6c 79 2e 20 20 41 75 74 6f 63 6f  ctively.  Autoco
363e0 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 6f 6e 20  mmit mode is on 
363f0 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 20 41  by default..** A
36400 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69  utocommit mode i
36410 73 20 64 69 73 61 62 6c 65 64 20 62 79 20 61 20  s disabled by a 
36420 5b 42 45 47 49 4e 5d 20 73 74 61 74 65 6d 65 6e  [BEGIN] statemen
36430 74 2e 0a 2a 2a 20 41 75 74 6f 63 6f 6d 6d 69 74  t..** Autocommit
36440 20 6d 6f 64 65 20 69 73 20 72 65 2d 65 6e 61 62   mode is re-enab
36450 6c 65 64 20 62 79 20 61 20 5b 43 4f 4d 4d 49 54  led by a [COMMIT
36460 5d 20 6f 72 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2e  ] or [ROLLBACK].
36470 0a 2a 2a 0a 2a 2a 20 49 66 20 63 65 72 74 61 69  .**.** If certai
36480 6e 20 6b 69 6e 64 73 20 6f 66 20 65 72 72 6f 72  n kinds of error
36490 73 20 6f 63 63 75 72 20 6f 6e 20 61 20 73 74 61  s occur on a sta
364a0 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 61 20  tement within a 
364b0 6d 75 6c 74 69 2d 73 74 61 74 65 6d 65 6e 74 0a  multi-statement.
364c0 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 28  ** transaction (
364d0 65 72 72 6f 72 73 20 69 6e 63 6c 75 64 69 6e 67  errors including
364e0 20 5b 53 51 4c 49 54 45 5f 46 55 4c 4c 5d 2c 20   [SQLITE_FULL], 
364f0 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d 2c 0a  [SQLITE_IOERR],.
36500 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d  ** [SQLITE_NOMEM
36510 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  ], [SQLITE_BUSY]
36520 2c 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 49 4e  , and [SQLITE_IN
36530 54 45 52 52 55 50 54 5d 29 20 74 68 65 6e 20 74  TERRUPT]) then t
36540 68 65 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f  he.** transactio
36550 6e 20 6d 69 67 68 74 20 62 65 20 72 6f 6c 6c 65  n might be rolle
36560 64 20 62 61 63 6b 20 61 75 74 6f 6d 61 74 69 63  d back automatic
36570 61 6c 6c 79 2e 20 20 54 68 65 20 6f 6e 6c 79 20  ally.  The only 
36580 77 61 79 20 74 6f 0a 2a 2a 20 66 69 6e 64 20 6f  way to.** find o
36590 75 74 20 77 68 65 74 68 65 72 20 53 51 4c 69 74  ut whether SQLit
365a0 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  e automatically 
365b0 72 6f 6c 6c 65 64 20 62 61 63 6b 20 74 68 65 20  rolled back the 
365c0 74 72 61 6e 73 61 63 74 69 6f 6e 20 61 66 74 65  transaction afte
365d0 72 0a 2a 2a 20 61 6e 20 65 72 72 6f 72 20 69 73  r.** an error is
365e0 20 74 6f 20 75 73 65 20 74 68 69 73 20 66 75 6e   to use this fun
365f0 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56  ction..**.** INV
36600 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
36610 48 31 32 39 33 31 7d 20 54 68 65 20 5b 73 71 6c  H12931} The [sql
36620 69 74 65 33 5f 67 65 74 5f 61 75 74 6f 63 6f 6d  ite3_get_autocom
36630 6d 69 74 28 44 29 5d 20 69 6e 74 65 72 66 61 63  mit(D)] interfac
36640 65 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65  e returns non-ze
36650 72 6f 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20  ro or.**        
36660 20 20 7a 65 72 6f 20 69 66 20 74 68 65 20 5b 64    zero if the [d
36670 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
36680 6f 6e 5d 20 44 20 69 73 20 6f 72 20 69 73 20 6e  on] D is or is n
36690 6f 74 20 69 6e 20 61 75 74 6f 63 6f 6d 6d 69 74  ot in autocommit
366a0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 6f 64  .**          mod
366b0 65 2c 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e  e, respectively.
366c0 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 33 32 7d 20  .**.** {H12932} 
366d0 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20  Autocommit mode 
366e0 69 73 20 6f 6e 20 62 79 20 64 65 66 61 75 6c 74  is on by default
366f0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 33 33 7d  ..**.** {H12933}
36700 20 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65   Autocommit mode
36710 20 69 73 20 64 69 73 61 62 6c 65 64 20 62 79 20   is disabled by 
36720 61 20 73 75 63 63 65 73 73 66 75 6c 20 5b 42 45  a successful [BE
36730 47 49 4e 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a  GIN] statement..
36740 2a 2a 0a 2a 2a 20 7b 48 31 32 39 33 34 7d 20 41  **.** {H12934} A
36750 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69  utocommit mode i
36760 73 20 65 6e 61 62 6c 65 64 20 62 79 20 61 20 73  s enabled by a s
36770 75 63 63 65 73 73 66 75 6c 20 5b 43 4f 4d 4d 49  uccessful [COMMI
36780 54 5d 20 6f 72 20 5b 52 4f 4c 4c 42 41 43 4b 5d  T] or [ROLLBACK]
36790 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 74 61  .**          sta
367a0 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 41 53  tement..**.** AS
367b0 53 55 4d 50 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a  SUMPTIONS:.**.**
367c0 20 7b 41 31 32 39 33 36 7d 20 49 66 20 61 6e 6f   {A12936} If ano
367d0 74 68 65 72 20 74 68 72 65 61 64 20 63 68 61 6e  ther thread chan
367e0 67 65 73 20 74 68 65 20 61 75 74 6f 63 6f 6d 6d  ges the autocomm
367f0 69 74 20 73 74 61 74 75 73 20 6f 66 20 74 68 65  it status of the
36800 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 20 20 20   database.**    
36810 20 20 20 20 20 20 63 6f 6e 6e 65 63 74 69 6f 6e        connection
36820 20 77 68 69 6c 65 20 74 68 69 73 20 72 6f 75 74   while this rout
36830 69 6e 65 20 69 73 20 72 75 6e 6e 69 6e 67 2c 20  ine is running, 
36840 74 68 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20  then the return 
36850 76 61 6c 75 65 0a 2a 2a 20 20 20 20 20 20 20 20  value.**        
36860 20 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a    is undefined..
36870 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 67  */.int sqlite3_g
36880 65 74 5f 61 75 74 6f 63 6f 6d 6d 69 74 28 73 71  et_autocommit(sq
36890 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  lite3*);../*.** 
368a0 43 41 50 49 33 52 45 46 3a 20 46 69 6e 64 20 54  CAPI3REF: Find T
368b0 68 65 20 44 61 74 61 62 61 73 65 20 48 61 6e 64  he Database Hand
368c0 6c 65 20 4f 66 20 41 20 50 72 65 70 61 72 65 64  le Of A Prepared
368d0 20 53 74 61 74 65 6d 65 6e 74 20 7b 48 31 33 31   Statement {H131
368e0 32 30 7d 20 3c 53 36 30 36 30 30 3e 0a 2a 2a 0a  20} <S60600>.**.
368f0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 64  ** The sqlite3_d
36900 62 5f 68 61 6e 64 6c 65 20 69 6e 74 65 72 66 61  b_handle interfa
36910 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 5b  ce returns the [
36920 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
36930 69 6f 6e 5d 20 68 61 6e 64 6c 65 0a 2a 2a 20 74  ion] handle.** t
36940 6f 20 77 68 69 63 68 20 61 20 5b 70 72 65 70 61  o which a [prepa
36950 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 62  red statement] b
36960 65 6c 6f 6e 67 73 2e 20 20 54 68 65 20 64 61 74  elongs.  The dat
36970 61 62 61 73 65 20 68 61 6e 64 6c 65 20 72 65 74  abase handle ret
36980 75 72 6e 65 64 20 62 79 0a 2a 2a 20 73 71 6c 69  urned by.** sqli
36990 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65 20 69 73  te3_db_handle is
369a0 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61   the same databa
369b0 73 65 20 68 61 6e 64 6c 65 20 74 68 61 74 20 77  se handle that w
369c0 61 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67  as the first arg
369d0 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 74 68 65 20  ument.** to the 
369e0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
369f0 5f 76 32 28 29 5d 20 63 61 6c 6c 20 28 6f 72 20  _v2()] call (or 
36a00 69 74 73 20 76 61 72 69 61 6e 74 73 29 20 74 68  its variants) th
36a10 61 74 20 77 61 73 20 75 73 65 64 20 74 6f 0a 2a  at was used to.*
36a20 2a 20 63 72 65 61 74 65 20 74 68 65 20 73 74 61  * create the sta
36a30 74 65 6d 65 6e 74 20 69 6e 20 74 68 65 20 66 69  tement in the fi
36a40 72 73 74 20 70 6c 61 63 65 2e 0a 2a 2a 0a 2a 2a  rst place..**.**
36a50 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
36a60 2a 2a 20 7b 48 31 33 31 32 33 7d 20 54 68 65 20  ** {H13123} The 
36a70 5b 73 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64  [sqlite3_db_hand
36a80 6c 65 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65  le(S)] interface
36a90 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
36aa0 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  er.**          t
36ab0 6f 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  o the [database 
36ac0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 73 73 6f  connection] asso
36ad0 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 0a  ciated with the.
36ae0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 65  **          [pre
36af0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
36b00 20 53 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 20 2a   S..*/.sqlite3 *
36b10 73 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c  sqlite3_db_handl
36b20 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29  e(sqlite3_stmt*)
36b30 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
36b40 46 3a 20 46 69 6e 64 20 74 68 65 20 6e 65 78 74  F: Find the next
36b50 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
36b60 65 6e 74 20 7b 48 31 33 31 34 30 7d 20 3c 53 36  ent {H13140} <S6
36b70 30 36 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  0600>.**.** This
36b80 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
36b90 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
36ba0 74 68 65 20 6e 65 78 74 20 5b 70 72 65 70 61 72  the next [prepar
36bb0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 66  ed statement] af
36bc0 74 65 72 0a 2a 2a 20 70 53 74 6d 74 20 61 73 73  ter.** pStmt ass
36bd0 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65  ociated with the
36be0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
36bf0 63 74 69 6f 6e 5d 20 70 44 62 2e 20 20 49 66 20  ction] pDb.  If 
36c00 70 53 74 6d 74 20 69 73 20 4e 55 4c 4c 0a 2a 2a  pStmt is NULL.**
36c10 20 74 68 65 6e 20 74 68 69 73 20 69 6e 74 65 72   then this inter
36c20 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70  face returns a p
36c30 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 66 69  ointer to the fi
36c40 72 73 74 20 70 72 65 70 61 72 65 64 20 73 74 61  rst prepared sta
36c50 74 65 6d 65 6e 74 0a 2a 2a 20 61 73 73 6f 63 69  tement.** associ
36c60 61 74 65 64 20 77 69 74 68 20 74 68 65 20 64 61  ated with the da
36c70 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
36c80 6e 20 70 44 62 2e 20 20 49 66 20 6e 6f 20 70 72  n pDb.  If no pr
36c90 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
36ca0 0a 2a 2a 20 73 61 74 69 73 66 69 65 73 20 74 68  .** satisfies th
36cb0 65 20 63 6f 6e 64 69 74 69 6f 6e 73 20 6f 66 20  e conditions of 
36cc0 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 69 74  this routine, it
36cd0 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 2e 0a 2a   returns NULL..*
36ce0 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
36cf0 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 31 34 33 7d 20  .**.** {H13143} 
36d00 49 66 20 44 20 69 73 20 61 20 5b 64 61 74 61 62  If D is a [datab
36d10 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
36d20 74 68 61 74 20 68 6f 6c 64 73 20 6f 6e 65 20 6f  that holds one o
36d30 72 20 6d 6f 72 65 0a 2a 2a 20 20 20 20 20 20 20  r more.**       
36d40 20 20 20 75 6e 66 69 6e 61 6c 69 7a 65 64 20 5b     unfinalized [
36d50 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
36d60 6e 74 73 5d 20 61 6e 64 20 53 20 69 73 20 61 20  nts] and S is a 
36d70 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 0a 2a 2a  NULL pointer,.**
36d80 20 20 20 20 20 20 20 20 20 20 74 68 65 6e 20 5b            then [
36d90 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d  sqlite3_next_stm
36da0 74 28 44 2c 20 53 29 5d 20 72 6f 75 74 69 6e 65  t(D, S)] routine
36db0 20 73 68 61 6c 6c 20 72 65 74 75 72 6e 20 61 20   shall return a 
36dc0 70 6f 69 6e 74 65 72 0a 2a 2a 20 20 20 20 20 20  pointer.**      
36dd0 20 20 20 20 74 6f 20 6f 6e 65 20 6f 66 20 74 68      to one of th
36de0 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  e prepared state
36df0 6d 65 6e 74 73 20 61 73 73 6f 63 69 61 74 65 64  ments associated
36e00 20 77 69 74 68 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b   with D..**.** {
36e10 48 31 33 31 34 36 7d 20 49 66 20 44 20 69 73 20  H13146} If D is 
36e20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  a [database conn
36e30 65 63 74 69 6f 6e 5d 20 74 68 61 74 20 68 6f 6c  ection] that hol
36e40 64 73 20 6e 6f 20 75 6e 66 69 6e 61 6c 69 7a 65  ds no unfinalize
36e50 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70  d.**          [p
36e60 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
36e70 74 73 5d 20 61 6e 64 20 53 20 69 73 20 61 20 4e  ts] and S is a N
36e80 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65  ULL pointer, the
36e90 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  n.**          [s
36ea0 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74  qlite3_next_stmt
36eb0 28 44 2c 20 53 29 5d 20 72 6f 75 74 69 6e 65 20  (D, S)] routine 
36ec0 73 68 61 6c 6c 20 72 65 74 75 72 6e 20 61 20 4e  shall return a N
36ed0 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a  ULL pointer..**.
36ee0 2a 2a 20 7b 48 31 33 31 34 39 7d 20 49 66 20 53  ** {H13149} If S
36ef0 20 69 73 20 61 20 5b 70 72 65 70 61 72 65 64 20   is a [prepared 
36f00 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 74 68  statement] in th
36f10 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
36f20 65 63 74 69 6f 6e 5d 20 44 0a 2a 2a 20 20 20 20  ection] D.**    
36f30 20 20 20 20 20 20 61 6e 64 20 53 20 69 73 20 6e        and S is n
36f40 6f 74 20 74 68 65 20 6c 61 73 74 20 70 72 65 70  ot the last prep
36f50 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 69  ared statement i
36f60 6e 20 44 2c 20 74 68 65 6e 0a 2a 2a 20 20 20 20  n D, then.**    
36f70 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 6e        [sqlite3_n
36f80 65 78 74 5f 73 74 6d 74 28 44 2c 20 53 29 5d 20  ext_stmt(D, S)] 
36f90 72 6f 75 74 69 6e 65 20 73 68 61 6c 6c 20 72 65  routine shall re
36fa0 74 75 72 6e 20 61 20 70 6f 69 6e 74 65 72 0a 2a  turn a pointer.*
36fb0 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20 74 68  *          to th
36fc0 65 20 6e 65 78 74 20 70 72 65 70 61 72 65 64 20  e next prepared 
36fd0 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 44 20 61  statement in D a
36fe0 66 74 65 72 20 53 2e 0a 2a 2a 0a 2a 2a 20 7b 48  fter S..**.** {H
36ff0 31 33 31 35 32 7d 20 49 66 20 53 20 69 73 20 74  13152} If S is t
37000 68 65 20 6c 61 73 74 20 5b 70 72 65 70 61 72 65  he last [prepare
37010 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20  d statement] in 
37020 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
37030 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
37040 74 69 6f 6e 5d 20 44 20 74 68 65 6e 20 74 68 65  tion] D then the
37050 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73   [sqlite3_next_s
37060 74 6d 74 28 44 2c 20 53 29 5d 0a 2a 2a 20 20 20  tmt(D, S)].**   
37070 20 20 20 20 20 20 20 72 6f 75 74 69 6e 65 20 73         routine s
37080 68 61 6c 6c 20 72 65 74 75 72 6e 20 61 20 4e 55  hall return a NU
37090 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a  LL pointer..**.*
370a0 2a 20 41 53 53 55 4d 50 54 49 4f 4e 53 3a 0a 2a  * ASSUMPTIONS:.*
370b0 2a 0a 2a 2a 20 7b 41 31 33 31 35 34 7d 20 54 68  *.** {A13154} Th
370c0 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
370d0 65 63 74 69 6f 6e 5d 20 70 6f 69 6e 74 65 72 20  ection] pointer 
370e0 44 20 69 6e 20 61 20 63 61 6c 6c 20 74 6f 0a 2a  D in a call to.*
370f0 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
37100 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 44 2c  te3_next_stmt(D,
37110 53 29 5d 20 6d 75 73 74 20 72 65 66 65 72 20 74  S)] must refer t
37120 6f 20 61 6e 20 6f 70 65 6e 20 64 61 74 61 62 61  o an open databa
37130 73 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63  se.**          c
37140 6f 6e 6e 65 63 74 69 6f 6e 20 61 6e 64 20 69 6e  onnection and in
37150 20 70 61 72 74 69 63 75 6c 61 72 20 6d 75 73 74   particular must
37160 20 6e 6f 74 20 62 65 20 61 20 4e 55 4c 4c 20 70   not be a NULL p
37170 6f 69 6e 74 65 72 2e 0a 2a 2f 0a 73 71 6c 69 74  ointer..*/.sqlit
37180 65 33 5f 73 74 6d 74 20 2a 73 71 6c 69 74 65 33  e3_stmt *sqlite3
37190 5f 6e 65 78 74 5f 73 74 6d 74 28 73 71 6c 69 74  _next_stmt(sqlit
371a0 65 33 20 2a 70 44 62 2c 20 73 71 6c 69 74 65 33  e3 *pDb, sqlite3
371b0 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a  _stmt *pStmt);..
371c0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
371d0 43 6f 6d 6d 69 74 20 41 6e 64 20 52 6f 6c 6c 62  Commit And Rollb
371e0 61 63 6b 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e  ack Notification
371f0 20 43 61 6c 6c 62 61 63 6b 73 20 7b 48 31 32 39   Callbacks {H129
37200 35 30 7d 20 3c 53 36 30 34 30 30 3e 0a 2a 2a 0a  50} <S60400>.**.
37210 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63  ** The sqlite3_c
37220 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 20 69 6e 74  ommit_hook() int
37230 65 72 66 61 63 65 20 72 65 67 69 73 74 65 72 73  erface registers
37240 20 61 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66   a callback.** f
37250 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 69 6e  unction to be in
37260 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61  voked whenever a
37270 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20   transaction is 
37280 63 6f 6d 6d 69 74 74 65 64 2e 0a 2a 2a 20 41 6e  committed..** An
37290 79 20 63 61 6c 6c 62 61 63 6b 20 73 65 74 20 62  y callback set b
372a0 79 20 61 20 70 72 65 76 69 6f 75 73 20 63 61 6c  y a previous cal
372b0 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6d  l to sqlite3_com
372c0 6d 69 74 5f 68 6f 6f 6b 28 29 0a 2a 2a 20 66 6f  mit_hook().** fo
372d0 72 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62  r the same datab
372e0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
372f0 73 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a  s overridden..**
37300 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 6f 6c   The sqlite3_rol
37310 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29 20 69 6e 74  lback_hook() int
37320 65 72 66 61 63 65 20 72 65 67 69 73 74 65 72 73  erface registers
37330 20 61 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66   a callback.** f
37340 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 69 6e  unction to be in
37350 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61  voked whenever a
37360 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20   transaction is 
37370 63 6f 6d 6d 69 74 74 65 64 2e 0a 2a 2a 20 41 6e  committed..** An
37380 79 20 63 61 6c 6c 62 61 63 6b 20 73 65 74 20 62  y callback set b
37390 79 20 61 20 70 72 65 76 69 6f 75 73 20 63 61 6c  y a previous cal
373a0 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6d  l to sqlite3_com
373b0 6d 69 74 5f 68 6f 6f 6b 28 29 0a 2a 2a 20 66 6f  mit_hook().** fo
373c0 72 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62  r the same datab
373d0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
373e0 73 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a  s overridden..**
373f0 20 54 68 65 20 70 41 72 67 20 61 72 67 75 6d 65   The pArg argume
37400 6e 74 20 69 73 20 70 61 73 73 65 64 20 74 68 72  nt is passed thr
37410 6f 75 67 68 20 74 6f 20 74 68 65 20 63 61 6c 6c  ough to the call
37420 62 61 63 6b 2e 0a 2a 2a 20 49 66 20 74 68 65 20  back..** If the 
37430 63 61 6c 6c 62 61 63 6b 20 6f 6e 20 61 20 63 6f  callback on a co
37440 6d 6d 69 74 20 68 6f 6f 6b 20 66 75 6e 63 74 69  mmit hook functi
37450 6f 6e 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a  on returns non-z
37460 65 72 6f 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ero,.** then the
37470 20 63 6f 6d 6d 69 74 20 69 73 20 63 6f 6e 76 65   commit is conve
37480 72 74 65 64 20 69 6e 74 6f 20 61 20 72 6f 6c 6c  rted into a roll
37490 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61  back..**.** If a
374a0 6e 6f 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 20  nother function 
374b0 77 61 73 20 70 72 65 76 69 6f 75 73 6c 79 20 72  was previously r
374c0 65 67 69 73 74 65 72 65 64 2c 20 69 74 73 0a 2a  egistered, its.*
374d0 2a 20 70 41 72 67 20 76 61 6c 75 65 20 69 73 20  * pArg value is 
374e0 72 65 74 75 72 6e 65 64 2e 20 20 4f 74 68 65 72  returned.  Other
374f0 77 69 73 65 20 4e 55 4c 4c 20 69 73 20 72 65 74  wise NULL is ret
37500 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 67  urned..**.** Reg
37510 69 73 74 65 72 69 6e 67 20 61 20 4e 55 4c 4c 20  istering a NULL 
37520 66 75 6e 63 74 69 6f 6e 20 64 69 73 61 62 6c 65  function disable
37530 73 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e 0a  s the callback..
37540 2a 2a 0a 2a 2a 20 46 6f 72 20 74 68 65 20 70 75  **.** For the pu
37550 72 70 6f 73 65 73 20 6f 66 20 74 68 69 73 20 41  rposes of this A
37560 50 49 2c 20 61 20 74 72 61 6e 73 61 63 74 69 6f  PI, a transactio
37570 6e 20 69 73 20 73 61 69 64 20 74 6f 20 68 61 76  n is said to hav
37580 65 20 62 65 65 6e 0a 2a 2a 20 72 6f 6c 6c 65 64  e been.** rolled
37590 20 62 61 63 6b 20 69 66 20 61 6e 20 65 78 70 6c   back if an expl
375a0 69 63 69 74 20 22 52 4f 4c 4c 42 41 43 4b 22 20  icit "ROLLBACK" 
375b0 73 74 61 74 65 6d 65 6e 74 20 69 73 20 65 78 65  statement is exe
375c0 63 75 74 65 64 2c 20 6f 72 0a 2a 2a 20 61 6e 20  cuted, or.** an 
375d0 65 72 72 6f 72 20 6f 72 20 63 6f 6e 73 74 72 61  error or constra
375e0 69 6e 74 20 63 61 75 73 65 73 20 61 6e 20 69 6d  int causes an im
375f0 70 6c 69 63 69 74 20 72 6f 6c 6c 62 61 63 6b 20  plicit rollback 
37600 74 6f 20 6f 63 63 75 72 2e 0a 2a 2a 20 54 68 65  to occur..** The
37610 20 72 6f 6c 6c 62 61 63 6b 20 63 61 6c 6c 62 61   rollback callba
37620 63 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65  ck is not invoke
37630 64 20 69 66 20 61 20 74 72 61 6e 73 61 63 74 69  d if a transacti
37640 6f 6e 20 69 73 0a 2a 2a 20 61 75 74 6f 6d 61 74  on is.** automat
37650 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61  ically rolled ba
37660 63 6b 20 62 65 63 61 75 73 65 20 74 68 65 20 64  ck because the d
37670 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
37680 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a  on is closed..**
37690 20 54 68 65 20 72 6f 6c 6c 62 61 63 6b 20 63 61   The rollback ca
376a0 6c 6c 62 61 63 6b 20 69 73 20 6e 6f 74 20 69 6e  llback is not in
376b0 76 6f 6b 65 64 20 69 66 20 61 20 74 72 61 6e 73  voked if a trans
376c0 61 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 72 6f 6c  action is.** rol
376d0 6c 65 64 20 62 61 63 6b 20 62 65 63 61 75 73 65  led back because
376e0 20 61 20 63 6f 6d 6d 69 74 20 63 61 6c 6c 62 61   a commit callba
376f0 63 6b 20 72 65 74 75 72 6e 65 64 20 6e 6f 6e 2d  ck returned non-
37700 7a 65 72 6f 2e 0a 2a 2a 20 3c 74 6f 64 6f 3e 20  zero..** <todo> 
37710 43 68 65 63 6b 20 6f 6e 20 74 68 69 73 20 3c 2f  Check on this </
37720 74 6f 64 6f 3e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  todo>.**.** INVA
37730 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48  RIANTS:.**.** {H
37740 31 32 39 35 31 7d 20 54 68 65 20 5b 73 71 6c 69  12951} The [sqli
37750 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28  te3_commit_hook(
37760 44 2c 46 2c 50 29 5d 20 69 6e 74 65 72 66 61 63  D,F,P)] interfac
37770 65 20 72 65 67 69 73 74 65 72 73 20 74 68 65 0a  e registers the.
37780 2a 2a 20 20 20 20 20 20 20 20 20 20 63 61 6c 6c  **          call
37790 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 46 20  back function F 
377a0 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69  to be invoked wi
377b0 74 68 20 61 72 67 75 6d 65 6e 74 20 50 20 77 68  th argument P wh
377c0 65 6e 65 76 65 72 0a 2a 2a 20 20 20 20 20 20 20  enever.**       
377d0 20 20 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e     a transaction
377e0 20 63 6f 6d 6d 69 74 73 20 6f 6e 20 74 68 65 20   commits on the 
377f0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
37800 74 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b  tion] D..**.** {
37810 48 31 32 39 35 32 7d 20 54 68 65 20 5b 73 71 6c  H12952} The [sql
37820 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b  ite3_commit_hook
37830 28 44 2c 46 2c 50 29 5d 20 69 6e 74 65 72 66 61  (D,F,P)] interfa
37840 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 50  ce returns the P
37850 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 20 20 20   argument.**    
37860 20 20 20 20 20 20 66 72 6f 6d 20 74 68 65 20 70        from the p
37870 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 77 69 74  revious call wit
37880 68 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61  h the same [data
37890 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
378a0 20 44 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   D,.**          
378b0 6f 72 20 4e 55 4c 4c 20 6f 6e 20 74 68 65 20 66  or NULL on the f
378c0 69 72 73 74 20 63 61 6c 6c 20 66 6f 72 20 61 20  irst call for a 
378d0 70 61 72 74 69 63 75 6c 61 72 20 64 61 74 61 62  particular datab
378e0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44  ase connection D
378f0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 35 33 7d  ..**.** {H12953}
37900 20 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 5b 73   Each call to [s
37910 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f  qlite3_commit_ho
37920 6f 6b 28 29 5d 20 6f 76 65 72 77 72 69 74 65 73  ok()] overwrites
37930 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a   the callback.**
37940 20 20 20 20 20 20 20 20 20 20 72 65 67 69 73 74            regist
37950 65 72 65 64 20 62 79 20 70 72 69 6f 72 20 63 61  ered by prior ca
37960 6c 6c 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39  lls..**.** {H129
37970 35 34 7d 20 49 66 20 74 68 65 20 46 20 61 72 67  54} If the F arg
37980 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65  ument to [sqlite
37990 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 44 2c  3_commit_hook(D,
379a0 46 2c 50 29 5d 20 69 73 20 4e 55 4c 4c 0a 2a 2a  F,P)] is NULL.**
379b0 20 20 20 20 20 20 20 20 20 20 74 68 65 6e 20 74            then t
379c0 68 65 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b 20 63  he commit hook c
379d0 61 6c 6c 62 61 63 6b 20 69 73 20 63 61 6e 63 65  allback is cance
379e0 6c 65 64 20 61 6e 64 20 6e 6f 20 63 61 6c 6c 62  led and no callb
379f0 61 63 6b 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ack.**          
37a00 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20  is invoked when 
37a10 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f  a transaction co
37a20 6d 6d 69 74 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  mmits..**.** {H1
37a30 32 39 35 35 7d 20 49 66 20 74 68 65 20 63 6f 6d  2955} If the com
37a40 6d 69 74 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  mit callback ret
37a50 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 20 74 68  urns non-zero th
37a60 65 6e 20 74 68 65 20 63 6f 6d 6d 69 74 20 69 73  en the commit is
37a70 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6e  .**          con
37a80 76 65 72 74 65 64 20 69 6e 74 6f 20 61 20 72 6f  verted into a ro
37a90 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 7b 48  llback..**.** {H
37aa0 31 32 39 36 31 7d 20 54 68 65 20 5b 73 71 6c 69  12961} The [sqli
37ab0 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f  te3_rollback_hoo
37ac0 6b 28 44 2c 46 2c 50 29 5d 20 69 6e 74 65 72 66  k(D,F,P)] interf
37ad0 61 63 65 20 72 65 67 69 73 74 65 72 73 20 74 68  ace registers th
37ae0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 61  e.**          ca
37af0 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
37b00 46 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20  F to be invoked 
37b10 77 69 74 68 20 61 72 67 75 6d 65 6e 74 20 50 20  with argument P 
37b20 77 68 65 6e 65 76 65 72 0a 2a 2a 20 20 20 20 20  whenever.**     
37b30 20 20 20 20 20 61 20 74 72 61 6e 73 61 63 74 69       a transacti
37b40 6f 6e 20 72 6f 6c 6c 73 20 62 61 63 6b 20 6f 6e  on rolls back on
37b50 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
37b60 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2e 0a 2a 2a  onnection] D..**
37b70 0a 2a 2a 20 7b 48 31 32 39 36 32 7d 20 54 68 65  .** {H12962} The
37b80 20 5b 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61   [sqlite3_rollba
37b90 63 6b 5f 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d 20  ck_hook(D,F,P)] 
37ba0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
37bb0 73 20 74 68 65 20 50 0a 2a 2a 20 20 20 20 20 20  s the P.**      
37bc0 20 20 20 20 61 72 67 75 6d 65 6e 74 20 66 72 6f      argument fro
37bd0 6d 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 63  m the previous c
37be0 61 6c 6c 20 77 69 74 68 20 74 68 65 20 73 61 6d  all with the sam
37bf0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 64  e.**          [d
37c00 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
37c10 6f 6e 5d 20 44 2c 20 6f 72 20 4e 55 4c 4c 20 6f  on] D, or NULL o
37c20 6e 20 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c  n the first call
37c30 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 6f 72  .**          for
37c40 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 64 61   a particular da
37c50 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
37c60 6e 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39  n D..**.** {H129
37c70 36 33 7d 20 45 61 63 68 20 63 61 6c 6c 20 74 6f  63} Each call to
37c80 20 5b 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61   [sqlite3_rollba
37c90 63 6b 5f 68 6f 6f 6b 28 29 5d 20 6f 76 65 72 77  ck_hook()] overw
37ca0 72 69 74 65 73 20 74 68 65 20 63 61 6c 6c 62 61  rites the callba
37cb0 63 6b 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72  ck.**          r
37cc0 65 67 69 73 74 65 72 65 64 20 62 79 20 70 72 69  egistered by pri
37cd0 6f 72 20 63 61 6c 6c 73 2e 0a 2a 2a 0a 2a 2a 20  or calls..**.** 
37ce0 7b 48 31 32 39 36 34 7d 20 49 66 20 74 68 65 20  {H12964} If the 
37cf0 46 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73  F argument to [s
37d00 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f  qlite3_rollback_
37d10 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d 20 69 73 20  hook(D,F,P)] is 
37d20 4e 55 4c 4c 0a 2a 2a 20 20 20 20 20 20 20 20 20  NULL.**         
37d30 20 74 68 65 6e 20 74 68 65 20 72 6f 6c 6c 62 61   then the rollba
37d40 63 6b 20 68 6f 6f 6b 20 63 61 6c 6c 62 61 63 6b  ck hook callback
37d50 20 69 73 20 63 61 6e 63 65 6c 65 64 20 61 6e 64   is canceled and
37d60 20 6e 6f 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20   no callback.** 
37d70 20 20 20 20 20 20 20 20 20 69 73 20 69 6e 76 6f           is invo
37d80 6b 65 64 20 77 68 65 6e 20 61 20 74 72 61 6e 73  ked when a trans
37d90 61 63 74 69 6f 6e 20 72 6f 6c 6c 73 20 62 61 63  action rolls bac
37da0 6b 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69  k..*/.void *sqli
37db0 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28  te3_commit_hook(
37dc0 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28 2a 29  sqlite3*, int(*)
37dd0 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b  (void*), void*);
37de0 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 72  .void *sqlite3_r
37df0 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 73 71 6c  ollback_hook(sql
37e00 69 74 65 33 2a 2c 20 76 6f 69 64 28 2a 29 28 76  ite3*, void(*)(v
37e10 6f 69 64 20 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a  oid *), void*);.
37e20 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
37e30 20 44 61 74 61 20 43 68 61 6e 67 65 20 4e 6f 74   Data Change Not
37e40 69 66 69 63 61 74 69 6f 6e 20 43 61 6c 6c 62 61  ification Callba
37e50 63 6b 73 20 7b 48 31 32 39 37 30 7d 20 3c 53 36  cks {H12970} <S6
37e60 30 34 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  0400>.**.** The 
37e70 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68  sqlite3_update_h
37e80 6f 6f 6b 28 29 20 69 6e 74 65 72 66 61 63 65 20  ook() interface 
37e90 72 65 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c  registers a call
37ea0 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  back function.**
37eb0 20 77 69 74 68 20 74 68 65 20 5b 64 61 74 61 62   with the [datab
37ec0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
37ed0 69 64 65 6e 74 69 66 69 65 64 20 62 79 20 74 68  identified by th
37ee0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
37ef0 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65  .** to be invoke
37f00 64 20 77 68 65 6e 65 76 65 72 20 61 20 72 6f 77  d whenever a row
37f10 20 69 73 20 75 70 64 61 74 65 64 2c 20 69 6e 73   is updated, ins
37f20 65 72 74 65 64 20 6f 72 20 64 65 6c 65 74 65 64  erted or deleted
37f30 2e 0a 2a 2a 20 41 6e 79 20 63 61 6c 6c 62 61 63  ..** Any callbac
37f40 6b 20 73 65 74 20 62 79 20 61 20 70 72 65 76 69  k set by a previ
37f50 6f 75 73 20 63 61 6c 6c 20 74 6f 20 74 68 69 73  ous call to this
37f60 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 66 6f 72   function.** for
37f70 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61   the same databa
37f80 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
37f90 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 0a   overridden..**.
37fa0 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72  ** The second ar
37fb0 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e  gument is a poin
37fc0 74 65 72 20 74 6f 20 74 68 65 20 66 75 6e 63 74  ter to the funct
37fd0 69 6f 6e 20 74 6f 20 69 6e 76 6f 6b 65 20 77 68  ion to invoke wh
37fe0 65 6e 20 61 0a 2a 2a 20 72 6f 77 20 69 73 20 75  en a.** row is u
37ff0 70 64 61 74 65 64 2c 20 69 6e 73 65 72 74 65 64  pdated, inserted
38000 20 6f 72 20 64 65 6c 65 74 65 64 2e 0a 2a 2a 20   or deleted..** 
38010 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
38020 6e 74 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61  nt to the callba
38030 63 6b 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20  ck is a copy of 
38040 74 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65  the third argume
38050 6e 74 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33  nt.** to sqlite3
38060 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 29 2e 0a  _update_hook()..
38070 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 63 61  ** The second ca
38080 6c 6c 62 61 63 6b 20 61 72 67 75 6d 65 6e 74 20  llback argument 
38090 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54  is one of [SQLIT
380a0 45 5f 49 4e 53 45 52 54 5d 2c 20 5b 53 51 4c 49  E_INSERT], [SQLI
380b0 54 45 5f 44 45 4c 45 54 45 5d 2c 0a 2a 2a 20 6f  TE_DELETE],.** o
380c0 72 20 5b 53 51 4c 49 54 45 5f 55 50 44 41 54 45  r [SQLITE_UPDATE
380d0 5d 2c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20  ], depending on 
380e0 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 74 68  the operation th
380f0 61 74 20 63 61 75 73 65 64 20 74 68 65 20 63 61  at caused the ca
38100 6c 6c 62 61 63 6b 0a 2a 2a 20 74 6f 20 62 65 20  llback.** to be 
38110 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 20 54 68 65 20  invoked..** The 
38120 74 68 69 72 64 20 61 6e 64 20 66 6f 75 72 74 68  third and fourth
38130 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68   arguments to th
38140 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61  e callback conta
38150 69 6e 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 74  in pointers to t
38160 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 61  he.** database a
38170 6e 64 20 74 61 62 6c 65 20 6e 61 6d 65 20 63 6f  nd table name co
38180 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 61 66 66  ntaining the aff
38190 65 63 74 65 64 20 72 6f 77 2e 0a 2a 2a 20 54 68  ected row..** Th
381a0 65 20 66 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b  e final callback
381b0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
381c0 65 20 72 6f 77 69 64 20 6f 66 20 74 68 65 20 72  e rowid of the r
381d0 6f 77 2e 20 49 6e 20 74 68 65 20 63 61 73 65 20  ow. In the case 
381e0 6f 66 0a 2a 2a 20 61 6e 20 75 70 64 61 74 65 2c  of.** an update,
381f0 20 74 68 69 73 20 69 73 20 74 68 65 20 72 6f 77   this is the row
38200 69 64 20 61 66 74 65 72 20 74 68 65 20 75 70 64  id after the upd
38210 61 74 65 20 74 61 6b 65 73 20 70 6c 61 63 65 2e  ate takes place.
38220 0a 2a 2a 0a 2a 2a 20 54 68 65 20 75 70 64 61 74  .**.** The updat
38230 65 20 68 6f 6f 6b 20 69 73 20 6e 6f 74 20 69 6e  e hook is not in
38240 76 6f 6b 65 64 20 77 68 65 6e 20 69 6e 74 65 72  voked when inter
38250 6e 61 6c 20 73 79 73 74 65 6d 20 74 61 62 6c 65  nal system table
38260 73 20 61 72 65 0a 2a 2a 20 6d 6f 64 69 66 69 65  s are.** modifie
38270 64 20 28 69 2e 65 2e 20 73 71 6c 69 74 65 5f 6d  d (i.e. sqlite_m
38280 61 73 74 65 72 20 61 6e 64 20 73 71 6c 69 74 65  aster and sqlite
38290 5f 73 65 71 75 65 6e 63 65 29 2e 0a 2a 2a 0a 2a  _sequence)..**.*
382a0 2a 20 49 66 20 61 6e 6f 74 68 65 72 20 66 75 6e  * If another fun
382b0 63 74 69 6f 6e 20 77 61 73 20 70 72 65 76 69 6f  ction was previo
382c0 75 73 6c 79 20 72 65 67 69 73 74 65 72 65 64 2c  usly registered,
382d0 20 69 74 73 20 70 41 72 67 20 76 61 6c 75 65 0a   its pArg value.
382e0 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20  ** is returned. 
382f0 20 4f 74 68 65 72 77 69 73 65 20 4e 55 4c 4c 20   Otherwise NULL 
38300 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  is returned..**.
38310 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
38320 2a 0a 2a 2a 20 7b 48 31 32 39 37 31 7d 20 54 68  *.** {H12971} Th
38330 65 20 5b 73 71 6c 69 74 65 33 5f 75 70 64 61 74  e [sqlite3_updat
38340 65 5f 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d 20 69  e_hook(D,F,P)] i
38350 6e 74 65 72 66 61 63 65 20 63 61 75 73 65 73 20  nterface causes 
38360 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20  the callback.** 
38370 20 20 20 20 20 20 20 20 20 66 75 6e 63 74 69 6f           functio
38380 6e 20 46 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65  n F to be invoke
38390 64 20 77 69 74 68 20 66 69 72 73 74 20 70 61 72  d with first par
383a0 61 6d 65 74 65 72 20 50 20 77 68 65 6e 65 76 65  ameter P wheneve
383b0 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20  r.**          a 
383c0 74 61 62 6c 65 20 72 6f 77 20 69 73 20 6d 6f 64  table row is mod
383d0 69 66 69 65 64 2c 20 69 6e 73 65 72 74 65 64 2c  ified, inserted,
383e0 20 6f 72 20 64 65 6c 65 74 65 64 20 6f 6e 0a 2a   or deleted on.*
383f0 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 5b  *          the [
38400 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
38410 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 48  ion] D..**.** {H
38420 31 32 39 37 33 7d 20 54 68 65 20 5b 73 71 6c 69  12973} The [sqli
38430 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28  te3_update_hook(
38440 44 2c 46 2c 50 29 5d 20 69 6e 74 65 72 66 61 63  D,F,P)] interfac
38450 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 76 61  e returns the va
38460 6c 75 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  lue.**          
38470 6f 66 20 50 20 66 6f 72 20 74 68 65 20 70 72 65  of P for the pre
38480 76 69 6f 75 73 20 63 61 6c 6c 20 6f 6e 20 74 68  vious call on th
38490 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65  e same [database
384a0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2c 0a   connection] D,.
384b0 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 4e  **          or N
384c0 55 4c 4c 20 66 6f 72 20 74 68 65 20 66 69 72 73  ULL for the firs
384d0 74 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 7b 48  t call..**.** {H
384e0 31 32 39 37 35 7d 20 49 66 20 74 68 65 20 75 70  12975} If the up
384f0 64 61 74 65 20 68 6f 6f 6b 20 63 61 6c 6c 62 61  date hook callba
38500 63 6b 20 46 20 69 6e 20 5b 73 71 6c 69 74 65 33  ck F in [sqlite3
38510 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 44 2c 46  _update_hook(D,F
38520 2c 50 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  ,P)].**         
38530 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68   is NULL then th
38540 65 20 6e 6f 20 75 70 64 61 74 65 20 63 61 6c 6c  e no update call
38550 62 61 63 6b 73 20 61 72 65 20 6d 61 64 65 2e 0a  backs are made..
38560 2a 2a 0a 2a 2a 20 7b 48 31 32 39 37 37 7d 20 45  **.** {H12977} E
38570 61 63 68 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ach call to [sql
38580 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b  ite3_update_hook
38590 28 44 2c 46 2c 50 29 5d 20 6f 76 65 72 72 69 64  (D,F,P)] overrid
385a0 65 73 20 70 72 69 6f 72 20 63 61 6c 6c 73 0a 2a  es prior calls.*
385b0 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20 74 68  *          to th
385c0 65 20 73 61 6d 65 20 69 6e 74 65 72 66 61 63 65  e same interface
385d0 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b 64 61   on the same [da
385e0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
385f0 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  n] D..**.** {H12
38600 39 37 39 7d 20 54 68 65 20 75 70 64 61 74 65 20  979} The update 
38610 68 6f 6f 6b 20 63 61 6c 6c 62 61 63 6b 20 69 73  hook callback is
38620 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 77 68 65   not invoked whe
38630 6e 20 69 6e 74 65 72 6e 61 6c 20 73 79 73 74 65  n internal syste
38640 6d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 61  m.**          ta
38650 62 6c 65 73 20 73 75 63 68 20 61 73 20 73 71 6c  bles such as sql
38660 69 74 65 5f 6d 61 73 74 65 72 20 61 6e 64 20 73  ite_master and s
38670 71 6c 69 74 65 5f 73 65 71 75 65 6e 63 65 20 61  qlite_sequence a
38680 72 65 20 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a 0a  re modified..**.
38690 2a 2a 20 7b 48 31 32 39 38 31 7d 20 54 68 65 20  ** {H12981} The 
386a0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
386b0 20 74 6f 20 74 68 65 20 75 70 64 61 74 65 20 63   to the update c
386c0 61 6c 6c 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20  allback.**      
386d0 20 20 20 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53      is one of [S
386e0 51 4c 49 54 45 5f 49 4e 53 45 52 54 5d 2c 20 5b  QLITE_INSERT], [
386f0 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d 20 6f  SQLITE_DELETE] o
38700 72 20 5b 53 51 4c 49 54 45 5f 55 50 44 41 54 45  r [SQLITE_UPDATE
38710 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64  ],.**          d
38720 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20  epending on the 
38730 6f 70 65 72 61 74 69 6f 6e 20 74 68 61 74 20 63  operation that c
38740 61 75 73 65 64 20 74 68 65 20 63 61 6c 6c 62 61  aused the callba
38750 63 6b 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64  ck to be invoked
38760 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 38 33 7d  ..**.** {H12983}
38770 20 54 68 65 20 74 68 69 72 64 20 61 6e 64 20 66   The third and f
38780 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 73 20  ourth arguments 
38790 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  to the callback 
387a0 63 6f 6e 74 61 69 6e 20 70 6f 69 6e 74 65 72 73  contain pointers
387b0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20  .**          to 
387c0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
387d0 55 54 46 2d 38 20 73 74 72 69 6e 67 73 20 77 68  UTF-8 strings wh
387e0 69 63 68 20 61 72 65 20 74 68 65 20 6e 61 6d 65  ich are the name
387f0 73 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 20  s of the.**     
38800 20 20 20 20 20 64 61 74 61 62 61 73 65 20 61 6e       database an
38810 64 20 74 61 62 6c 65 20 74 68 61 74 20 69 73 20  d table that is 
38820 62 65 69 6e 67 20 75 70 64 61 74 65 64 2e 0a 0a  being updated...
38830 2a 2a 20 7b 48 31 32 39 38 35 7d 20 54 68 65 20  ** {H12985} The 
38840 66 69 6e 61 6c 20 63 61 6c 6c 62 61 63