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

Artifact 2373d1d70664f7fcd78e79af3c51792bb0a0753e:


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 2e 68 2e 69   $Id: sqlite.h.i
05e0: 6e 2c 76 20 31 2e 33 39 33 20 32 30 30 38 2f 30  n,v 1.393 2008/0
05f0: 38 2f 32 32 20 30 30 3a 32 32 3a 33 35 20 61 73  8/22 00:22:35 as
0600: 77 69 66 74 20 45 78 70 20 24 0a 2a 2f 0a 23 69  wift 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 2d 2d 56 45 52 53 2d 2d 22 0a       "--VERS--".
10a0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56  #define SQLITE_V
10b0: 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 20 2d  ERSION_NUMBER  -
10c0: 2d 56 45 52 53 49 4f 4e 2d 4e 55 4d 42 45 52 2d  -VERSION-NUMBER-
10d0: 2d 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  -../*.** CAPI3RE
10e0: 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72  F: Run-Time Libr
10f0: 61 72 79 20 56 65 72 73 69 6f 6e 20 4e 75 6d 62  ary Version Numb
1100: 65 72 73 20 7b 48 31 30 30 32 30 7d 20 3c 53 36  ers {H10020} <S6
1110: 30 31 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44  0100>.** KEYWORD
1120: 53 3a 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69  S: sqlite3_versi
1130: 6f 6e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66  on.**.** These f
1140: 65 61 74 75 72 65 73 20 70 72 6f 76 69 64 65 20  eatures provide 
1150: 74 68 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61  the same informa
1160: 74 69 6f 6e 20 61 73 20 74 68 65 20 5b 53 51 4c  tion as the [SQL
1170: 49 54 45 5f 56 45 52 53 49 4f 4e 5d 0a 2a 2a 20  ITE_VERSION].** 
1180: 61 6e 64 20 5b 53 51 4c 49 54 45 5f 56 45 52 53  and [SQLITE_VERS
1190: 49 4f 4e 5f 4e 55 4d 42 45 52 5d 20 23 64 65 66  ION_NUMBER] #def
11a0: 69 6e 65 73 20 69 6e 20 74 68 65 20 68 65 61 64  ines in the head
11b0: 65 72 2c 20 62 75 74 20 61 72 65 20 61 73 73 6f  er, but are asso
11c0: 63 69 61 74 65 64 0a 2a 2a 20 77 69 74 68 20 74  ciated.** with t
11d0: 68 65 20 6c 69 62 72 61 72 79 20 69 6e 73 74 65  he library inste
11e0: 61 64 20 6f 66 20 74 68 65 20 68 65 61 64 65 72  ad of the header
11f0: 20 66 69 6c 65 2e 20 20 43 61 75 74 69 6f 75 73   file.  Cautious
1200: 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67   programmers mig
1210: 68 74 0a 2a 2a 20 69 6e 63 6c 75 64 65 20 61 20  ht.** include a 
1220: 63 68 65 63 6b 20 69 6e 20 74 68 65 69 72 20 61  check in their a
1230: 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 76 65  pplication to ve
1240: 72 69 66 79 20 74 68 61 74 0a 2a 2a 20 73 71 6c  rify that.** sql
1250: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f  ite3_libversion_
1260: 6e 75 6d 62 65 72 28 29 20 61 6c 77 61 79 73 20  number() always 
1270: 72 65 74 75 72 6e 73 20 74 68 65 20 76 61 6c 75  returns the valu
1280: 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 45 52  e.** [SQLITE_VER
1290: 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2e 0a 2a 2a  SION_NUMBER]..**
12a0: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
12b0: 6c 69 62 76 65 72 73 69 6f 6e 28 29 20 66 75 6e  libversion() fun
12c0: 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68  ction returns th
12d0: 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69  e same informati
12e0: 6f 6e 20 61 73 20 69 73 0a 2a 2a 20 69 6e 20 74  on as is.** in t
12f0: 68 65 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69  he sqlite3_versi
1300: 6f 6e 5b 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73  on[] string cons
1310: 74 61 6e 74 2e 20 20 54 68 65 20 66 75 6e 63 74  tant.  The funct
1320: 69 6f 6e 20 69 73 20 70 72 6f 76 69 64 65 64 0a  ion is provided.
1330: 2a 2a 20 66 6f 72 20 75 73 65 20 69 6e 20 44 4c  ** for use in DL
1340: 4c 73 20 73 69 6e 63 65 20 44 4c 4c 20 75 73 65  Ls since DLL use
1350: 72 73 20 75 73 75 61 6c 6c 79 20 64 6f 20 6e 6f  rs usually do no
1360: 74 20 68 61 76 65 20 64 69 72 65 63 74 20 61 63  t have direct ac
1370: 63 65 73 73 20 74 6f 20 73 74 72 69 6e 67 0a 2a  cess to string.*
1380: 2a 20 63 6f 6e 73 74 61 6e 74 73 20 77 69 74 68  * constants with
1390: 69 6e 20 74 68 65 20 44 4c 4c 2e 0a 2a 2a 0a 2a  in the DLL..**.*
13a0: 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
13b0: 0a 2a 2a 20 7b 48 31 30 30 32 31 7d 20 54 68 65  .** {H10021} The
13c0: 20 5b 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72   [sqlite3_libver
13d0: 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 5d 20 69  sion_number()] i
13e0: 6e 74 65 72 66 61 63 65 20 73 68 61 6c 6c 20 72  nterface shall r
13f0: 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20  eturn.**        
1400: 20 20 61 6e 20 69 6e 74 65 67 65 72 20 65 71 75    an integer equ
1410: 61 6c 20 74 6f 20 5b 53 51 4c 49 54 45 5f 56 45  al to [SQLITE_VE
1420: 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2e 0a 2a  RSION_NUMBER]..*
1430: 2a 0a 2a 2a 20 7b 48 31 30 30 32 32 7d 20 54 68  *.** {H10022} Th
1440: 65 20 5b 73 71 6c 69 74 65 33 5f 76 65 72 73 69  e [sqlite3_versi
1450: 6f 6e 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74  on] string const
1460: 61 6e 74 20 73 68 61 6c 6c 20 63 6f 6e 74 61 69  ant shall contai
1470: 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  n.**          th
1480: 65 20 74 65 78 74 20 6f 66 20 74 68 65 20 5b 53  e text of the [S
1490: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 20 73  QLITE_VERSION] s
14a0: 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  tring..**.** {H1
14b0: 30 30 32 33 7d 20 54 68 65 20 5b 73 71 6c 69 74  0023} The [sqlit
14c0: 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 5d  e3_libversion()]
14d0: 20 66 75 6e 63 74 69 6f 6e 20 73 68 61 6c 6c 20   function shall 
14e0: 72 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20  return.**       
14f0: 20 20 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20     a pointer to 
1500: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 65 72  the [sqlite3_ver
1510: 73 69 6f 6e 5d 20 73 74 72 69 6e 67 20 63 6f 6e  sion] string con
1520: 73 74 61 6e 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45  stant..*/.SQLITE
1530: 5f 45 58 54 45 52 4e 20 63 6f 6e 73 74 20 63 68  _EXTERN const ch
1540: 61 72 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69  ar sqlite3_versi
1550: 6f 6e 5b 5d 3b 0a 63 6f 6e 73 74 20 63 68 61 72  on[];.const char
1560: 20 2a 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72   *sqlite3_libver
1570: 73 69 6f 6e 28 76 6f 69 64 29 3b 0a 69 6e 74 20  sion(void);.int 
1580: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
1590: 6f 6e 5f 6e 75 6d 62 65 72 28 76 6f 69 64 29 3b  on_number(void);
15a0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
15b0: 3a 20 54 65 73 74 20 54 6f 20 53 65 65 20 49 66  : Test To See If
15c0: 20 54 68 65 20 4c 69 62 72 61 72 79 20 49 73 20   The Library Is 
15d0: 54 68 72 65 61 64 73 61 66 65 20 7b 48 31 30 31  Threadsafe {H101
15e0: 30 30 7d 20 3c 53 36 30 31 30 30 3e 0a 2a 2a 0a  00} <S60100>.**.
15f0: 2a 2a 20 53 51 4c 69 74 65 20 63 61 6e 20 62 65  ** SQLite can be
1600: 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 6f   compiled with o
1610: 72 20 77 69 74 68 6f 75 74 20 6d 75 74 65 78 65  r without mutexe
1620: 73 2e 20 20 57 68 65 6e 0a 2a 2a 20 74 68 65 20  s.  When.** the 
1630: 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
1640: 46 45 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73  FE] C preprocess
1650: 6f 72 20 6d 61 63 72 6f 20 69 73 20 74 72 75 65  or macro is true
1660: 2c 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72 65  , mutexes.** are
1670: 20 65 6e 61 62 6c 65 64 20 61 6e 64 20 53 51 4c   enabled and SQL
1680: 69 74 65 20 69 73 20 74 68 72 65 61 64 73 61 66  ite is threadsaf
1690: 65 2e 20 20 57 68 65 6e 20 74 68 61 74 20 6d 61  e.  When that ma
16a0: 63 72 6f 20 69 73 20 66 61 6c 73 65 2c 0a 2a 2a  cro is false,.**
16b0: 20 74 68 65 20 6d 75 74 65 78 65 73 20 61 72 65   the mutexes are
16c0: 20 6f 6d 69 74 74 65 64 2e 20 20 57 69 74 68 6f   omitted.  Witho
16d0: 75 74 20 74 68 65 20 6d 75 74 65 78 65 73 2c 20  ut the mutexes, 
16e0: 69 74 20 69 73 20 6e 6f 74 20 73 61 66 65 0a 2a  it is not safe.*
16f0: 2a 20 74 6f 20 75 73 65 20 53 51 4c 69 74 65 20  * to use SQLite 
1700: 63 6f 6e 63 75 72 72 65 6e 74 6c 79 20 66 72 6f  concurrently fro
1710: 6d 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20  m more than one 
1720: 74 68 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 45 6e  thread..**.** En
1730: 61 62 6c 69 6e 67 20 6d 75 74 65 78 65 73 20 69  abling mutexes i
1740: 6e 63 75 72 73 20 61 20 6d 65 61 73 75 72 61 62  ncurs a measurab
1750: 6c 65 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 70  le performance p
1760: 65 6e 61 6c 74 79 2e 0a 2a 2a 20 53 6f 20 69 66  enalty..** So if
1770: 20 73 70 65 65 64 20 69 73 20 6f 66 20 75 74 6d   speed is of utm
1780: 6f 73 74 20 69 6d 70 6f 72 74 61 6e 63 65 2c 20  ost importance, 
1790: 69 74 20 6d 61 6b 65 73 20 73 65 6e 73 65 20 74  it makes sense t
17a0: 6f 20 64 69 73 61 62 6c 65 0a 2a 2a 20 74 68 65  o disable.** the
17b0: 20 6d 75 74 65 78 65 73 2e 20 20 42 75 74 20 66   mutexes.  But f
17c0: 6f 72 20 6d 61 78 69 6d 75 6d 20 73 61 66 65 74  or maximum safet
17d0: 79 2c 20 6d 75 74 65 78 65 73 20 73 68 6f 75 6c  y, mutexes shoul
17e0: 64 20 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a  d be enabled..**
17f0: 20 54 68 65 20 64 65 66 61 75 6c 74 20 62 65 68   The default beh
1800: 61 76 69 6f 72 20 69 73 20 66 6f 72 20 6d 75 74  avior is for mut
1810: 65 78 65 73 20 74 6f 20 62 65 20 65 6e 61 62 6c  exes to be enabl
1820: 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69  ed..**.** This i
1830: 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20  nterface can be 
1840: 75 73 65 64 20 62 79 20 61 20 70 72 6f 67 72 61  used by a progra
1850: 6d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74  m to make sure t
1860: 68 61 74 20 74 68 65 0a 2a 2a 20 76 65 72 73 69  hat the.** versi
1870: 6f 6e 20 6f 66 20 53 51 4c 69 74 65 20 74 68 61  on of SQLite tha
1880: 74 20 69 74 20 69 73 20 6c 69 6e 6b 69 6e 67 20  t it is linking 
1890: 61 67 61 69 6e 73 74 20 77 61 73 20 63 6f 6d 70  against was comp
18a0: 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65  iled with.** the
18b0: 20 64 65 73 69 72 65 64 20 73 65 74 74 69 6e 67   desired setting
18c0: 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   of the [SQLITE_
18d0: 54 48 52 45 41 44 53 41 46 45 5d 20 6d 61 63 72  THREADSAFE] macr
18e0: 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e  o..**.** This in
18f0: 74 65 72 66 61 63 65 20 6f 6e 6c 79 20 72 65 70  terface only rep
1900: 6f 72 74 73 20 6f 6e 20 74 68 65 20 63 6f 6d 70  orts on the comp
1910: 69 6c 65 2d 74 69 6d 65 20 6d 75 74 65 78 20 73  ile-time mutex s
1920: 65 74 74 69 6e 67 0a 2a 2a 20 6f 66 20 74 68 65  etting.** of the
1930: 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53   [SQLITE_THREADS
1940: 41 46 45 5d 20 66 6c 61 67 2e 20 20 49 66 20 53  AFE] flag.  If S
1950: 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
1960: 64 20 77 69 74 68 0a 2a 2a 20 53 51 4c 49 54 45  d with.** SQLITE
1970: 5f 54 48 52 45 41 44 53 41 46 45 3d 31 20 74 68  _THREADSAFE=1 th
1980: 65 6e 20 6d 75 74 65 78 65 73 20 61 72 65 20 65  en mutexes are e
1990: 6e 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c  nabled by defaul
19a0: 74 20 62 75 74 0a 2a 2a 20 63 61 6e 20 62 65 20  t but.** can be 
19b0: 66 75 6c 6c 79 20 6f 72 20 70 61 72 74 69 61 6c  fully or partial
19c0: 6c 79 20 64 69 73 61 62 6c 65 64 20 75 73 69 6e  ly disabled usin
19d0: 67 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  g a call to [sql
19e0: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 0a 2a  ite3_config()].*
19f0: 2a 20 77 69 74 68 20 74 68 65 20 76 65 72 62 73  * with the verbs
1a00: 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
1a10: 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 2c 20 5b  SINGLETHREAD], [
1a20: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
1a30: 4c 54 49 54 48 52 45 41 44 5d 2c 0a 2a 2a 20 6f  LTITHREAD],.** o
1a40: 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  r [SQLITE_CONFIG
1a50: 5f 4d 55 54 45 58 5d 2e 20 20 54 68 65 20 72 65  _MUTEX].  The re
1a60: 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68  turn value of th
1a70: 69 73 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 77  is function show
1a80: 73 0a 2a 2a 20 6f 6e 6c 79 20 74 68 65 20 64 65  s.** only the de
1a90: 66 61 75 6c 74 20 63 6f 6d 70 69 6c 65 2d 74 69  fault compile-ti
1aa0: 6d 65 20 73 65 74 74 69 6e 67 2c 20 6e 6f 74 20  me setting, not 
1ab0: 61 6e 79 20 72 75 6e 2d 74 69 6d 65 20 63 68 61  any run-time cha
1ac0: 6e 67 65 73 0a 2a 2a 20 74 6f 20 74 68 61 74 20  nges.** to that 
1ad0: 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 49  setting..**.** I
1ae0: 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
1af0: 20 7b 48 31 30 31 30 31 7d 20 54 68 65 20 5b 73   {H10101} The [s
1b00: 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66  qlite3_threadsaf
1b10: 65 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20 73 68  e()] function sh
1b20: 61 6c 6c 20 72 65 74 75 72 6e 20 6e 6f 6e 7a 65  all return nonze
1b30: 72 6f 20 69 66 0a 2a 2a 20 20 20 20 20 20 20 20  ro if.**        
1b40: 20 20 53 51 4c 69 74 65 20 77 61 73 20 63 6f 6d    SQLite was com
1b50: 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 20 69  piled with the i
1b60: 74 73 20 6d 75 74 65 78 65 73 20 65 6e 61 62 6c  ts mutexes enabl
1b70: 65 64 20 62 79 20 64 65 66 61 75 6c 74 0a 2a 2a  ed by default.**
1b80: 20 20 20 20 20 20 20 20 20 20 6f 72 20 7a 65 72            or zer
1b90: 6f 20 69 66 20 53 51 4c 69 74 65 20 77 61 73 20  o if SQLite was 
1ba0: 63 6f 6d 70 69 6c 65 64 20 73 75 63 68 20 74 68  compiled such th
1bb0: 61 74 20 6d 75 74 65 78 65 73 20 61 72 65 0a 2a  at mutexes are.*
1bc0: 2a 20 20 20 20 20 20 20 20 20 20 70 65 72 6d 61  *          perma
1bd0: 6e 65 6e 74 6c 79 20 64 69 73 61 62 6c 65 64 2e  nently disabled.
1be0: 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 31 30 32 7d 20  .**.** {H10102} 
1bf0: 54 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  The value return
1c00: 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74  ed by the [sqlit
1c10: 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 5d  e3_threadsafe()]
1c20: 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 20 20 20   function.**    
1c30: 20 20 20 20 20 20 73 68 61 6c 6c 20 6e 6f 74 20        shall not 
1c40: 63 68 61 6e 67 65 20 77 68 65 6e 20 6d 75 74 65  change when mute
1c50: 78 20 73 65 74 74 69 6e 67 20 61 72 65 20 6d 6f  x setting are mo
1c60: 64 69 66 69 65 64 20 61 74 0a 2a 2a 20 20 20 20  dified at.**    
1c70: 20 20 20 20 20 20 72 75 6e 74 69 6d 65 20 75 73        runtime us
1c80: 69 6e 67 20 74 68 65 20 5b 73 71 6c 69 74 65 33  ing the [sqlite3
1c90: 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72  _config()] inter
1ca0: 66 61 63 65 20 61 6e 64 20 0a 2a 2a 20 20 20 20  face and .**    
1cb0: 20 20 20 20 20 20 65 73 70 65 63 69 61 6c 6c 79        especially
1cc0: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e   the [SQLITE_CON
1cd0: 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44  FIG_SINGLETHREAD
1ce0: 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  ],.**          [
1cf0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
1d00: 4c 54 49 54 48 52 45 41 44 5d 2c 20 5b 53 51 4c  LTITHREAD], [SQL
1d10: 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41  ITE_CONFIG_SERIA
1d20: 4c 49 5a 45 44 5d 2c 0a 2a 2a 20 20 20 20 20 20  LIZED],.**      
1d30: 20 20 20 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f      and [SQLITE_
1d40: 43 4f 4e 46 49 47 5f 4d 55 54 45 58 5d 20 76 65  CONFIG_MUTEX] ve
1d50: 72 62 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  rbs..*/.int sqli
1d60: 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 76  te3_threadsafe(v
1d70: 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  oid);../*.** CAP
1d80: 49 33 52 45 46 3a 20 44 61 74 61 62 61 73 65 20  I3REF: Database 
1d90: 43 6f 6e 6e 65 63 74 69 6f 6e 20 48 61 6e 64 6c  Connection Handl
1da0: 65 20 7b 48 31 32 30 30 30 7d 20 3c 53 34 30 32  e {H12000} <S402
1db0: 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  00>.** KEYWORDS:
1dc0: 20 7b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   {database conne
1dd0: 63 74 69 6f 6e 7d 20 7b 64 61 74 61 62 61 73 65  ction} {database
1de0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 7d 0a 2a 2a   connections}.**
1df0: 0a 2a 2a 20 45 61 63 68 20 6f 70 65 6e 20 53 51  .** Each open SQ
1e00: 4c 69 74 65 20 64 61 74 61 62 61 73 65 20 69 73  Lite database is
1e10: 20 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20   represented by 
1e20: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
1e30: 69 6e 73 74 61 6e 63 65 20 6f 66 0a 2a 2a 20 74  instance of.** t
1e40: 68 65 20 6f 70 61 71 75 65 20 73 74 72 75 63 74  he opaque struct
1e50: 75 72 65 20 6e 61 6d 65 64 20 22 73 71 6c 69 74  ure named "sqlit
1e60: 65 33 22 2e 20 20 49 74 20 69 73 20 75 73 65 66  e3".  It is usef
1e70: 75 6c 20 74 6f 20 74 68 69 6e 6b 20 6f 66 20 61  ul to think of a
1e80: 6e 20 73 71 6c 69 74 65 33 0a 2a 2a 20 70 6f 69  n sqlite3.** poi
1e90: 6e 74 65 72 20 61 73 20 61 6e 20 6f 62 6a 65 63  nter as an objec
1ea0: 74 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33  t.  The [sqlite3
1eb0: 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74  _open()], [sqlit
1ec0: 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 61 6e  e3_open16()], an
1ed0: 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70  d.** [sqlite3_op
1ee0: 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61  en_v2()] interfa
1ef0: 63 65 73 20 61 72 65 20 69 74 73 20 63 6f 6e 73  ces are its cons
1f00: 74 72 75 63 74 6f 72 73 2c 20 61 6e 64 20 5b 73  tructors, and [s
1f10: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 0a  qlite3_close()].
1f20: 2a 2a 20 69 73 20 69 74 73 20 64 65 73 74 72 75  ** is its destru
1f30: 63 74 6f 72 2e 20 20 54 68 65 72 65 20 61 72 65  ctor.  There are
1f40: 20 6d 61 6e 79 20 6f 74 68 65 72 20 69 6e 74 65   many other inte
1f50: 72 66 61 63 65 73 20 28 73 75 63 68 20 61 73 0a  rfaces (such as.
1f60: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
1f70: 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69  are_v2()], [sqli
1f80: 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
1f90: 69 6f 6e 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b  ion()], and.** [
1fa0: 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d  sqlite3_busy_tim
1fb0: 65 6f 75 74 28 29 5d 20 74 6f 20 6e 61 6d 65 20  eout()] to name 
1fc0: 62 75 74 20 74 68 72 65 65 29 20 74 68 61 74 20  but three) that 
1fd0: 61 72 65 20 6d 65 74 68 6f 64 73 20 6f 6e 20 61  are methods on a
1fe0: 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 20 6f 62 6a  n.** sqlite3 obj
1ff0: 65 63 74 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ect..*/.typedef 
2000: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 20 73  struct sqlite3 s
2010: 71 6c 69 74 65 33 3b 0a 0a 2f 2a 0a 2a 2a 20 43  qlite3;../*.** C
2020: 41 50 49 33 52 45 46 3a 20 36 34 2d 42 69 74 20  API3REF: 64-Bit 
2030: 49 6e 74 65 67 65 72 20 54 79 70 65 73 20 7b 48  Integer Types {H
2040: 31 30 32 30 30 7d 20 3c 53 31 30 31 31 30 3e 0a  10200} <S10110>.
2050: 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c  ** KEYWORDS: sql
2060: 69 74 65 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  ite_int64 sqlite
2070: 5f 75 69 6e 74 36 34 0a 2a 2a 0a 2a 2a 20 42 65  _uint64.**.** Be
2080: 63 61 75 73 65 20 74 68 65 72 65 20 69 73 20 6e  cause there is n
2090: 6f 20 63 72 6f 73 73 2d 70 6c 61 74 66 6f 72 6d  o cross-platform
20a0: 20 77 61 79 20 74 6f 20 73 70 65 63 69 66 79 20   way to specify 
20b0: 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72 20 74  64-bit integer t
20c0: 79 70 65 73 0a 2a 2a 20 53 51 4c 69 74 65 20 69  ypes.** SQLite i
20d0: 6e 63 6c 75 64 65 73 20 74 79 70 65 64 65 66 73  ncludes typedefs
20e0: 20 66 6f 72 20 36 34 2d 62 69 74 20 73 69 67 6e   for 64-bit sign
20f0: 65 64 20 61 6e 64 20 75 6e 73 69 67 6e 65 64 20  ed and unsigned 
2100: 69 6e 74 65 67 65 72 73 2e 0a 2a 2a 0a 2a 2a 20  integers..**.** 
2110: 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  The sqlite3_int6
2120: 34 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 75 69  4 and sqlite3_ui
2130: 6e 74 36 34 20 61 72 65 20 74 68 65 20 70 72 65  nt64 are the pre
2140: 66 65 72 72 65 64 20 74 79 70 65 20 64 65 66 69  ferred type defi
2150: 6e 69 74 69 6f 6e 73 2e 0a 2a 2a 20 54 68 65 20  nitions..** The 
2160: 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 61 6e 64  sqlite_int64 and
2170: 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 20 74   sqlite_uint64 t
2180: 79 70 65 73 20 61 72 65 20 73 75 70 70 6f 72 74  ypes are support
2190: 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73  ed for backwards
21a0: 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  .** compatibilit
21b0: 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 49 4e  y only..**.** IN
21c0: 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
21d0: 7b 48 31 30 32 30 31 7d 20 54 68 65 20 5b 73 71  {H10201} The [sq
21e0: 6c 69 74 65 5f 69 6e 74 36 34 5d 20 61 6e 64 20  lite_int64] and 
21f0: 5b 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 5d 20  [sqlite3_int64] 
2200: 74 79 70 65 20 73 68 61 6c 6c 20 73 70 65 63 69  type shall speci
2210: 66 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  fy.**          a
2220: 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69   64-bit signed i
2230: 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48  nteger..**.** {H
2240: 31 30 32 30 32 7d 20 54 68 65 20 5b 73 71 6c 69  10202} The [sqli
2250: 74 65 5f 75 69 6e 74 36 34 5d 20 61 6e 64 20 5b  te_uint64] and [
2260: 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 5d 20  sqlite3_uint64] 
2270: 74 79 70 65 20 73 68 61 6c 6c 20 73 70 65 63 69  type shall speci
2280: 66 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  fy.**          a
2290: 20 36 34 2d 62 69 74 20 75 6e 73 69 67 6e 65 64   64-bit unsigned
22a0: 20 69 6e 74 65 67 65 72 2e 0a 2a 2f 0a 23 69 66   integer..*/.#if
22b0: 64 65 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34  def SQLITE_INT64
22c0: 5f 54 59 50 45 0a 20 20 74 79 70 65 64 65 66 20  _TYPE.  typedef 
22d0: 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50  SQLITE_INT64_TYP
22e0: 45 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a  E sqlite_int64;.
22f0: 20 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e    typedef unsign
2300: 65 64 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f  ed SQLITE_INT64_
2310: 54 59 50 45 20 73 71 6c 69 74 65 5f 75 69 6e 74  TYPE sqlite_uint
2320: 36 34 3b 0a 23 65 6c 69 66 20 64 65 66 69 6e 65  64;.#elif define
2330: 64 28 5f 4d 53 43 5f 56 45 52 29 20 7c 7c 20 64  d(_MSC_VER) || d
2340: 65 66 69 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e 44  efined(__BORLAND
2350: 43 5f 5f 29 0a 20 20 74 79 70 65 64 65 66 20 5f  C__).  typedef _
2360: 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 5f 69 6e  _int64 sqlite_in
2370: 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75  t64;.  typedef u
2380: 6e 73 69 67 6e 65 64 20 5f 5f 69 6e 74 36 34 20  nsigned __int64 
2390: 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23  sqlite_uint64;.#
23a0: 65 6c 73 65 0a 20 20 74 79 70 65 64 65 66 20 6c  else.  typedef l
23b0: 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c  ong long int sql
23c0: 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70  ite_int64;.  typ
23d0: 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20 6c 6f  edef unsigned lo
23e0: 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69  ng long int sqli
23f0: 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6e 64 69  te_uint64;.#endi
2400: 66 0a 74 79 70 65 64 65 66 20 73 71 6c 69 74 65  f.typedef sqlite
2410: 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 69  _int64 sqlite3_i
2420: 6e 74 36 34 3b 0a 74 79 70 65 64 65 66 20 73 71  nt64;.typedef sq
2430: 6c 69 74 65 5f 75 69 6e 74 36 34 20 73 71 6c 69  lite_uint64 sqli
2440: 74 65 33 5f 75 69 6e 74 36 34 3b 0a 0a 2f 2a 0a  te3_uint64;../*.
2450: 2a 2a 20 49 66 20 63 6f 6d 70 69 6c 69 6e 67 20  ** If compiling 
2460: 66 6f 72 20 61 20 70 72 6f 63 65 73 73 6f 72 20  for a processor 
2470: 74 68 61 74 20 6c 61 63 6b 73 20 66 6c 6f 61 74  that lacks float
2480: 69 6e 67 20 70 6f 69 6e 74 20 73 75 70 70 6f 72  ing point suppor
2490: 74 2c 0a 2a 2a 20 73 75 62 73 74 69 74 75 74 65  t,.** substitute
24a0: 20 69 6e 74 65 67 65 72 20 66 6f 72 20 66 6c 6f   integer for flo
24b0: 61 74 69 6e 67 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a  ating-point..*/.
24c0: 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d  #ifdef SQLITE_OM
24d0: 49 54 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e  IT_FLOATING_POIN
24e0: 54 0a 23 20 64 65 66 69 6e 65 20 64 6f 75 62 6c  T.# define doubl
24f0: 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 0a  e sqlite3_int64.
2500: 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41  #endif../*.** CA
2510: 50 49 33 52 45 46 3a 20 43 6c 6f 73 69 6e 67 20  PI3REF: Closing 
2520: 41 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65  A Database Conne
2530: 63 74 69 6f 6e 20 7b 48 31 32 30 31 30 7d 20 3c  ction {H12010} <
2540: 53 33 30 31 30 30 3e 3c 53 34 30 32 30 30 3e 0a  S30100><S40200>.
2550: 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69  **.** This routi
2560: 6e 65 20 69 73 20 74 68 65 20 64 65 73 74 72 75  ne is the destru
2570: 63 74 6f 72 20 66 6f 72 20 74 68 65 20 5b 73 71  ctor for the [sq
2580: 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2e 0a 2a  lite3] object..*
2590: 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e  *.** Application
25a0: 73 20 73 68 6f 75 6c 64 20 5b 73 71 6c 69 74 65  s should [sqlite
25b0: 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e  3_finalize | fin
25c0: 61 6c 69 7a 65 5d 20 61 6c 6c 20 5b 70 72 65 70  alize] all [prep
25d0: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d  ared statements]
25e0: 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  .** and [sqlite3
25f0: 5f 62 6c 6f 62 5f 63 6c 6f 73 65 20 7c 20 63 6c  _blob_close | cl
2600: 6f 73 65 5d 20 61 6c 6c 20 5b 42 4c 4f 42 20 68  ose] all [BLOB h
2610: 61 6e 64 6c 65 73 5d 20 61 73 73 6f 63 69 61 74  andles] associat
2620: 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b  ed with.** the [
2630: 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20  sqlite3] object 
2640: 70 72 69 6f 72 20 74 6f 20 61 74 74 65 6d 70 74  prior to attempt
2650: 69 6e 67 20 74 6f 20 63 6c 6f 73 65 20 74 68 65  ing to close the
2660: 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 54 68 65 20   object..** The 
2670: 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74  [sqlite3_next_st
2680: 6d 74 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  mt()] interface 
2690: 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6c  can be used to l
26a0: 6f 63 61 74 65 20 61 6c 6c 0a 2a 2a 20 5b 70 72  ocate all.** [pr
26b0: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
26c0: 73 5d 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  s] associated wi
26d0: 74 68 20 61 20 5b 64 61 74 61 62 61 73 65 20 63  th a [database c
26e0: 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 66 20 64 65  onnection] if de
26f0: 73 69 72 65 64 2e 0a 2a 2a 20 54 79 70 69 63 61  sired..** Typica
2700: 6c 20 63 6f 64 65 20 6d 69 67 68 74 20 6c 6f 6f  l code might loo
2710: 6b 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a  k like this:.**.
2720: 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
2730: 70 72 65 3e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  pre>.** sqlite3_
2740: 73 74 6d 74 20 2a 70 53 74 6d 74 3b 0a 2a 2a 20  stmt *pStmt;.** 
2750: 77 68 69 6c 65 28 20 28 70 53 74 6d 74 20 3d 20  while( (pStmt = 
2760: 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d  sqlite3_next_stm
2770: 74 28 64 62 2c 20 30 29 29 21 3d 30 20 29 7b 0a  t(db, 0))!=0 ){.
2780: 2a 2a 20 26 6e 62 73 70 3b 20 20 20 73 71 6c 69  ** &nbsp;   sqli
2790: 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 70 53 74  te3_finalize(pSt
27a0: 6d 74 29 3b 0a 2a 2a 20 7d 0a 2a 2a 20 3c 2f 70  mt);.** }.** </p
27b0: 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
27c0: 0a 2a 2a 0a 2a 2a 20 49 66 20 5b 73 71 6c 69 74  .**.** If [sqlit
27d0: 65 33 5f 63 6c 6f 73 65 28 29 5d 20 69 73 20 69  e3_close()] is i
27e0: 6e 76 6f 6b 65 64 20 77 68 69 6c 65 20 61 20 74  nvoked while a t
27f0: 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 6f 70  ransaction is op
2800: 65 6e 2c 0a 2a 2a 20 74 68 65 20 74 72 61 6e 73  en,.** the trans
2810: 61 63 74 69 6f 6e 20 69 73 20 61 75 74 6f 6d 61  action is automa
2820: 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62  tically rolled b
2830: 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  ack..**.** INVAR
2840: 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31  IANTS:.**.** {H1
2850: 32 30 31 31 7d 20 41 20 73 75 63 63 65 73 73 66  2011} A successf
2860: 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  ul call to [sqli
2870: 74 65 33 5f 63 6c 6f 73 65 28 43 29 5d 20 73 68  te3_close(C)] sh
2880: 61 6c 6c 20 64 65 73 74 72 6f 79 20 74 68 65 0a  all destroy the.
2890: 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 64 61 74  **          [dat
28a0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
28b0: 5d 20 6f 62 6a 65 63 74 20 43 2e 0a 2a 2a 0a 2a  ] object C..**.*
28c0: 2a 20 7b 48 31 32 30 31 32 7d 20 41 20 73 75 63  * {H12012} A suc
28d0: 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20  cessful call to 
28e0: 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 43  [sqlite3_close(C
28f0: 29 5d 20 73 68 61 6c 6c 20 72 65 74 75 72 6e 20  )] shall return 
2900: 53 51 4c 49 54 45 5f 4f 4b 2e 0a 2a 2a 0a 2a 2a  SQLITE_OK..**.**
2910: 20 7b 48 31 32 30 31 33 7d 20 41 20 73 75 63 63   {H12013} A succ
2920: 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b  essful call to [
2930: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 43 29  sqlite3_close(C)
2940: 5d 20 73 68 61 6c 6c 20 72 65 6c 65 61 73 65 20  ] shall release 
2950: 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  all.**          
2960: 6d 65 6d 6f 72 79 20 61 6e 64 20 73 79 73 74 65  memory and syste
2970: 6d 20 72 65 73 6f 75 72 63 65 73 20 61 73 73 6f  m resources asso
2980: 63 69 61 74 65 64 20 77 69 74 68 20 5b 64 61 74  ciated with [dat
2990: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
29a0: 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 43 2e  ].**          C.
29b0: 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 30 31 34 7d 20  .**.** {H12014} 
29c0: 41 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  A call to [sqlit
29d0: 65 33 5f 63 6c 6f 73 65 28 43 29 5d 20 6f 6e 20  e3_close(C)] on 
29e0: 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  a [database conn
29f0: 65 63 74 69 6f 6e 5d 20 43 20 74 68 61 74 0a 2a  ection] C that.*
2a00: 2a 20 20 20 20 20 20 20 20 20 20 68 61 73 20 6f  *          has o
2a10: 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 70 65 6e 20  ne or more open 
2a20: 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2a30: 65 6e 74 73 5d 20 73 68 61 6c 6c 20 66 61 69 6c  ents] shall fail
2a40: 20 77 69 74 68 0a 2a 2a 20 20 20 20 20 20 20 20   with.**        
2a50: 20 20 61 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53    an [SQLITE_BUS
2a60: 59 5d 20 65 72 72 6f 72 20 63 6f 64 65 2e 0a 2a  Y] error code..*
2a70: 2a 0a 2a 2a 20 7b 48 31 32 30 31 35 7d 20 41 20  *.** {H12015} A 
2a80: 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
2a90: 5f 63 6c 6f 73 65 28 43 29 5d 20 77 68 65 72 65  _close(C)] where
2aa0: 20 43 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69   C is a NULL poi
2ab0: 6e 74 65 72 20 73 68 61 6c 6c 0a 2a 2a 20 20 20  nter shall.**   
2ac0: 20 20 20 20 20 20 20 72 65 74 75 72 6e 20 53 51         return SQ
2ad0: 4c 49 54 45 5f 4f 4b 2e 0a 2a 2a 0a 2a 2a 20 7b  LITE_OK..**.** {
2ae0: 48 31 32 30 31 39 7d 20 57 68 65 6e 20 5b 73 71  H12019} When [sq
2af0: 6c 69 74 65 33 5f 63 6c 6f 73 65 28 43 29 5d 20  lite3_close(C)] 
2b00: 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 20 61 20  is invoked on a 
2b10: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
2b20: 74 69 6f 6e 5d 20 43 0a 2a 2a 20 20 20 20 20 20  tion] C.**      
2b30: 20 20 20 20 74 68 61 74 20 68 61 73 20 61 20 70      that has a p
2b40: 65 6e 64 69 6e 67 20 74 72 61 6e 73 61 63 74 69  ending transacti
2b50: 6f 6e 2c 20 74 68 65 20 74 72 61 6e 73 61 63 74  on, the transact
2b60: 69 6f 6e 20 73 68 61 6c 6c 20 62 65 0a 2a 2a 20  ion shall be.** 
2b70: 20 20 20 20 20 20 20 20 20 72 6f 6c 6c 65 64 20           rolled 
2b80: 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 41 53 53 55  back..**.** ASSU
2b90: 4d 50 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b  MPTIONS:.**.** {
2ba0: 41 31 32 30 31 36 7d 20 54 68 65 20 43 20 70 61  A12016} The C pa
2bb0: 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69  rameter to [sqli
2bc0: 74 65 33 5f 63 6c 6f 73 65 28 43 29 5d 20 6d 75  te3_close(C)] mu
2bd0: 73 74 20 62 65 20 65 69 74 68 65 72 20 61 20 4e  st be either a N
2be0: 55 4c 4c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ULL.**          
2bf0: 70 6f 69 6e 74 65 72 20 6f 72 20 61 6e 20 5b 73  pointer or an [s
2c00: 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 70  qlite3] object p
2c10: 6f 69 6e 74 65 72 20 6f 62 74 61 69 6e 65 64 0a  ointer obtained.
2c20: 2a 2a 20 20 20 20 20 20 20 20 20 20 66 72 6f 6d  **          from
2c30: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
2c40: 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ], [sqlite3_open
2c50: 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20  16()], or.**    
2c60: 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 6f        [sqlite3_o
2c70: 70 65 6e 5f 76 32 28 29 5d 2c 20 61 6e 64 20 6e  pen_v2()], and n
2c80: 6f 74 20 70 72 65 76 69 6f 75 73 6c 79 20 63 6c  ot previously cl
2c90: 6f 73 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  osed..*/.int sql
2ca0: 69 74 65 33 5f 63 6c 6f 73 65 28 73 71 6c 69 74  ite3_close(sqlit
2cb0: 65 33 20 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68  e3 *);../*.** Th
2cc0: 65 20 74 79 70 65 20 66 6f 72 20 61 20 63 61 6c  e type for a cal
2cd0: 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 2e 0a  lback function..
2ce0: 2a 2a 20 54 68 69 73 20 69 73 20 6c 65 67 61 63  ** This is legac
2cf0: 79 20 61 6e 64 20 64 65 70 72 65 63 61 74 65 64  y and deprecated
2d00: 2e 20 20 49 74 20 69 73 20 69 6e 63 6c 75 64 65  .  It is include
2d10: 64 20 66 6f 72 20 68 69 73 74 6f 72 69 63 61 6c  d for historical
2d20: 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  .** compatibilit
2d30: 79 20 61 6e 64 20 69 73 20 6e 6f 74 20 64 6f 63  y and is not doc
2d40: 75 6d 65 6e 74 65 64 2e 0a 2a 2f 0a 74 79 70 65  umented..*/.type
2d50: 64 65 66 20 69 6e 74 20 28 2a 73 71 6c 69 74 65  def int (*sqlite
2d60: 33 5f 63 61 6c 6c 62 61 63 6b 29 28 76 6f 69 64  3_callback)(void
2d70: 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 20 63 68  *,int,char**, ch
2d80: 61 72 2a 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ar**);../*.** CA
2d90: 50 49 33 52 45 46 3a 20 4f 6e 65 2d 53 74 65 70  PI3REF: One-Step
2da0: 20 51 75 65 72 79 20 45 78 65 63 75 74 69 6f 6e   Query Execution
2db0: 20 49 6e 74 65 72 66 61 63 65 20 7b 48 31 32 31   Interface {H121
2dc0: 30 30 7d 20 3c 53 31 30 30 30 30 3e 0a 2a 2a 0a  00} <S10000>.**.
2dd0: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 65  ** The sqlite3_e
2de0: 78 65 63 28 29 20 69 6e 74 65 72 66 61 63 65 20  xec() interface 
2df0: 69 73 20 61 20 63 6f 6e 76 65 6e 69 65 6e 74 20  is a convenient 
2e00: 77 61 79 20 6f 66 20 72 75 6e 6e 69 6e 67 20 6f  way of running o
2e10: 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 53 51  ne or more.** SQ
2e20: 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 77 69 74  L statements wit
2e30: 68 6f 75 74 20 68 61 76 69 6e 67 20 74 6f 20 77  hout having to w
2e40: 72 69 74 65 20 61 20 6c 6f 74 20 6f 66 20 43 20  rite a lot of C 
2e50: 63 6f 64 65 2e 20 20 54 68 65 20 55 54 46 2d 38  code.  The UTF-8
2e60: 20 65 6e 63 6f 64 65 64 0a 2a 2a 20 53 51 4c 20   encoded.** SQL 
2e70: 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 70  statements are p
2e80: 61 73 73 65 64 20 69 6e 20 61 73 20 74 68 65 20  assed in as the 
2e90: 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
2ea0: 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63   to sqlite3_exec
2eb0: 28 29 2e 0a 2a 2a 20 54 68 65 20 73 74 61 74 65  ()..** The state
2ec0: 6d 65 6e 74 73 20 61 72 65 20 65 76 61 6c 75 61  ments are evalua
2ed0: 74 65 64 20 6f 6e 65 20 62 79 20 6f 6e 65 20 75  ted one by one u
2ee0: 6e 74 69 6c 20 65 69 74 68 65 72 20 61 6e 20 65  ntil either an e
2ef0: 72 72 6f 72 20 6f 72 0a 2a 2a 20 61 6e 20 69 6e  rror or.** an in
2f00: 74 65 72 72 75 70 74 20 69 73 20 65 6e 63 6f 75  terrupt is encou
2f10: 6e 74 65 72 65 64 2c 20 6f 72 20 75 6e 74 69 6c  ntered, or until
2f20: 20 74 68 65 79 20 61 72 65 20 61 6c 6c 20 64 6f   they are all do
2f30: 6e 65 2e 20 20 54 68 65 20 33 72 64 20 70 61 72  ne.  The 3rd par
2f40: 61 6d 65 74 65 72 0a 2a 2a 20 69 73 20 61 6e 20  ameter.** is an 
2f50: 6f 70 74 69 6f 6e 61 6c 20 63 61 6c 6c 62 61 63  optional callbac
2f60: 6b 20 74 68 61 74 20 69 73 20 69 6e 76 6f 6b 65  k that is invoke
2f70: 64 20 6f 6e 63 65 20 66 6f 72 20 65 61 63 68 20  d once for each 
2f80: 72 6f 77 20 6f 66 20 61 6e 79 20 71 75 65 72 79  row of any query
2f90: 0a 2a 2a 20 72 65 73 75 6c 74 73 20 70 72 6f 64  .** results prod
2fa0: 75 63 65 64 20 62 79 20 74 68 65 20 53 51 4c 20  uced by the SQL 
2fb0: 73 74 61 74 65 6d 65 6e 74 73 2e 20 20 54 68 65  statements.  The
2fc0: 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   5th parameter t
2fd0: 65 6c 6c 73 20 77 68 65 72 65 0a 2a 2a 20 74 6f  ells where.** to
2fe0: 20 77 72 69 74 65 20 61 6e 79 20 65 72 72 6f 72   write any error
2ff0: 20 6d 65 73 73 61 67 65 73 2e 0a 2a 2a 0a 2a 2a   messages..**.**
3000: 20 54 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61   The error messa
3010: 67 65 20 70 61 73 73 65 64 20 62 61 63 6b 20 74  ge passed back t
3020: 68 72 6f 75 67 68 20 74 68 65 20 35 74 68 20 70  hrough the 5th p
3030: 61 72 61 6d 65 74 65 72 20 69 73 20 68 65 6c 64  arameter is held
3040: 0a 2a 2a 20 69 6e 20 6d 65 6d 6f 72 79 20 6f 62  .** in memory ob
3050: 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c  tained from [sql
3060: 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20  ite3_malloc()]. 
3070: 20 54 6f 20 61 76 6f 69 64 20 61 20 6d 65 6d 6f   To avoid a memo
3080: 72 79 20 6c 65 61 6b 2c 0a 2a 2a 20 74 68 65 20  ry leak,.** the 
3090: 63 61 6c 6c 69 6e 67 20 61 70 70 6c 69 63 61 74  calling applicat
30a0: 69 6f 6e 20 73 68 6f 75 6c 64 20 63 61 6c 6c 20  ion should call 
30b0: 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
30c0: 20 6f 6e 20 61 6e 79 20 65 72 72 6f 72 0a 2a 2a   on any error.**
30d0: 20 6d 65 73 73 61 67 65 20 72 65 74 75 72 6e 65   message returne
30e0: 64 20 74 68 72 6f 75 67 68 20 74 68 65 20 35 74  d through the 5t
30f0: 68 20 70 61 72 61 6d 65 74 65 72 20 77 68 65 6e  h parameter when
3100: 20 69 74 20 68 61 73 20 66 69 6e 69 73 68 65 64   it has finished
3110: 20 75 73 69 6e 67 0a 2a 2a 20 74 68 65 20 65 72   using.** the er
3120: 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a  ror message..**.
3130: 2a 2a 20 49 66 20 74 68 65 20 53 51 4c 20 73 74  ** If the SQL st
3140: 61 74 65 6d 65 6e 74 20 69 6e 20 74 68 65 20 32  atement in the 2
3150: 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  nd parameter is 
3160: 4e 55 4c 4c 20 6f 72 20 61 6e 20 65 6d 70 74 79  NULL or an empty
3170: 20 73 74 72 69 6e 67 0a 2a 2a 20 6f 72 20 61 20   string.** or a 
3180: 73 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e 69 6e  string containin
3190: 67 20 6f 6e 6c 79 20 77 68 69 74 65 73 70 61 63  g only whitespac
31a0: 65 20 61 6e 64 20 63 6f 6d 6d 65 6e 74 73 2c 20  e and comments, 
31b0: 74 68 65 6e 20 6e 6f 20 53 51 4c 0a 2a 2a 20 73  then no SQL.** s
31c0: 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 65 76  tatements are ev
31d0: 61 6c 75 61 74 65 64 20 61 6e 64 20 74 68 65 20  aluated and the 
31e0: 64 61 74 61 62 61 73 65 20 69 73 20 6e 6f 74 20  database is not 
31f0: 63 68 61 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  changed..**.** T
3200: 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  he sqlite3_exec(
3210: 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 69  ) interface is i
3220: 6d 70 6c 65 6d 65 6e 74 65 64 20 69 6e 20 74 65  mplemented in te
3230: 72 6d 73 20 6f 66 0a 2a 2a 20 5b 73 71 6c 69 74  rms of.** [sqlit
3240: 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
3250: 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  , [sqlite3_step(
3260: 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  )], and [sqlite3
3270: 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a  _finalize()]..**
3280: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65   The sqlite3_exe
3290: 63 28 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 73  c() routine does
32a0: 20 6e 6f 74 68 69 6e 67 20 74 6f 20 74 68 65 20   nothing to the 
32b0: 64 61 74 61 62 61 73 65 20 74 68 61 74 20 63 61  database that ca
32c0: 6e 6e 6f 74 20 62 65 20 64 6f 6e 65 0a 2a 2a 20  nnot be done.** 
32d0: 62 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  by [sqlite3_prep
32e0: 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69  are_v2()], [sqli
32f0: 74 65 33 5f 73 74 65 70 28 29 5d 2c 20 61 6e 64  te3_step()], and
3300: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
3310: 7a 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56  ze()]..**.** INV
3320: 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
3330: 48 31 32 31 30 31 7d 20 41 20 73 75 63 63 65 73  H12101} A succes
3340: 73 66 75 6c 20 69 6e 76 6f 63 61 74 69 6f 6e 20  sful invocation 
3350: 6f 66 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63  of [sqlite3_exec
3360: 28 44 2c 53 2c 43 2c 41 2c 45 29 5d 0a 2a 2a 20  (D,S,C,A,E)].** 
3370: 20 20 20 20 20 20 20 20 20 73 68 61 6c 6c 20 73           shall s
3380: 65 71 75 65 6e 74 69 61 6c 6c 79 20 65 76 61 6c  equentially eval
3390: 75 61 74 65 20 61 6c 6c 20 6f 66 20 74 68 65 20  uate all of the 
33a0: 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 2c 0a 2a  UTF-8 encoded,.*
33b0: 2a 20 20 20 20 20 20 20 20 20 20 73 65 6d 69 63  *          semic
33c0: 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 65 64 20 53  olon-separated S
33d0: 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69 6e  QL statements in
33e0: 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e   the zero-termin
33f0: 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20  ated.**         
3400: 20 73 74 72 69 6e 67 20 53 20 77 69 74 68 69 6e   string S within
3410: 20 74 68 65 20 63 6f 6e 74 65 78 74 20 6f 66 20   the context of 
3420: 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
3430: 6e 6e 65 63 74 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a  nnection] D..**.
3440: 2a 2a 20 7b 48 31 32 31 30 32 7d 20 49 66 20 74  ** {H12102} If t
3450: 68 65 20 53 20 70 61 72 61 6d 65 74 65 72 20 74  he S parameter t
3460: 6f 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28  o [sqlite3_exec(
3470: 44 2c 53 2c 43 2c 41 2c 45 29 5d 20 69 73 20 4e  D,S,C,A,E)] is N
3480: 55 4c 4c 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20  ULL then.**     
3490: 20 20 20 20 20 74 68 65 20 61 63 74 69 6f 6e 73       the actions
34a0: 20 6f 66 20 74 68 65 20 69 6e 74 65 72 66 61 63   of the interfac
34b0: 65 20 73 68 61 6c 6c 20 62 65 20 74 68 65 20 73  e shall be the s
34c0: 61 6d 65 20 61 73 20 69 66 20 74 68 65 0a 2a 2a  ame as if the.**
34d0: 20 20 20 20 20 20 20 20 20 20 53 20 70 61 72 61            S para
34e0: 6d 65 74 65 72 20 77 65 72 65 20 61 6e 20 65 6d  meter were an em
34f0: 70 74 79 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a  pty string..**.*
3500: 2a 20 7b 48 31 32 31 30 34 7d 20 54 68 65 20 72  * {H12104} The r
3510: 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 5b  eturn value of [
3520: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20  sqlite3_exec()] 
3530: 73 68 61 6c 6c 20 62 65 20 5b 53 51 4c 49 54 45  shall be [SQLITE
3540: 5f 4f 4b 5d 20 69 66 20 61 6c 6c 0a 2a 2a 20 20  _OK] if all.**  
3550: 20 20 20 20 20 20 20 20 53 51 4c 20 73 74 61 74          SQL stat
3560: 65 6d 65 6e 74 73 20 72 75 6e 20 73 75 63 63 65  ements run succe
3570: 73 73 66 75 6c 6c 79 20 61 6e 64 20 74 6f 20 63  ssfully and to c
3580: 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  ompletion..**.**
3590: 20 7b 48 31 32 31 30 35 7d 20 54 68 65 20 72 65   {H12105} The re
35a0: 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 5b 73  turn value of [s
35b0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 73  qlite3_exec()] s
35c0: 68 61 6c 6c 20 62 65 20 61 6e 20 61 70 70 72 6f  hall be an appro
35d0: 70 72 69 61 74 65 0a 2a 2a 20 20 20 20 20 20 20  priate.**       
35e0: 20 20 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72     non-zero [err
35f0: 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 6e 79 20  or code] if any 
3600: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 66 61  SQL statement fa
3610: 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 31  ils..**.** {H121
3620: 30 37 7d 20 49 66 20 6f 6e 65 20 6f 72 20 6d 6f  07} If one or mo
3630: 72 65 20 6f 66 20 74 68 65 20 53 51 4c 20 73 74  re of the SQL st
3640: 61 74 65 6d 65 6e 74 73 20 68 61 6e 64 65 64 20  atements handed 
3650: 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63  to [sqlite3_exec
3660: 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ()].**          
3670: 72 65 74 75 72 6e 20 72 65 73 75 6c 74 73 20 61  return results a
3680: 6e 64 20 74 68 65 20 33 72 64 20 70 61 72 61 6d  nd the 3rd param
3690: 65 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  eter is not NULL
36a0: 2c 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20  , then.**       
36b0: 20 20 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20     the callback 
36c0: 66 75 6e 63 74 69 6f 6e 20 73 70 65 63 69 66 69  function specifi
36d0: 65 64 20 62 79 20 74 68 65 20 33 72 64 20 70 61  ed by the 3rd pa
36e0: 72 61 6d 65 74 65 72 20 73 68 61 6c 6c 20 62 65  rameter shall be
36f0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 76  .**          inv
3700: 6f 6b 65 64 20 6f 6e 63 65 20 66 6f 72 20 65 61  oked once for ea
3710: 63 68 20 72 6f 77 20 6f 66 20 72 65 73 75 6c 74  ch row of result
3720: 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 31 31 30 7d  ..**.** {H12110}
3730: 20 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   If the callback
3740: 20 72 65 74 75 72 6e 73 20 61 20 6e 6f 6e 2d 7a   returns a non-z
3750: 65 72 6f 20 76 61 6c 75 65 20 74 68 65 6e 20 5b  ero value then [
3760: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 0a  sqlite3_exec()].
3770: 2a 2a 20 20 20 20 20 20 20 20 20 20 73 68 61 6c  **          shal
3780: 6c 20 61 62 6f 72 74 20 74 68 65 20 53 51 4c 20  l abort the SQL 
3790: 73 74 61 74 65 6d 65 6e 74 20 69 74 20 69 73 20  statement it is 
37a0: 63 75 72 72 65 6e 74 6c 79 20 65 76 61 6c 75 61  currently evalua
37b0: 74 69 6e 67 2c 0a 2a 2a 20 20 20 20 20 20 20 20  ting,.**        
37c0: 20 20 73 6b 69 70 20 61 6c 6c 20 73 75 62 73 65    skip all subse
37d0: 71 75 65 6e 74 20 53 51 4c 20 73 74 61 74 65 6d  quent SQL statem
37e0: 65 6e 74 73 2c 20 61 6e 64 20 72 65 74 75 72 6e  ents, and return
37f0: 20 5b 53 51 4c 49 54 45 5f 41 42 4f 52 54 5d 2e   [SQLITE_ABORT].
3800: 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 31 31 33 7d 20  .**.** {H12113} 
3810: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 65 78 65  The [sqlite3_exe
3820: 63 28 29 5d 20 72 6f 75 74 69 6e 65 20 73 68 61  c()] routine sha
3830: 6c 6c 20 70 61 73 73 20 69 74 73 20 34 74 68 20  ll pass its 4th 
3840: 70 61 72 61 6d 65 74 65 72 20 74 68 72 6f 75 67  parameter throug
3850: 68 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 73  h.**          as
3860: 20 74 68 65 20 31 73 74 20 70 61 72 61 6d 65 74   the 1st paramet
3870: 65 72 20 6f 66 20 74 68 65 20 63 61 6c 6c 62 61  er of the callba
3880: 63 6b 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 31 31  ck..**.** {H1211
3890: 36 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  6} The [sqlite3_
38a0: 65 78 65 63 28 29 5d 20 72 6f 75 74 69 6e 65 20  exec()] routine 
38b0: 73 68 61 6c 6c 20 73 65 74 20 74 68 65 20 32 6e  shall set the 2n
38c0: 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 69  d parameter of i
38d0: 74 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63  ts.**          c
38e0: 61 6c 6c 62 61 63 6b 20 74 6f 20 62 65 20 74 68  allback to be th
38f0: 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  e number of colu
3900: 6d 6e 73 20 69 6e 20 74 68 65 20 63 75 72 72 65  mns in the curre
3910: 6e 74 20 72 6f 77 20 6f 66 0a 2a 2a 20 20 20 20  nt row of.**    
3920: 20 20 20 20 20 20 72 65 73 75 6c 74 2e 0a 2a 2a        result..**
3930: 0a 2a 2a 20 7b 48 31 32 31 31 39 7d 20 54 68 65  .** {H12119} The
3940: 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29   [sqlite3_exec()
3950: 5d 20 72 6f 75 74 69 6e 65 20 73 68 61 6c 6c 20  ] routine shall 
3960: 73 65 74 20 74 68 65 20 33 72 64 20 70 61 72 61  set the 3rd para
3970: 6d 65 74 65 72 20 6f 66 20 69 74 73 0a 2a 2a 20  meter of its.** 
3980: 20 20 20 20 20 20 20 20 20 63 61 6c 6c 62 61 63           callbac
3990: 6b 20 74 6f 20 62 65 20 61 6e 20 61 72 72 61 79  k to be an array
39a0: 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20   of pointers to 
39b0: 73 74 72 69 6e 67 73 20 68 6f 6c 64 69 6e 67 20  strings holding 
39c0: 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
39d0: 76 61 6c 75 65 73 20 66 6f 72 20 65 61 63 68 20  values for each 
39e0: 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 20 63 75  column in the cu
39f0: 72 72 65 6e 74 20 72 65 73 75 6c 74 20 73 65 74  rrent result set
3a00: 20 72 6f 77 20 61 73 0a 2a 2a 20 20 20 20 20 20   row as.**      
3a10: 20 20 20 20 6f 62 74 61 69 6e 65 64 20 66 72 6f      obtained fro
3a20: 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  m [sqlite3_colum
3a30: 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a  n_text()]..**.**
3a40: 20 7b 48 31 32 31 32 32 7d 20 54 68 65 20 5b 73   {H12122} The [s
3a50: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 72  qlite3_exec()] r
3a60: 6f 75 74 69 6e 65 20 73 68 61 6c 6c 20 73 65 74  outine shall set
3a70: 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74   the 4th paramet
3a80: 65 72 20 6f 66 20 69 74 73 0a 2a 2a 20 20 20 20  er of its.**    
3a90: 20 20 20 20 20 20 63 61 6c 6c 62 61 63 6b 20 74        callback t
3aa0: 6f 20 62 65 20 61 6e 20 61 72 72 61 79 20 6f 66  o be an array of
3ab0: 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72   pointers to str
3ac0: 69 6e 67 73 20 68 6f 6c 64 69 6e 67 20 74 68 65  ings holding the
3ad0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 61 6d  .**          nam
3ae0: 65 73 20 6f 66 20 72 65 73 75 6c 74 20 63 6f 6c  es of result col
3af0: 75 6d 6e 73 20 61 73 20 6f 62 74 61 69 6e 65 64  umns as obtained
3b00: 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63   from [sqlite3_c
3b10: 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 5d 2e 0a 2a  olumn_name()]..*
3b20: 2a 0a 2a 2a 20 7b 48 31 32 31 32 35 7d 20 49 66  *.** {H12125} If
3b30: 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74   the 3rd paramet
3b40: 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65  er to [sqlite3_e
3b50: 78 65 63 28 29 5d 20 69 73 20 4e 55 4c 4c 20 74  xec()] is NULL t
3b60: 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  hen.**          
3b70: 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d  [sqlite3_exec()]
3b80: 20 73 68 61 6c 6c 20 73 69 6c 65 6e 74 6c 79 20   shall silently 
3b90: 64 69 73 63 61 72 64 20 71 75 65 72 79 20 72 65  discard query re
3ba0: 73 75 6c 74 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  sults..**.** {H1
3bb0: 32 31 33 31 7d 20 49 66 20 61 6e 20 65 72 72 6f  2131} If an erro
3bc0: 72 20 6f 63 63 75 72 73 20 77 68 69 6c 65 20 70  r occurs while p
3bd0: 61 72 73 69 6e 67 20 6f 72 20 65 76 61 6c 75 61  arsing or evalua
3be0: 74 69 6e 67 20 61 6e 79 20 6f 66 20 74 68 65 20  ting any of the 
3bf0: 53 51 4c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  SQL.**          
3c00: 73 74 61 74 65 6d 65 6e 74 73 20 69 6e 20 74 68  statements in th
3c10: 65 20 53 20 70 61 72 61 6d 65 74 65 72 20 6f 66  e S parameter of
3c20: 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 44   [sqlite3_exec(D
3c30: 2c 53 2c 43 2c 41 2c 45 29 5d 20 61 6e 64 20 69  ,S,C,A,E)] and i
3c40: 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  f.**          th
3c50: 65 20 45 20 70 61 72 61 6d 65 74 65 72 20 69 73  e E parameter is
3c60: 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20   not NULL, then 
3c70: 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d  [sqlite3_exec()]
3c80: 20 73 68 61 6c 6c 20 73 74 6f 72 65 0a 2a 2a 20   shall store.** 
3c90: 20 20 20 20 20 20 20 20 20 69 6e 20 2a 45 20 61           in *E a
3ca0: 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20 65 72  n appropriate er
3cb0: 72 6f 72 20 6d 65 73 73 61 67 65 20 77 72 69 74  ror message writ
3cc0: 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20  ten into memory 
3cd0: 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 20 20 20 20  obtained.**     
3ce0: 20 20 20 20 20 66 72 6f 6d 20 5b 73 71 6c 69 74       from [sqlit
3cf0: 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a  e3_malloc()]..**
3d00: 0a 2a 2a 20 7b 48 31 32 31 33 34 7d 20 54 68 65  .** {H12134} The
3d10: 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 44   [sqlite3_exec(D
3d20: 2c 53 2c 43 2c 41 2c 45 29 5d 20 72 6f 75 74 69  ,S,C,A,E)] routi
3d30: 6e 65 20 73 68 61 6c 6c 20 73 65 74 20 74 68 65  ne shall set the
3d40: 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 20 20 20   value of.**    
3d50: 20 20 20 20 20 20 2a 45 20 74 6f 20 4e 55 4c 4c        *E to NULL
3d60: 20 69 66 20 45 20 69 73 20 6e 6f 74 20 4e 55 4c   if E is not NUL
3d70: 4c 20 61 6e 64 20 74 68 65 72 65 20 61 72 65 20  L and there are 
3d80: 6e 6f 20 65 72 72 6f 72 73 2e 0a 2a 2a 0a 2a 2a  no errors..**.**
3d90: 20 7b 48 31 32 31 33 37 7d 20 54 68 65 20 5b 73   {H12137} The [s
3da0: 71 6c 69 74 65 33 5f 65 78 65 63 28 44 2c 53 2c  qlite3_exec(D,S,
3db0: 43 2c 41 2c 45 29 5d 20 66 75 6e 63 74 69 6f 6e  C,A,E)] function
3dc0: 20 73 68 61 6c 6c 20 73 65 74 20 74 68 65 20 5b   shall set the [
3dd0: 65 72 72 6f 72 20 63 6f 64 65 5d 0a 2a 2a 20 20  error code].**  
3de0: 20 20 20 20 20 20 20 20 61 6e 64 20 6d 65 73 73          and mess
3df0: 61 67 65 20 61 63 63 65 73 73 69 62 6c 65 20 76  age accessible v
3e00: 69 61 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63  ia [sqlite3_errc
3e10: 6f 64 65 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 20  ode()],.**      
3e20: 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 65 72 72      [sqlite3_err
3e30: 6d 73 67 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c  msg()], and [sql
3e40: 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 5d  ite3_errmsg16()]
3e50: 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 31 33 38 7d  ..**.** {H12138}
3e60: 20 49 66 20 74 68 65 20 53 20 70 61 72 61 6d 65   If the S parame
3e70: 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ter to [sqlite3_
3e80: 65 78 65 63 28 44 2c 53 2c 43 2c 41 2c 45 29 5d  exec(D,S,C,A,E)]
3e90: 20 69 73 20 4e 55 4c 4c 20 6f 72 20 61 6e 0a 2a   is NULL or an.*
3ea0: 2a 20 20 20 20 20 20 20 20 20 20 65 6d 70 74 79  *          empty
3eb0: 20 73 74 72 69 6e 67 20 6f 72 20 63 6f 6e 74 61   string or conta
3ec0: 69 6e 73 20 6e 6f 74 68 69 6e 67 20 6f 74 68 65  ins nothing othe
3ed0: 72 20 74 68 61 6e 20 77 68 69 74 65 73 70 61 63  r than whitespac
3ee0: 65 2c 20 63 6f 6d 6d 65 6e 74 73 2c 0a 2a 2a 20  e, comments,.** 
3ef0: 20 20 20 20 20 20 20 20 20 61 6e 64 2f 6f 72 20           and/or 
3f00: 73 65 6d 69 63 6f 6c 6f 6e 73 2c 20 74 68 65 6e  semicolons, then
3f10: 20 72 65 73 75 6c 74 73 20 6f 66 20 5b 73 71 6c   results of [sql
3f20: 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 2c  ite3_errcode()],
3f30: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
3f40: 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2c  lite3_errmsg()],
3f50: 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 65 72   and [sqlite3_er
3f60: 72 6d 73 67 31 36 28 29 5d 0a 2a 2a 20 20 20 20  rmsg16()].**    
3f70: 20 20 20 20 20 20 73 68 61 6c 6c 20 72 65 73 65        shall rese
3f80: 74 20 74 6f 20 69 6e 64 69 63 61 74 65 20 6e 6f  t to indicate no
3f90: 20 65 72 72 6f 72 73 2e 0a 2a 2a 0a 2a 2a 20 41   errors..**.** A
3fa0: 53 53 55 4d 50 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a  SSUMPTIONS:.**.*
3fb0: 2a 20 7b 41 31 32 31 34 31 7d 20 54 68 65 20 66  * {A12141} The f
3fc0: 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74  irst parameter t
3fd0: 6f 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28  o [sqlite3_exec(
3fe0: 29 5d 20 6d 75 73 74 20 62 65 20 61 6e 20 76 61  )] must be an va
3ff0: 6c 69 64 20 61 6e 64 20 6f 70 65 6e 0a 2a 2a 20  lid and open.** 
4000: 20 20 20 20 20 20 20 20 20 5b 64 61 74 61 62 61           [databa
4010: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a  se connection]..
4020: 2a 2a 0a 2a 2a 20 7b 41 31 32 31 34 32 7d 20 54  **.** {A12142} T
4030: 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
4040: 65 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20  ection must not 
4050: 62 65 20 63 6c 6f 73 65 64 20 77 68 69 6c 65 0a  be closed while.
4060: 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
4070: 69 74 65 33 5f 65 78 65 63 28 29 5d 20 69 73 20  ite3_exec()] is 
4080: 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b  running..**.** {
4090: 41 31 32 31 34 33 7d 20 54 68 65 20 63 61 6c 6c  A12143} The call
40a0: 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f  ing function sho
40b0: 75 6c 64 20 75 73 65 20 5b 73 71 6c 69 74 65 33  uld use [sqlite3
40c0: 5f 66 72 65 65 28 29 5d 20 74 6f 20 66 72 65 65  _free()] to free
40d0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
40e0: 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 2a 65 72   memory that *er
40f0: 72 6d 73 67 20 69 73 20 6c 65 66 74 20 70 6f 69  rmsg is left poi
4100: 6e 74 69 6e 67 20 61 74 20 6f 6e 63 65 20 74 68  nting at once th
4110: 65 20 65 72 72 6f 72 0a 2a 2a 20 20 20 20 20 20  e error.**      
4120: 20 20 20 20 6d 65 73 73 61 67 65 20 69 73 20 6e      message is n
4130: 6f 20 6c 6f 6e 67 65 72 20 6e 65 65 64 65 64 2e  o longer needed.
4140: 0a 2a 2a 0a 2a 2a 20 7b 41 31 32 31 34 35 7d 20  .**.** {A12145} 
4150: 54 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  The SQL statemen
4160: 74 20 74 65 78 74 20 69 6e 20 74 68 65 20 32 6e  t text in the 2n
4170: 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  d parameter to [
4180: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 0a  sqlite3_exec()].
4190: 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 75 73 74  **          must
41a0: 20 72 65 6d 61 69 6e 20 75 6e 63 68 61 6e 67 65   remain unchange
41b0: 64 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33  d while [sqlite3
41c0: 5f 65 78 65 63 28 29 5d 20 69 73 20 72 75 6e 6e  _exec()] is runn
41d0: 69 6e 67 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ing..*/.int sqli
41e0: 74 65 33 5f 65 78 65 63 28 0a 20 20 73 71 6c 69  te3_exec(.  sqli
41f0: 74 65 33 2a 2c 20 20 20 20 20 20 20 20 20 20 20  te3*,           
4200: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4210: 20 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65         /* An ope
4220: 6e 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 20  n database */.  
4230: 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 2c  const char *sql,
4240: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4250: 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 51             /* SQ
4260: 4c 20 74 6f 20 62 65 20 65 76 61 6c 75 61 74 65  L to be evaluate
4270: 64 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 63 61 6c  d */.  int (*cal
4280: 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e 74  lback)(void*,int
4290: 2c 63 68 61 72 2a 2a 2c 63 68 61 72 2a 2a 29 2c  ,char**,char**),
42a0: 20 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 66 75    /* Callback fu
42b0: 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64  nction */.  void
42c0: 20 2a 2c 20 20 20 20 20 20 20 20 20 20 20 20 20   *,             
42d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
42e0: 20 20 20 20 20 20 20 2f 2a 20 31 73 74 20 61 72         /* 1st ar
42f0: 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 62 61  gument to callba
4300: 63 6b 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 65  ck */.  char **e
4310: 72 72 6d 73 67 20 20 20 20 20 20 20 20 20 20 20  rrmsg           
4320: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4330: 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20     /* Error msg 
4340: 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a  written here */.
4350: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
4360: 45 46 3a 20 52 65 73 75 6c 74 20 43 6f 64 65 73  EF: Result Codes
4370: 20 7b 48 31 30 32 31 30 7d 20 3c 53 31 30 37 30   {H10210} <S1070
4380: 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  0>.** KEYWORDS: 
4390: 53 51 4c 49 54 45 5f 4f 4b 20 7b 65 72 72 6f 72  SQLITE_OK {error
43a0: 20 63 6f 64 65 7d 20 7b 65 72 72 6f 72 20 63 6f   code} {error co
43b0: 64 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  des}.** KEYWORDS
43c0: 3a 20 7b 72 65 73 75 6c 74 20 63 6f 64 65 7d 20  : {result code} 
43d0: 7b 72 65 73 75 6c 74 20 63 6f 64 65 73 7d 0a 2a  {result codes}.*
43e0: 2a 0a 2a 2a 20 4d 61 6e 79 20 53 51 4c 69 74 65  *.** Many SQLite
43f0: 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72   functions retur
4400: 6e 20 61 6e 20 69 6e 74 65 67 65 72 20 72 65 73  n an integer res
4410: 75 6c 74 20 63 6f 64 65 20 66 72 6f 6d 20 74 68  ult code from th
4420: 65 20 73 65 74 20 73 68 6f 77 6e 0a 2a 2a 20 68  e set shown.** h
4430: 65 72 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  ere in order to 
4440: 69 6e 64 69 63 61 74 65 73 20 73 75 63 63 65 73  indicates succes
4450: 73 20 6f 72 20 66 61 69 6c 75 72 65 2e 0a 2a 2a  s or failure..**
4460: 0a 2a 2a 20 4e 65 77 20 65 72 72 6f 72 20 63 6f  .** New error co
4470: 64 65 73 20 6d 61 79 20 62 65 20 61 64 64 65 64  des may be added
4480: 20 69 6e 20 66 75 74 75 72 65 20 76 65 72 73 69   in future versi
4490: 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  ons of SQLite..*
44a0: 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
44b0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 41  SQLITE_IOERR_REA
44c0: 44 20 7c 20 65 78 74 65 6e 64 65 64 20 72 65 73  D | extended res
44d0: 75 6c 74 20 63 6f 64 65 73 5d 0a 2a 2f 0a 23 64  ult codes].*/.#d
44e0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 4b 20  efine SQLITE_OK 
44f0: 20 20 20 20 20 20 20 20 20 20 30 20 20 20 2f 2a            0   /*
4500: 20 53 75 63 63 65 73 73 66 75 6c 20 72 65 73 75   Successful resu
4510: 6c 74 20 2a 2f 0a 2f 2a 20 62 65 67 69 6e 6e 69  lt */./* beginni
4520: 6e 67 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f 64 65  ng-of-error-code
4530: 73 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  s */.#define SQL
4540: 49 54 45 5f 45 52 52 4f 52 20 20 20 20 20 20 20  ITE_ERROR       
4550: 20 31 20 20 20 2f 2a 20 53 51 4c 20 65 72 72 6f   1   /* SQL erro
4560: 72 20 6f 72 20 6d 69 73 73 69 6e 67 20 64 61 74  r or missing dat
4570: 61 62 61 73 65 20 2a 2f 0a 23 64 65 66 69 6e 65  abase */.#define
4580: 20 53 51 4c 49 54 45 5f 49 4e 54 45 52 4e 41 4c   SQLITE_INTERNAL
4590: 20 20 20 20 20 32 20 20 20 2f 2a 20 49 6e 74 65       2   /* Inte
45a0: 72 6e 61 6c 20 6c 6f 67 69 63 20 65 72 72 6f 72  rnal logic error
45b0: 20 69 6e 20 53 51 4c 69 74 65 20 2a 2f 0a 23 64   in SQLite */.#d
45c0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 45 52  efine SQLITE_PER
45d0: 4d 20 20 20 20 20 20 20 20 20 33 20 20 20 2f 2a  M         3   /*
45e0: 20 41 63 63 65 73 73 20 70 65 72 6d 69 73 73 69   Access permissi
45f0: 6f 6e 20 64 65 6e 69 65 64 20 2a 2f 0a 23 64 65  on denied */.#de
4600: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 42 4f 52  fine SQLITE_ABOR
4610: 54 20 20 20 20 20 20 20 20 34 20 20 20 2f 2a 20  T        4   /* 
4620: 43 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65  Callback routine
4630: 20 72 65 71 75 65 73 74 65 64 20 61 6e 20 61 62   requested an ab
4640: 6f 72 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ort */.#define S
4650: 51 4c 49 54 45 5f 42 55 53 59 20 20 20 20 20 20  QLITE_BUSY      
4660: 20 20 20 35 20 20 20 2f 2a 20 54 68 65 20 64 61     5   /* The da
4670: 74 61 62 61 73 65 20 66 69 6c 65 20 69 73 20 6c  tabase file is l
4680: 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  ocked */.#define
4690: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 20 20   SQLITE_LOCKED  
46a0: 20 20 20 20 20 36 20 20 20 2f 2a 20 41 20 74 61       6   /* A ta
46b0: 62 6c 65 20 69 6e 20 74 68 65 20 64 61 74 61 62  ble in the datab
46c0: 61 73 65 20 69 73 20 6c 6f 63 6b 65 64 20 2a 2f  ase is locked */
46d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
46e0: 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 37 20 20  NOMEM        7  
46f0: 20 2f 2a 20 41 20 6d 61 6c 6c 6f 63 28 29 20 66   /* A malloc() f
4700: 61 69 6c 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  ailed */.#define
4710: 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59   SQLITE_READONLY
4720: 20 20 20 20 20 38 20 20 20 2f 2a 20 41 74 74 65       8   /* Atte
4730: 6d 70 74 20 74 6f 20 77 72 69 74 65 20 61 20 72  mpt to write a r
4740: 65 61 64 6f 6e 6c 79 20 64 61 74 61 62 61 73 65  eadonly database
4750: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4760: 54 45 5f 49 4e 54 45 52 52 55 50 54 20 20 20 20  TE_INTERRUPT    
4770: 39 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e  9   /* Operation
4780: 20 74 65 72 6d 69 6e 61 74 65 64 20 62 79 20 73   terminated by s
4790: 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
47a0: 28 29 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ()*/.#define SQL
47b0: 49 54 45 5f 49 4f 45 52 52 20 20 20 20 20 20 20  ITE_IOERR       
47c0: 31 30 20 20 20 2f 2a 20 53 6f 6d 65 20 6b 69 6e  10   /* Some kin
47d0: 64 20 6f 66 20 64 69 73 6b 20 49 2f 4f 20 65 72  d of disk I/O er
47e0: 72 6f 72 20 6f 63 63 75 72 72 65 64 20 2a 2f 0a  ror occurred */.
47f0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
4800: 4f 52 52 55 50 54 20 20 20 20 20 31 31 20 20 20  ORRUPT     11   
4810: 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73 65 20  /* The database 
4820: 64 69 73 6b 20 69 6d 61 67 65 20 69 73 20 6d 61  disk image is ma
4830: 6c 66 6f 72 6d 65 64 20 2a 2f 0a 23 64 65 66 69  lformed */.#defi
4840: 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55  ne SQLITE_NOTFOU
4850: 4e 44 20 20 20 20 31 32 20 20 20 2f 2a 20 4e 4f  ND    12   /* NO
4860: 54 20 55 53 45 44 2e 20 54 61 62 6c 65 20 6f 72  T USED. Table or
4870: 20 72 65 63 6f 72 64 20 6e 6f 74 20 66 6f 75 6e   record not foun
4880: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
4890: 49 54 45 5f 46 55 4c 4c 20 20 20 20 20 20 20 20  ITE_FULL        
48a0: 31 33 20 20 20 2f 2a 20 49 6e 73 65 72 74 69 6f  13   /* Insertio
48b0: 6e 20 66 61 69 6c 65 64 20 62 65 63 61 75 73 65  n failed because
48c0: 20 64 61 74 61 62 61 73 65 20 69 73 20 66 75 6c   database is ful
48d0: 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  l */.#define SQL
48e0: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 20 20 20  ITE_CANTOPEN    
48f0: 31 34 20 20 20 2f 2a 20 55 6e 61 62 6c 65 20 74  14   /* Unable t
4900: 6f 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62  o open the datab
4910: 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66  ase file */.#def
4920: 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 4f 54 4f  ine SQLITE_PROTO
4930: 43 4f 4c 20 20 20 20 31 35 20 20 20 2f 2a 20 4e  COL    15   /* N
4940: 4f 54 20 55 53 45 44 2e 20 44 61 74 61 62 61 73  OT USED. Databas
4950: 65 20 6c 6f 63 6b 20 70 72 6f 74 6f 63 6f 6c 20  e lock protocol 
4960: 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65  error */.#define
4970: 20 53 51 4c 49 54 45 5f 45 4d 50 54 59 20 20 20   SQLITE_EMPTY   
4980: 20 20 20 20 31 36 20 20 20 2f 2a 20 44 61 74 61      16   /* Data
4990: 62 61 73 65 20 69 73 20 65 6d 70 74 79 20 2a 2f  base is empty */
49a0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
49b0: 53 43 48 45 4d 41 20 20 20 20 20 20 31 37 20 20  SCHEMA      17  
49c0: 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73 65   /* The database
49d0: 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 64 20   schema changed 
49e0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
49f0: 45 5f 54 4f 4f 42 49 47 20 20 20 20 20 20 31 38  E_TOOBIG      18
4a00: 20 20 20 2f 2a 20 53 74 72 69 6e 67 20 6f 72 20     /* String or 
4a10: 42 4c 4f 42 20 65 78 63 65 65 64 73 20 73 69 7a  BLOB exceeds siz
4a20: 65 20 6c 69 6d 69 74 20 2a 2f 0a 23 64 65 66 69  e limit */.#defi
4a30: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52  ne SQLITE_CONSTR
4a40: 41 49 4e 54 20 20 31 39 20 20 20 2f 2a 20 41 62  AINT  19   /* Ab
4a50: 6f 72 74 20 64 75 65 20 74 6f 20 63 6f 6e 73 74  ort due to const
4a60: 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20  raint violation 
4a70: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4a80: 45 5f 4d 49 53 4d 41 54 43 48 20 20 20 20 32 30  E_MISMATCH    20
4a90: 20 20 20 2f 2a 20 44 61 74 61 20 74 79 70 65 20     /* Data type 
4aa0: 6d 69 73 6d 61 74 63 68 20 2a 2f 0a 23 64 65 66  mismatch */.#def
4ab0: 69 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53 55 53  ine SQLITE_MISUS
4ac0: 45 20 20 20 20 20 20 32 31 20 20 20 2f 2a 20 4c  E      21   /* L
4ad0: 69 62 72 61 72 79 20 75 73 65 64 20 69 6e 63 6f  ibrary used inco
4ae0: 72 72 65 63 74 6c 79 20 2a 2f 0a 23 64 65 66 69  rrectly */.#defi
4af0: 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4c 46 53 20  ne SQLITE_NOLFS 
4b00: 20 20 20 20 20 20 32 32 20 20 20 2f 2a 20 55 73        22   /* Us
4b10: 65 73 20 4f 53 20 66 65 61 74 75 72 65 73 20 6e  es OS features n
4b20: 6f 74 20 73 75 70 70 6f 72 74 65 64 20 6f 6e 20  ot supported on 
4b30: 68 6f 73 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20  host */.#define 
4b40: 53 51 4c 49 54 45 5f 41 55 54 48 20 20 20 20 20  SQLITE_AUTH     
4b50: 20 20 20 32 33 20 20 20 2f 2a 20 41 75 74 68 6f     23   /* Autho
4b60: 72 69 7a 61 74 69 6f 6e 20 64 65 6e 69 65 64 20  rization denied 
4b70: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4b80: 45 5f 46 4f 52 4d 41 54 20 20 20 20 20 20 32 34  E_FORMAT      24
4b90: 20 20 20 2f 2a 20 41 75 78 69 6c 69 61 72 79 20     /* Auxiliary 
4ba0: 64 61 74 61 62 61 73 65 20 66 6f 72 6d 61 74 20  database format 
4bb0: 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65  error */.#define
4bc0: 20 53 51 4c 49 54 45 5f 52 41 4e 47 45 20 20 20   SQLITE_RANGE   
4bd0: 20 20 20 20 32 35 20 20 20 2f 2a 20 32 6e 64 20      25   /* 2nd 
4be0: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
4bf0: 69 74 65 33 5f 62 69 6e 64 20 6f 75 74 20 6f 66  ite3_bind out of
4c00: 20 72 61 6e 67 65 20 2a 2f 0a 23 64 65 66 69 6e   range */.#defin
4c10: 65 20 53 51 4c 49 54 45 5f 4e 4f 54 41 44 42 20  e SQLITE_NOTADB 
4c20: 20 20 20 20 20 32 36 20 20 20 2f 2a 20 46 69 6c       26   /* Fil
4c30: 65 20 6f 70 65 6e 65 64 20 74 68 61 74 20 69 73  e opened that is
4c40: 20 6e 6f 74 20 61 20 64 61 74 61 62 61 73 65 20   not a database 
4c50: 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  file */.#define 
4c60: 53 51 4c 49 54 45 5f 52 4f 57 20 20 20 20 20 20  SQLITE_ROW      
4c70: 20 20 20 31 30 30 20 20 2f 2a 20 73 71 6c 69 74     100  /* sqlit
4c80: 65 33 5f 73 74 65 70 28 29 20 68 61 73 20 61 6e  e3_step() has an
4c90: 6f 74 68 65 72 20 72 6f 77 20 72 65 61 64 79 20  other row ready 
4ca0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4cb0: 45 5f 44 4f 4e 45 20 20 20 20 20 20 20 20 31 30  E_DONE        10
4cc0: 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74  1  /* sqlite3_st
4cd0: 65 70 28 29 20 68 61 73 20 66 69 6e 69 73 68 65  ep() has finishe
4ce0: 64 20 65 78 65 63 75 74 69 6e 67 20 2a 2f 0a 2f  d executing */./
4cf0: 2a 20 65 6e 64 2d 6f 66 2d 65 72 72 6f 72 2d 63  * end-of-error-c
4d00: 6f 64 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43  odes */../*.** C
4d10: 41 50 49 33 52 45 46 3a 20 45 78 74 65 6e 64 65  API3REF: Extende
4d20: 64 20 52 65 73 75 6c 74 20 43 6f 64 65 73 20 7b  d Result Codes {
4d30: 48 31 30 32 32 30 7d 20 3c 53 31 30 37 30 30 3e  H10220} <S10700>
4d40: 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 65  .** KEYWORDS: {e
4d50: 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f  xtended error co
4d60: 64 65 7d 20 7b 65 78 74 65 6e 64 65 64 20 65 72  de} {extended er
4d70: 72 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b 45  ror codes}.** KE
4d80: 59 57 4f 52 44 53 3a 20 7b 65 78 74 65 6e 64 65  YWORDS: {extende
4d90: 64 20 72 65 73 75 6c 74 20 63 6f 64 65 7d 20 7b  d result code} {
4da0: 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
4db0: 63 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20  codes}.**.** In 
4dc0: 69 74 73 20 64 65 66 61 75 6c 74 20 63 6f 6e 66  its default conf
4dd0: 69 67 75 72 61 74 69 6f 6e 2c 20 53 51 4c 69 74  iguration, SQLit
4de0: 65 20 41 50 49 20 72 6f 75 74 69 6e 65 73 20 72  e API routines r
4df0: 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 32 36 20  eturn one of 26 
4e00: 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 53 51 4c 49  integer.** [SQLI
4e10: 54 45 5f 4f 4b 20 7c 20 72 65 73 75 6c 74 20 63  TE_OK | result c
4e20: 6f 64 65 73 5d 2e 20 20 48 6f 77 65 76 65 72 2c  odes].  However,
4e30: 20 65 78 70 65 72 69 65 6e 63 65 20 68 61 73 20   experience has 
4e40: 73 68 6f 77 6e 20 74 68 61 74 20 6d 61 6e 79 20  shown that many 
4e50: 6f 66 0a 2a 2a 20 74 68 65 73 65 20 72 65 73 75  of.** these resu
4e60: 6c 74 20 63 6f 64 65 73 20 61 72 65 20 74 6f 6f  lt codes are too
4e70: 20 63 6f 61 72 73 65 2d 67 72 61 69 6e 65 64 2e   coarse-grained.
4e80: 20 20 54 68 65 79 20 64 6f 20 6e 6f 74 20 70 72    They do not pr
4e90: 6f 76 69 64 65 20 61 73 0a 2a 2a 20 6d 75 63 68  ovide as.** much
4ea0: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f   information abo
4eb0: 75 74 20 70 72 6f 62 6c 65 6d 73 20 61 73 20 70  ut problems as p
4ec0: 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67 68 74  rogrammers might
4ed0: 20 6c 69 6b 65 2e 20 20 49 6e 20 61 6e 20 65 66   like.  In an ef
4ee0: 66 6f 72 74 20 74 6f 0a 2a 2a 20 61 64 64 72 65  fort to.** addre
4ef0: 73 73 20 74 68 69 73 2c 20 6e 65 77 65 72 20 76  ss this, newer v
4f00: 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
4f10: 65 20 28 76 65 72 73 69 6f 6e 20 33 2e 33 2e 38  e (version 3.3.8
4f20: 20 61 6e 64 20 6c 61 74 65 72 29 20 69 6e 63 6c   and later) incl
4f30: 75 64 65 0a 2a 2a 20 73 75 70 70 6f 72 74 20 66  ude.** support f
4f40: 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 72 65  or additional re
4f50: 73 75 6c 74 20 63 6f 64 65 73 20 74 68 61 74 20  sult codes that 
4f60: 70 72 6f 76 69 64 65 20 6d 6f 72 65 20 64 65 74  provide more det
4f70: 61 69 6c 65 64 20 69 6e 66 6f 72 6d 61 74 69 6f  ailed informatio
4f80: 6e 0a 2a 2a 20 61 62 6f 75 74 20 65 72 72 6f 72  n.** about error
4f90: 73 2e 20 54 68 65 20 65 78 74 65 6e 64 65 64 20  s. The extended 
4fa0: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65  result codes are
4fb0: 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61   enabled or disa
4fc0: 62 6c 65 64 0a 2a 2a 20 6f 6e 20 61 20 70 65 72  bled.** on a per
4fd0: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
4fe0: 74 69 6f 6e 20 62 61 73 69 73 20 75 73 69 6e 67  tion basis using
4ff0: 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
5000: 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74  _extended_result
5010: 5f 63 6f 64 65 73 28 29 5d 20 41 50 49 2e 0a 2a  _codes()] API..*
5020: 2a 0a 2a 2a 20 53 6f 6d 65 20 6f 66 20 74 68 65  *.** Some of the
5030: 20 61 76 61 69 6c 61 62 6c 65 20 65 78 74 65 6e   available exten
5040: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
5050: 20 61 72 65 20 6c 69 73 74 65 64 20 68 65 72 65   are listed here
5060: 2e 0a 2a 2a 20 4f 6e 65 20 6d 61 79 20 65 78 70  ..** One may exp
5070: 65 63 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  ect the number o
5080: 66 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c  f extended resul
5090: 74 20 63 6f 64 65 73 20 77 69 6c 6c 20 62 65 20  t codes will be 
50a0: 65 78 70 61 6e 64 0a 2a 2a 20 6f 76 65 72 20 74  expand.** over t
50b0: 69 6d 65 2e 20 20 53 6f 66 74 77 61 72 65 20 74  ime.  Software t
50c0: 68 61 74 20 75 73 65 73 20 65 78 74 65 6e 64 65  hat uses extende
50d0: 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 73  d result codes s
50e0: 68 6f 75 6c 64 20 65 78 70 65 63 74 0a 2a 2a 20  hould expect.** 
50f0: 74 6f 20 73 65 65 20 6e 65 77 20 72 65 73 75 6c  to see new resul
5100: 74 20 63 6f 64 65 73 20 69 6e 20 66 75 74 75 72  t codes in futur
5110: 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51  e releases of SQ
5120: 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  Lite..**.** The 
5130: 53 51 4c 49 54 45 5f 4f 4b 20 72 65 73 75 6c 74  SQLITE_OK result
5140: 20 63 6f 64 65 20 77 69 6c 6c 20 6e 65 76 65 72   code will never
5150: 20 62 65 20 65 78 74 65 6e 64 65 64 2e 20 20 49   be extended.  I
5160: 74 20 77 69 6c 6c 20 61 6c 77 61 79 73 0a 2a 2a  t will always.**
5170: 20 62 65 20 65 78 61 63 74 6c 79 20 7a 65 72 6f   be exactly zero
5180: 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  ..**.** INVARIAN
5190: 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 32 32  TS:.**.** {H1022
51a0: 33 7d 20 54 68 65 20 73 79 6d 62 6f 6c 69 63 20  3} The symbolic 
51b0: 6e 61 6d 65 20 66 6f 72 20 61 6e 20 65 78 74 65  name for an exte
51c0: 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
51d0: 20 73 68 61 6c 6c 20 63 6f 6e 74 61 69 6e 73 0a   shall contains.
51e0: 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20 72 65  **          a re
51f0: 6c 61 74 65 64 20 70 72 69 6d 61 72 79 20 72 65  lated primary re
5200: 73 75 6c 74 20 63 6f 64 65 20 61 73 20 61 20 70  sult code as a p
5210: 72 65 66 69 78 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  refix..**.** {H1
5220: 30 32 32 34 7d 20 50 72 69 6d 61 72 79 20 72 65  0224} Primary re
5230: 73 75 6c 74 20 63 6f 64 65 20 6e 61 6d 65 73 20  sult code names 
5240: 73 68 61 6c 6c 20 63 6f 6e 74 61 69 6e 20 61 20  shall contain a 
5250: 73 69 6e 67 6c 65 20 22 5f 22 20 63 68 61 72 61  single "_" chara
5260: 63 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 30  cter..**.** {H10
5270: 32 32 35 7d 20 45 78 74 65 6e 64 65 64 20 72 65  225} Extended re
5280: 73 75 6c 74 20 63 6f 64 65 20 6e 61 6d 65 73 20  sult code names 
5290: 73 68 61 6c 6c 20 63 6f 6e 74 61 69 6e 20 74 77  shall contain tw
52a0: 6f 20 6f 72 20 6d 6f 72 65 20 22 5f 22 20 63 68  o or more "_" ch
52b0: 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20  aracters..**.** 
52c0: 7b 48 31 30 32 32 36 7d 20 54 68 65 20 6e 75 6d  {H10226} The num
52d0: 65 72 69 63 20 76 61 6c 75 65 20 6f 66 20 61 6e  eric value of an
52e0: 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74   extended result
52f0: 20 63 6f 64 65 20 73 68 61 6c 6c 20 63 6f 6e 74   code shall cont
5300: 61 69 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  ain the.**      
5310: 20 20 20 20 6e 75 6d 65 72 69 63 20 76 61 6c 75      numeric valu
5320: 65 20 6f 66 20 69 74 73 20 63 6f 72 72 65 73 70  e of its corresp
5330: 6f 6e 64 69 6e 67 20 70 72 69 6d 61 72 79 20 72  onding primary r
5340: 65 73 75 6c 74 20 63 6f 64 65 20 69 6e 0a 2a 2a  esult code in.**
5350: 20 20 20 20 20 20 20 20 20 20 69 74 73 20 6c 65            its le
5360: 61 73 74 20 73 69 67 6e 69 66 69 63 61 6e 74 20  ast significant 
5370: 38 20 62 69 74 73 2e 0a 2a 2f 0a 23 64 65 66 69  8 bits..*/.#defi
5380: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5390: 52 45 41 44 20 20 20 20 20 20 20 20 20 20 20 20  READ            
53a0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
53b0: 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (1<<8)).#defin
53c0: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53  e SQLITE_IOERR_S
53d0: 48 4f 52 54 5f 52 45 41 44 20 20 20 20 20 20 20  HORT_READ       
53e0: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
53f0: 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (2<<8)).#define
5400: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 57 52   SQLITE_IOERR_WR
5410: 49 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20  ITE             
5420: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
5430: 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (3<<8)).#define 
5440: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46 53 59  SQLITE_IOERR_FSY
5450: 4e 43 20 20 20 20 20 20 20 20 20 20 20 20 20 28  NC             (
5460: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
5470: 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  4<<8)).#define S
5480: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49 52 5f  QLITE_IOERR_DIR_
5490: 46 53 59 4e 43 20 20 20 20 20 20 20 20 20 28 53  FSYNC         (S
54a0: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 35  QLITE_IOERR | (5
54b0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
54c0: 4c 49 54 45 5f 49 4f 45 52 52 5f 54 52 55 4e 43  LITE_IOERR_TRUNC
54d0: 41 54 45 20 20 20 20 20 20 20 20 20 20 28 53 51  ATE          (SQ
54e0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 36 3c  LITE_IOERR | (6<
54f0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5500: 49 54 45 5f 49 4f 45 52 52 5f 46 53 54 41 54 20  ITE_IOERR_FSTAT 
5510: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
5520: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 37 3c 3c  ITE_IOERR | (7<<
5530: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5540: 54 45 5f 49 4f 45 52 52 5f 55 4e 4c 4f 43 4b 20  TE_IOERR_UNLOCK 
5550: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
5560: 54 45 5f 49 4f 45 52 52 20 7c 20 28 38 3c 3c 38  TE_IOERR | (8<<8
5570: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5580: 45 5f 49 4f 45 52 52 5f 52 44 4c 4f 43 4b 20 20  E_IOERR_RDLOCK  
5590: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
55a0: 45 5f 49 4f 45 52 52 20 7c 20 28 39 3c 3c 38 29  E_IOERR | (9<<8)
55b0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
55c0: 5f 49 4f 45 52 52 5f 44 45 4c 45 54 45 20 20 20  _IOERR_DELETE   
55d0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
55e0: 5f 49 4f 45 52 52 20 7c 20 28 31 30 3c 3c 38 29  _IOERR | (10<<8)
55f0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5600: 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 20 20  _IOERR_BLOCKED  
5610: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5620: 5f 49 4f 45 52 52 20 7c 20 28 31 31 3c 3c 38 29  _IOERR | (11<<8)
5630: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5640: 5f 49 4f 45 52 52 5f 4e 4f 4d 45 4d 20 20 20 20  _IOERR_NOMEM    
5650: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5660: 5f 49 4f 45 52 52 20 7c 20 28 31 32 3c 3c 38 29  _IOERR | (12<<8)
5670: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5680: 5f 49 4f 45 52 52 5f 41 43 43 45 53 53 20 20 20  _IOERR_ACCESS   
5690: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
56a0: 5f 49 4f 45 52 52 20 7c 20 28 31 33 3c 3c 38 29  _IOERR | (13<<8)
56b0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
56c0: 5f 49 4f 45 52 52 5f 43 48 45 43 4b 52 45 53 45  _IOERR_CHECKRESE
56d0: 52 56 45 44 4c 4f 43 4b 20 28 53 51 4c 49 54 45  RVEDLOCK (SQLITE
56e0: 5f 49 4f 45 52 52 20 7c 20 28 31 34 3c 3c 38 29  _IOERR | (14<<8)
56f0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5700: 5f 49 4f 45 52 52 5f 4c 4f 43 4b 20 20 20 20 20  _IOERR_LOCK     
5710: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5720: 5f 49 4f 45 52 52 20 7c 20 28 31 35 3c 3c 38 29  _IOERR | (15<<8)
5730: 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  )../*.** CAPI3RE
5740: 46 3a 20 46 6c 61 67 73 20 46 6f 72 20 46 69 6c  F: Flags For Fil
5750: 65 20 4f 70 65 6e 20 4f 70 65 72 61 74 69 6f 6e  e Open Operation
5760: 73 20 7b 48 31 30 32 33 30 7d 20 3c 48 31 31 31  s {H10230} <H111
5770: 32 30 3e 20 3c 48 31 32 37 30 30 3e 0a 2a 2a 0a  20> <H12700>.**.
5780: 2a 2a 20 54 68 65 73 65 20 62 69 74 20 76 61 6c  ** These bit val
5790: 75 65 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64  ues are intended
57a0: 20 66 6f 72 20 75 73 65 20 69 6e 20 74 68 65 0a   for use in the.
57b0: 2a 2a 20 33 72 64 20 70 61 72 61 6d 65 74 65 72  ** 3rd parameter
57c0: 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
57d0: 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65  _open_v2()] inte
57e0: 72 66 61 63 65 20 61 6e 64 0a 2a 2a 20 69 6e 20  rface and.** in 
57f0: 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65  the 4th paramete
5800: 72 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 20 6d  r to the xOpen m
5810: 65 74 68 6f 64 20 6f 66 20 74 68 65 0a 2a 2a 20  ethod of the.** 
5820: 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62  [sqlite3_vfs] ob
5830: 6a 65 63 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  ject..*/.#define
5840: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41   SQLITE_OPEN_REA
5850: 44 4f 4e 4c 59 20 20 20 20 20 20 20 20 20 30 78  DONLY         0x
5860: 30 30 30 30 30 30 30 31 0a 23 64 65 66 69 6e 65  00000001.#define
5870: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41   SQLITE_OPEN_REA
5880: 44 57 52 49 54 45 20 20 20 20 20 20 20 20 30 78  DWRITE        0x
5890: 30 30 30 30 30 30 30 32 0a 23 64 65 66 69 6e 65  00000002.#define
58a0: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45   SQLITE_OPEN_CRE
58b0: 41 54 45 20 20 20 20 20 20 20 20 20 20 20 30 78  ATE           0x
58c0: 30 30 30 30 30 30 30 34 0a 23 64 65 66 69 6e 65  00000004.#define
58d0: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c   SQLITE_OPEN_DEL
58e0: 45 54 45 4f 4e 43 4c 4f 53 45 20 20 20 20 30 78  ETEONCLOSE    0x
58f0: 30 30 30 30 30 30 30 38 0a 23 64 65 66 69 6e 65  00000008.#define
5900: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43   SQLITE_OPEN_EXC
5910: 4c 55 53 49 56 45 20 20 20 20 20 20 20 20 30 78  LUSIVE        0x
5920: 30 30 30 30 30 30 31 30 0a 23 64 65 66 69 6e 65  00000010.#define
5930: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49   SQLITE_OPEN_MAI
5940: 4e 5f 44 42 20 20 20 20 20 20 20 20 20 20 30 78  N_DB          0x
5950: 30 30 30 30 30 31 30 30 0a 23 64 65 66 69 6e 65  00000100.#define
5960: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d   SQLITE_OPEN_TEM
5970: 50 5f 44 42 20 20 20 20 20 20 20 20 20 20 30 78  P_DB          0x
5980: 30 30 30 30 30 32 30 30 0a 23 64 65 66 69 6e 65  00000200.#define
5990: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41   SQLITE_OPEN_TRA
59a0: 4e 53 49 45 4e 54 5f 44 42 20 20 20 20 20 30 78  NSIENT_DB     0x
59b0: 30 30 30 30 30 34 30 30 0a 23 64 65 66 69 6e 65  00000400.#define
59c0: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49   SQLITE_OPEN_MAI
59d0: 4e 5f 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30 78  N_JOURNAL     0x
59e0: 30 30 30 30 30 38 30 30 0a 23 64 65 66 69 6e 65  00000800.#define
59f0: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d   SQLITE_OPEN_TEM
5a00: 50 5f 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30 78  P_JOURNAL     0x
5a10: 30 30 30 30 31 30 30 30 0a 23 64 65 66 69 6e 65  00001000.#define
5a20: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42   SQLITE_OPEN_SUB
5a30: 4a 4f 55 52 4e 41 4c 20 20 20 20 20 20 20 30 78  JOURNAL       0x
5a40: 30 30 30 30 32 30 30 30 0a 23 64 65 66 69 6e 65  00002000.#define
5a50: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53   SQLITE_OPEN_MAS
5a60: 54 45 52 5f 4a 4f 55 52 4e 41 4c 20 20 20 30 78  TER_JOURNAL   0x
5a70: 30 30 30 30 34 30 30 30 0a 23 64 65 66 69 6e 65  00004000.#define
5a80: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d   SQLITE_OPEN_NOM
5a90: 55 54 45 58 20 20 20 20 20 20 20 20 20 20 30 78  UTEX          0x
5aa0: 30 30 30 30 38 30 30 30 0a 0a 2f 2a 0a 2a 2a 20  00008000../*.** 
5ab0: 43 41 50 49 33 52 45 46 3a 20 44 65 76 69 63 65  CAPI3REF: Device
5ac0: 20 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73   Characteristics
5ad0: 20 7b 48 31 30 32 34 30 7d 20 3c 48 31 31 31 32   {H10240} <H1112
5ae0: 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 44 65  0>.**.** The xDe
5af0: 76 69 63 65 43 61 70 61 62 69 6c 69 74 69 65 73  viceCapabilities
5b00: 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 5b   method of the [
5b10: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
5b20: 64 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65  ds].** object re
5b30: 74 75 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 72  turns an integer
5b40: 20 77 68 69 63 68 20 69 73 20 61 20 76 65 63 74   which is a vect
5b50: 6f 72 20 6f 66 20 74 68 65 20 74 68 65 73 65 0a  or of the these.
5b60: 2a 2a 20 62 69 74 20 76 61 6c 75 65 73 20 65 78  ** bit values ex
5b70: 70 72 65 73 73 69 6e 67 20 49 2f 4f 20 63 68 61  pressing I/O cha
5b80: 72 61 63 74 65 72 69 73 74 69 63 73 20 6f 66 20  racteristics of 
5b90: 74 68 65 20 6d 61 73 73 20 73 74 6f 72 61 67 65  the mass storage
5ba0: 0a 2a 2a 20 64 65 76 69 63 65 20 74 68 61 74 20  .** device that 
5bb0: 68 6f 6c 64 73 20 74 68 65 20 66 69 6c 65 20 74  holds the file t
5bc0: 68 61 74 20 74 68 65 20 5b 73 71 6c 69 74 65 33  hat the [sqlite3
5bd0: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20  _io_methods].** 
5be0: 72 65 66 65 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a  refers to..**.**
5bf0: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
5c00: 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74  P_ATOMIC propert
5c10: 79 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c  y means that all
5c20: 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e   writes of.** an
5c30: 79 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69  y size are atomi
5c40: 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  c.  The SQLITE_I
5c50: 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76  OCAP_ATOMICnnn v
5c60: 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68  alues.** mean th
5c70: 61 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f  at writes of blo
5c80: 63 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e  cks that are nnn
5c90: 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61   bytes in size a
5ca0: 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65  nd.** are aligne
5cb0: 64 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20  d to an address 
5cc0: 77 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65  which is an inte
5cd0: 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a  ger multiple of.
5ce0: 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69  ** nnn are atomi
5cf0: 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  c.  The SQLITE_I
5d00: 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44  OCAP_SAFE_APPEND
5d10: 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20   value means.** 
5d20: 74 68 61 74 20 77 68 65 6e 20 64 61 74 61 20 69  that when data i
5d30: 73 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20  s appended to a 
5d40: 66 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69  file, the data i
5d50: 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69  s appended.** fi
5d60: 72 73 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a  rst then the siz
5d70: 65 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73  e of the file is
5d80: 20 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72   extended, never
5d90: 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61   the other.** wa
5da0: 79 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53  y around.  The S
5db0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55  QLITE_IOCAP_SEQU
5dc0: 45 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20  ENTIAL property 
5dd0: 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e  means that.** in
5de0: 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69  formation is wri
5df0: 74 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20  tten to disk in 
5e00: 74 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61  the same order a
5e10: 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57  s calls.** to xW
5e20: 72 69 74 65 28 29 2e 0a 2a 2f 0a 23 64 65 66 69  rite()..*/.#defi
5e30: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
5e40: 41 54 4f 4d 49 43 20 20 20 20 20 20 20 20 20 20  ATOMIC          
5e50: 30 78 30 30 30 30 30 30 30 31 0a 23 64 65 66 69  0x00000001.#defi
5e60: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
5e70: 41 54 4f 4d 49 43 35 31 32 20 20 20 20 20 20 20  ATOMIC512       
5e80: 30 78 30 30 30 30 30 30 30 32 0a 23 64 65 66 69  0x00000002.#defi
5e90: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
5ea0: 41 54 4f 4d 49 43 31 4b 20 20 20 20 20 20 20 20  ATOMIC1K        
5eb0: 30 78 30 30 30 30 30 30 30 34 0a 23 64 65 66 69  0x00000004.#defi
5ec0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
5ed0: 41 54 4f 4d 49 43 32 4b 20 20 20 20 20 20 20 20  ATOMIC2K        
5ee0: 30 78 30 30 30 30 30 30 30 38 0a 23 64 65 66 69  0x00000008.#defi
5ef0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
5f00: 41 54 4f 4d 49 43 34 4b 20 20 20 20 20 20 20 20  ATOMIC4K        
5f10: 30 78 30 30 30 30 30 30 31 30 0a 23 64 65 66 69  0x00000010.#defi
5f20: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
5f30: 41 54 4f 4d 49 43 38 4b 20 20 20 20 20 20 20 20  ATOMIC8K        
5f40: 30 78 30 30 30 30 30 30 32 30 0a 23 64 65 66 69  0x00000020.#defi
5f50: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
5f60: 41 54 4f 4d 49 43 31 36 4b 20 20 20 20 20 20 20  ATOMIC16K       
5f70: 30 78 30 30 30 30 30 30 34 30 0a 23 64 65 66 69  0x00000040.#defi
5f80: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
5f90: 41 54 4f 4d 49 43 33 32 4b 20 20 20 20 20 20 20  ATOMIC32K       
5fa0: 30 78 30 30 30 30 30 30 38 30 0a 23 64 65 66 69  0x00000080.#defi
5fb0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
5fc0: 41 54 4f 4d 49 43 36 34 4b 20 20 20 20 20 20 20  ATOMIC64K       
5fd0: 30 78 30 30 30 30 30 31 30 30 0a 23 64 65 66 69  0x00000100.#defi
5fe0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
5ff0: 53 41 46 45 5f 41 50 50 45 4e 44 20 20 20 20 20  SAFE_APPEND     
6000: 30 78 30 30 30 30 30 32 30 30 0a 23 64 65 66 69  0x00000200.#defi
6010: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
6020: 53 45 51 55 45 4e 54 49 41 4c 20 20 20 20 20 20  SEQUENTIAL      
6030: 30 78 30 30 30 30 30 34 30 30 0a 0a 2f 2a 0a 2a  0x00000400../*.*
6040: 2a 20 43 41 50 49 33 52 45 46 3a 20 46 69 6c 65  * CAPI3REF: File
6050: 20 4c 6f 63 6b 69 6e 67 20 4c 65 76 65 6c 73 20   Locking Levels 
6060: 7b 48 31 30 32 35 30 7d 20 3c 48 31 31 31 32 30  {H10250} <H11120
6070: 3e 20 3c 48 31 31 33 31 30 3e 0a 2a 2a 0a 2a 2a  > <H11310>.**.**
6080: 20 53 51 4c 69 74 65 20 75 73 65 73 20 6f 6e 65   SQLite uses one
6090: 20 6f 66 20 74 68 65 73 65 20 69 6e 74 65 67 65   of these intege
60a0: 72 20 76 61 6c 75 65 73 20 61 73 20 74 68 65 20  r values as the 
60b0: 73 65 63 6f 6e 64 0a 2a 2a 20 61 72 67 75 6d 65  second.** argume
60c0: 6e 74 20 74 6f 20 63 61 6c 6c 73 20 69 74 20 6d  nt to calls it m
60d0: 61 6b 65 73 20 74 6f 20 74 68 65 20 78 4c 6f 63  akes to the xLoc
60e0: 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28  k() and xUnlock(
60f0: 29 20 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f 66 20  ) methods.** of 
6100: 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  an [sqlite3_io_m
6110: 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e 0a  ethods] object..
6120: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6130: 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20 20 20 20 20  E_LOCK_NONE     
6140: 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53       0.#define S
6150: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45  QLITE_LOCK_SHARE
6160: 44 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69  D        1.#defi
6170: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52  ne SQLITE_LOCK_R
6180: 45 53 45 52 56 45 44 20 20 20 20 20 20 32 0a 23  ESERVED      2.#
6190: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f  define SQLITE_LO
61a0: 43 4b 5f 50 45 4e 44 49 4e 47 20 20 20 20 20 20  CK_PENDING      
61b0: 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   3.#define SQLIT
61c0: 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45  E_LOCK_EXCLUSIVE
61d0: 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20 43 41       4../*.** CA
61e0: 50 49 33 52 45 46 3a 20 53 79 6e 63 68 72 6f 6e  PI3REF: Synchron
61f0: 69 7a 61 74 69 6f 6e 20 54 79 70 65 20 46 6c 61  ization Type Fla
6200: 67 73 20 7b 48 31 30 32 36 30 7d 20 3c 48 31 31  gs {H10260} <H11
6210: 31 32 30 3e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20  120>.**.** When 
6220: 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73 20 74  SQLite invokes t
6230: 68 65 20 78 53 79 6e 63 28 29 20 6d 65 74 68 6f  he xSync() metho
6240: 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69  d of an.** [sqli
6250: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20  te3_io_methods] 
6260: 6f 62 6a 65 63 74 20 69 74 20 75 73 65 73 20 61  object it uses a
6270: 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 0a   combination of.
6280: 2a 2a 20 74 68 65 73 65 20 69 6e 74 65 67 65 72  ** these integer
6290: 20 76 61 6c 75 65 73 20 61 73 20 74 68 65 20 73   values as the s
62a0: 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a  econd argument..
62b0: 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 53  **.** When the S
62c0: 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f  QLITE_SYNC_DATAO
62d0: 4e 4c 59 20 66 6c 61 67 20 69 73 20 75 73 65 64  NLY flag is used
62e0: 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20  , it means that 
62f0: 74 68 65 0a 2a 2a 20 73 79 6e 63 20 6f 70 65 72  the.** sync oper
6300: 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65 65 64 73  ation only needs
6310: 20 74 6f 20 66 6c 75 73 68 20 64 61 74 61 20 74   to flush data t
6320: 6f 20 6d 61 73 73 20 73 74 6f 72 61 67 65 2e 20  o mass storage. 
6330: 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66 6f 72 6d   Inode.** inform
6340: 61 74 69 6f 6e 20 6e 65 65 64 20 6e 6f 74 20 62  ation need not b
6350: 65 20 66 6c 75 73 68 65 64 2e 20 54 68 65 20 53  e flushed. The S
6360: 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41  QLITE_SYNC_NORMA
6370: 4c 20 66 6c 61 67 20 6d 65 61 6e 73 0a 2a 2a 20  L flag means.** 
6380: 74 6f 20 75 73 65 20 6e 6f 72 6d 61 6c 20 66 73  to use normal fs
6390: 79 6e 63 28 29 20 73 65 6d 61 6e 74 69 63 73 2e  ync() semantics.
63a0: 20 54 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43   The SQLITE_SYNC
63b0: 5f 46 55 4c 4c 20 66 6c 61 67 20 6d 65 61 6e 73  _FULL flag means
63c0: 0a 2a 2a 20 74 6f 20 75 73 65 20 4d 61 63 20 4f  .** to use Mac O
63d0: 53 2d 58 20 73 74 79 6c 65 20 66 75 6c 6c 73 79  S-X style fullsy
63e0: 6e 63 20 69 6e 73 74 65 61 64 20 6f 66 20 66 73  nc instead of fs
63f0: 79 6e 63 28 29 2e 0a 2a 2f 0a 23 64 65 66 69 6e  ync()..*/.#defin
6400: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f  e SQLITE_SYNC_NO
6410: 52 4d 41 4c 20 20 20 20 20 20 20 20 30 78 30 30  RMAL        0x00
6420: 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  002.#define SQLI
6430: 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 20 20 20  TE_SYNC_FULL    
6440: 20 20 20 20 20 20 30 78 30 30 30 30 33 0a 23 64        0x00003.#d
6450: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e  efine SQLITE_SYN
6460: 43 5f 44 41 54 41 4f 4e 4c 59 20 20 20 20 20 20  C_DATAONLY      
6470: 30 78 30 30 30 31 30 0a 0a 2f 2a 0a 2a 2a 20 43  0x00010../*.** C
6480: 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65  API3REF: OS Inte
6490: 72 66 61 63 65 20 4f 70 65 6e 20 46 69 6c 65 20  rface Open File 
64a0: 48 61 6e 64 6c 65 20 7b 48 31 31 31 31 30 7d 20  Handle {H11110} 
64b0: 3c 53 32 30 31 31 30 3e 0a 2a 2a 0a 2a 2a 20 41  <S20110>.**.** A
64c0: 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  n [sqlite3_file]
64d0: 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e   object represen
64e0: 74 73 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20  ts an open file 
64f0: 69 6e 20 74 68 65 20 4f 53 0a 2a 2a 20 69 6e 74  in the OS.** int
6500: 65 72 66 61 63 65 20 6c 61 79 65 72 2e 20 20 49  erface layer.  I
6510: 6e 64 69 76 69 64 75 61 6c 20 4f 53 20 69 6e 74  ndividual OS int
6520: 65 72 66 61 63 65 20 69 6d 70 6c 65 6d 65 6e 74  erface implement
6530: 61 74 69 6f 6e 73 20 77 69 6c 6c 0a 2a 2a 20 77  ations will.** w
6540: 61 6e 74 20 74 6f 20 73 75 62 63 6c 61 73 73 20  ant to subclass 
6550: 74 68 69 73 20 6f 62 6a 65 63 74 20 62 79 20 61  this object by a
6560: 70 70 65 6e 64 69 6e 67 20 61 64 64 69 74 69 6f  ppending additio
6570: 6e 61 6c 20 66 69 65 6c 64 73 0a 2a 2a 20 66 6f  nal fields.** fo
6580: 72 20 74 68 65 69 72 20 6f 77 6e 20 75 73 65 2e  r their own use.
6590: 20 20 54 68 65 20 70 4d 65 74 68 6f 64 73 20 65    The pMethods e
65a0: 6e 74 72 79 20 69 73 20 61 20 70 6f 69 6e 74 65  ntry is a pointe
65b0: 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69  r to an.** [sqli
65c0: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20  te3_io_methods] 
65d0: 6f 62 6a 65 63 74 20 74 68 61 74 20 64 65 66 69  object that defi
65e0: 6e 65 73 20 6d 65 74 68 6f 64 73 20 66 6f 72 20  nes methods for 
65f0: 70 65 72 66 6f 72 6d 69 6e 67 0a 2a 2a 20 49 2f  performing.** I/
6600: 4f 20 6f 70 65 72 61 74 69 6f 6e 73 20 6f 6e 20  O operations on 
6610: 74 68 65 20 6f 70 65 6e 20 66 69 6c 65 2e 0a 2a  the open file..*
6620: 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
6630: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 73 71   sqlite3_file sq
6640: 6c 69 74 65 33 5f 66 69 6c 65 3b 0a 73 74 72 75  lite3_file;.stru
6650: 63 74 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20  ct sqlite3_file 
6660: 7b 0a 20 20 63 6f 6e 73 74 20 73 74 72 75 63 74  {.  const struct
6670: 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68   sqlite3_io_meth
6680: 6f 64 73 20 2a 70 4d 65 74 68 6f 64 73 3b 20 20  ods *pMethods;  
6690: 2f 2a 20 4d 65 74 68 6f 64 73 20 66 6f 72 20 61  /* Methods for a
66a0: 6e 20 6f 70 65 6e 20 66 69 6c 65 20 2a 2f 0a 7d  n open file */.}
66b0: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
66c0: 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20  F: OS Interface 
66d0: 46 69 6c 65 20 56 69 72 74 75 61 6c 20 4d 65 74  File Virtual Met
66e0: 68 6f 64 73 20 4f 62 6a 65 63 74 20 7b 48 31 31  hods Object {H11
66f0: 31 32 30 7d 20 3c 53 32 30 31 31 30 3e 0a 2a 2a  120} <S20110>.**
6700: 0a 2a 2a 20 45 76 65 72 79 20 66 69 6c 65 20 6f  .** Every file o
6710: 70 65 6e 65 64 20 62 79 20 74 68 65 20 5b 73 71  pened by the [sq
6720: 6c 69 74 65 33 5f 76 66 73 5d 20 78 4f 70 65 6e  lite3_vfs] xOpen
6730: 20 6d 65 74 68 6f 64 20 70 6f 70 75 6c 61 74 65   method populate
6740: 73 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  s an.** [sqlite3
6750: 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 28 6f  _file] object (o
6760: 72 2c 20 6d 6f 72 65 20 63 6f 6d 6d 6f 6e 6c 79  r, more commonly
6770: 2c 20 61 20 73 75 62 63 6c 61 73 73 20 6f 66 20  , a subclass of 
6780: 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
6790: 66 69 6c 65 5d 20 6f 62 6a 65 63 74 29 20 77 69  file] object) wi
67a0: 74 68 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  th a pointer to 
67b0: 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  an instance of t
67c0: 68 69 73 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 54  his object..** T
67d0: 68 69 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e  his object defin
67e0: 65 73 20 74 68 65 20 6d 65 74 68 6f 64 73 20 75  es the methods u
67f0: 73 65 64 20 74 6f 20 70 65 72 66 6f 72 6d 20 76  sed to perform v
6800: 61 72 69 6f 75 73 20 6f 70 65 72 61 74 69 6f 6e  arious operation
6810: 73 0a 2a 2a 20 61 67 61 69 6e 73 74 20 74 68 65  s.** against the
6820: 20 6f 70 65 6e 20 66 69 6c 65 20 72 65 70 72 65   open file repre
6830: 73 65 6e 74 65 64 20 62 79 20 74 68 65 20 5b 73  sented by the [s
6840: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a  qlite3_file] obj
6850: 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  ect..**.** The f
6860: 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f  lags argument to
6870: 20 78 53 79 6e 63 20 6d 61 79 20 62 65 20 6f 6e   xSync may be on
6880: 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 53 59 4e  e of [SQLITE_SYN
6890: 43 5f 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a 20  C_NORMAL] or.** 
68a0: 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c  [SQLITE_SYNC_FUL
68b0: 4c 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20 63  L].  The first c
68c0: 68 6f 69 63 65 20 69 73 20 74 68 65 20 6e 6f 72  hoice is the nor
68d0: 6d 61 6c 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 20  mal fsync()..** 
68e0: 54 68 65 20 73 65 63 6f 6e 64 20 63 68 6f 69 63  The second choic
68f0: 65 20 69 73 20 61 20 4d 61 63 20 4f 53 2d 58 20  e is a Mac OS-X 
6900: 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 2e 20  style fullsync. 
6910: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 53 59 4e   The [SQLITE_SYN
6920: 43 5f 44 41 54 41 4f 4e 4c 59 5d 0a 2a 2a 20 66  C_DATAONLY].** f
6930: 6c 61 67 20 6d 61 79 20 62 65 20 4f 52 65 64 20  lag may be ORed 
6940: 69 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74  in to indicate t
6950: 68 61 74 20 6f 6e 6c 79 20 74 68 65 20 64 61 74  hat only the dat
6960: 61 20 6f 66 20 74 68 65 20 66 69 6c 65 0a 2a 2a  a of the file.**
6970: 20 61 6e 64 20 6e 6f 74 20 69 74 73 20 69 6e 6f   and not its ino
6980: 64 65 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73  de needs to be s
6990: 79 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ynced..**.** The
69a0: 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20   integer values 
69b0: 74 6f 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78  to xLock() and x
69c0: 55 6e 6c 6f 63 6b 28 29 20 61 72 65 20 6f 6e 65  Unlock() are one
69d0: 20 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c   of.** <ul>.** <
69e0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  li> [SQLITE_LOCK
69f0: 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20  _NONE],.** <li> 
6a00: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41  [SQLITE_LOCK_SHA
6a10: 52 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  RED],.** <li> [S
6a20: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52  QLITE_LOCK_RESER
6a30: 56 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  VED],.** <li> [S
6a40: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49  QLITE_LOCK_PENDI
6a50: 4e 47 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20  NG], or.** <li> 
6a60: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43  [SQLITE_LOCK_EXC
6a70: 4c 55 53 49 56 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c  LUSIVE]..** </ul
6a80: 3e 0a 2a 2a 20 78 4c 6f 63 6b 28 29 20 69 6e 63  >.** xLock() inc
6a90: 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e  reases the lock.
6aa0: 20 78 55 6e 6c 6f 63 6b 28 29 20 64 65 63 72 65   xUnlock() decre
6ab0: 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 0a 2a  ases the lock..*
6ac0: 2a 20 54 68 65 20 78 43 68 65 63 6b 52 65 73 65  * The xCheckRese
6ad0: 72 76 65 64 4c 6f 63 6b 28 29 20 6d 65 74 68 6f  rvedLock() metho
6ae0: 64 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72  d checks whether
6af0: 20 61 6e 79 20 64 61 74 61 62 61 73 65 20 63 6f   any database co
6b00: 6e 6e 65 63 74 69 6f 6e 2c 0a 2a 2a 20 65 69 74  nnection,.** eit
6b10: 68 65 72 20 69 6e 20 74 68 69 73 20 70 72 6f 63  her in this proc
6b20: 65 73 73 20 6f 72 20 69 6e 20 73 6f 6d 65 20 6f  ess or in some o
6b30: 74 68 65 72 20 70 72 6f 63 65 73 73 2c 20 69 73  ther process, is
6b40: 20 68 6f 6c 64 69 6e 67 20 61 20 52 45 53 45 52   holding a RESER
6b50: 56 45 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e 47 2c  VED,.** PENDING,
6b60: 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20 6c 6f   or EXCLUSIVE lo
6b70: 63 6b 20 6f 6e 20 74 68 65 20 66 69 6c 65 2e 20  ck on the file. 
6b80: 20 49 74 20 72 65 74 75 72 6e 73 20 74 72 75 65   It returns true
6b90: 0a 2a 2a 20 69 66 20 73 75 63 68 20 61 20 6c 6f  .** if such a lo
6ba0: 63 6b 20 65 78 69 73 74 73 20 61 6e 64 20 66 61  ck exists and fa
6bb0: 6c 73 65 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a  lse otherwise..*
6bc0: 2a 0a 2a 2a 20 54 68 65 20 78 46 69 6c 65 43 6f  *.** The xFileCo
6bd0: 6e 74 72 6f 6c 28 29 20 6d 65 74 68 6f 64 20 69  ntrol() method i
6be0: 73 20 61 20 67 65 6e 65 72 69 63 20 69 6e 74 65  s a generic inte
6bf0: 72 66 61 63 65 20 74 68 61 74 20 61 6c 6c 6f 77  rface that allow
6c00: 73 20 63 75 73 74 6f 6d 0a 2a 2a 20 56 46 53 20  s custom.** VFS 
6c10: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
6c20: 74 6f 20 64 69 72 65 63 74 6c 79 20 63 6f 6e 74  to directly cont
6c30: 72 6f 6c 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65  rol an open file
6c40: 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73   using the.** [s
6c50: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
6c60: 72 6f 6c 28 29 5d 20 69 6e 74 65 72 66 61 63 65  rol()] interface
6c70: 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 22 6f  .  The second "o
6c80: 70 22 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  p" argument is a
6c90: 6e 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6f 70 63  n.** integer opc
6ca0: 6f 64 65 2e 20 20 54 68 65 20 74 68 69 72 64 20  ode.  The third 
6cb0: 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 67 65  argument is a ge
6cc0: 6e 65 72 69 63 20 70 6f 69 6e 74 65 72 20 69 6e  neric pointer in
6cd0: 74 65 6e 64 65 64 20 74 6f 0a 2a 2a 20 70 6f 69  tended to.** poi
6ce0: 6e 74 20 74 6f 20 61 20 73 74 72 75 63 74 75 72  nt to a structur
6cf0: 65 20 74 68 61 74 20 6d 61 79 20 63 6f 6e 74 61  e that may conta
6d00: 69 6e 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20  in arguments or 
6d10: 73 70 61 63 65 20 69 6e 20 77 68 69 63 68 20 74  space in which t
6d20: 6f 0a 2a 2a 20 77 72 69 74 65 20 72 65 74 75 72  o.** write retur
6d30: 6e 20 76 61 6c 75 65 73 2e 20 20 50 6f 74 65 6e  n values.  Poten
6d40: 74 69 61 6c 20 75 73 65 73 20 66 6f 72 20 78 46  tial uses for xF
6d50: 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 69 67  ileControl() mig
6d60: 68 74 20 62 65 0a 2a 2a 20 66 75 6e 63 74 69 6f  ht be.** functio
6d70: 6e 73 20 74 6f 20 65 6e 61 62 6c 65 20 62 6c 6f  ns to enable blo
6d80: 63 6b 69 6e 67 20 6c 6f 63 6b 73 20 77 69 74 68  cking locks with
6d90: 20 74 69 6d 65 6f 75 74 73 2c 20 74 6f 20 63 68   timeouts, to ch
6da0: 61 6e 67 65 20 74 68 65 0a 2a 2a 20 6c 6f 63 6b  ange the.** lock
6db0: 69 6e 67 20 73 74 72 61 74 65 67 79 20 28 66 6f  ing strategy (fo
6dc0: 72 20 65 78 61 6d 70 6c 65 20 74 6f 20 75 73 65  r example to use
6dd0: 20 64 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b 73 29   dot-file locks)
6de0: 2c 20 74 6f 20 69 6e 71 75 69 72 65 0a 2a 2a 20  , to inquire.** 
6df0: 61 62 6f 75 74 20 74 68 65 20 73 74 61 74 75 73  about the status
6e00: 20 6f 66 20 61 20 6c 6f 63 6b 2c 20 6f 72 20 74   of a lock, or t
6e10: 6f 20 62 72 65 61 6b 20 73 74 61 6c 65 20 6c 6f  o break stale lo
6e20: 63 6b 73 2e 20 20 54 68 65 20 53 51 4c 69 74 65  cks.  The SQLite
6e30: 0a 2a 2a 20 63 6f 72 65 20 72 65 73 65 72 76 65  .** core reserve
6e40: 73 20 61 6c 6c 20 6f 70 63 6f 64 65 73 20 6c 65  s all opcodes le
6e50: 73 73 20 74 68 61 6e 20 31 30 30 20 66 6f 72 20  ss than 100 for 
6e60: 69 74 73 20 6f 77 6e 20 75 73 65 2e 0a 2a 2a 20  its own use..** 
6e70: 41 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  A [SQLITE_FCNTL_
6e80: 4c 4f 43 4b 53 54 41 54 45 20 7c 20 6c 69 73 74  LOCKSTATE | list
6e90: 20 6f 66 20 6f 70 63 6f 64 65 73 5d 20 6c 65 73   of opcodes] les
6ea0: 73 20 74 68 61 6e 20 31 30 30 20 69 73 20 61 76  s than 100 is av
6eb0: 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 41 70 70 6c  ailable..** Appl
6ec0: 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 64 65  ications that de
6ed0: 66 69 6e 65 20 61 20 63 75 73 74 6f 6d 20 78 46  fine a custom xF
6ee0: 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f  ileControl metho
6ef0: 64 20 73 68 6f 75 6c 64 20 75 73 65 20 6f 70 63  d should use opc
6f00: 6f 64 65 73 0a 2a 2a 20 67 72 65 61 74 65 72 20  odes.** greater 
6f10: 74 68 61 6e 20 31 30 30 20 74 6f 20 61 76 6f 69  than 100 to avoi
6f20: 64 20 63 6f 6e 66 6c 69 63 74 73 2e 0a 2a 2a 0a  d conflicts..**.
6f30: 2a 2a 20 54 68 65 20 78 53 65 63 74 6f 72 53 69  ** The xSectorSi
6f40: 7a 65 28 29 20 6d 65 74 68 6f 64 20 72 65 74 75  ze() method retu
6f50: 72 6e 73 20 74 68 65 20 73 65 63 74 6f 72 20 73  rns the sector s
6f60: 69 7a 65 20 6f 66 20 74 68 65 0a 2a 2a 20 64 65  ize of the.** de
6f70: 76 69 63 65 20 74 68 61 74 20 75 6e 64 65 72 6c  vice that underl
6f80: 69 65 73 20 74 68 65 20 66 69 6c 65 2e 20 20 54  ies the file.  T
6f90: 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20 69  he sector size i
6fa0: 73 20 74 68 65 0a 2a 2a 20 6d 69 6e 69 6d 75 6d  s the.** minimum
6fb0: 20 77 72 69 74 65 20 74 68 61 74 20 63 61 6e 20   write that can 
6fc0: 62 65 20 70 65 72 66 6f 72 6d 65 64 20 77 69 74  be performed wit
6fd0: 68 6f 75 74 20 64 69 73 74 75 72 62 69 6e 67 0a  hout disturbing.
6fe0: 2a 2a 20 6f 74 68 65 72 20 62 79 74 65 73 20 69  ** other bytes i
6ff0: 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65  n the file.  The
7000: 20 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65   xDeviceCharacte
7010: 72 69 73 74 69 63 73 28 29 0a 2a 2a 20 6d 65 74  ristics().** met
7020: 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20 62 69  hod returns a bi
7030: 74 20 76 65 63 74 6f 72 20 64 65 73 63 72 69 62  t vector describ
7040: 69 6e 67 20 62 65 68 61 76 69 6f 72 73 20 6f 66  ing behaviors of
7050: 20 74 68 65 0a 2a 2a 20 75 6e 64 65 72 6c 79 69   the.** underlyi
7060: 6e 67 20 64 65 76 69 63 65 3a 0a 2a 2a 0a 2a 2a  ng device:.**.**
7070: 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53   <ul>.** <li> [S
7080: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
7090: 49 43 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  IC].** <li> [SQL
70a0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
70b0: 35 31 32 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  512].** <li> [SQ
70c0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
70d0: 43 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  C1K].** <li> [SQ
70e0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
70f0: 43 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  C2K].** <li> [SQ
7100: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
7110: 43 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  C4K].** <li> [SQ
7120: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
7130: 43 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  C8K].** <li> [SQ
7140: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
7150: 43 31 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  C16K].** <li> [S
7160: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
7170: 49 43 33 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  IC32K].** <li> [
7180: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
7190: 4d 49 43 36 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20  MIC64K].** <li> 
71a0: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41  [SQLITE_IOCAP_SA
71b0: 46 45 5f 41 50 50 45 4e 44 5d 0a 2a 2a 20 3c 6c  FE_APPEND].** <l
71c0: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
71d0: 5f 53 45 51 55 45 4e 54 49 41 4c 5d 0a 2a 2a 20  _SEQUENTIAL].** 
71e0: 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  </ul>.**.** The 
71f0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
7200: 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61  MIC property mea
7210: 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74  ns that all writ
7220: 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a  es of.** any siz
7230: 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54  e are atomic.  T
7240: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
7250: 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73  ATOMICnnn values
7260: 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72  .** mean that wr
7270: 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74  ites of blocks t
7280: 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65  hat are nnn byte
7290: 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a  s in size and.**
72a0: 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20   are aligned to 
72b0: 61 6e 20 61 64 64 72 65 73 73 20 77 68 69 63 68  an address which
72c0: 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d   is an integer m
72d0: 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e  ultiple of.** nn
72e0: 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54  n are atomic.  T
72f0: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
7300: 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75  SAFE_APPEND valu
7310: 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20  e means.** that 
7320: 77 68 65 6e 20 64 61 74 61 20 69 73 20 61 70 70  when data is app
7330: 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c  ended to a file,
7340: 20 74 68 65 20 64 61 74 61 20 69 73 20 61 70 70   the data is app
7350: 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74  ended.** first t
7360: 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20  hen the size of 
7370: 74 68 65 20 66 69 6c 65 20 69 73 20 65 78 74 65  the file is exte
7380: 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20  nded, never the 
7390: 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f  other.** way aro
73a0: 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45  und.  The SQLITE
73b0: 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41  _IOCAP_SEQUENTIA
73c0: 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73  L property means
73d0: 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61   that.** informa
73e0: 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20  tion is written 
73f0: 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73  to disk in the s
7400: 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c  ame order as cal
7410: 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28  ls.** to xWrite(
7420: 29 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  )..*/.typedef st
7430: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f  ruct sqlite3_io_
7440: 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65 33 5f  methods sqlite3_
7450: 69 6f 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75  io_methods;.stru
7460: 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  ct sqlite3_io_me
7470: 74 68 6f 64 73 20 7b 0a 20 20 69 6e 74 20 69 56  thods {.  int iV
7480: 65 72 73 69 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a  ersion;.  int (*
7490: 78 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f  xClose)(sqlite3_
74a0: 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  file*);.  int (*
74b0: 78 52 65 61 64 29 28 73 71 6c 69 74 65 33 5f 66  xRead)(sqlite3_f
74c0: 69 6c 65 2a 2c 20 76 6f 69 64 2a 2c 20 69 6e 74  ile*, void*, int
74d0: 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69   iAmt, sqlite3_i
74e0: 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69  nt64 iOfst);.  i
74f0: 6e 74 20 28 2a 78 57 72 69 74 65 29 28 73 71 6c  nt (*xWrite)(sql
7500: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 63 6f 6e 73  ite3_file*, cons
7510: 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d  t void*, int iAm
7520: 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  t, sqlite3_int64
7530: 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28   iOfst);.  int (
7540: 2a 78 54 72 75 6e 63 61 74 65 29 28 73 71 6c 69  *xTruncate)(sqli
7550: 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74  te3_file*, sqlit
7560: 65 33 5f 69 6e 74 36 34 20 73 69 7a 65 29 3b 0a  e3_int64 size);.
7570: 20 20 69 6e 74 20 28 2a 78 53 79 6e 63 29 28 73    int (*xSync)(s
7580: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e  qlite3_file*, in
7590: 74 20 66 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20  t flags);.  int 
75a0: 28 2a 78 46 69 6c 65 53 69 7a 65 29 28 73 71 6c  (*xFileSize)(sql
75b0: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69  ite3_file*, sqli
75c0: 74 65 33 5f 69 6e 74 36 34 20 2a 70 53 69 7a 65  te3_int64 *pSize
75d0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4c 6f 63 6b  );.  int (*xLock
75e0: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
75f0: 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78   int);.  int (*x
7600: 55 6e 6c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f  Unlock)(sqlite3_
7610: 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69  file*, int);.  i
7620: 6e 74 20 28 2a 78 43 68 65 63 6b 52 65 73 65 72  nt (*xCheckReser
7630: 76 65 64 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33  vedLock)(sqlite3
7640: 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 2a 70 52 65  _file*, int *pRe
7650: 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78  sOut);.  int (*x
7660: 46 69 6c 65 43 6f 6e 74 72 6f 6c 29 28 73 71 6c  FileControl)(sql
7670: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20  ite3_file*, int 
7680: 6f 70 2c 20 76 6f 69 64 20 2a 70 41 72 67 29 3b  op, void *pArg);
7690: 0a 20 20 69 6e 74 20 28 2a 78 53 65 63 74 6f 72  .  int (*xSector
76a0: 53 69 7a 65 29 28 73 71 6c 69 74 65 33 5f 66 69  Size)(sqlite3_fi
76b0: 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44  le*);.  int (*xD
76c0: 65 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73  eviceCharacteris
76d0: 74 69 63 73 29 28 73 71 6c 69 74 65 33 5f 66 69  tics)(sqlite3_fi
76e0: 6c 65 2a 29 3b 0a 20 20 2f 2a 20 41 64 64 69 74  le*);.  /* Addit
76f0: 69 6f 6e 61 6c 20 6d 65 74 68 6f 64 73 20 6d 61  ional methods ma
7700: 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75  y be added in fu
7710: 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 2a 2f  ture releases */
7720: 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .};../*.** CAPI3
7730: 52 45 46 3a 20 53 74 61 6e 64 61 72 64 20 46 69  REF: Standard Fi
7740: 6c 65 20 43 6f 6e 74 72 6f 6c 20 4f 70 63 6f 64  le Control Opcod
7750: 65 73 20 7b 48 31 31 33 31 30 7d 20 3c 53 33 30  es {H11310} <S30
7760: 38 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  800>.**.** These
7770: 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e   integer constan
7780: 74 73 20 61 72 65 20 6f 70 63 6f 64 65 73 20 66  ts are opcodes f
7790: 6f 72 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74  or the xFileCont
77a0: 72 6f 6c 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f 66  rol method.** of
77b0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f   the [sqlite3_io
77c0: 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74  _methods] object
77d0: 20 61 6e 64 20 66 6f 72 20 74 68 65 20 5b 73 71   and for the [sq
77e0: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72  lite3_file_contr
77f0: 6f 6c 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61  ol()].** interfa
7800: 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53  ce..**.** The [S
7810: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b  QLITE_FCNTL_LOCK
7820: 53 54 41 54 45 5d 20 6f 70 63 6f 64 65 20 69 73  STATE] opcode is
7830: 20 75 73 65 64 20 66 6f 72 20 64 65 62 75 67 67   used for debugg
7840: 69 6e 67 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70  ing.  This.** op
7850: 63 6f 64 65 20 63 61 75 73 65 73 20 74 68 65 20  code causes the 
7860: 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74  xFileControl met
7870: 68 6f 64 20 74 6f 20 77 72 69 74 65 20 74 68 65  hod to write the
7880: 20 63 75 72 72 65 6e 74 20 73 74 61 74 65 20 6f   current state o
7890: 66 0a 2a 2a 20 74 68 65 20 6c 6f 63 6b 20 28 6f  f.** the lock (o
78a0: 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 4c 4f  ne of [SQLITE_LO
78b0: 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54  CK_NONE], [SQLIT
78c0: 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 5d 2c 0a  E_LOCK_SHARED],.
78d0: 2a 2a 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ** [SQLITE_LOCK_
78e0: 52 45 53 45 52 56 45 44 5d 2c 20 5b 53 51 4c 49  RESERVED], [SQLI
78f0: 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d  TE_LOCK_PENDING]
7900: 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  , or [SQLITE_LOC
7910: 4b 5f 45 58 43 4c 55 53 49 56 45 5d 29 0a 2a 2a  K_EXCLUSIVE]).**
7920: 20 69 6e 74 6f 20 61 6e 20 69 6e 74 65 67 65 72   into an integer
7930: 20 74 68 61 74 20 74 68 65 20 70 41 72 67 20 61   that the pArg a
7940: 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 73 20 74  rgument points t
7950: 6f 2e 20 54 68 69 73 20 63 61 70 61 62 69 6c 69  o. This capabili
7960: 74 79 0a 2a 2a 20 69 73 20 75 73 65 64 20 64 75  ty.** is used du
7970: 72 69 6e 67 20 74 65 73 74 69 6e 67 20 61 6e 64  ring testing and
7980: 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20 62   only needs to b
7990: 65 20 73 75 70 70 6f 72 74 65 64 20 77 68 65 6e  e supported when
79a0: 20 53 51 4c 49 54 45 5f 54 45 53 54 0a 2a 2a 20   SQLITE_TEST.** 
79b0: 69 73 20 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 23  is defined..*/.#
79c0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
79d0: 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 20 20  NTL_LOCKSTATE   
79e0: 20 20 20 20 20 31 0a 0a 2f 2a 0a 2a 2a 20 43 41       1../*.** CA
79f0: 50 49 33 52 45 46 3a 20 4d 75 74 65 78 20 48 61  PI3REF: Mutex Ha
7a00: 6e 64 6c 65 20 7b 48 31 37 31 31 30 7d 20 3c 53  ndle {H17110} <S
7a10: 32 30 31 33 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  20130>.**.** The
7a20: 20 6d 75 74 65 78 20 6d 6f 64 75 6c 65 20 77 69   mutex module wi
7a30: 74 68 69 6e 20 53 51 4c 69 74 65 20 64 65 66 69  thin SQLite defi
7a40: 6e 65 73 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  nes [sqlite3_mut
7a50: 65 78 5d 20 74 6f 20 62 65 20 61 6e 0a 2a 2a 20  ex] to be an.** 
7a60: 61 62 73 74 72 61 63 74 20 74 79 70 65 20 66 6f  abstract type fo
7a70: 72 20 61 20 6d 75 74 65 78 20 6f 62 6a 65 63 74  r a mutex object
7a80: 2e 20 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f  .  The SQLite co
7a90: 72 65 20 6e 65 76 65 72 20 6c 6f 6f 6b 73 0a 2a  re never looks.*
7aa0: 2a 20 61 74 20 74 68 65 20 69 6e 74 65 72 6e 61  * at the interna
7ab0: 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e  l representation
7ac0: 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f   of an [sqlite3_
7ad0: 6d 75 74 65 78 5d 2e 20 20 49 74 20 6f 6e 6c 79  mutex].  It only
7ae0: 0a 2a 2a 20 64 65 61 6c 73 20 77 69 74 68 20 70  .** deals with p
7af0: 6f 69 6e 74 65 72 73 20 74 6f 20 74 68 65 20 5b  ointers to the [
7b00: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 6f  sqlite3_mutex] o
7b10: 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74  bject..**.** Mut
7b20: 65 78 65 73 20 61 72 65 20 63 72 65 61 74 65 64  exes are created
7b30: 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
7b40: 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 2e 0a  mutex_alloc()]..
7b50: 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
7b60: 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20  t sqlite3_mutex 
7b70: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 3b 0a 0a  sqlite3_mutex;..
7b80: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
7b90: 4f 53 20 49 6e 74 65 72 66 61 63 65 20 4f 62 6a  OS Interface Obj
7ba0: 65 63 74 20 7b 48 31 31 31 34 30 7d 20 3c 53 32  ect {H11140} <S2
7bb0: 30 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 41 6e 20 69  0100>.**.** An i
7bc0: 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 73  nstance of the s
7bd0: 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63  qlite3_vfs objec
7be0: 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e  t defines the in
7bf0: 74 65 72 66 61 63 65 20 62 65 74 77 65 65 6e 0a  terface between.
7c00: 2a 2a 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f  ** the SQLite co
7c10: 72 65 20 61 6e 64 20 74 68 65 20 75 6e 64 65 72  re and the under
7c20: 6c 79 69 6e 67 20 6f 70 65 72 61 74 69 6e 67 20  lying operating 
7c30: 73 79 73 74 65 6d 2e 20 20 54 68 65 20 22 76 66  system.  The "vf
7c40: 73 22 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61 6d  s".** in the nam
7c50: 65 20 6f 66 20 74 68 65 20 6f 62 6a 65 63 74 20  e of the object 
7c60: 73 74 61 6e 64 73 20 66 6f 72 20 22 76 69 72 74  stands for "virt
7c70: 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 22  ual file system"
7c80: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 76 61 6c 75  ..**.** The valu
7c90: 65 20 6f 66 20 74 68 65 20 69 56 65 72 73 69 6f  e of the iVersio
7ca0: 6e 20 66 69 65 6c 64 20 69 73 20 69 6e 69 74 69  n field is initi
7cb0: 61 6c 6c 79 20 31 20 62 75 74 20 6d 61 79 20 62  ally 1 but may b
7cc0: 65 20 6c 61 72 67 65 72 20 69 6e 0a 2a 2a 20 66  e larger in.** f
7cd0: 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f  uture versions o
7ce0: 66 20 53 51 4c 69 74 65 2e 20 20 41 64 64 69 74  f SQLite.  Addit
7cf0: 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20 6d 61 79  ional fields may
7d00: 20 62 65 20 61 70 70 65 6e 64 65 64 20 74 6f 20   be appended to 
7d10: 74 68 69 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 77  this.** object w
7d20: 68 65 6e 20 74 68 65 20 69 56 65 72 73 69 6f 6e  hen the iVersion
7d30: 20 76 61 6c 75 65 20 69 73 20 69 6e 63 72 65 61   value is increa
7d40: 73 65 64 2e 20 20 4e 6f 74 65 20 74 68 61 74 20  sed.  Note that 
7d50: 74 68 65 20 73 74 72 75 63 74 75 72 65 0a 2a 2a  the structure.**
7d60: 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f   of the sqlite3_
7d70: 76 66 73 20 6f 62 6a 65 63 74 20 63 68 61 6e 67  vfs object chang
7d80: 65 73 20 69 6e 20 74 68 65 20 74 72 61 6e 73 61  es in the transa
7d90: 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 0a 2a 2a  ction between.**
7da0: 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
7db0: 33 2e 35 2e 39 20 61 6e 64 20 33 2e 36 2e 30 20  3.5.9 and 3.6.0 
7dc0: 61 6e 64 20 79 65 74 20 74 68 65 20 69 56 65 72  and yet the iVer
7dd0: 73 69 6f 6e 20 66 69 65 6c 64 20 77 61 73 20 6e  sion field was n
7de0: 6f 74 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 2e 0a  ot.** modified..
7df0: 2a 2a 0a 2a 2a 20 54 68 65 20 73 7a 4f 73 46 69  **.** The szOsFi
7e00: 6c 65 20 66 69 65 6c 64 20 69 73 20 74 68 65 20  le field is the 
7e10: 73 69 7a 65 20 6f 66 20 74 68 65 20 73 75 62 63  size of the subc
7e20: 6c 61 73 73 65 64 20 5b 73 71 6c 69 74 65 33 5f  lassed [sqlite3_
7e30: 66 69 6c 65 5d 0a 2a 2a 20 73 74 72 75 63 74 75  file].** structu
7e40: 72 65 20 75 73 65 64 20 62 79 20 74 68 69 73 20  re used by this 
7e50: 56 46 53 2e 20 20 6d 78 50 61 74 68 6e 61 6d 65  VFS.  mxPathname
7e60: 20 69 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 20   is the maximum 
7e70: 6c 65 6e 67 74 68 20 6f 66 0a 2a 2a 20 61 20 70  length of.** a p
7e80: 61 74 68 6e 61 6d 65 20 69 6e 20 74 68 69 73 20  athname in this 
7e90: 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73  VFS..**.** Regis
7ea0: 74 65 72 65 64 20 73 71 6c 69 74 65 33 5f 76 66  tered sqlite3_vf
7eb0: 73 20 6f 62 6a 65 63 74 73 20 61 72 65 20 6b 65  s objects are ke
7ec0: 70 74 20 6f 6e 20 61 20 6c 69 6e 6b 65 64 20 6c  pt on a linked l
7ed0: 69 73 74 20 66 6f 72 6d 65 64 20 62 79 0a 2a 2a  ist formed by.**
7ee0: 20 74 68 65 20 70 4e 65 78 74 20 70 6f 69 6e 74   the pNext point
7ef0: 65 72 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65  er.  The [sqlite
7f00: 33 5f 76 66 73 5f 72 65 67 69 73 74 65 72 28 29  3_vfs_register()
7f10: 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65  ].** and [sqlite
7f20: 33 5f 76 66 73 5f 75 6e 72 65 67 69 73 74 65 72  3_vfs_unregister
7f30: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 6d  ()] interfaces m
7f40: 61 6e 61 67 65 20 74 68 69 73 20 6c 69 73 74 0a  anage this list.
7f50: 2a 2a 20 69 6e 20 61 20 74 68 72 65 61 64 2d 73  ** in a thread-s
7f60: 61 66 65 20 77 61 79 2e 20 20 54 68 65 20 5b 73  afe way.  The [s
7f70: 71 6c 69 74 65 33 5f 76 66 73 5f 66 69 6e 64 28  qlite3_vfs_find(
7f80: 29 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  )] interface.** 
7f90: 73 65 61 72 63 68 65 73 20 74 68 65 20 6c 69 73  searches the lis
7fa0: 74 2e 20 20 4e 65 69 74 68 65 72 20 74 68 65 20  t.  Neither the 
7fb0: 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65  application code
7fc0: 20 6e 6f 72 20 74 68 65 20 56 46 53 0a 2a 2a 20   nor the VFS.** 
7fd0: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73  implementation s
7fe0: 68 6f 75 6c 64 20 75 73 65 20 74 68 65 20 70 4e  hould use the pN
7ff0: 65 78 74 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a  ext pointer..**.
8000: 2a 2a 20 54 68 65 20 70 4e 65 78 74 20 66 69 65  ** The pNext fie
8010: 6c 64 20 69 73 20 74 68 65 20 6f 6e 6c 79 20 66  ld is the only f
8020: 69 65 6c 64 20 69 6e 20 74 68 65 20 73 71 6c 69  ield in the sqli
8030: 74 65 33 5f 76 66 73 0a 2a 2a 20 73 74 72 75 63  te3_vfs.** struc
8040: 74 75 72 65 20 74 68 61 74 20 53 51 4c 69 74 65  ture that SQLite
8050: 20 77 69 6c 6c 20 65 76 65 72 20 6d 6f 64 69 66   will ever modif
8060: 79 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  y.  SQLite will 
8070: 6f 6e 6c 79 20 61 63 63 65 73 73 0a 2a 2a 20 6f  only access.** o
8080: 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20 66 69  r modify this fi
8090: 65 6c 64 20 77 68 69 6c 65 20 68 6f 6c 64 69 6e  eld while holdin
80a0: 67 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 73  g a particular s
80b0: 74 61 74 69 63 20 6d 75 74 65 78 2e 0a 2a 2a 20  tatic mutex..** 
80c0: 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
80d0: 73 68 6f 75 6c 64 20 6e 65 76 65 72 20 6d 6f 64  should never mod
80e0: 69 66 79 20 61 6e 79 74 68 69 6e 67 20 77 69 74  ify anything wit
80f0: 68 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f  hin the sqlite3_
8100: 76 66 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 6f 6e  vfs.** object on
8110: 63 65 20 74 68 65 20 6f 62 6a 65 63 74 20 68 61  ce the object ha
8120: 73 20 62 65 65 6e 20 72 65 67 69 73 74 65 72 65  s been registere
8130: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 7a 4e 61  d..**.** The zNa
8140: 6d 65 20 66 69 65 6c 64 20 68 6f 6c 64 73 20 74  me field holds t
8150: 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 56  he name of the V
8160: 46 53 20 6d 6f 64 75 6c 65 2e 20 20 54 68 65 20  FS module.  The 
8170: 6e 61 6d 65 20 6d 75 73 74 0a 2a 2a 20 62 65 20  name must.** be 
8180: 75 6e 69 71 75 65 20 61 63 72 6f 73 73 20 61 6c  unique across al
8190: 6c 20 56 46 53 20 6d 6f 64 75 6c 65 73 2e 0a 2a  l VFS modules..*
81a0: 2a 0a 2a 2a 20 7b 48 31 31 31 34 31 7d 20 53 51  *.** {H11141} SQ
81b0: 4c 69 74 65 20 77 69 6c 6c 20 67 75 61 72 61 6e  Lite will guaran
81c0: 74 65 65 20 74 68 61 74 20 74 68 65 20 7a 46 69  tee that the zFi
81d0: 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72  lename parameter
81e0: 20 74 6f 20 78 4f 70 65 6e 0a 2a 2a 20 69 73 20   to xOpen.** is 
81f0: 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 20 70 6f  either a NULL po
8200: 69 6e 74 65 72 20 6f 72 20 73 74 72 69 6e 67 20  inter or string 
8210: 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d  obtained.** from
8220: 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 28 29   xFullPathname()
8230: 2e 20 20 53 51 4c 69 74 65 20 66 75 72 74 68 65  .  SQLite furthe
8240: 72 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61  r guarantees tha
8250: 74 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20  t.** the string 
8260: 77 69 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 6e  will be valid an
8270: 64 20 75 6e 63 68 61 6e 67 65 64 20 75 6e 74 69  d unchanged unti
8280: 6c 20 78 43 6c 6f 73 65 28 29 20 69 73 0a 2a 2a  l xClose() is.**
8290: 20 63 61 6c 6c 65 64 2e 20 7b 45 4e 44 7d 20 20   called. {END}  
82a0: 42 65 63 61 75 73 65 20 6f 66 20 74 68 65 20 70  Because of the p
82b0: 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 73 65  revious sentense
82c0: 2c 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65  ,.** the [sqlite
82d0: 33 5f 66 69 6c 65 5d 20 63 61 6e 20 73 61 66 65  3_file] can safe
82e0: 6c 79 20 73 74 6f 72 65 20 61 20 70 6f 69 6e 74  ly store a point
82f0: 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 6c  er to the.** fil
8300: 65 6e 61 6d 65 20 69 66 20 69 74 20 6e 65 65 64  ename if it need
8310: 73 20 74 6f 20 72 65 6d 65 6d 62 65 72 20 74 68  s to remember th
8320: 65 20 66 69 6c 65 6e 61 6d 65 20 66 6f 72 20 73  e filename for s
8330: 6f 6d 65 20 72 65 61 73 6f 6e 2e 0a 2a 2a 20 49  ome reason..** I
8340: 66 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20  f the zFilename 
8350: 70 61 72 61 6d 65 74 65 72 20 69 73 20 78 4f 70  parameter is xOp
8360: 65 6e 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  en is a NULL poi
8370: 6e 74 65 72 20 74 68 65 6e 20 78 4f 70 65 6e 0a  nter then xOpen.
8380: 2a 2a 20 6d 75 73 74 20 69 6e 76 69 74 65 20 69  ** must invite i
8390: 74 73 20 6f 77 6e 20 74 65 6d 70 6f 72 61 72 79  ts own temporary
83a0: 20 6e 61 6d 65 20 66 6f 72 20 74 68 65 20 66 69   name for the fi
83b0: 6c 65 2e 20 20 57 68 65 6e 65 76 65 72 20 74 68  le.  Whenever th
83c0: 65 20 0a 2a 2a 20 78 46 69 6c 65 6e 61 6d 65 20  e .** xFilename 
83d0: 70 61 72 61 6d 65 74 65 72 20 69 73 20 4e 55 4c  parameter is NUL
83e0: 4c 20 69 74 20 77 69 6c 6c 20 61 6c 73 6f 20 62  L it will also b
83f0: 65 20 74 68 65 20 63 61 73 65 20 74 68 61 74 20  e the case that 
8400: 74 68 65 0a 2a 2a 20 66 6c 61 67 73 20 70 61 72  the.** flags par
8410: 61 6d 65 74 65 72 20 77 69 6c 6c 20 69 6e 63 6c  ameter will incl
8420: 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  ude [SQLITE_OPEN
8430: 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 2e  _DELETEONCLOSE].
8440: 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 31 34 32 7d 20  .**.** {H11142} 
8450: 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65  The flags argume
8460: 6e 74 20 74 6f 20 78 4f 70 65 6e 28 29 20 69 6e  nt to xOpen() in
8470: 63 6c 75 64 65 73 20 61 6c 6c 20 62 69 74 73 20  cludes all bits 
8480: 73 65 74 20 69 6e 0a 2a 2a 20 74 68 65 20 66 6c  set in.** the fl
8490: 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ags argument to 
84a0: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
84b0: 28 29 5d 2e 20 20 4f 72 20 69 66 20 5b 73 71 6c  ()].  Or if [sql
84c0: 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20  ite3_open()].** 
84d0: 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  or [sqlite3_open
84e0: 31 36 28 29 5d 20 69 73 20 75 73 65 64 2c 20 74  16()] is used, t
84f0: 68 65 6e 20 66 6c 61 67 73 20 69 6e 63 6c 75 64  hen flags includ
8500: 65 73 20 61 74 20 6c 65 61 73 74 0a 2a 2a 20 5b  es at least.** [
8510: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
8520: 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45  WRITE] | [SQLITE
8530: 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 2e 20 7b  _OPEN_CREATE]. {
8540: 45 4e 44 7d 0a 2a 2a 20 49 66 20 78 4f 70 65 6e  END}.** If xOpen
8550: 28 29 20 6f 70 65 6e 73 20 61 20 66 69 6c 65 20  () opens a file 
8560: 72 65 61 64 2d 6f 6e 6c 79 20 74 68 65 6e 20 69  read-only then i
8570: 74 20 73 65 74 73 20 2a 70 4f 75 74 46 6c 61 67  t sets *pOutFlag
8580: 73 20 74 6f 0a 2a 2a 20 69 6e 63 6c 75 64 65 20  s to.** include 
8590: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
85a0: 44 4f 4e 4c 59 5d 2e 20 20 4f 74 68 65 72 20 62  DONLY].  Other b
85b0: 69 74 73 20 69 6e 20 2a 70 4f 75 74 46 6c 61 67  its in *pOutFlag
85c0: 73 20 6d 61 79 20 62 65 20 73 65 74 2e 0a 2a 2a  s may be set..**
85d0: 0a 2a 2a 20 7b 48 31 31 31 34 33 7d 20 53 51 4c  .** {H11143} SQL
85e0: 69 74 65 20 77 69 6c 6c 20 61 6c 73 6f 20 61 64  ite will also ad
85f0: 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c  d one of the fol
8600: 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20 74 6f 20  lowing flags to 
8610: 74 68 65 20 78 4f 70 65 6e 28 29 0a 2a 2a 20 63  the xOpen().** c
8620: 61 6c 6c 2c 20 64 65 70 65 6e 64 69 6e 67 20 6f  all, depending o
8630: 6e 20 74 68 65 20 6f 62 6a 65 63 74 20 62 65 69  n the object bei
8640: 6e 67 20 6f 70 65 6e 65 64 3a 0a 2a 2a 0a 2a 2a  ng opened:.**.**
8650: 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 5b   <ul>.** <li>  [
8660: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e  SQLITE_OPEN_MAIN
8670: 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  _DB].** <li>  [S
8680: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f  QLITE_OPEN_MAIN_
8690: 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e  JOURNAL].** <li>
86a0: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54    [SQLITE_OPEN_T
86b0: 45 4d 50 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20  EMP_DB].** <li> 
86c0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45   [SQLITE_OPEN_TE
86d0: 4d 50 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c  MP_JOURNAL].** <
86e0: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
86f0: 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42 5d 0a  N_TRANSIENT_DB].
8700: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
8710: 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c  _OPEN_SUBJOURNAL
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 4d 41 53 54 45 52 5f 4a  TE_OPEN_MASTER_J
8740: 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e  OURNAL].** </ul>
8750: 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 65   {END}.**.** The
8760: 20 66 69 6c 65 20 49 2f 4f 20 69 6d 70 6c 65 6d   file I/O implem
8770: 65 6e 74 61 74 69 6f 6e 20 63 61 6e 20 75 73 65  entation can use
8780: 20 74 68 65 20 6f 62 6a 65 63 74 20 74 79 70 65   the object type
8790: 20 66 6c 61 67 73 20 74 6f 0a 2a 2a 20 63 68 61   flags to.** cha
87a0: 6e 67 65 20 74 68 65 20 77 61 79 20 69 74 20 64  nge the way it d
87b0: 65 61 6c 73 20 77 69 74 68 20 66 69 6c 65 73 2e  eals with files.
87c0: 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61    For example, a
87d0: 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a  n application.**
87e0: 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 63   that does not c
87f0: 61 72 65 20 61 62 6f 75 74 20 63 72 61 73 68 20  are about crash 
8800: 72 65 63 6f 76 65 72 79 20 6f 72 20 72 6f 6c 6c  recovery or roll
8810: 62 61 63 6b 20 6d 69 67 68 74 20 6d 61 6b 65 0a  back might make.
8820: 2a 2a 20 74 68 65 20 6f 70 65 6e 20 6f 66 20 61  ** the open of a
8830: 20 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 61 20   journal file a 
8840: 6e 6f 2d 6f 70 2e 20 20 57 72 69 74 65 73 20 74  no-op.  Writes t
8850: 6f 20 74 68 69 73 20 6a 6f 75 72 6e 61 6c 20 77  o this journal w
8860: 6f 75 6c 64 0a 2a 2a 20 61 6c 73 6f 20 62 65 20  ould.** also be 
8870: 6e 6f 2d 6f 70 73 2c 20 61 6e 64 20 61 6e 79 20  no-ops, and any 
8880: 61 74 74 65 6d 70 74 20 74 6f 20 72 65 61 64 20  attempt to read 
8890: 74 68 65 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c  the journal woul
88a0: 64 20 72 65 74 75 72 6e 0a 2a 2a 20 53 51 4c 49  d return.** SQLI
88b0: 54 45 5f 49 4f 45 52 52 2e 20 20 4f 72 20 74 68  TE_IOERR.  Or th
88c0: 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
88d0: 20 6d 69 67 68 74 20 72 65 63 6f 67 6e 69 7a 65   might recognize
88e0: 20 74 68 61 74 20 61 20 64 61 74 61 62 61 73 65   that a database
88f0: 0a 2a 2a 20 66 69 6c 65 20 77 69 6c 6c 20 62 65  .** file will be
8900: 20 64 6f 69 6e 67 20 70 61 67 65 2d 61 6c 69 67   doing page-alig
8910: 6e 65 64 20 73 65 63 74 6f 72 20 72 65 61 64 73  ned sector reads
8920: 20 61 6e 64 20 77 72 69 74 65 73 20 69 6e 20 61   and writes in a
8930: 20 72 61 6e 64 6f 6d 0a 2a 2a 20 6f 72 64 65 72   random.** order
8940: 20 61 6e 64 20 73 65 74 20 75 70 20 69 74 73 20   and set up its 
8950: 49 2f 4f 20 73 75 62 73 79 73 74 65 6d 20 61 63  I/O subsystem ac
8960: 63 6f 72 64 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a 2a  cordingly..**.**
8970: 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20 61 6c   SQLite might al
8980: 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68  so add one of th
8990: 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67  e following flag
89a0: 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 20 6d  s to the xOpen m
89b0: 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  ethod:.**.** <ul
89c0: 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  >.** <li> [SQLIT
89d0: 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43  E_OPEN_DELETEONC
89e0: 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  LOSE].** <li> [S
89f0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55  QLITE_OPEN_EXCLU
8a00: 53 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  SIVE].** </ul>.*
8a10: 2a 0a 2a 2a 20 7b 48 31 31 31 34 35 7d 20 54 68  *.** {H11145} Th
8a20: 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44  e [SQLITE_OPEN_D
8a30: 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 20 66 6c  ELETEONCLOSE] fl
8a40: 61 67 20 6d 65 61 6e 73 20 74 68 65 20 66 69 6c  ag means the fil
8a50: 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 64  e should be.** d
8a60: 65 6c 65 74 65 64 20 77 68 65 6e 20 69 74 20 69  eleted when it i
8a70: 73 20 63 6c 6f 73 65 64 2e 20 20 7b 48 31 31 31  s closed.  {H111
8a80: 34 36 7d 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  46} The [SQLITE_
8a90: 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f  OPEN_DELETEONCLO
8aa0: 53 45 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 73  SE].** will be s
8ab0: 65 74 20 66 6f 72 20 54 45 4d 50 20 20 64 61 74  et for TEMP  dat
8ac0: 61 62 61 73 65 73 2c 20 6a 6f 75 72 6e 61 6c 73  abases, journals
8ad0: 20 61 6e 64 20 66 6f 72 20 73 75 62 6a 6f 75 72   and for subjour
8ae0: 6e 61 6c 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31  nals..**.** {H11
8af0: 31 34 37 7d 20 54 68 65 20 5b 53 51 4c 49 54 45  147} The [SQLITE
8b00: 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d  _OPEN_EXCLUSIVE]
8b10: 20 66 6c 61 67 20 6d 65 61 6e 73 20 74 68 65 20   flag means the 
8b20: 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 6f  file should be o
8b30: 70 65 6e 65 64 0a 2a 2a 20 66 6f 72 20 65 78 63  pened.** for exc
8b40: 6c 75 73 69 76 65 20 61 63 63 65 73 73 2e 20 20  lusive access.  
8b50: 54 68 69 73 20 66 6c 61 67 20 69 73 20 73 65 74  This flag is set
8b60: 20 66 6f 72 20 61 6c 6c 20 66 69 6c 65 73 20 65   for all files e
8b70: 78 63 65 70 74 0a 2a 2a 20 66 6f 72 20 74 68 65  xcept.** for the
8b80: 20 6d 61 69 6e 20 64 61 74 61 62 61 73 65 20 66   main database f
8b90: 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 31  ile..**.** {H111
8ba0: 34 38 7d 20 41 74 20 6c 65 61 73 74 20 73 7a 4f  48} At least szO
8bb0: 73 46 69 6c 65 20 62 79 74 65 73 20 6f 66 20 6d  sFile bytes of m
8bc0: 65 6d 6f 72 79 20 61 72 65 20 61 6c 6c 6f 63 61  emory are alloca
8bd0: 74 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a  ted by SQLite.**
8be0: 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 20 5b 73   to hold the  [s
8bf0: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 73 74 72  qlite3_file] str
8c00: 75 63 74 75 72 65 20 70 61 73 73 65 64 20 61 73  ucture passed as
8c10: 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 61 72   the third.** ar
8c20: 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 2e  gument to xOpen.
8c30: 20 7b 45 4e 44 7d 20 20 54 68 65 20 78 4f 70 65   {END}  The xOpe
8c40: 6e 20 6d 65 74 68 6f 64 20 64 6f 65 73 20 6e 6f  n method does no
8c50: 74 20 68 61 76 65 20 74 6f 0a 2a 2a 20 61 6c 6c  t have to.** all
8c60: 6f 63 61 74 65 20 74 68 65 20 73 74 72 75 63 74  ocate the struct
8c70: 75 72 65 3b 20 69 74 20 73 68 6f 75 6c 64 20 6a  ure; it should j
8c80: 75 73 74 20 66 69 6c 6c 20 69 74 20 69 6e 2e 0a  ust fill it in..
8c90: 2a 2a 0a 2a 2a 20 7b 48 31 31 31 34 39 7d 20 54  **.** {H11149} T
8ca0: 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e  he flags argumen
8cb0: 74 20 74 6f 20 78 41 63 63 65 73 73 28 29 20 6d  t to xAccess() m
8cc0: 61 79 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 43  ay be [SQLITE_AC
8cd0: 43 45 53 53 5f 45 58 49 53 54 53 5d 0a 2a 2a 20  CESS_EXISTS].** 
8ce0: 74 6f 20 74 65 73 74 20 66 6f 72 20 74 68 65 20  to test for the 
8cf0: 65 78 69 73 74 65 6e 63 65 20 6f 66 20 61 20 66  existence of a f
8d00: 69 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  ile, or [SQLITE_
8d10: 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45  ACCESS_READWRITE
8d20: 5d 20 74 6f 0a 2a 2a 20 74 65 73 74 20 77 68 65  ] to.** test whe
8d30: 74 68 65 72 20 61 20 66 69 6c 65 20 69 73 20 72  ther a file is r
8d40: 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74  eadable and writ
8d50: 61 62 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45  able, or [SQLITE
8d60: 5f 41 43 43 45 53 53 5f 52 45 41 44 5d 0a 2a 2a  _ACCESS_READ].**
8d70: 20 74 6f 20 74 65 73 74 20 77 68 65 74 68 65 72   to test whether
8d80: 20 61 20 66 69 6c 65 20 69 73 20 61 74 20 6c 65   a file is at le
8d90: 61 73 74 20 72 65 61 64 61 62 6c 65 2e 20 7b 45  ast readable. {E
8da0: 4e 44 7d 20 20 54 68 65 20 66 69 6c 65 20 63 61  ND}  The file ca
8db0: 6e 20 62 65 20 61 0a 2a 2a 20 64 69 72 65 63 74  n be a.** direct
8dc0: 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 31  ory..**.** {H111
8dd0: 35 30 7d 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  50} SQLite will 
8de0: 61 6c 77 61 79 73 20 61 6c 6c 6f 63 61 74 65 20  always allocate 
8df0: 61 74 20 6c 65 61 73 74 20 6d 78 50 61 74 68 6e  at least mxPathn
8e00: 61 6d 65 2b 31 20 62 79 74 65 73 20 66 6f 72 20  ame+1 bytes for 
8e10: 74 68 65 0a 2a 2a 20 6f 75 74 70 75 74 20 62 75  the.** output bu
8e20: 66 66 65 72 20 78 46 75 6c 6c 50 61 74 68 6e 61  ffer xFullPathna
8e30: 6d 65 2e 20 7b 48 31 31 31 35 31 7d 20 54 68 65  me. {H11151} The
8e40: 20 65 78 61 63 74 20 73 69 7a 65 20 6f 66 20 74   exact size of t
8e50: 68 65 20 6f 75 74 70 75 74 20 62 75 66 66 65 72  he output buffer
8e60: 0a 2a 2a 20 69 73 20 61 6c 73 6f 20 70 61 73 73  .** is also pass
8e70: 65 64 20 61 73 20 61 20 70 61 72 61 6d 65 74 65  ed as a paramete
8e80: 72 20 74 6f 20 62 6f 74 68 20 20 6d 65 74 68 6f  r to both  metho
8e90: 64 73 2e 20 7b 45 4e 44 7d 20 20 49 66 20 74 68  ds. {END}  If th
8ea0: 65 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 0a  e output buffer.
8eb0: 2a 2a 20 69 73 20 6e 6f 74 20 6c 61 72 67 65 20  ** is not large 
8ec0: 65 6e 6f 75 67 68 2c 20 5b 53 51 4c 49 54 45 5f  enough, [SQLITE_
8ed0: 43 41 4e 54 4f 50 45 4e 5d 20 73 68 6f 75 6c 64  CANTOPEN] should
8ee0: 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20 53 69   be returned. Si
8ef0: 6e 63 65 20 74 68 69 73 20 69 73 0a 2a 2a 20 68  nce this is.** h
8f00: 61 6e 64 6c 65 64 20 61 73 20 61 20 66 61 74 61  andled as a fata
8f10: 6c 20 65 72 72 6f 72 20 62 79 20 53 51 4c 69 74  l error by SQLit
8f20: 65 2c 20 76 66 73 20 69 6d 70 6c 65 6d 65 6e 74  e, vfs implement
8f30: 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 65 6e  ations should en
8f40: 64 65 61 76 6f 72 0a 2a 2a 20 74 6f 20 70 72 65  deavor.** to pre
8f50: 76 65 6e 74 20 74 68 69 73 20 62 79 20 73 65 74  vent this by set
8f60: 74 69 6e 67 20 6d 78 50 61 74 68 6e 61 6d 65 20  ting mxPathname 
8f70: 74 6f 20 61 20 73 75 66 66 69 63 69 65 6e 74 6c  to a sufficientl
8f80: 79 20 6c 61 72 67 65 20 76 61 6c 75 65 2e 0a 2a  y large value..*
8f90: 2a 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d  *.** The xRandom
8fa0: 6e 65 73 73 28 29 2c 20 78 53 6c 65 65 70 28 29  ness(), xSleep()
8fb0: 2c 20 61 6e 64 20 78 43 75 72 72 65 6e 74 54 69  , and xCurrentTi
8fc0: 6d 65 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a  me() interfaces.
8fd0: 2a 2a 20 61 72 65 20 6e 6f 74 20 73 74 72 69 63  ** are not stric
8fe0: 74 6c 79 20 61 20 70 61 72 74 20 6f 66 20 74 68  tly a part of th
8ff0: 65 20 66 69 6c 65 73 79 73 74 65 6d 2c 20 62 75  e filesystem, bu
9000: 74 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 69 6e  t they are.** in
9010: 63 6c 75 64 65 64 20 69 6e 20 74 68 65 20 56 46  cluded in the VF
9020: 53 20 73 74 72 75 63 74 75 72 65 20 66 6f 72 20  S structure for 
9030: 63 6f 6d 70 6c 65 74 65 6e 65 73 73 2e 0a 2a 2a  completeness..**
9040: 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73   The xRandomness
9050: 28 29 20 66 75 6e 63 74 69 6f 6e 20 61 74 74 65  () function atte
9060: 6d 70 74 73 20 74 6f 20 72 65 74 75 72 6e 20 6e  mpts to return n
9070: 42 79 74 65 73 20 62 79 74 65 73 0a 2a 2a 20 6f  Bytes bytes.** o
9080: 66 20 67 6f 6f 64 2d 71 75 61 6c 69 74 79 20 72  f good-quality r
9090: 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 7a  andomness into z
90a0: 4f 75 74 2e 20 20 54 68 65 20 72 65 74 75 72 6e  Out.  The return
90b0: 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20 74 68 65   value is.** the
90c0: 20 61 63 74 75 61 6c 20 6e 75 6d 62 65 72 20 6f   actual number o
90d0: 66 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64 6f  f bytes of rando
90e0: 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 2e 0a  mness obtained..
90f0: 2a 2a 20 54 68 65 20 78 53 6c 65 65 70 28 29 20  ** The xSleep() 
9100: 6d 65 74 68 6f 64 20 63 61 75 73 65 73 20 74 68  method causes th
9110: 65 20 63 61 6c 6c 69 6e 67 20 74 68 72 65 61 64  e calling thread
9120: 20 74 6f 20 73 6c 65 65 70 20 66 6f 72 20 61 74   to sleep for at
9130: 0a 2a 2a 20 6c 65 61 73 74 20 74 68 65 20 6e 75  .** least the nu
9140: 6d 62 65 72 20 6f 66 20 6d 69 63 72 6f 73 65 63  mber of microsec
9150: 6f 6e 64 73 20 67 69 76 65 6e 2e 20 20 54 68 65  onds given.  The
9160: 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29 0a   xCurrentTime().
9170: 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e  ** method return
9180: 73 20 61 20 4a 75 6c 69 61 6e 20 44 61 79 20 4e  s a Julian Day N
9190: 75 6d 62 65 72 20 66 6f 72 20 74 68 65 20 63 75  umber for the cu
91a0: 72 72 65 6e 74 20 64 61 74 65 20 61 6e 64 20 74  rrent date and t
91b0: 69 6d 65 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ime..*/.typedef 
91c0: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76  struct sqlite3_v
91d0: 66 73 20 73 71 6c 69 74 65 33 5f 76 66 73 3b 0a  fs sqlite3_vfs;.
91e0: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76  struct sqlite3_v
91f0: 66 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73  fs {.  int iVers
9200: 69 6f 6e 3b 20 20 20 20 20 20 20 20 20 20 20 20  ion;            
9210: 2f 2a 20 53 74 72 75 63 74 75 72 65 20 76 65 72  /* Structure ver
9220: 73 69 6f 6e 20 6e 75 6d 62 65 72 20 2a 2f 0a 20  sion number */. 
9230: 20 69 6e 74 20 73 7a 4f 73 46 69 6c 65 3b 20 20   int szOsFile;  
9240: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 69 7a            /* Siz
9250: 65 20 6f 66 20 73 75 62 63 6c 61 73 73 65 64 20  e of subclassed 
9260: 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 2a 2f 0a  sqlite3_file */.
9270: 20 20 69 6e 74 20 6d 78 50 61 74 68 6e 61 6d 65    int mxPathname
9280: 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61  ;          /* Ma
9290: 78 69 6d 75 6d 20 66 69 6c 65 20 70 61 74 68 6e  ximum file pathn
92a0: 61 6d 65 20 6c 65 6e 67 74 68 20 2a 2f 0a 20 20  ame length */.  
92b0: 73 71 6c 69 74 65 33 5f 76 66 73 20 2a 70 4e 65  sqlite3_vfs *pNe
92c0: 78 74 3b 20 20 20 20 20 20 2f 2a 20 4e 65 78 74  xt;      /* Next
92d0: 20 72 65 67 69 73 74 65 72 65 64 20 56 46 53 20   registered VFS 
92e0: 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
92f0: 2a 7a 4e 61 6d 65 3b 20 20 20 20 20 20 20 2f 2a  *zName;       /*
9300: 20 4e 61 6d 65 20 6f 66 20 74 68 69 73 20 76 69   Name of this vi
9310: 72 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65  rtual file syste
9320: 6d 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70  m */.  void *pAp
9330: 70 44 61 74 61 3b 20 20 20 20 20 20 20 20 20 20  pData;          
9340: 2f 2a 20 50 6f 69 6e 74 65 72 20 74 6f 20 61 70  /* Pointer to ap
9350: 70 6c 69 63 61 74 69 6f 6e 2d 73 70 65 63 69 66  plication-specif
9360: 69 63 20 64 61 74 61 20 2a 2f 0a 20 20 69 6e 74  ic data */.  int
9370: 20 28 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74 65   (*xOpen)(sqlite
9380: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
9390: 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74  ar *zName, sqlit
93a0: 65 33 5f 66 69 6c 65 2a 2c 0a 20 20 20 20 20 20  e3_file*,.      
93b0: 20 20 20 20 20 20 20 20 20 69 6e 74 20 66 6c 61           int fla
93c0: 67 73 2c 20 69 6e 74 20 2a 70 4f 75 74 46 6c 61  gs, int *pOutFla
93d0: 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65  gs);.  int (*xDe
93e0: 6c 65 74 65 29 28 73 71 6c 69 74 65 33 5f 76 66  lete)(sqlite3_vf
93f0: 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  s*, const char *
9400: 7a 4e 61 6d 65 2c 20 69 6e 74 20 73 79 6e 63 44  zName, int syncD
9410: 69 72 29 3b 0a 20 20 69 6e 74 20 28 2a 78 41 63  ir);.  int (*xAc
9420: 63 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66  cess)(sqlite3_vf
9430: 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  s*, const char *
9440: 7a 4e 61 6d 65 2c 20 69 6e 74 20 66 6c 61 67 73  zName, int flags
9450: 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b  , int *pResOut);
9460: 0a 20 20 69 6e 74 20 28 2a 78 46 75 6c 6c 50 61  .  int (*xFullPa
9470: 74 68 6e 61 6d 65 29 28 73 71 6c 69 74 65 33 5f  thname)(sqlite3_
9480: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
9490: 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 6e 4f 75   *zName, int nOu
94a0: 74 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a  t, char *zOut);.
94b0: 20 20 76 6f 69 64 20 2a 28 2a 78 44 6c 4f 70 65    void *(*xDlOpe
94c0: 6e 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  n)(sqlite3_vfs*,
94d0: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69   const char *zFi
94e0: 6c 65 6e 61 6d 65 29 3b 0a 20 20 76 6f 69 64 20  lename);.  void 
94f0: 28 2a 78 44 6c 45 72 72 6f 72 29 28 73 71 6c 69  (*xDlError)(sqli
9500: 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42  te3_vfs*, int nB
9510: 79 74 65 2c 20 63 68 61 72 20 2a 7a 45 72 72 4d  yte, char *zErrM
9520: 73 67 29 3b 0a 20 20 76 6f 69 64 20 2a 28 2a 78  sg);.  void *(*x
9530: 44 6c 53 79 6d 29 28 73 71 6c 69 74 65 33 5f 76  DlSym)(sqlite3_v
9540: 66 73 2a 2c 76 6f 69 64 2a 2c 20 63 6f 6e 73 74  fs*,void*, const
9550: 20 63 68 61 72 20 2a 7a 53 79 6d 62 6f 6c 29 3b   char *zSymbol);
9560: 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 43 6c 6f  .  void (*xDlClo
9570: 73 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  se)(sqlite3_vfs*
9580: 2c 20 76 6f 69 64 2a 29 3b 0a 20 20 69 6e 74 20  , void*);.  int 
9590: 28 2a 78 52 61 6e 64 6f 6d 6e 65 73 73 29 28 73  (*xRandomness)(s
95a0: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74  qlite3_vfs*, int
95b0: 20 6e 42 79 74 65 2c 20 63 68 61 72 20 2a 7a 4f   nByte, char *zO
95c0: 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 6c  ut);.  int (*xSl
95d0: 65 65 70 29 28 73 71 6c 69 74 65 33 5f 76 66 73  eep)(sqlite3_vfs
95e0: 2a 2c 20 69 6e 74 20 6d 69 63 72 6f 73 65 63 6f  *, int microseco
95f0: 6e 64 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43  nds);.  int (*xC
9600: 75 72 72 65 6e 74 54 69 6d 65 29 28 73 71 6c 69  urrentTime)(sqli
9610: 74 65 33 5f 76 66 73 2a 2c 20 64 6f 75 62 6c 65  te3_vfs*, double
9620: 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 47 65 74  *);.  int (*xGet
9630: 4c 61 73 74 45 72 72 6f 72 29 28 73 71 6c 69 74  LastError)(sqlit
9640: 65 33 5f 76 66 73 2a 2c 20 69 6e 74 2c 20 63 68  e3_vfs*, int, ch
9650: 61 72 20 2a 29 3b 0a 20 20 2f 2a 20 4e 65 77 20  ar *);.  /* New 
9660: 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61 70  fields may be ap
9670: 70 65 6e 64 65 64 20 69 6e 20 66 69 67 75 72 65  pended in figure
9680: 20 76 65 72 73 69 6f 6e 73 2e 20 20 54 68 65 20   versions.  The 
9690: 69 56 65 72 73 69 6f 6e 0a 20 20 2a 2a 20 76 61  iVersion.  ** va
96a0: 6c 75 65 20 77 69 6c 6c 20 69 6e 63 72 65 6d 65  lue will increme
96b0: 6e 74 20 77 68 65 6e 65 76 65 72 20 74 68 69 73  nt whenever this
96c0: 20 68 61 70 70 65 6e 73 2e 20 2a 2f 0a 7d 3b 0a   happens. */.};.
96d0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
96e0: 20 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20 78   Flags for the x
96f0: 41 63 63 65 73 73 20 56 46 53 20 6d 65 74 68 6f  Access VFS metho
9700: 64 20 7b 48 31 31 31 39 30 7d 20 3c 48 31 31 31  d {H11190} <H111
9710: 34 30 3e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 31 39  40>.**.** {H1119
9720: 31 7d 20 54 68 65 73 65 20 69 6e 74 65 67 65 72  1} These integer
9730: 20 63 6f 6e 73 74 61 6e 74 73 20 63 61 6e 20 62   constants can b
9740: 65 20 75 73 65 64 20 61 73 20 74 68 65 20 74 68  e used as the th
9750: 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ird parameter to
9760: 0a 2a 2a 20 74 68 65 20 78 41 63 63 65 73 73 20  .** the xAccess 
9770: 6d 65 74 68 6f 64 20 6f 66 20 61 6e 20 5b 73 71  method of an [sq
9780: 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63  lite3_vfs] objec
9790: 74 2e 20 7b 45 4e 44 7d 20 20 54 68 65 79 20 64  t. {END}  They d
97a0: 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 77 68 61 74  etermine.** what
97b0: 20 6b 69 6e 64 20 6f 66 20 70 65 72 6d 69 73 73   kind of permiss
97c0: 69 6f 6e 73 20 74 68 65 20 78 41 63 63 65 73 73  ions the xAccess
97d0: 20 6d 65 74 68 6f 64 20 69 73 20 6c 6f 6f 6b 69   method is looki
97e0: 6e 67 20 66 6f 72 2e 0a 2a 2a 20 7b 48 31 31 31  ng for..** {H111
97f0: 39 32 7d 20 57 69 74 68 20 53 51 4c 49 54 45 5f  92} With SQLITE_
9800: 41 43 43 45 53 53 5f 45 58 49 53 54 53 2c 20 74  ACCESS_EXISTS, t
9810: 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f  he xAccess metho
9820: 64 0a 2a 2a 20 73 69 6d 70 6c 79 20 63 68 65 63  d.** simply chec
9830: 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20 66  ks whether the f
9840: 69 6c 65 20 65 78 69 73 74 73 2e 0a 2a 2a 20 7b  ile exists..** {
9850: 48 31 31 31 39 33 7d 20 57 69 74 68 20 53 51 4c  H11193} With SQL
9860: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57  ITE_ACCESS_READW
9870: 52 49 54 45 2c 20 74 68 65 20 78 41 63 63 65 73  RITE, the xAcces
9880: 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63  s method.** chec
9890: 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20 66  ks whether the f
98a0: 69 6c 65 20 69 73 20 62 6f 74 68 20 72 65 61 64  ile is both read
98b0: 61 62 6c 65 20 61 6e 64 20 77 72 69 74 61 62 6c  able and writabl
98c0: 65 2e 0a 2a 2a 20 7b 48 31 31 31 39 34 7d 20 57  e..** {H11194} W
98d0: 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53  ith SQLITE_ACCES
98e0: 53 5f 52 45 41 44 2c 20 74 68 65 20 78 41 63 63  S_READ, the xAcc
98f0: 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68  ess method.** ch
9900: 65 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65  ecks whether the
9910: 20 66 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c   file is readabl
9920: 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  e..*/.#define SQ
9930: 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53  LITE_ACCESS_EXIS
9940: 54 53 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20  TS    0.#define 
9950: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45  SQLITE_ACCESS_RE
9960: 41 44 57 52 49 54 45 20 31 0a 23 64 65 66 69 6e  ADWRITE 1.#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 20 20 20 20 20 20 32 0a 0a 2f 2a 0a  READ      2../*.
9990: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 69  ** CAPI3REF: Ini
99a0: 74 69 61 6c 69 7a 65 20 54 68 65 20 53 51 4c 69  tialize The SQLi
99b0: 74 65 20 4c 69 62 72 61 72 79 20 7b 48 31 30 31  te Library {H101
99c0: 33 30 7d 20 3c 53 32 30 30 30 30 3e 3c 53 33 30  30} <S20000><S30
99d0: 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  100>.**.** The s
99e0: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
99f0: 65 28 29 20 72 6f 75 74 69 6e 65 20 69 6e 69 74  e() routine init
9a00: 69 61 6c 69 7a 65 73 20 74 68 65 0a 2a 2a 20 53  ializes the.** S
9a10: 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20  QLite library.  
9a20: 54 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74  The sqlite3_shut
9a30: 64 6f 77 6e 28 29 20 72 6f 75 74 69 6e 65 0a 2a  down() routine.*
9a40: 2a 20 64 65 61 6c 6c 6f 63 61 74 65 73 20 61 6e  * deallocates an
9a50: 79 20 72 65 73 6f 75 72 63 65 73 20 74 68 61 74  y resources that
9a60: 20 77 65 72 65 20 61 6c 6c 6f 63 61 74 65 64 20   were allocated 
9a70: 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  by sqlite3_initi
9a80: 61 6c 69 7a 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 41  alize()..**.** A
9a90: 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
9aa0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73  _initialize() is
9ab0: 20 61 6e 20 22 65 66 66 65 63 74 69 76 65 22 20   an "effective" 
9ac0: 63 61 6c 6c 20 69 66 20 69 74 20 69 73 0a 2a 2a  call if it is.**
9ad0: 20 74 68 65 20 66 69 72 73 74 20 74 69 6d 65 20   the first time 
9ae0: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
9af0: 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20  ze() is invoked 
9b00: 64 75 72 69 6e 67 20 74 68 65 20 6c 69 66 65 74  during the lifet
9b10: 69 6d 65 20 6f 66 0a 2a 2a 20 74 68 65 20 70 72  ime of.** the pr
9b20: 6f 63 65 73 73 2c 20 6f 72 20 69 66 20 69 74 20  ocess, or if it 
9b30: 69 73 20 74 68 65 20 66 69 72 73 74 20 74 69 6d  is the first tim
9b40: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
9b50: 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65  lize() is invoke
9b60: 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61  d.** following a
9b70: 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
9b80: 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 4f 6e  _shutdown().  On
9b90: 6c 79 20 61 6e 20 65 66 66 65 63 74 69 76 65 20  ly an effective 
9ba0: 63 61 6c 6c 0a 2a 2a 20 6f 66 20 73 71 6c 69 74  call.** of sqlit
9bb0: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
9bc0: 64 6f 65 73 20 61 6e 79 20 69 6e 69 74 69 61 6c  does any initial
9bd0: 69 7a 61 74 69 6f 6e 2e 20 20 41 6c 6c 20 6f 74  ization.  All ot
9be0: 68 65 72 20 63 61 6c 6c 73 0a 2a 2a 20 61 72 65  her calls.** are
9bf0: 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73   harmless no-ops
9c00: 2e 0a 2a 2a 0a 2a 2a 20 41 6d 6f 6e 67 20 6f 74  ..**.** Among ot
9c10: 68 65 72 20 74 68 69 6e 67 73 2c 20 73 71 6c 69  her things, sqli
9c20: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
9c30: 20 73 68 61 6c 6c 20 69 6e 76 6f 6b 65 0a 2a 2a   shall invoke.**
9c40: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
9c50: 28 29 2e 20 20 53 69 6d 69 6c 61 72 6c 79 2c 20  ().  Similarly, 
9c60: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
9c70: 28 29 0a 2a 2a 20 73 68 61 6c 6c 20 69 6e 76 6f  ().** shall invo
9c80: 6b 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  ke sqlite3_os_en
9c90: 64 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  d()..**.** The s
9ca0: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
9cb0: 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75  e() routine retu
9cc0: 72 6e 73 20 53 51 4c 49 54 45 5f 4f 4b 20 6f 6e  rns SQLITE_OK on
9cd0: 20 73 75 63 63 65 73 73 2e 0a 2a 2a 20 49 66 20   success..** If 
9ce0: 66 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2c  for some reason,
9cf0: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
9d00: 69 7a 65 28 29 20 69 73 20 75 6e 61 62 6c 65 20  ize() is unable 
9d10: 74 6f 20 69 6e 69 74 69 61 6c 69 7a 65 0a 2a 2a  to initialize.**
9d20: 20 74 68 65 20 6c 69 62 72 61 72 79 20 28 70 65   the library (pe
9d30: 72 68 61 70 73 20 69 74 20 69 73 20 75 6e 61 62  rhaps it is unab
9d40: 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 61  le to allocate a
9d50: 20 6e 65 65 64 65 64 20 72 65 73 6f 75 72 63 65   needed resource
9d60: 20 73 75 63 68 0a 2a 2a 20 61 73 20 61 20 6d 75   such.** as a mu
9d70: 74 65 78 29 20 69 74 20 72 65 74 75 72 6e 73 20  tex) it returns 
9d80: 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  an [error code] 
9d90: 6f 74 68 65 72 20 74 68 61 6e 20 53 51 4c 49 54  other than SQLIT
9da0: 45 5f 4f 4b 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  E_OK..**.** The 
9db0: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
9dc0: 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20  ze() routine is 
9dd0: 63 61 6c 6c 65 64 20 69 6e 74 65 72 6e 61 6c 6c  called internall
9de0: 79 20 62 79 20 6d 61 6e 79 20 6f 74 68 65 72 0a  y by many other.
9df0: 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  ** SQLite interf
9e00: 61 63 65 73 20 73 6f 20 74 68 61 74 20 61 6e 20  aces so that an 
9e10: 61 70 70 6c 69 63 61 74 69 6f 6e 20 75 73 75 61  application usua
9e20: 6c 6c 79 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65  lly does not nee
9e30: 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73  d to.** invoke s
9e40: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
9e50: 65 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20 46  e() directly.  F
9e60: 6f 72 20 65 78 61 6d 70 6c 65 2c 20 5b 73 71 6c  or example, [sql
9e70: 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20  ite3_open()].** 
9e80: 63 61 6c 6c 73 20 73 71 6c 69 74 65 33 5f 69 6e  calls sqlite3_in
9e90: 69 74 69 61 6c 69 7a 65 28 29 20 73 6f 20 74 68  itialize() so th
9ea0: 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79  e SQLite library
9eb0: 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74   will be automat
9ec0: 69 63 61 6c 6c 79 0a 2a 2a 20 69 6e 69 74 69 61  ically.** initia
9ed0: 6c 69 7a 65 64 20 77 68 65 6e 20 5b 73 71 6c 69  lized when [sqli
9ee0: 74 65 33 5f 6f 70 65 6e 28 29 5d 20 69 73 20 63  te3_open()] is c
9ef0: 61 6c 6c 65 64 20 69 66 20 69 74 20 68 61 73 20  alled if it has 
9f00: 6e 6f 74 20 62 65 20 69 6e 69 74 69 61 6c 69 7a  not be initializ
9f10: 65 64 0a 2a 2a 20 61 6c 72 65 61 64 79 2e 20 20  ed.** already.  
9f20: 48 6f 77 65 76 65 72 2c 20 69 66 20 53 51 4c 69  However, if SQLi
9f30: 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
9f40: 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 4f  ith the SQLITE_O
9f50: 4d 49 54 5f 41 55 54 4f 49 4e 49 54 0a 2a 2a 20  MIT_AUTOINIT.** 
9f60: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
9f70: 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 61 75  ion, then the au
9f80: 74 6f 6d 61 74 69 63 20 63 61 6c 6c 73 20 74 6f  tomatic calls to
9f90: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
9fa0: 69 7a 65 28 29 0a 2a 2a 20 61 72 65 20 6f 6d 69  ize().** are omi
9fb0: 74 74 65 64 20 61 6e 64 20 74 68 65 20 61 70 70  tted and the app
9fc0: 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 63 61  lication must ca
9fd0: 6c 6c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  ll sqlite3_initi
9fe0: 61 6c 69 7a 65 28 29 20 64 69 72 65 63 74 6c 79  alize() directly
9ff0: 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 75 73 69  .** prior to usi
a000: 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51 4c  ng any other SQL
a010: 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20  ite interface.  
a020: 46 6f 72 20 6d 61 78 69 6d 75 6d 20 70 6f 72 74  For maximum port
a030: 61 62 69 6c 69 74 79 2c 0a 2a 2a 20 69 74 20 69  ability,.** it i
a040: 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68  s recommended th
a050: 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  at applications 
a060: 61 6c 77 61 79 73 20 69 6e 76 6f 6b 65 20 73 71  always invoke sq
a070: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
a080: 28 29 0a 2a 2a 20 64 69 72 65 63 74 6c 79 20 70  ().** directly p
a090: 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61 6e  rior to using an
a0a0: 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69  y other SQLite i
a0b0: 6e 74 65 72 66 61 63 65 2e 20 20 46 75 74 75 72  nterface.  Futur
a0c0: 65 20 72 65 6c 65 61 73 65 73 0a 2a 2a 20 6f 66  e releases.** of
a0d0: 20 53 51 4c 69 74 65 20 6d 61 79 20 72 65 71 75   SQLite may requ
a0e0: 69 72 65 20 74 68 69 73 2e 20 20 49 6e 20 6f 74  ire this.  In ot
a0f0: 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 62  her words, the b
a100: 65 68 61 76 69 6f 72 20 65 78 68 69 62 69 74 65  ehavior exhibite
a110: 64 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74 65  d.** when SQLite
a120: 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
a130: 68 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55  h SQLITE_OMIT_AU
a140: 54 4f 49 4e 49 54 20 6d 69 67 68 74 20 62 65 63  TOINIT might bec
a150: 6f 6d 65 20 74 68 65 0a 2a 2a 20 64 65 66 61 75  ome the.** defau
a160: 6c 74 20 62 65 68 61 76 69 6f 72 20 69 6e 20 73  lt behavior in s
a170: 6f 6d 65 20 66 75 74 75 72 65 20 72 65 6c 65 61  ome future relea
a180: 73 65 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a  se of SQLite..**
a190: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
a1a0: 6f 73 5f 69 6e 69 74 28 29 20 72 6f 75 74 69 6e  os_init() routin
a1b0: 65 20 64 6f 65 73 20 6f 70 65 72 61 74 69 6e 67  e does operating
a1c0: 2d 73 79 73 74 65 6d 20 73 70 65 63 69 66 69 63  -system specific
a1d0: 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  .** initializati
a1e0: 6f 6e 20 6f 66 20 74 68 65 20 53 51 4c 69 74 65  on of the SQLite
a1f0: 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65 20 73   library.  The s
a200: 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a  qlite3_os_end().
a210: 2a 2a 20 72 6f 75 74 69 6e 65 20 75 6e 64 6f 65  ** routine undoe
a220: 73 20 74 68 65 20 65 66 66 65 63 74 20 6f 66 20  s the effect of 
a230: 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
a240: 29 2e 20 20 54 79 70 69 63 61 6c 20 74 61 73 6b  ).  Typical task
a250: 73 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 62  s.** performed b
a260: 79 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  y these routines
a270: 20 69 6e 63 6c 75 64 65 20 61 6c 6c 6f 63 61 74   include allocat
a280: 69 6f 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74  ion or deallocat
a290: 69 6f 6e 0a 2a 2a 20 6f 66 20 73 74 61 74 69 63  ion.** of static
a2a0: 20 72 65 73 6f 75 72 63 65 73 2c 20 69 6e 69 74   resources, init
a2b0: 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 67 6c  ialization of gl
a2c0: 6f 62 61 6c 20 76 61 72 69 61 62 6c 65 73 2c 0a  obal variables,.
a2d0: 2a 2a 20 73 65 74 74 69 6e 67 20 75 70 20 61 20  ** setting up a 
a2e0: 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33  default [sqlite3
a2f0: 5f 76 66 73 5d 20 6d 6f 64 75 6c 65 2c 20 6f 72  _vfs] module, or
a300: 20 73 65 74 74 69 6e 67 20 75 70 0a 2a 2a 20 61   setting up.** a
a310: 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75   default configu
a320: 72 61 74 69 6f 6e 20 75 73 69 6e 67 20 5b 73 71  ration using [sq
a330: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 2e  lite3_config()].
a340: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69  .**.** The appli
a350: 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65  cation should ne
a360: 76 65 72 20 69 6e 76 6f 6b 65 20 65 69 74 68 65  ver invoke eithe
a370: 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  r sqlite3_os_ini
a380: 74 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65  t().** or sqlite
a390: 33 5f 6f 73 5f 65 6e 64 28 29 20 64 69 72 65 63  3_os_end() direc
a3a0: 74 6c 79 2e 20 20 54 68 65 20 61 70 70 6c 69 63  tly.  The applic
a3b0: 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6f 6e 6c  ation should onl
a3c0: 79 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69  y invoke.** sqli
a3d0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
a3e0: 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 73 68 75   and sqlite3_shu
a3f0: 74 64 6f 77 6e 28 29 2e 20 20 54 68 65 20 73 71  tdown().  The sq
a400: 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a  lite3_os_init().
a410: 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  ** interface is 
a420: 63 61 6c 6c 65 64 20 61 75 74 6f 6d 61 74 69 63  called automatic
a430: 61 6c 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f  ally by sqlite3_
a440: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 61 6e 64  initialize() and
a450: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65  .** sqlite3_os_e
a460: 6e 64 28 29 20 69 73 20 63 61 6c 6c 65 64 20 62  nd() is called b
a470: 79 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  y sqlite3_shutdo
a480: 77 6e 28 29 2e 20 20 41 70 70 72 6f 70 72 69 61  wn().  Appropria
a490: 74 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  te.** implementa
a4a0: 74 69 6f 6e 73 20 66 6f 72 20 73 71 6c 69 74 65  tions for sqlite
a4b0: 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 20  3_os_init() and 
a4c0: 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29  sqlite3_os_end()
a4d0: 0a 2a 2a 20 61 72 65 20 62 75 69 6c 74 20 69 6e  .** are built in
a4e0: 74 6f 20 53 51 4c 69 74 65 20 77 68 65 6e 20 69  to SQLite when i
a4f0: 74 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 66 6f  t is compiled fo
a500: 72 20 75 6e 69 78 2c 20 77 69 6e 64 6f 77 73 2c  r unix, windows,
a510: 20 6f 72 20 6f 73 2f 32 2e 0a 2a 2a 20 57 68 65   or os/2..** Whe
a520: 6e 20 62 75 69 6c 74 20 66 6f 72 20 6f 74 68 65  n built for othe
a530: 72 20 70 6c 61 74 66 6f 72 6d 73 20 28 75 73 69  r platforms (usi
a540: 6e 67 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 53  ng the SQLITE_OS
a550: 5f 4f 54 48 45 52 3d 31 20 63 6f 6d 70 69 6c 65  _OTHER=1 compile
a560: 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 29  -time.** option)
a570: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
a580: 20 6d 75 73 74 20 73 75 70 70 6c 79 20 61 20 73   must supply a s
a590: 75 69 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e  uitable implemen
a5a0: 74 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20 73 71  tation for.** sq
a5b0: 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20  lite3_os_init() 
a5c0: 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65  and sqlite3_os_e
a5d0: 6e 64 28 29 2e 20 20 41 6e 20 61 70 70 6c 69 63  nd().  An applic
a5e0: 61 74 69 6f 6e 2d 73 75 70 70 6c 69 65 64 0a 2a  ation-supplied.*
a5f0: 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
a600: 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69   of sqlite3_os_i
a610: 6e 69 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33  nit() or sqlite3
a620: 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 6d 75 73  _os_end().** mus
a630: 74 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f  t return SQLITE_
a640: 4f 4b 20 6f 6e 20 73 75 63 63 65 73 73 20 61 6e  OK on success an
a650: 64 20 73 6f 6d 65 20 6f 74 68 65 72 20 5b 65 72  d some other [er
a660: 72 6f 72 20 63 6f 64 65 5d 20 75 70 6f 6e 0a 2a  ror code] upon.*
a670: 2a 20 66 61 69 6c 75 72 65 2e 0a 2a 2f 0a 69 6e  * failure..*/.in
a680: 74 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  t sqlite3_initia
a690: 6c 69 7a 65 28 76 6f 69 64 29 3b 0a 69 6e 74 20  lize(void);.int 
a6a0: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
a6b0: 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69  (void);.int sqli
a6c0: 74 65 33 5f 6f 73 5f 69 6e 69 74 28 76 6f 69 64  te3_os_init(void
a6d0: 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f  );.int sqlite3_o
a6e0: 73 5f 65 6e 64 28 76 6f 69 64 29 3b 0a 0a 2f 2a  s_end(void);../*
a6f0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
a700: 6e 66 69 67 75 72 69 6e 67 20 54 68 65 20 53 51  nfiguring The SQ
a710: 4c 69 74 65 20 4c 69 62 72 61 72 79 20 7b 48 31  Lite Library {H1
a720: 30 31 34 35 7d 20 3c 53 32 30 30 30 30 3e 3c 53  0145} <S20000><S
a730: 33 30 32 30 30 3e 0a 2a 2a 20 45 58 50 45 52 49  30200>.** EXPERI
a740: 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 65  MENTAL.**.** The
a750: 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
a760: 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 75  ) interface is u
a770: 73 65 64 20 74 6f 20 6d 61 6b 65 20 67 6c 6f 62  sed to make glob
a780: 61 6c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  al configuration
a790: 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 53  .** changes to S
a7a0: 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20 74  QLite in order t
a7b0: 6f 20 74 75 6e 65 20 53 51 4c 69 74 65 20 74 6f  o tune SQLite to
a7c0: 20 74 68 65 20 73 70 65 63 69 66 69 63 20 6e 65   the specific ne
a7d0: 65 64 73 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70  eds of.** the ap
a7e0: 70 6c 69 63 61 74 69 6f 6e 2e 20 20 54 68 65 20  plication.  The 
a7f0: 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72  default configur
a800: 61 74 69 6f 6e 20 69 73 20 72 65 63 6f 6d 6d 65  ation is recomme
a810: 6e 64 65 64 20 66 6f 72 20 6d 6f 73 74 0a 2a 2a  nded for most.**
a820: 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 61 6e   applications an
a830: 64 20 73 6f 20 74 68 69 73 20 72 6f 75 74 69 6e  d so this routin
a840: 65 20 69 73 20 75 73 75 61 6c 6c 79 20 6e 6f 74  e is usually not
a850: 20 6e 65 63 65 73 73 61 72 79 2e 20 20 49 74 20   necessary.  It 
a860: 69 73 0a 2a 2a 20 70 72 6f 76 69 64 65 64 20 74  is.** provided t
a870: 6f 20 73 75 70 70 6f 72 74 20 72 61 72 65 20 61  o support rare a
a880: 70 70 6c 69 63 61 74 69 6f 6e 73 20 77 69 74 68  pplications with
a890: 20 75 6e 75 73 75 61 6c 20 6e 65 65 64 73 2e 0a   unusual needs..
a8a0: 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
a8b0: 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72  3_config() inter
a8c0: 66 61 63 65 20 69 73 20 6e 6f 74 20 74 68 72 65  face is not thre
a8d0: 61 64 73 61 66 65 2e 20 20 54 68 65 20 61 70 70  adsafe.  The app
a8e0: 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74  lication.** must
a8f0: 20 69 6e 73 75 72 65 20 74 68 61 74 20 6e 6f 20   insure that no 
a900: 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74  other SQLite int
a910: 65 72 66 61 63 65 73 20 61 72 65 20 69 6e 76 6f  erfaces are invo
a920: 6b 65 64 20 62 79 20 6f 74 68 65 72 0a 2a 2a 20  ked by other.** 
a930: 74 68 72 65 61 64 73 20 77 68 69 6c 65 20 73 71  threads while sq
a940: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69  lite3_config() i
a950: 73 20 72 75 6e 6e 69 6e 67 2e 20 20 46 75 72 74  s running.  Furt
a960: 68 65 72 6d 6f 72 65 2c 20 73 71 6c 69 74 65 33  hermore, sqlite3
a970: 5f 63 6f 6e 66 69 67 28 29 0a 2a 2a 20 6d 61 79  _config().** may
a980: 20 6f 6e 6c 79 20 62 65 20 69 6e 76 6f 6b 65 64   only be invoked
a990: 20 70 72 69 6f 72 20 74 6f 20 6c 69 62 72 61 72   prior to librar
a9a0: 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e  y initialization
a9b0: 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74   using.** [sqlit
a9c0: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d  e3_initialize()]
a9d0: 20 6f 72 20 61 66 74 65 72 20 73 68 75 74 64 6f   or after shutdo
a9e0: 77 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73  wn by [sqlite3_s
a9f0: 68 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 20 4e  hutdown()]..** N
aa00: 6f 74 65 2c 20 68 6f 77 65 76 65 72 2c 20 74 68  ote, however, th
aa10: 61 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  at sqlite3_confi
aa20: 67 28 29 20 63 61 6e 20 62 65 20 63 61 6c 6c 65  g() can be calle
aa30: 64 20 61 73 20 70 61 72 74 20 6f 66 20 74 68 65  d as part of the
aa40: 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
aa50: 6f 6e 20 6f 66 20 61 6e 20 61 70 70 6c 69 63 61  on of an applica
aa60: 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 5b 73 71  tion-defined [sq
aa70: 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 5d  lite3_os_init()]
aa80: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73  ..**.** The firs
aa90: 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71  t argument to sq
aaa0: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69  lite3_config() i
aab0: 73 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20  s an integer.** 
aac0: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  [SQLITE_CONFIG_S
aad0: 49 4e 47 4c 45 54 48 52 45 41 44 20 7c 20 63 6f  INGLETHREAD | co
aae0: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
aaf0: 6f 6e 5d 20 74 68 61 74 20 64 65 74 65 72 6d 69  on] that determi
ab00: 6e 65 73 0a 2a 2a 20 77 68 61 74 20 70 72 6f 70  nes.** what prop
ab10: 65 72 74 79 20 6f 66 20 53 51 4c 69 74 65 20 69  erty of SQLite i
ab20: 73 20 74 6f 20 62 65 20 63 6f 6e 66 69 67 75 72  s to be configur
ab30: 65 64 2e 20 20 53 75 62 73 65 71 75 65 6e 74 20  ed.  Subsequent 
ab40: 61 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 76 61 72  arguments.** var
ab50: 79 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74  y depending on t
ab60: 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  he [SQLITE_CONFI
ab70: 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 20 7c  G_SINGLETHREAD |
ab80: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
ab90: 70 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65  ption].** in the
aba0: 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e   first argument.
abb0: 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 61 20 63 6f  .**.** When a co
abc0: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
abd0: 6f 6e 20 69 73 20 73 65 74 2c 20 73 71 6c 69 74  on is set, sqlit
abe0: 65 33 5f 63 6f 6e 66 69 67 28 29 20 72 65 74 75  e3_config() retu
abf0: 72 6e 73 20 53 51 4c 49 54 45 5f 4f 4b 2e 0a 2a  rns SQLITE_OK..*
ac00: 2a 20 49 66 20 74 68 65 20 6f 70 74 69 6f 6e 20  * If the option 
ac10: 69 73 20 75 6e 6b 6e 6f 77 6e 20 6f 72 20 53 51  is unknown or SQ
ac20: 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74  Lite is unable t
ac30: 6f 20 73 65 74 20 74 68 65 20 6f 70 74 69 6f 6e  o set the option
ac40: 0a 2a 2a 20 74 68 65 6e 20 74 68 69 73 20 72 6f  .** then this ro
ac50: 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20  utine returns a 
ac60: 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20  non-zero [error 
ac70: 63 6f 64 65 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45  code]..*/.SQLITE
ac80: 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 69 6e  _EXPERIMENTAL in
ac90: 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  t sqlite3_config
aca0: 28 69 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a  (int, ...);../*.
acb0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e  ** CAPI3REF: Con
acc0: 66 69 67 75 72 65 20 64 61 74 61 62 61 73 65 20  figure database 
acd0: 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 20 7b 48 31  connections  {H1
ace0: 30 31 38 30 7d 20 3c 53 32 30 30 30 30 3e 0a 2a  0180} <S20000>.*
acf0: 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a  * EXPERIMENTAL.*
ad00: 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
ad10: 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74  _db_config() int
ad20: 65 72 66 61 63 65 20 69 73 20 75 73 65 64 20 74  erface is used t
ad30: 6f 20 6d 61 6b 65 20 63 6f 6e 66 69 67 75 72 61  o make configura
ad40: 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20  tion.** changes 
ad50: 74 6f 20 61 20 5b 64 61 74 61 62 61 73 65 20 63  to a [database c
ad60: 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65  onnection].  The
ad70: 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 73 69   interface is si
ad80: 6d 69 6c 61 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c  milar to.** [sql
ad90: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 65  ite3_config()] e
ada0: 78 63 65 70 74 20 74 68 61 74 20 74 68 65 20 63  xcept that the c
adb0: 68 61 6e 67 65 73 20 61 70 70 6c 79 20 74 6f 20  hanges apply to 
adc0: 61 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b 64 61 74  a single.** [dat
add0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
ade0: 5d 20 28 73 70 65 63 69 66 69 65 64 20 69 6e 20  ] (specified in 
adf0: 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
ae00: 6e 74 29 2e 20 20 54 68 65 0a 2a 2a 20 73 71 6c  nt).  The.** sql
ae10: 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29  ite3_db_config()
ae20: 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 6f   interface can o
ae30: 6e 6c 79 20 62 65 20 75 73 65 64 20 69 6d 6d 65  nly be used imme
ae40: 64 69 61 74 65 6c 79 20 61 66 74 65 72 0a 2a 2a  diately after.**
ae50: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
ae60: 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 72 65 61  nnection is crea
ae70: 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ted using [sqlit
ae80: 65 33 5f 6f 70 65 6e 28 29 5d 2c 0a 2a 2a 20 5b  e3_open()],.** [
ae90: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
aea0: 5d 2c 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f  ], or [sqlite3_o
aeb0: 70 65 6e 5f 76 32 28 29 5d 2e 20 20 0a 2a 2a 0a  pen_v2()].  .**.
aec0: 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72  ** The second ar
aed0: 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65  gument to sqlite
aee0: 33 5f 64 62 5f 63 6f 6e 66 69 67 28 44 2c 56 2c  3_db_config(D,V,
aef0: 2e 2e 2e 29 20 20 69 73 20 74 68 65 0a 2a 2a 20  ...)  is the.** 
af00: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 76 65  configuration ve
af10: 72 62 20 2d 20 61 6e 20 69 6e 74 65 67 65 72 20  rb - an integer 
af20: 63 6f 64 65 20 74 68 61 74 20 69 6e 64 69 63 61  code that indica
af30: 74 65 73 20 77 68 61 74 0a 2a 2a 20 61 73 70 65  tes what.** aspe
af40: 63 74 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62  ct of the [datab
af50: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
af60: 69 73 20 62 65 69 6e 67 20 63 6f 6e 66 69 67 75  is being configu
af70: 72 65 64 2e 0a 2a 2a 20 54 68 65 20 6f 6e 6c 79  red..** The only
af80: 20 63 68 6f 69 63 65 20 66 6f 72 20 74 68 69 73   choice for this
af90: 20 76 61 6c 75 65 20 69 73 20 5b 53 51 4c 49 54   value is [SQLIT
afa0: 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  E_DBCONFIG_LOOKA
afb0: 53 49 44 45 5d 2e 0a 2a 2a 20 4e 65 77 20 76 65  SIDE]..** New ve
afc0: 72 62 73 20 61 72 65 20 6c 69 6b 65 6c 79 20 74  rbs are likely t
afd0: 6f 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75  o be added in fu
afe0: 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66  ture releases of
aff0: 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 41 64 64 69   SQLite..** Addi
b000: 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73  tional arguments
b010: 20 64 65 70 65 6e 64 20 6f 6e 20 74 68 65 20 76   depend on the v
b020: 65 72 62 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45  erb..*/.SQLITE_E
b030: 58 50 45 52 49 4d 45 4e 54 41 4c 20 69 6e 74 20  XPERIMENTAL int 
b040: 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
b050: 67 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20  g(sqlite3*, int 
b060: 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a  op, ...);../*.**
b070: 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72   CAPI3REF: Memor
b080: 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 52 6f 75  y Allocation Rou
b090: 74 69 6e 65 73 20 7b 48 31 30 31 35 35 7d 20 3c  tines {H10155} <
b0a0: 53 32 30 31 32 30 3e 0a 2a 2a 20 45 58 50 45 52  S20120>.** EXPER
b0b0: 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 41 6e  IMENTAL.**.** An
b0c0: 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69   instance of thi
b0d0: 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73  s object defines
b0e0: 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 62   the interface b
b0f0: 65 74 77 65 65 6e 20 53 51 4c 69 74 65 0a 2a 2a  etween SQLite.**
b100: 20 61 6e 64 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d   and low-level m
b110: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
b120: 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a   routines..**.**
b130: 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20   This object is 
b140: 75 73 65 64 20 69 6e 20 6f 6e 6c 79 20 6f 6e 65  used in only one
b150: 20 70 6c 61 63 65 20 69 6e 20 74 68 65 20 53 51   place in the SQ
b160: 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 0a  Lite interface..
b170: 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20  ** A pointer to 
b180: 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  an instance of t
b190: 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 74 68  his object is th
b1a0: 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a  e argument to.**
b1b0: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
b1c0: 28 29 5d 20 77 68 65 6e 20 74 68 65 20 63 6f 6e  ()] when the con
b1d0: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
b1e0: 6e 20 69 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  n is.** [SQLITE_
b1f0: 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 2e 20  CONFIG_MALLOC]. 
b200: 20 42 79 20 63 72 65 61 74 69 6e 67 20 61 6e 20   By creating an 
b210: 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73  instance of this
b220: 20 6f 62 6a 65 63 74 0a 2a 2a 20 61 6e 64 20 70   object.** and p
b230: 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71  assing it to [sq
b240: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
b250: 64 75 72 69 6e 67 20 63 6f 6e 66 69 67 75 72 61  during configura
b260: 74 69 6f 6e 2c 20 61 6e 0a 2a 2a 20 61 70 70 6c  tion, an.** appl
b270: 69 63 61 74 69 6f 6e 20 63 61 6e 20 73 70 65 63  ication can spec
b280: 69 66 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 69  ify an alternati
b290: 76 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ve memory alloca
b2a0: 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 0a 2a  tion subsystem.*
b2b0: 2a 20 66 6f 72 20 53 51 4c 69 74 65 20 74 6f 20  * for SQLite to 
b2c0: 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69  use for all of i
b2d0: 74 73 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72  ts dynamic memor
b2e0: 79 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 4e  y needs..**.** N
b2f0: 6f 74 65 20 74 68 61 74 20 53 51 4c 69 74 65 20  ote that SQLite 
b300: 63 6f 6d 65 73 20 77 69 74 68 20 61 20 62 75 69  comes with a bui
b310: 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c  lt-in memory all
b320: 6f 63 61 74 6f 72 20 74 68 61 74 20 69 73 0a 2a  ocator that is.*
b330: 2a 20 70 65 72 66 65 63 74 6c 79 20 61 64 65 71  * perfectly adeq
b340: 75 61 74 65 20 66 6f 72 20 74 68 65 20 6f 76 65  uate for the ove
b350: 72 77 68 65 6c 6d 69 6e 67 20 6d 61 6a 6f 72 69  rwhelming majori
b360: 74 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f  ty of applicatio
b370: 6e 73 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20 74  ns.** and that t
b380: 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 6f 6e  his object is on
b390: 6c 79 20 75 73 65 66 75 6c 20 74 6f 20 61 20 74  ly useful to a t
b3a0: 69 6e 79 20 6d 69 6e 6f 72 69 74 79 20 6f 66 20  iny minority of 
b3b0: 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20  applications.** 
b3c0: 77 69 74 68 20 73 70 65 63 69 61 6c 69 7a 65 64  with specialized
b3d0: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
b3e0: 6f 6e 20 72 65 71 75 69 72 65 6d 65 6e 74 73 2e  on requirements.
b3f0: 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73    This object is
b400: 0a 2a 2a 20 61 6c 73 6f 20 75 73 65 64 20 64 75  .** also used du
b410: 72 69 6e 67 20 74 65 73 74 69 6e 67 20 6f 66 20  ring testing of 
b420: 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20  SQLite in order 
b430: 74 6f 20 73 70 65 63 69 66 79 20 61 6e 20 61 6c  to specify an al
b440: 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d  ternative.** mem
b450: 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 74 68  ory allocator th
b460: 61 74 20 73 69 6d 75 6c 61 74 65 73 20 6d 65 6d  at simulates mem
b470: 6f 72 79 20 6f 75 74 2d 6f 66 2d 6d 65 6d 6f 72  ory out-of-memor
b480: 79 20 63 6f 6e 64 69 74 69 6f 6e 73 20 69 6e 0a  y conditions in.
b490: 2a 2a 20 6f 72 64 65 72 20 74 6f 20 76 65 72 69  ** order to veri
b4a0: 66 79 20 74 68 61 74 20 53 51 4c 69 74 65 20 72  fy that SQLite r
b4b0: 65 63 6f 76 65 72 73 20 67 72 61 63 65 66 75 6c  ecovers graceful
b4c0: 6c 79 20 66 72 6f 6d 20 73 75 63 68 0a 2a 2a 20  ly from such.** 
b4d0: 63 6f 6e 64 69 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a  conditions..**.*
b4e0: 2a 20 54 68 65 20 78 4d 61 6c 6c 6f 63 2c 20 78  * The xMalloc, x
b4f0: 46 72 65 65 2c 20 61 6e 64 20 78 52 65 61 6c 6c  Free, and xReall
b500: 6f 63 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 20  oc methods must 
b510: 77 6f 72 6b 20 6c 69 6b 65 20 74 68 65 0a 2a 2a  work like the.**
b520: 20 6d 61 6c 6c 6f 63 28 29 2c 20 66 72 65 65 28   malloc(), free(
b530: 29 2c 20 61 6e 64 20 72 65 61 6c 6c 6f 63 28 29  ), and realloc()
b540: 20 66 75 6e 63 74 69 6f 6e 73 20 66 72 6f 6d 20   functions from 
b550: 74 68 65 20 73 74 61 6e 64 61 72 64 20 6c 69 62  the standard lib
b560: 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 78 53 69 7a  rary..**.** xSiz
b570: 65 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20  e should return 
b580: 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69  the allocated si
b590: 7a 65 20 6f 66 20 61 20 6d 65 6d 6f 72 79 20 61  ze of a memory a
b5a0: 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 70 72 65  llocation.** pre
b5b0: 76 69 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65 64  viously obtained
b5c0: 20 66 72 6f 6d 20 78 4d 61 6c 6c 6f 63 20 6f 72   from xMalloc or
b5d0: 20 78 52 65 61 6c 6c 6f 63 2e 20 20 54 68 65 20   xRealloc.  The 
b5e0: 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 0a 2a  allocated size.*
b5f0: 2a 20 69 73 20 61 6c 77 61 79 73 20 61 74 20 6c  * is always at l
b600: 65 61 73 74 20 61 73 20 62 69 67 20 61 73 20 74  east as big as t
b610: 68 65 20 72 65 71 75 65 73 74 65 64 20 73 69 7a  he requested siz
b620: 65 20 62 75 74 20 6d 61 79 20 62 65 20 6c 61 72  e but may be lar
b630: 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  ger..**.** The x
b640: 52 6f 75 6e 64 75 70 20 6d 65 74 68 6f 64 20 72  Roundup method r
b650: 65 74 75 72 6e 73 20 77 68 61 74 20 77 6f 75 6c  eturns what woul
b660: 64 20 62 65 20 74 68 65 20 61 6c 6c 6f 63 61 74  d be the allocat
b670: 65 64 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 61 20  ed size of.** a 
b680: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
b690: 6e 20 67 69 76 65 6e 20 61 20 70 61 72 74 69 63  n given a partic
b6a0: 75 6c 61 72 20 72 65 71 75 65 73 74 65 64 20 73  ular requested s
b6b0: 69 7a 65 2e 20 20 4d 6f 73 74 20 6d 65 6d 6f 72  ize.  Most memor
b6c0: 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 73 20  y.** allocators 
b6d0: 72 6f 75 6e 64 20 75 70 20 6d 65 6d 6f 72 79 20  round up memory 
b6e0: 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 61 74 20 6c  allocations at l
b6f0: 65 61 73 74 20 74 6f 20 74 68 65 20 6e 65 78 74  east to the next
b700: 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 6f 66 20   multiple.** of 
b710: 38 2e 20 20 53 6f 6d 65 20 61 6c 6c 6f 63 61 74  8.  Some allocat
b720: 6f 72 73 20 72 6f 75 6e 64 20 75 70 20 74 6f 20  ors round up to 
b730: 61 20 6c 61 72 67 65 72 20 6d 75 6c 74 69 70 6c  a larger multipl
b740: 65 20 6f 72 20 74 6f 20 61 20 70 6f 77 65 72 20  e or to a power 
b750: 6f 66 20 32 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  of 2..**.** The 
b760: 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 69 6e 69  xInit method ini
b770: 74 69 61 6c 69 7a 65 73 20 74 68 65 20 6d 65 6d  tializes the mem
b780: 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 2e 20 20  ory allocator.  
b790: 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a  (For example,.**
b7a0: 20 69 74 20 6d 69 67 68 74 20 61 6c 6c 6f 63 61   it might alloca
b7b0: 74 65 20 61 6e 79 20 72 65 71 75 69 72 65 20 6d  te any require m
b7c0: 75 74 65 78 65 73 20 6f 72 20 69 6e 69 74 69 61  utexes or initia
b7d0: 6c 69 7a 65 20 69 6e 74 65 72 6e 61 6c 20 64 61  lize internal da
b7e0: 74 61 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 73  ta.** structures
b7f0: 2e 20 20 54 68 65 20 78 53 68 75 74 64 6f 77 6e  .  The xShutdown
b800: 20 6d 65 74 68 6f 64 20 69 73 20 69 6e 76 6f 6b   method is invok
b810: 65 64 20 28 69 6e 64 69 72 65 63 74 6c 79 29 20  ed (indirectly) 
b820: 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  by.** [sqlite3_s
b830: 68 75 74 64 6f 77 6e 28 29 5d 20 61 6e 64 20 73  hutdown()] and s
b840: 68 6f 75 6c 64 20 64 65 61 6c 6c 6f 63 61 74 65  hould deallocate
b850: 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73 20 61   any resources a
b860: 63 71 75 69 72 65 64 0a 2a 2a 20 62 79 20 78 49  cquired.** by xI
b870: 6e 69 74 2e 20 20 54 68 65 20 70 41 70 70 44 61  nit.  The pAppDa
b880: 74 61 20 70 6f 69 6e 74 65 72 20 69 73 20 75 73  ta pointer is us
b890: 65 64 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 70  ed as the only p
b8a0: 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 78  arameter to.** x
b8b0: 49 6e 69 74 20 61 6e 64 20 78 53 68 75 74 64 6f  Init and xShutdo
b8c0: 77 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  wn..*/.typedef s
b8d0: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 65  truct sqlite3_me
b8e0: 6d 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65  m_methods sqlite
b8f0: 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 3b 0a 73  3_mem_methods;.s
b900: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 65  truct sqlite3_me
b910: 6d 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 76 6f  m_methods {.  vo
b920: 69 64 20 2a 28 2a 78 4d 61 6c 6c 6f 63 29 28 69  id *(*xMalloc)(i
b930: 6e 74 29 3b 20 20 20 20 20 20 20 20 20 2f 2a 20  nt);         /* 
b940: 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  Memory allocatio
b950: 6e 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20  n function */.  
b960: 76 6f 69 64 20 28 2a 78 46 72 65 65 29 28 76 6f  void (*xFree)(vo
b970: 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 2f  id*);          /
b980: 2a 20 46 72 65 65 20 61 20 70 72 69 6f 72 20 61  * Free a prior a
b990: 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 76  llocation */.  v
b9a0: 6f 69 64 20 2a 28 2a 78 52 65 61 6c 6c 6f 63 29  oid *(*xRealloc)
b9b0: 28 76 6f 69 64 2a 2c 69 6e 74 29 3b 20 20 2f 2a  (void*,int);  /*
b9c0: 20 52 65 73 69 7a 65 20 61 6e 20 61 6c 6c 6f 63   Resize an alloc
b9d0: 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28  ation */.  int (
b9e0: 2a 78 53 69 7a 65 29 28 76 6f 69 64 2a 29 3b 20  *xSize)(void*); 
b9f0: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 52 65 74            /* Ret
ba00: 75 72 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20  urn the size of 
ba10: 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f  an allocation */
ba20: 0a 20 20 69 6e 74 20 28 2a 78 52 6f 75 6e 64 75  .  int (*xRoundu
ba30: 70 29 28 69 6e 74 29 3b 20 20 20 20 20 20 20 20  p)(int);        
ba40: 20 20 2f 2a 20 52 6f 75 6e 64 20 75 70 20 72 65    /* Round up re
ba50: 71 75 65 73 74 20 73 69 7a 65 20 74 6f 20 61 6c  quest size to al
ba60: 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 2a 2f  location size */
ba70: 0a 20 20 69 6e 74 20 28 2a 78 49 6e 69 74 29 28  .  int (*xInit)(
ba80: 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20  void*);         
ba90: 20 20 2f 2a 20 49 6e 69 74 69 61 6c 69 7a 65 20    /* Initialize 
baa0: 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  the memory alloc
bab0: 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 28  ator */.  void (
bac0: 2a 78 53 68 75 74 64 6f 77 6e 29 28 76 6f 69 64  *xShutdown)(void
bad0: 2a 29 3b 20 20 20 20 20 20 2f 2a 20 44 65 69 6e  *);      /* Dein
bae0: 69 74 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d  itialize the mem
baf0: 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f  ory allocator */
bb00: 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 44 61 74  .  void *pAppDat
bb10: 61 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  a;              
bb20: 20 20 2f 2a 20 41 72 67 75 6d 65 6e 74 20 74 6f    /* Argument to
bb30: 20 78 49 6e 69 74 28 29 20 61 6e 64 20 78 53 68   xInit() and xSh
bb40: 75 74 64 6f 77 6e 28 29 20 2a 2f 0a 7d 3b 0a 0a  utdown() */.};..
bb50: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
bb60: 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f 70  Configuration Op
bb70: 74 69 6f 6e 73 20 7b 48 31 30 31 36 30 7d 20 3c  tions {H10160} <
bb80: 53 32 30 30 30 30 3e 0a 2a 2a 20 45 58 50 45 52  S20000>.** EXPER
bb90: 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68  IMENTAL.**.** Th
bba0: 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72  ese constants ar
bbb0: 65 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20  e the available 
bbc0: 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 67 75 72  integer configur
bbd0: 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68  ation options th
bbe0: 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 73  at.** can be pas
bbf0: 73 65 64 20 61 73 20 74 68 65 20 66 69 72 73 74  sed as the first
bc00: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
bc10: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
bc20: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  ()] interface..*
bc30: 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75  *.** New configu
bc40: 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d  ration options m
bc50: 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66  ay be added in f
bc60: 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f  uture releases o
bc70: 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69  f SQLite..** Exi
bc80: 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74  sting configurat
bc90: 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68  ion options migh
bca0: 74 20 62 65 20 64 69 73 63 6f 6e 74 69 6e 75 65  t be discontinue
bcb0: 64 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  d.  Applications
bcc0: 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65 63 6b  .** should check
bcd0: 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65   the return code
bce0: 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63   from [sqlite3_c
bcf0: 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65  onfig()] to make
bd00: 20 73 75 72 65 20 74 68 61 74 0a 2a 2a 20 74 68   sure that.** th
bd10: 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20  e call worked.  
bd20: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  The [sqlite3_con
bd30: 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65  fig()] interface
bd40: 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a   will return a.*
bd50: 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f  * non-zero [erro
bd60: 72 20 63 6f 64 65 5d 20 69 66 20 61 20 64 69 73  r code] if a dis
bd70: 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e 73  continued or uns
bd80: 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67 75  upported configu
bd90: 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a  ration option.**
bda0: 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a   is invoked..**.
bdb0: 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53  ** <dl>.** <dt>S
bdc0: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e  QLITE_CONFIG_SIN
bdd0: 47 4c 45 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a  GLETHREAD</dt>.*
bde0: 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20  * <dd>There are 
bdf0: 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20  no arguments to 
be00: 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 54 68  this option.  Th
be10: 69 73 20 6f 70 74 69 6f 6e 20 64 69 73 61 62 6c  is option disabl
be20: 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 69  es.** all mutexi
be30: 6e 67 20 61 6e 64 20 70 75 74 73 20 53 51 4c 69  ng and puts SQLi
be40: 74 65 20 69 6e 74 6f 20 61 20 6d 6f 64 65 20 77  te into a mode w
be50: 68 65 72 65 20 69 74 20 63 61 6e 20 6f 6e 6c 79  here it can only
be60: 20 62 65 20 75 73 65 64 0a 2a 2a 20 62 79 20 61   be used.** by a
be70: 20 73 69 6e 67 6c 65 20 74 68 72 65 61 64 2e 3c   single thread.<
be80: 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
be90: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c  QLITE_CONFIG_MUL
bea0: 54 49 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a  TITHREAD</dt>.**
beb0: 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e   <dd>There are n
bec0: 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74  o arguments to t
bed0: 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 54 68 69  his option.  Thi
bee0: 73 20 6f 70 74 69 6f 6e 20 64 69 73 61 62 6c 65  s option disable
bef0: 73 0a 2a 2a 20 6d 75 74 65 78 69 6e 67 20 6f 6e  s.** mutexing on
bf00: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
bf10: 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70  ction] and [prep
bf20: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
bf30: 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 54 68 65 20  objects..** The 
bf40: 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 20 72  application is r
bf50: 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 73  esponsible for s
bf60: 65 72 69 61 6c 69 7a 69 6e 67 20 61 63 63 65 73  erializing acces
bf70: 73 20 74 6f 0a 2a 2a 20 5b 64 61 74 61 62 61 73  s to.** [databas
bf80: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61  e connections] a
bf90: 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  nd [prepared sta
bfa0: 74 65 6d 65 6e 74 73 5d 2e 20 20 42 75 74 20 6f  tements].  But o
bfb0: 74 68 65 72 20 6d 75 74 65 78 65 73 0a 2a 2a 20  ther mutexes.** 
bfc0: 61 72 65 20 65 6e 61 62 6c 65 64 20 73 6f 20 74  are enabled so t
bfd0: 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  hat SQLite will 
bfe0: 62 65 20 73 61 66 65 20 74 6f 20 75 73 65 20 69  be safe to use i
bff0: 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 64  n a multi-thread
c000: 65 64 0a 2a 2a 20 65 6e 76 69 72 6f 6e 6d 65 6e  ed.** environmen
c010: 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  t.</dd>.**.** <d
c020: 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
c030: 53 45 52 49 41 4c 49 5a 45 44 3c 2f 64 74 3e 0a  SERIALIZED</dt>.
c040: 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65  ** <dd>There are
c050: 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f   no arguments to
c060: 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 54   this option.  T
c070: 68 69 73 20 6f 70 74 69 6f 6e 20 65 6e 61 62 6c  his option enabl
c080: 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 65  es.** all mutexe
c090: 73 20 69 6e 63 6c 75 64 69 6e 67 20 74 68 65 20  s including the 
c0a0: 72 65 63 75 72 73 69 76 65 0a 2a 2a 20 6d 75 74  recursive.** mut
c0b0: 65 78 65 73 20 6f 6e 20 5b 64 61 74 61 62 61 73  exes on [databas
c0c0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e  e connection] an
c0d0: 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  d [prepared stat
c0e0: 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a  ement] objects..
c0f0: 2a 2a 20 49 6e 20 74 68 69 73 20 6d 6f 64 65 20  ** In this mode 
c100: 28 77 68 69 63 68 20 69 73 20 74 68 65 20 64 65  (which is the de
c110: 66 61 75 6c 74 20 77 68 65 6e 20 53 51 4c 69 74  fault when SQLit
c120: 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
c130: 74 68 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48  th.** [SQLITE_TH
c140: 52 45 41 44 53 41 46 45 3d 31 5d 29 20 74 68 65  READSAFE=1]) the
c150: 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20   SQLite library 
c160: 77 69 6c 6c 20 69 74 73 65 6c 66 20 73 65 72 69  will itself seri
c170: 61 6c 69 7a 65 20 61 63 63 65 73 73 0a 2a 2a 20  alize access.** 
c180: 74 6f 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  to [database con
c190: 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70  nections] and [p
c1a0: 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
c1b0: 74 73 5d 20 73 6f 20 74 68 61 74 20 74 68 65 0a  ts] so that the.
c1c0: 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69  ** application i
c1d0: 73 20 66 72 65 65 20 74 6f 20 75 73 65 20 74 68  s free to use th
c1e0: 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65  e same [database
c1f0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 72 20   connection] or 
c200: 74 68 65 0a 2a 2a 20 73 61 6d 65 20 5b 70 72 65  the.** same [pre
c210: 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
c220: 20 69 6e 20 64 69 66 66 65 72 65 6e 74 20 74 68   in different th
c230: 72 65 61 64 73 20 61 74 20 74 68 65 20 73 61 6d  reads at the sam
c240: 65 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 3c 70  e time..**.** <p
c250: 3e 54 68 69 73 20 63 6f 6e 66 69 67 75 72 61 74  >This configurat
c260: 69 6f 6e 20 6f 70 74 69 6f 6e 20 6d 65 72 65 6c  ion option merel
c270: 79 20 73 65 74 73 20 74 68 65 20 64 65 66 61 75  y sets the defau
c280: 6c 74 20 6d 75 74 65 78 20 0a 2a 2a 20 62 65 68  lt mutex .** beh
c290: 61 76 69 6f 72 20 74 6f 20 73 65 72 69 61 6c 69  avior to seriali
c2a0: 7a 65 20 61 63 63 65 73 73 20 74 6f 20 5b 64 61  ze access to [da
c2b0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
c2c0: 6e 73 5d 2e 20 20 49 6e 64 69 76 69 64 75 61 6c  ns].  Individual
c2d0: 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
c2e0: 6e 6e 65 63 74 69 6f 6e 73 5d 20 63 61 6e 20 6f  nnections] can o
c2f0: 76 65 72 72 69 64 65 20 74 68 69 73 20 73 65 74  verride this set
c300: 74 69 6e 67 0a 2a 2a 20 75 73 69 6e 67 20 74 68  ting.** using th
c310: 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e  e [SQLITE_OPEN_N
c320: 4f 4d 55 54 45 58 5d 20 66 6c 61 67 20 74 6f 20  OMUTEX] flag to 
c330: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
c340: 28 29 5d 2e 3c 2f 70 3e 3c 2f 64 64 3e 0a 2a 2a  ()].</p></dd>.**
c350: 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  .** <dt>SQLITE_C
c360: 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 3c 2f 64 74  ONFIG_MALLOC</dt
c370: 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70  >.** <dd>This op
c380: 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e  tion takes a sin
c390: 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69  gle argument whi
c3a0: 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  ch is a pointer 
c3b0: 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63  to an.** instanc
c3c0: 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  e of the [sqlite
c3d0: 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73  3_mem_methods] s
c3e0: 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 20 61  tructure.  The a
c3f0: 72 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65  rgument specifie
c400: 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76 65  s.** alternative
c410: 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72   low-level memor
c420: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75  y allocation rou
c430: 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65 64  tines to be used
c440: 20 69 6e 20 70 6c 61 63 65 20 6f 66 0a 2a 2a 20   in place of.** 
c450: 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  the memory alloc
c460: 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 62  ation routines b
c470: 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65  uilt into SQLite
c480: 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74  .</dd>.**.** <dt
c490: 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47  >SQLITE_CONFIG_G
c4a0: 45 54 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a  ETMALLOC</dt>.**
c4b0: 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e   <dd>This option
c4c0: 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
c4d0: 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69  argument which i
c4e0: 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
c4f0: 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66  n.** instance of
c500: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65   the [sqlite3_me
c510: 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63  m_methods] struc
c520: 74 75 72 65 2e 20 20 54 68 65 20 5b 73 71 6c 69  ture.  The [sqli
c530: 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d  te3_mem_methods]
c540: 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 69 73  .** structure is
c550: 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65   filled with the
c560: 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e   currently defin
c570: 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ed memory alloca
c580: 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 0a 2a  tion routines..*
c590: 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61  * This option ca
c5a0: 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65  n be used to ove
c5b0: 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c  rload the defaul
c5c0: 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  t memory allocat
c5d0: 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20  ion.** routines 
c5e0: 77 69 74 68 20 61 20 77 72 61 70 70 65 72 20 74  with a wrapper t
c5f0: 68 61 74 20 73 69 6d 75 6c 61 74 69 6f 6e 73 20  hat simulations 
c600: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
c610: 6e 20 66 61 69 6c 75 72 65 20 6f 72 0a 2a 2a 20  n failure or.** 
c620: 74 72 61 63 6b 73 20 6d 65 6d 6f 72 79 20 75 73  tracks memory us
c630: 61 67 65 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65  age, for example
c640: 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74  .</dd>.**.** <dt
c650: 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  >SQLITE_CONFIG_M
c660: 45 4d 53 54 41 54 55 53 3c 2f 64 74 3e 0a 2a 2a  EMSTATUS</dt>.**
c670: 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e   <dd>This option
c680: 20 74 61 6b 65 73 20 73 69 6e 67 6c 65 20 61 72   takes single ar
c690: 67 75 6d 65 6e 74 20 6f 66 20 74 79 70 65 20 69  gument of type i
c6a0: 6e 74 2c 20 69 6e 74 65 72 70 72 65 74 65 64 20  nt, interpreted 
c6b0: 61 73 20 61 20 0a 2a 2a 20 62 6f 6f 6c 65 61 6e  as a .** boolean
c6c0: 2c 20 77 68 69 63 68 20 65 6e 61 62 6c 65 73 20  , which enables 
c6d0: 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68 65 20  or disables the 
c6e0: 63 6f 6c 6c 65 63 74 69 6f 6e 20 6f 66 20 6d 65  collection of me
c6f0: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
c700: 0a 2a 2a 20 73 74 61 74 69 73 74 69 63 73 2e 20  .** statistics. 
c710: 57 68 65 6e 20 64 69 73 61 62 6c 65 64 2c 20 74  When disabled, t
c720: 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c  he following SQL
c730: 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 62  ite interfaces b
c740: 65 63 6f 6d 65 20 0a 2a 2a 20 6e 6f 6e 2d 6f 70  ecome .** non-op
c750: 65 72 61 74 69 6f 6e 61 6c 3a 0a 2a 2a 20 20 20  erational:.**   
c760: 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b  <ul>.**   <li> [
c770: 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75  sqlite3_memory_u
c780: 73 65 64 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e  sed()].**   <li>
c790: 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
c7a0: 5f 68 69 67 68 77 61 74 65 72 28 29 5d 0a 2a 2a  _highwater()].**
c7b0: 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33     <li> [sqlite3
c7c0: 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74  _soft_heap_limit
c7d0: 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73  ()].**   <li> [s
c7e0: 71 6c 69 74 65 33 5f 73 74 61 74 75 73 28 29 5d  qlite3_status()]
c7f0: 0a 2a 2a 20 20 20 3c 2f 75 6c 3e 0a 2a 2a 20 3c  .**   </ul>.** <
c800: 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
c810: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52  QLITE_CONFIG_SCR
c820: 41 54 43 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  ATCH</dt>.** <dd
c830: 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 65  >This option spe
c840: 63 69 66 69 65 73 20 61 20 73 74 61 74 69 63 20  cifies a static 
c850: 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 68  memory buffer th
c860: 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20 75 73  at SQLite can us
c870: 65 20 66 6f 72 0a 2a 2a 20 73 63 72 61 74 63 68  e for.** scratch
c880: 20 6d 65 6d 6f 72 79 2e 20 20 54 68 65 72 65 20   memory.  There 
c890: 61 72 65 20 74 68 72 65 65 20 61 72 67 75 6d 65  are three argume
c8a0: 6e 74 73 3a 20 20 41 20 70 6f 69 6e 74 65 72 20  nts:  A pointer 
c8b0: 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79 2c 20 74  to the memory, t
c8c0: 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61  he.** size of ea
c8d0: 63 68 20 73 63 72 61 74 63 68 20 62 75 66 66 65  ch scratch buffe
c8e0: 72 20 28 73 7a 29 2c 20 61 6e 64 20 74 68 65 20  r (sz), and the 
c8f0: 6e 75 6d 62 65 72 20 6f 66 20 62 75 66 66 65 72  number of buffer
c900: 73 20 28 4e 29 2e 20 20 54 68 65 20 73 7a 0a 2a  s (N).  The sz.*
c910: 2a 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20  * argument must 
c920: 62 65 20 61 20 6d 75 6c 74 69 70 6c 65 20 6f 66  be a multiple of
c930: 20 31 36 2e 20 54 68 65 20 73 7a 20 70 61 72 61   16. The sz para
c940: 6d 65 74 65 72 20 73 68 6f 75 6c 64 20 62 65 20  meter should be 
c950: 61 20 66 65 77 20 62 79 74 65 73 0a 2a 2a 20 6c  a few bytes.** l
c960: 61 72 67 65 72 20 74 68 61 6e 20 74 68 65 20 61  arger than the a
c970: 63 74 75 61 6c 20 73 63 72 61 74 63 68 20 73 70  ctual scratch sp
c980: 61 63 65 20 72 65 71 75 69 72 65 64 20 64 75 65  ace required due
c990: 20 69 6e 74 65 72 6e 61 6c 20 6f 76 65 72 68 65   internal overhe
c9a0: 61 64 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  ad..** The first
c9b0: 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f  .** argument sho
c9c0: 75 6c 64 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20  uld point to an 
c9d0: 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 66 20 61 74  allocation of at
c9e0: 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79 74 65   least sz*N byte
c9f0: 73 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20  s of memory..** 
ca00: 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20  SQLite will use 
ca10: 6e 6f 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65  no more than one
ca20: 20 73 63 72 61 74 63 68 20 62 75 66 66 65 72 20   scratch buffer 
ca30: 61 74 20 6f 6e 63 65 20 70 65 72 20 74 68 72 65  at once per thre
ca40: 61 64 2c 20 73 6f 0a 2a 2a 20 4e 20 73 68 6f 75  ad, so.** N shou
ca50: 6c 64 20 62 65 20 73 65 74 20 74 6f 20 74 68 65  ld be set to the
ca60: 20 65 78 70 65 63 74 65 64 20 6d 61 78 69 6d 75   expected maximu
ca70: 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74 68 72 65  m number of thre
ca80: 61 64 73 2e 20 20 54 68 65 20 73 7a 0a 2a 2a 20  ads.  The sz.** 
ca90: 70 61 72 61 6d 65 74 65 72 20 73 68 6f 75 6c 64  parameter should
caa0: 20 62 65 20 36 20 74 69 6d 65 73 20 74 68 65 20   be 6 times the 
cab0: 73 69 7a 65 20 6f 66 20 74 68 65 20 6c 61 72 67  size of the larg
cac0: 65 73 74 20 64 61 74 61 62 61 73 65 20 70 61 67  est database pag
cad0: 65 20 73 69 7a 65 2e 0a 2a 2a 20 53 63 72 61 74  e size..** Scrat
cae0: 63 68 20 62 75 66 66 65 72 73 20 61 72 65 20 75  ch buffers are u
caf0: 73 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 74  sed as part of t
cb00: 68 65 20 62 74 72 65 65 20 62 61 6c 61 6e 63 65  he btree balance
cb10: 20 6f 70 65 72 61 74 69 6f 6e 2e 20 20 49 66 0a   operation.  If.
cb20: 2a 2a 20 54 68 65 20 62 74 72 65 65 20 62 61 6c  ** The btree bal
cb30: 61 6e 63 65 72 20 6e 65 65 64 73 20 61 64 64 69  ancer needs addi
cb40: 74 69 6f 6e 61 6c 20 6d 65 6d 6f 72 79 20 62 65  tional memory be
cb50: 79 6f 6e 64 20 77 68 61 74 20 69 73 20 70 72 6f  yond what is pro
cb60: 76 69 64 65 64 20 62 79 0a 2a 2a 20 73 63 72 61  vided by.** scra
cb70: 74 63 68 20 62 75 66 66 65 72 73 20 6f 72 20 69  tch buffers or i
cb80: 66 20 6e 6f 20 73 63 72 61 74 63 68 20 62 75 66  f no scratch buf
cb90: 66 65 72 20 73 70 61 63 65 20 69 73 20 73 70 65  fer space is spe
cba0: 63 69 66 69 65 64 2c 20 74 68 65 6e 20 53 51 4c  cified, then SQL
cbb0: 69 74 65 0a 2a 2a 20 67 6f 65 73 20 74 6f 20 5b  ite.** goes to [
cbc0: 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
cbd0: 5d 20 74 6f 20 6f 62 74 61 69 6e 20 74 68 65 20  ] to obtain the 
cbe0: 6d 65 6d 6f 72 79 20 69 74 20 6e 65 65 64 73 2e  memory it needs.
cbf0: 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
cc00: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41  SQLITE_CONFIG_PA
cc10: 47 45 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20  GECACHE</dt>.** 
cc20: 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20  <dd>This option 
cc30: 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61 74  specifies a stat
cc40: 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72  ic memory buffer
cc50: 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e   that SQLite can
cc60: 20 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20   use for.** the 
cc70: 64 61 74 61 62 61 73 65 20 70 61 67 65 20 63 61  database page ca
cc80: 63 68 65 2e 20 20 54 68 65 72 65 20 61 72 65 20  che.  There are 
cc90: 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 3a  three arguments:
cca0: 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   A pointer to th
ccb0: 65 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 74 68 65  e.** memory, the
ccc0: 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 70 61   size of each pa
ccd0: 67 65 20 62 75 66 66 65 72 20 28 73 7a 29 2c 20  ge buffer (sz), 
cce0: 61 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  and the number o
ccf0: 66 20 70 61 67 65 73 20 28 4e 29 2e 0a 2a 2a 20  f pages (N)..** 
cd00: 54 68 65 20 73 7a 20 61 72 67 75 6d 65 6e 74 20  The sz argument 
cd10: 6d 75 73 74 20 62 65 20 61 20 70 6f 77 65 72 20  must be a power 
cd20: 6f 66 20 74 77 6f 20 62 65 74 77 65 65 6e 20 35  of two between 5
cd30: 31 32 20 61 6e 64 20 33 32 37 36 38 2e 20 20 54  12 and 32768.  T
cd40: 68 65 20 66 69 72 73 74 0a 2a 2a 20 61 72 67 75  he first.** argu
cd50: 6d 65 6e 74 20 73 68 6f 75 6c 64 20 70 6f 69 6e  ment should poin
cd60: 74 20 74 6f 20 61 6e 20 61 6c 6c 6f 63 61 74 69  t to an allocati
cd70: 6f 6e 20 6f 66 20 61 74 20 6c 65 61 73 74 20 73  on of at least s
cd80: 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d 65 6d  z*N bytes of mem
cd90: 6f 72 79 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 77  ory..** SQLite w
cda0: 69 6c 6c 20 75 73 65 20 74 68 65 20 6d 65 6d 6f  ill use the memo
cdb0: 72 79 20 70 72 6f 76 69 64 65 64 20 62 79 20 74  ry provided by t
cdc0: 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
cdd0: 74 20 74 6f 20 73 61 74 69 73 66 79 20 69 74 73  t to satisfy its
cde0: 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73  .** memory needs
cdf0: 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 4e   for the first N
ce00: 20 70 61 67 65 73 20 74 68 61 74 20 69 74 20 61   pages that it a
ce10: 64 64 73 20 74 6f 20 63 61 63 68 65 2e 20 20 49  dds to cache.  I
ce20: 66 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20  f additional.** 
ce30: 70 61 67 65 20 63 61 63 68 65 20 6d 65 6d 6f 72  page cache memor
ce40: 79 20 69 73 20 6e 65 65 64 65 64 20 62 65 79 6f  y is needed beyo
ce50: 6e 64 20 77 68 61 74 20 69 73 20 70 72 6f 76 69  nd what is provi
ce60: 64 65 64 20 62 79 20 74 68 69 73 20 6f 70 74 69  ded by this opti
ce70: 6f 6e 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69  on, then.** SQLi
ce80: 74 65 20 67 6f 65 73 20 74 6f 20 5b 73 71 6c 69  te goes to [sqli
ce90: 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 66 6f  te3_malloc()] fo
cea0: 72 20 74 68 65 20 61 64 64 69 74 69 6f 6e 61 6c  r the additional
ceb0: 20 73 74 6f 72 61 67 65 20 73 70 61 63 65 2e 0a   storage space..
cec0: 2a 2a 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74  ** The implement
ced0: 61 74 69 6f 6e 20 6d 69 67 68 74 20 75 73 65 20  ation might use 
cee0: 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20 74  one or more of t
cef0: 68 65 20 4e 20 62 75 66 66 65 72 73 20 74 6f 20  he N buffers to 
cf00: 68 6f 6c 64 20 0a 2a 2a 20 6d 65 6d 6f 72 79 20  hold .** memory 
cf10: 61 63 63 6f 75 6e 74 69 6e 67 20 69 6e 66 6f 72  accounting infor
cf20: 6d 61 74 69 6f 6e 2e 20 3c 2f 64 64 3e 0a 2a 2a  mation. </dd>.**
cf30: 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  .** <dt>SQLITE_C
cf40: 4f 4e 46 49 47 5f 48 45 41 50 3c 2f 64 74 3e 0a  ONFIG_HEAP</dt>.
cf50: 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69  ** <dd>This opti
cf60: 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 20 73  on specifies a s
cf70: 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66  tatic memory buf
cf80: 66 65 72 20 74 68 61 74 20 53 51 4c 69 74 65 20  fer that SQLite 
cf90: 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 66 6f 72 20  will use.** for 
cfa0: 61 6c 6c 20 6f 66 20 69 74 73 20 64 79 6e 61 6d  all of its dynam
cfb0: 69 63 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ic memory alloca
cfc0: 74 69 6f 6e 20 6e 65 65 64 73 20 62 65 79 6f 6e  tion needs beyon
cfd0: 64 20 74 68 6f 73 65 20 70 72 6f 76 69 64 65 64  d those provided
cfe0: 0a 2a 2a 20 66 6f 72 20 62 79 20 5b 53 51 4c 49  .** for by [SQLI
cff0: 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43  TE_CONFIG_SCRATC
d000: 48 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 43  H] and [SQLITE_C
d010: 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d  ONFIG_PAGECACHE]
d020: 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74  ..** There are t
d030: 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 3a 20  hree arguments: 
d040: 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  A pointer to the
d050: 20 6d 65 6d 6f 72 79 2c 20 74 68 65 20 6e 75 6d   memory, the num
d060: 62 65 72 20 6f 66 0a 2a 2a 20 62 79 74 65 73 20  ber of.** bytes 
d070: 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20 62 75  in the memory bu
d080: 66 66 65 72 2c 20 61 6e 64 20 74 68 65 20 6d 69  ffer, and the mi
d090: 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e  nimum allocation
d0a0: 20 73 69 7a 65 2e 20 20 49 66 0a 2a 2a 20 74 68   size.  If.** th
d0b0: 65 20 66 69 72 73 74 20 70 6f 69 6e 74 65 72 20  e first pointer 
d0c0: 28 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e  (the memory poin
d0d0: 74 65 72 29 20 69 73 20 4e 55 4c 4c 2c 20 74 68  ter) is NULL, th
d0e0: 65 6e 20 53 51 4c 69 74 65 20 72 65 76 65 72 74  en SQLite revert
d0f0: 73 0a 2a 2a 20 74 6f 20 75 73 69 6e 67 20 69 74  s.** to using it
d100: 73 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79  s default memory
d110: 20 61 6c 6c 6f 63 61 74 6f 72 20 28 74 68 65 20   allocator (the 
d120: 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20  system malloc() 
d130: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 29 2c  implementation),
d140: 0a 2a 2a 20 75 6e 64 6f 69 6e 67 20 61 6e 79 20  .** undoing any 
d150: 70 72 69 6f 72 20 69 6e 76 6f 63 61 74 69 6f 6e  prior invocation
d160: 20 6f 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46   of [SQLITE_CONF
d170: 49 47 5f 4d 41 4c 4c 4f 43 5d 2e 20 20 49 66 20  IG_MALLOC].  If 
d180: 74 68 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 70 6f  the.** memory po
d190: 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c  inter is not NUL
d1a0: 4c 20 61 6e 64 20 65 69 74 68 65 72 20 5b 53 51  L and either [SQ
d1b0: 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53  LITE_ENABLE_MEMS
d1c0: 59 53 33 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49  YS3] or.** [SQLI
d1d0: 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53  TE_ENABLE_MEMSYS
d1e0: 35 5d 20 61 72 65 20 64 65 66 69 6e 65 64 2c 20  5] are defined, 
d1f0: 74 68 65 6e 20 74 68 65 20 61 6c 74 65 72 6e 61  then the alterna
d200: 74 69 76 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61  tive memory.** a
d210: 6c 6c 6f 63 61 74 6f 72 20 69 73 20 65 6e 67 61  llocator is enga
d220: 67 65 64 20 74 6f 20 68 61 6e 64 6c 65 20 61 6c  ged to handle al
d230: 6c 20 6f 66 20 53 51 4c 69 74 65 73 20 6d 65 6d  l of SQLites mem
d240: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e  ory allocation n
d250: 65 65 64 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  eeds.</dd>.**.**
d260: 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
d270: 49 47 5f 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a  IG_MUTEX</dt>.**
d280: 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e   <dd>This option
d290: 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
d2a0: 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69  argument which i
d2b0: 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
d2c0: 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66  n.** instance of
d2d0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75   the [sqlite3_mu
d2e0: 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72  tex_methods] str
d2f0: 75 63 74 75 72 65 2e 20 20 54 68 65 20 61 72 67  ucture.  The arg
d300: 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73 0a  ument specifies.
d310: 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6c  ** alternative l
d320: 6f 77 2d 6c 65 76 65 6c 20 6d 75 74 65 78 20 72  ow-level mutex r
d330: 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73  outines to be us
d340: 65 64 20 69 6e 20 70 6c 61 63 65 0a 2a 2a 20 74  ed in place.** t
d350: 68 65 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65  he mutex routine
d360: 73 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c  s built into SQL
d370: 69 74 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ite.</dd>.**.** 
d380: 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
d390: 47 5f 47 45 54 4d 55 54 45 58 3c 2f 64 74 3e 0a  G_GETMUTEX</dt>.
d3a0: 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69  ** <dd>This opti
d3b0: 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
d3c0: 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  e argument which
d3d0: 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
d3e0: 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20   an.** instance 
d3f0: 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
d400: 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73  mutex_methods] s
d410: 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 0a 2a  tructure.  The.*
d420: 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  * [sqlite3_mutex
d430: 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72  _methods].** str
d440: 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c 65 64  ucture is filled
d450: 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65 6e   with the curren
d460: 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 75 74 65  tly defined mute
d470: 78 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20 54  x routines..** T
d480: 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62  his option can b
d490: 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f  e used to overlo
d4a0: 61 64 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d  ad the default m
d4b0: 75 74 65 78 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a  utex allocation.
d4c0: 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 69 74 68  ** routines with
d4d0: 20 61 20 77 72 61 70 70 65 72 20 75 73 65 64 20   a wrapper used 
d4e0: 74 6f 20 74 72 61 63 6b 20 6d 75 74 65 78 20 75  to track mutex u
d4f0: 73 61 67 65 20 66 6f 72 20 70 65 72 66 6f 72 6d  sage for perform
d500: 61 6e 63 65 0a 2a 2a 20 70 72 6f 66 69 6c 69 6e  ance.** profilin
d510: 67 20 6f 72 20 74 65 73 74 69 6e 67 2c 20 66 6f  g or testing, fo
d520: 72 20 65 78 61 6d 70 6c 65 2e 3c 2f 64 64 3e 0a  r example.</dd>.
d530: 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
d540: 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  _CONFIG_LOOKASID
d550: 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  E</dt>.** <dd>Th
d560: 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  is option takes 
d570: 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 68  two arguments th
d580: 61 74 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65  at determine the
d590: 20 64 65 66 61 75 6c 74 0a 2a 2a 20 6d 65 6d 6f   default.** memo
d5a0: 72 79 20 61 6c 6c 63 61 74 69 6f 6e 20 6c 6f 6f  ry allcation loo
d5b0: 6b 61 73 69 64 65 20 6f 70 74 69 6d 69 7a 61 74  kaside optimizat
d5c0: 69 6f 6e 2e 20 20 54 68 65 20 66 69 72 73 74 20  ion.  The first 
d5d0: 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a  argument is the.
d5e0: 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20  ** size of each 
d5f0: 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72  lookaside buffer
d600: 20 73 6c 6f 74 20 61 6e 64 20 74 68 65 20 73 65   slot and the se
d610: 63 6f 6e 64 20 69 73 20 74 68 65 20 6e 75 6d 62  cond is the numb
d620: 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 20 61  er of.** slots a
d630: 6c 6c 6f 63 61 74 65 64 20 74 6f 20 65 61 63 68  llocated to each
d640: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
d650: 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  tion.</dd>.**.**
d660: 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e   </dl>.*/.#defin
d670: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
d680: 53 49 4e 47 4c 45 54 48 52 45 41 44 20 20 31 20  SINGLETHREAD  1 
d690: 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69   /* nil */.#defi
d6a0: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
d6b0: 5f 4d 55 4c 54 49 54 48 52 45 41 44 20 20 20 32  _MULTITHREAD   2
d6c0: 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66    /* nil */.#def
d6d0: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
d6e0: 47 5f 53 45 52 49 41 4c 49 5a 45 44 20 20 20 20  G_SERIALIZED    
d6f0: 33 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65  3  /* nil */.#de
d700: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
d710: 49 47 5f 4d 41 4c 4c 4f 43 20 20 20 20 20 20 20  IG_MALLOC       
d720: 20 34 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d   4  /* sqlite3_m
d730: 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23  em_methods* */.#
d740: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
d750: 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 20  NFIG_GETMALLOC  
d760: 20 20 20 35 20 20 2f 2a 20 73 71 6c 69 74 65 33     5  /* sqlite3
d770: 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f  _mem_methods* */
d780: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
d790: 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 20 20  CONFIG_SCRATCH  
d7a0: 20 20 20 20 20 36 20 20 2f 2a 20 76 6f 69 64 2a       6  /* void*
d7b0: 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20  , int sz, int N 
d7c0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
d7d0: 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43  E_CONFIG_PAGECAC
d7e0: 48 45 20 20 20 20 20 37 20 20 2f 2a 20 76 6f 69  HE     7  /* voi
d7f0: 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20  d*, int sz, int 
d800: 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  N */.#define SQL
d810: 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20  ITE_CONFIG_HEAP 
d820: 20 20 20 20 20 20 20 20 20 38 20 20 2f 2a 20 76           8  /* v
d830: 6f 69 64 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c  oid*, int nByte,
d840: 20 69 6e 74 20 6d 69 6e 20 2a 2f 0a 23 64 65 66   int min */.#def
d850: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
d860: 47 5f 4d 45 4d 53 54 41 54 55 53 20 20 20 20 20  G_MEMSTATUS     
d870: 39 20 20 2f 2a 20 62 6f 6f 6c 65 61 6e 20 2a 2f  9  /* boolean */
d880: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
d890: 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 20 20 20  CONFIG_MUTEX    
d8a0: 20 20 20 20 31 30 20 20 2f 2a 20 73 71 6c 69 74      10  /* sqlit
d8b0: 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73  e3_mutex_methods
d8c0: 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
d8d0: 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55  ITE_CONFIG_GETMU
d8e0: 54 45 58 20 20 20 20 20 31 31 20 20 2f 2a 20 73  TEX     11  /* s
d8f0: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74  qlite3_mutex_met
d900: 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65  hods* */.#define
d910: 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43   SQLITE_CONFIG_C
d920: 48 55 4e 4b 41 4c 4c 4f 43 20 20 20 31 32 20 20  HUNKALLOC   12  
d930: 2f 2a 20 69 6e 74 20 74 68 72 65 73 68 6f 6c 64  /* int threshold
d940: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
d950: 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  TE_CONFIG_LOOKAS
d960: 49 44 45 20 20 20 20 31 33 20 20 2f 2a 20 69 6e  IDE    13  /* in
d970: 74 20 69 6e 74 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20  t int */../*.** 
d980: 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67  CAPI3REF: Config
d990: 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 20  uration Options 
d9a0: 7b 48 31 30 31 37 30 7d 20 3c 53 32 30 30 30 30  {H10170} <S20000
d9b0: 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41  >.** EXPERIMENTA
d9c0: 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f  L.**.** These co
d9d0: 6e 73 74 61 6e 74 73 20 61 72 65 20 74 68 65 20  nstants are the 
d9e0: 61 76 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 65  available intege
d9f0: 72 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  r configuration 
da00: 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20  options that.** 
da10: 63 61 6e 20 62 65 20 70 61 73 73 65 64 20 61 73  can be passed as
da20: 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
da30: 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c  ment to the [sql
da40: 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29  ite3_db_config()
da50: 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a  ] interface..**.
da60: 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75 72 61  ** New configura
da70: 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79  tion options may
da80: 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74   be added in fut
da90: 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20  ure releases of 
daa0: 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74  SQLite..** Exist
dab0: 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ing configuratio
dac0: 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74 20  n options might 
dad0: 62 65 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e  be discontinued.
dae0: 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a    Applications.*
daf0: 2a 20 73 68 6f 75 6c 64 20 63 68 65 63 6b 20 74  * should check t
db00: 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65 20 66  he return code f
db10: 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f  rom [sqlite3_db_
db20: 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b  config()] to mak
db30: 65 20 73 75 72 65 20 74 68 61 74 0a 2a 2a 20 74  e sure that.** t
db40: 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20  he call worked. 
db50: 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62   The [sqlite3_db
db60: 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72  _config()] inter
db70: 66 61 63 65 20 77 69 6c 6c 20 72 65 74 75 72 6e  face will return
db80: 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b   a.** non-zero [
db90: 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61  error code] if a
dba0: 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72   discontinued or
dbb0: 20 75 6e 73 75 70 70 6f 72 74 65 64 20 63 6f 6e   unsupported con
dbc0: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
dbd0: 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e  n.** is invoked.
dbe0: 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c  .**.** <dl>.** <
dbf0: 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  dt>SQLITE_DBCONF
dc00: 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74  IG_LOOKASIDE</dt
dc10: 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70  >.** <dd>This op
dc20: 74 69 6f 6e 20 74 61 6b 65 73 20 74 68 72 65 65  tion takes three
dc30: 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75   additional argu
dc40: 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74 65 72  ments that deter
dc50: 6d 69 6e 65 20 74 68 65 20 0a 2a 2a 20 5b 6c 6f  mine the .** [lo
dc60: 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 61  okaside memory a
dc70: 6c 6c 6f 63 61 74 6f 72 5d 20 63 6f 6e 66 69 67  llocator] config
dc80: 75 72 61 74 69 6f 6e 20 66 6f 72 20 74 68 65 20  uration for the 
dc90: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
dca0: 74 69 6f 6e 5d 2e 0a 2a 2a 20 54 68 65 20 66 69  tion]..** The fi
dcb0: 72 73 74 20 61 72 67 75 6d 65 6e 74 20 28 74 68  rst argument (th
dcc0: 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
dcd0: 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62  r to [sqlite3_db
dce0: 5f 63 6f 6e 66 69 67 28 29 5d 20 69 73 20 61 0a  _config()] is a.
dcf0: 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20  ** pointer to a 
dd00: 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 6f  memory buffer to
dd10: 20 75 73 65 20 66 6f 72 20 6c 6f 6f 6b 61 73 69   use for lookasi
dd20: 64 65 20 6d 65 6d 6f 72 79 2e 20 20 54 68 65 20  de memory.  The 
dd30: 66 69 72 73 74 0a 2a 2a 20 61 72 67 75 6d 65 6e  first.** argumen
dd40: 74 20 6d 61 79 20 62 65 20 4e 55 4c 4c 20 69 6e  t may be NULL in
dd50: 20 77 68 69 63 68 20 63 61 73 65 20 53 51 4c 69   which case SQLi
dd60: 74 65 20 77 69 6c 6c 20 61 6c 6c 6f 63 61 74 65  te will allocate
dd70: 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a   the lookaside.*
dd80: 2a 20 62 75 66 66 65 72 20 69 74 73 65 6c 66 20  * buffer itself 
dd90: 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d  using [sqlite3_m
dda0: 61 6c 6c 6f 63 28 29 5d 2e 20 20 54 68 65 20 73  alloc()].  The s
ddb0: 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69  econd argument i
ddc0: 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66  s the.** size of
ddd0: 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20   each lookaside 
dde0: 62 75 66 66 65 72 20 73 6c 6f 74 20 61 6e 64 20  buffer slot and 
ddf0: 74 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65  the third argume
de00: 6e 74 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72  nt is the number
de10: 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 2e 20 20 54   of.** slots.  T
de20: 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62  he size of the b
de30: 75 66 66 65 72 20 69 6e 20 74 68 65 20 66 69 72  uffer in the fir
de40: 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74  st argument must
de50: 20 62 65 20 67 72 65 61 74 65 72 20 74 68 61 6e   be greater than
de60: 0a 2a 2a 20 6f 72 20 65 71 75 61 6c 20 74 6f 20  .** or equal to 
de70: 74 68 65 20 70 72 6f 64 75 63 74 20 6f 66 20 74  the product of t
de80: 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68  he second and th
de90: 69 72 64 20 61 72 67 75 6d 65 6e 74 73 2e 3c 2f  ird arguments.</
dea0: 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a  dd>.**.** </dl>.
deb0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
dec0: 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  E_DBCONFIG_LOOKA
ded0: 53 49 44 45 20 20 20 20 31 30 30 31 20 20 2f 2a  SIDE    1001  /*
dee0: 20 76 6f 69 64 2a 20 69 6e 74 20 69 6e 74 20 2a   void* int int *
def0: 2f 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  /.../*.** CAPI3R
df00: 45 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44 69  EF: Enable Or Di
df10: 73 61 62 6c 65 20 45 78 74 65 6e 64 65 64 20 52  sable Extended R
df20: 65 73 75 6c 74 20 43 6f 64 65 73 20 7b 48 31 32  esult Codes {H12
df30: 32 30 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 2a  200} <S10700>.**
df40: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
df50: 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f  extended_result_
df60: 63 6f 64 65 73 28 29 20 72 6f 75 74 69 6e 65 20  codes() routine 
df70: 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62  enables or disab
df80: 6c 65 73 20 74 68 65 0a 2a 2a 20 5b 65 78 74 65  les the.** [exte
df90: 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
dfa0: 73 5d 20 66 65 61 74 75 72 65 20 6f 66 20 53 51  s] feature of SQ
dfb0: 4c 69 74 65 2e 20 54 68 65 20 65 78 74 65 6e 64  Lite. The extend
dfc0: 65 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 64  ed result.** cod
dfd0: 65 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 20  es are disabled 
dfe0: 62 79 20 64 65 66 61 75 6c 74 20 66 6f 72 20 68  by default for h
dff0: 69 73 74 6f 72 69 63 61 6c 20 63 6f 6d 70 61 74  istorical compat
e000: 69 62 69 6c 69 74 79 20 63 6f 6e 73 69 64 65 72  ibility consider
e010: 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 4e  ations..**.** IN
e020: 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
e030: 7b 48 31 32 32 30 31 7d 20 45 61 63 68 20 6e 65  {H12201} Each ne
e040: 77 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  w [database conn
e050: 65 63 74 69 6f 6e 5d 20 73 68 61 6c 6c 20 68 61  ection] shall ha
e060: 76 65 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  ve the.**       
e070: 20 20 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73     [extended res
e080: 75 6c 74 20 63 6f 64 65 73 5d 20 66 65 61 74 75  ult codes] featu
e090: 72 65 20 64 69 73 61 62 6c 65 64 20 62 79 20 64  re disabled by d
e0a0: 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48  efault..**.** {H
e0b0: 31 32 32 30 32 7d 20 54 68 65 20 5b 73 71 6c 69  12202} The [sqli
e0c0: 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73  te3_extended_res
e0d0: 75 6c 74 5f 63 6f 64 65 73 28 44 2c 46 29 5d 20  ult_codes(D,F)] 
e0e0: 69 6e 74 65 72 66 61 63 65 20 73 68 61 6c 6c 20  interface shall 
e0f0: 65 6e 61 62 6c 65 0a 2a 2a 20 20 20 20 20 20 20  enable.**       
e100: 20 20 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73     [extended res
e110: 75 6c 74 20 63 6f 64 65 73 5d 20 66 6f 72 20 74  ult codes] for t
e120: 68 65 20 20 5b 64 61 74 61 62 61 73 65 20 63 6f  he  [database co
e130: 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a 2a 20 20  nnection] D.**  
e140: 20 20 20 20 20 20 20 20 69 66 20 74 68 65 20 46          if the F
e150: 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 72   parameter is tr
e160: 75 65 2c 20 6f 72 20 64 69 73 61 62 6c 65 20 74  ue, or disable t
e170: 68 65 6d 20 69 66 20 46 20 69 73 20 66 61 6c 73  hem if F is fals
e180: 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  e..*/.int sqlite
e190: 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c  3_extended_resul
e1a0: 74 5f 63 6f 64 65 73 28 73 71 6c 69 74 65 33 2a  t_codes(sqlite3*
e1b0: 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f  , int onoff);../
e1c0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4c  *.** CAPI3REF: L
e1d0: 61 73 74 20 49 6e 73 65 72 74 20 52 6f 77 69 64  ast Insert Rowid
e1e0: 20 7b 48 31 32 32 32 30 7d 20 3c 53 31 30 37 30   {H12220} <S1070
e1f0: 30 3e 0a 2a 2a 0a 2a 2a 20 45 61 63 68 20 65 6e  0>.**.** Each en
e200: 74 72 79 20 69 6e 20 61 6e 20 53 51 4c 69 74 65  try in an SQLite
e210: 20 74 61 62 6c 65 20 68 61 73 20 61 20 75 6e 69   table has a uni
e220: 71 75 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65  que 64-bit signe
e230: 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6b 65 79  d.** integer key
e240: 20 63 61 6c 6c 65 64 20 74 68 65 20 22 72 6f 77   called the "row
e250: 69 64 22 2e 20 54 68 65 20 72 6f 77 69 64 20 69  id". The rowid i
e260: 73 20 61 6c 77 61 79 73 20 61 76 61 69 6c 61 62  s always availab
e270: 6c 65 0a 2a 2a 20 61 73 20 61 6e 20 75 6e 64 65  le.** as an unde
e280: 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 20 6e 61  clared column na
e290: 6d 65 64 20 52 4f 57 49 44 2c 20 4f 49 44 2c 20  med ROWID, OID, 
e2a0: 6f 72 20 5f 52 4f 57 49 44 5f 20 61 73 20 6c 6f  or _ROWID_ as lo
e2b0: 6e 67 20 61 73 20 74 68 6f 73 65 0a 2a 2a 20 6e  ng as those.** n
e2c0: 61 6d 65 73 20 61 72 65 20 6e 6f 74 20 61 6c 73  ames are not als
e2d0: 6f 20 75 73 65 64 20 62 79 20 65 78 70 6c 69 63  o used by explic
e2e0: 69 74 6c 79 20 64 65 63 6c 61 72 65 64 20 63 6f  itly declared co
e2f0: 6c 75 6d 6e 73 2e 20 49 66 0a 2a 2a 20 74 68 65  lumns. If.** the
e300: 20 74 61 62 6c 65 20 68 61 73 20 61 20 63 6f 6c   table has a col
e310: 75 6d 6e 20 6f 66 20 74 79 70 65 20 49 4e 54 45  umn of type INTE
e320: 47 45 52 20 50 52 49 4d 41 52 59 20 4b 45 59 20  GER PRIMARY KEY 
e330: 74 68 65 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e  then that column
e340: 0a 2a 2a 20 69 73 20 61 6e 6f 74 68 65 72 20 61  .** is another a
e350: 6c 69 61 73 20 66 6f 72 20 74 68 65 20 72 6f 77  lias for the row
e360: 69 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72  id..**.** This r
e370: 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74  outine returns t
e380: 68 65 20 72 6f 77 69 64 20 6f 66 20 74 68 65 20  he rowid of the 
e390: 6d 6f 73 74 20 72 65 63 65 6e 74 0a 2a 2a 20 73  most recent.** s
e3a0: 75 63 63 65 73 73 66 75 6c 20 49 4e 53 45 52 54  uccessful INSERT
e3b0: 20 69 6e 74 6f 20 74 68 65 20 64 61 74 61 62 61   into the databa
e3c0: 73 65 20 66 72 6f 6d 20 74 68 65 20 5b 64 61 74  se from the [dat
e3d0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
e3e0: 5d 0a 2a 2a 20 69 6e 20 74 68 65 20 66 69 72 73  ].** in the firs
e3f0: 74 20 61 72 67 75 6d 65 6e 74 2e 20 20 49 66 20  t argument.  If 
e400: 6e 6f 20 73 75 63 63 65 73 73 66 75 6c 20 49 4e  no successful IN
e410: 53 45 52 54 73 0a 2a 2a 20 68 61 76 65 20 65 76  SERTs.** have ev
e420: 65 72 20 6f 63 63 75 72 72 65 64 20 6f 6e 20 74  er occurred on t
e430: 68 61 74 20 64 61 74 61 62 61 73 65 20 63 6f 6e  hat database con
e440: 6e 65 63 74 69 6f 6e 2c 20 7a 65 72 6f 20 69 73  nection, zero is
e450: 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
e460: 20 49 66 20 61 6e 20 49 4e 53 45 52 54 20 6f 63   If an INSERT oc
e470: 63 75 72 73 20 77 69 74 68 69 6e 20 61 20 74 72  curs within a tr
e480: 69 67 67 65 72 2c 20 74 68 65 6e 20 74 68 65 20  igger, then the 
e490: 72 6f 77 69 64 20 6f 66 20 74 68 65 20 69 6e 73  rowid of the ins
e4a0: 65 72 74 65 64 0a 2a 2a 20 72 6f 77 20 69 73 20  erted.** row is 
e4b0: 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 69 73  returned by this
e4c0: 20 72 6f 75 74 69 6e 65 20 61 73 20 6c 6f 6e 67   routine as long
e4d0: 20 61 73 20 74 68 65 20 74 72 69 67 67 65 72 20   as the trigger 
e4e0: 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 42  is running..** B
e4f0: 75 74 20 6f 6e 63 65 20 74 68 65 20 74 72 69 67  ut once the trig
e500: 67 65 72 20 74 65 72 6d 69 6e 61 74 65 73 2c 20  ger terminates, 
e510: 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
e520: 65 64 20 62 79 20 74 68 69 73 20 72 6f 75 74 69  ed by this routi
e530: 6e 65 0a 2a 2a 20 72 65 76 65 72 74 73 20 74 6f  ne.** reverts to
e540: 20 74 68 65 20 6c 61 73 74 20 76 61 6c 75 65 20   the last value 
e550: 69 6e 73 65 72 74 65 64 20 62 65 66 6f 72 65 20  inserted before 
e560: 74 68 65 20 74 72 69 67 67 65 72 20 66 69 72 65  the trigger fire
e570: 64 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 49 4e 53 45  d..**.** An INSE
e580: 52 54 20 74 68 61 74 20 66 61 69 6c 73 20 64 75  RT that fails du
e590: 65 20 74 6f 20 61 20 63 6f 6e 73 74 72 61 69 6e  e to a constrain
e5a0: 74 20 76 69 6f 6c 61 74 69 6f 6e 20 69 73 20 6e  t violation is n
e5b0: 6f 74 20 61 0a 2a 2a 20 73 75 63 63 65 73 73 66  ot a.** successf
e5c0: 75 6c 20 49 4e 53 45 52 54 20 61 6e 64 20 64 6f  ul INSERT and do
e5d0: 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68  es not change th
e5e0: 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
e5f0: 20 62 79 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74   by this.** rout
e600: 69 6e 65 2e 20 20 54 68 75 73 20 49 4e 53 45 52  ine.  Thus INSER
e610: 54 20 4f 52 20 46 41 49 4c 2c 20 49 4e 53 45 52  T OR FAIL, INSER
e620: 54 20 4f 52 20 49 47 4e 4f 52 45 2c 20 49 4e 53  T OR IGNORE, INS
e630: 45 52 54 20 4f 52 20 52 4f 4c 4c 42 41 43 4b 2c  ERT OR ROLLBACK,
e640: 0a 2a 2a 20 61 6e 64 20 49 4e 53 45 52 54 20 4f  .** and INSERT O
e650: 52 20 41 42 4f 52 54 20 6d 61 6b 65 20 6e 6f 20  R ABORT make no 
e660: 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 20 72  changes to the r
e670: 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74  eturn value of t
e680: 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 77  his.** routine w
e690: 68 65 6e 20 74 68 65 69 72 20 69 6e 73 65 72 74  hen their insert
e6a0: 69 6f 6e 20 66 61 69 6c 73 2e 20 20 57 68 65 6e  ion fails.  When
e6b0: 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41   INSERT OR REPLA
e6c0: 43 45 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65 72 73  CE.** encounters
e6d0: 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69   a constraint vi
e6e0: 6f 6c 61 74 69 6f 6e 2c 20 69 74 20 64 6f 65 73  olation, it does
e6f0: 20 6e 6f 74 20 66 61 69 6c 2e 20 20 54 68 65 0a   not fail.  The.
e700: 2a 2a 20 49 4e 53 45 52 54 20 63 6f 6e 74 69 6e  ** INSERT contin
e710: 75 65 73 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f  ues to completio
e720: 6e 20 61 66 74 65 72 20 64 65 6c 65 74 69 6e 67  n after deleting
e730: 20 72 6f 77 73 20 74 68 61 74 20 63 61 75 73 65   rows that cause
e740: 64 0a 2a 2a 20 74 68 65 20 63 6f 6e 73 74 72 61  d.** the constra
e750: 69 6e 74 20 70 72 6f 62 6c 65 6d 20 73 6f 20 49  int problem so I
e760: 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43 45  NSERT OR REPLACE
e770: 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 63 68 61   will always cha
e780: 6e 67 65 0a 2a 2a 20 74 68 65 20 72 65 74 75 72  nge.** the retur
e790: 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73 20  n value of this 
e7a0: 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a  interface..**.**
e7b0: 20 46 6f 72 20 74 68 65 20 70 75 72 70 6f 73 65   For the purpose
e7c0: 73 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e  s of this routin
e7d0: 65 2c 20 61 6e 20 49 4e 53 45 52 54 20 69 73 20  e, an INSERT is 
e7e0: 63 6f 6e 73 69 64 65 72 65 64 20 74 6f 0a 2a 2a  considered to.**
e7f0: 20 62 65 20 73 75 63 63 65 73 73 66 75 6c 20 65   be successful e
e800: 76 65 6e 20 69 66 20 69 74 20 69 73 20 73 75 62  ven if it is sub
e810: 73 65 71 75 65 6e 74 6c 79 20 72 6f 6c 6c 65 64  sequently rolled
e820: 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56   back..**.** INV
e830: 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
e840: 48 31 32 32 32 31 7d 20 54 68 65 20 5b 73 71 6c  H12221} The [sql
e850: 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74  ite3_last_insert
e860: 5f 72 6f 77 69 64 28 29 5d 20 66 75 6e 63 74 69  _rowid()] functi
e870: 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 72  on returns the r
e880: 6f 77 69 64 0a 2a 2a 20 20 20 20 20 20 20 20 20  owid.**         
e890: 20 6f 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63   of the most rec
e8a0: 65 6e 74 20 73 75 63 63 65 73 73 66 75 6c 20 49  ent successful I
e8b0: 4e 53 45 52 54 20 70 65 72 66 6f 72 6d 65 64 20  NSERT performed 
e8c0: 6f 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 20  on the same.**  
e8d0: 20 20 20 20 20 20 20 20 5b 64 61 74 61 62 61 73          [databas
e8e0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e  e connection] an
e8f0: 64 20 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d  d within the sam
e900: 65 20 6f 72 20 68 69 67 68 65 72 20 6c 65 76 65  e or higher leve
e910: 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 72  l.**          tr
e920: 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2c 20 6f  igger context, o
e930: 72 20 7a 65 72 6f 20 69 66 20 74 68 65 72 65 20  r zero if there 
e940: 68 61 76 65 20 62 65 65 6e 20 6e 6f 20 71 75 61  have been no qua
e950: 6c 69 66 79 69 6e 67 20 69 6e 73 65 72 74 73 2e  lifying inserts.
e960: 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 32 33 7d 20  .**.** {H12223} 
e970: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73  The [sqlite3_las
e980: 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29  t_insert_rowid()
e990: 5d 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  ] function retur
e9a0: 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  ns the.**       
e9b0: 20 20 20 73 61 6d 65 20 76 61 6c 75 65 20 77 68     same value wh
e9c0: 65 6e 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74  en called from t
e9d0: 68 65 20 73 61 6d 65 20 74 72 69 67 67 65 72 20  he same trigger 
e9e0: 63 6f 6e 74 65 78 74 0a 2a 2a 20 20 20 20 20 20  context.**      
e9f0: 20 20 20 20 69 6d 6d 65 64 69 61 74 65 6c 79 20      immediately 
ea00: 62 65 66 6f 72 65 20 61 6e 64 20 61 66 74 65 72  before and after
ea10: 20 61 20 52 4f 4c 4c 42 41 43 4b 2e 0a 2a 2a 0a   a ROLLBACK..**.
ea20: 2a 2a 20 41 53 53 55 4d 50 54 49 4f 4e 53 3a 0a  ** ASSUMPTIONS:.
ea30: 2a 2a 0a 2a 2a 20 7b 41 31 32 32 33 32 7d 20 49  **.** {A12232} I
ea40: 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72  f a separate thr
ea50: 65 61 64 20 70 65 72 66 6f 72 6d 73 20 61 20 6e  ead performs a n
ea60: 65 77 20 49 4e 53 45 52 54 20 6f 6e 20 74 68 65  ew INSERT on the
ea70: 20 73 61 6d 65 0a 2a 2a 20 20 20 20 20 20 20 20   same.**        
ea80: 20 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65    database conne
ea90: 63 74 69 6f 6e 20 77 68 69 6c 65 20 74 68 65 20  ction while the 
eaa0: 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e  [sqlite3_last_in
eab0: 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 0a 2a 2a  sert_rowid()].**
eac0: 20 20 20 20 20 20 20 20 20 20 66 75 6e 63 74 69            functi
ead0: 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 20 61 6e  on is running an
eae0: 64 20 74 68 75 73 20 63 68 61 6e 67 65 73 20 74  d thus changes t
eaf0: 68 65 20 6c 61 73 74 20 69 6e 73 65 72 74 20 72  he last insert r
eb00: 6f 77 69 64 2c 0a 2a 2a 20 20 20 20 20 20 20 20  owid,.**        
eb10: 20 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65    then the value
eb20: 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71   returned by [sq
eb30: 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72  lite3_last_inser
eb40: 74 5f 72 6f 77 69 64 28 29 5d 20 69 73 0a 2a 2a  t_rowid()] is.**
eb50: 20 20 20 20 20 20 20 20 20 20 75 6e 70 72 65 64            unpred
eb60: 69 63 74 61 62 6c 65 20 61 6e 64 20 6d 69 67 68  ictable and migh
eb70: 74 20 6e 6f 74 20 65 71 75 61 6c 20 65 69 74 68  t not equal eith
eb80: 65 72 20 74 68 65 20 6f 6c 64 20 6f 72 20 74 68  er the old or th
eb90: 65 20 6e 65 77 0a 2a 2a 20 20 20 20 20 20 20 20  e new.**        
eba0: 20 20 6c 61 73 74 20 69 6e 73 65 72 74 20 72 6f    last insert ro
ebb0: 77 69 64 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f  wid..*/.sqlite3_
ebc0: 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6c 61  int64 sqlite3_la
ebd0: 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28  st_insert_rowid(
ebe0: 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a  sqlite3*);../*.*
ebf0: 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 75 6e  * CAPI3REF: Coun
ec00: 74 20 54 68 65 20 4e 75 6d 62 65 72 20 4f 66 20  t The Number Of 
ec10: 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 20 7b 48  Rows Modified {H
ec20: 31 32 32 34 30 7d 20 3c 53 31 30 36 30 30 3e 0a  12240} <S10600>.
ec30: 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74  **.** This funct
ec40: 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20  ion returns the 
ec50: 6e 75 6d 62 65 72 20 6f 66 20 64 61 74 61 62 61  number of databa
ec60: 73 65 20 72 6f 77 73 20 74 68 61 74 20 77 65 72  se rows that wer
ec70: 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20 6f 72 20  e changed.** or 
ec80: 69 6e 73 65 72 74 65 64 20 6f 72 20 64 65 6c 65  inserted or dele
ec90: 74 65 64 20 62 79 20 74 68 65 20 6d 6f 73 74 20  ted by the most 
eca0: 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74  recently complet
ecb0: 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ed SQL statement
ecc0: 0a 2a 2a 20 6f 6e 20 74 68 65 20 5b 64 61 74 61  .** on the [data
ecd0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
ece0: 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68   specified by th
ecf0: 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
ed00: 72 2e 0a 2a 2a 20 4f 6e 6c 79 20 63 68 61 6e 67  r..** Only chang
ed10: 65 73 20 74 68 61 74 20 61 72 65 20 64 69 72 65  es that are dire
ed20: 63 74 6c 79 20 73 70 65 63 69 66 69 65 64 20 62  ctly specified b
ed30: 79 20 74 68 65 20 49 4e 53 45 52 54 2c 20 55 50  y the INSERT, UP
ed40: 44 41 54 45 2c 0a 2a 2a 20 6f 72 20 44 45 4c 45  DATE,.** or DELE
ed50: 54 45 20 73 74 61 74 65 6d 65 6e 74 20 61 72 65  TE statement are
ed60: 20 63 6f 75 6e 74 65 64 2e 20 20 41 75 78 69 6c   counted.  Auxil
ed70: 69 61 72 79 20 63 68 61 6e 67 65 73 20 63 61 75  iary changes cau
ed80: 73 65 64 20 62 79 0a 2a 2a 20 74 72 69 67 67 65  sed by.** trigge
ed90: 72 73 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74  rs are not count
eda0: 65 64 2e 20 55 73 65 20 74 68 65 20 5b 73 71 6c  ed. Use the [sql
edb0: 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67  ite3_total_chang
edc0: 65 73 28 29 5d 20 66 75 6e 63 74 69 6f 6e 0a 2a  es()] function.*
edd0: 2a 20 74 6f 20 66 69 6e 64 20 74 68 65 20 74 6f  * to find the to
ede0: 74 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 63 68  tal number of ch
edf0: 61 6e 67 65 73 20 69 6e 63 6c 75 64 69 6e 67 20  anges including 
ee00: 63 68 61 6e 67 65 73 20 63 61 75 73 65 64 20 62  changes caused b
ee10: 79 20 74 72 69 67 67 65 72 73 2e 0a 2a 2a 0a 2a  y triggers..**.*
ee20: 2a 20 41 20 22 72 6f 77 20 63 68 61 6e 67 65 22  * A "row change"
ee30: 20 69 73 20 61 20 63 68 61 6e 67 65 20 74 6f 20   is a change to 
ee40: 61 20 73 69 6e 67 6c 65 20 72 6f 77 20 6f 66 20  a single row of 
ee50: 61 20 73 69 6e 67 6c 65 20 74 61 62 6c 65 0a 2a  a single table.*
ee60: 2a 20 63 61 75 73 65 64 20 62 79 20 61 6e 20 49  * caused by an I
ee70: 4e 53 45 52 54 2c 20 44 45 4c 45 54 45 2c 20 6f  NSERT, DELETE, o
ee80: 72 20 55 50 44 41 54 45 20 73 74 61 74 65 6d 65  r UPDATE stateme
ee90: 6e 74 2e 20 20 52 6f 77 73 20 74 68 61 74 0a 2a  nt.  Rows that.*
eea0: 2a 20 61 72 65 20 63 68 61 6e 67 65 64 20 61 73  * are changed as
eeb0: 20 73 69 64 65 20 65 66 66 65 63 74 73 20 6f 66   side effects of
eec0: 20 52 45 50 4c 41 43 45 20 63 6f 6e 73 74 72 61   REPLACE constra
eed0: 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e 2c 0a  int resolution,.
eee0: 2a 2a 20 72 6f 6c 6c 62 61 63 6b 2c 20 41 42 4f  ** rollback, ABO
eef0: 52 54 20 70 72 6f 63 65 73 73 69 6e 67 2c 20 44  RT processing, D
ef00: 52 4f 50 20 54 41 42 4c 45 2c 20 6f 72 20 62 79  ROP TABLE, or by
ef10: 20 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 6d 65   any other.** me
ef20: 63 68 61 6e 69 73 6d 73 20 64 6f 20 6e 6f 74 20  chanisms do not 
ef30: 63 6f 75 6e 74 20 61 73 20 64 69 72 65 63 74 20  count as direct 
ef40: 72 6f 77 20 63 68 61 6e 67 65 73 2e 0a 2a 2a 0a  row changes..**.
ef50: 2a 2a 20 41 20 22 74 72 69 67 67 65 72 20 63 6f  ** A "trigger co
ef60: 6e 74 65 78 74 22 20 69 73 20 61 20 73 63 6f 70  ntext" is a scop
ef70: 65 20 6f 66 20 65 78 65 63 75 74 69 6f 6e 20 74  e of execution t
ef80: 68 61 74 20 62 65 67 69 6e 73 20 61 6e 64 0a 2a  hat begins and.*
ef90: 2a 20 65 6e 64 73 20 77 69 74 68 20 74 68 65 20  * ends with the 
efa0: 73 63 72 69 70 74 20 6f 66 20 61 20 74 72 69 67  script of a trig
efb0: 67 65 72 2e 20 20 4d 6f 73 74 20 53 51 4c 20 73  ger.  Most SQL s
efc0: 74 61 74 65 6d 65 6e 74 73 20 61 72 65 0a 2a 2a  tatements are.**
efd0: 20 65 76 61 6c 75 61 74 65 64 20 6f 75 74 73 69   evaluated outsi
efe0: 64 65 20 6f 66 20 61 6e 79 20 74 72 69 67 67 65  de of any trigge
eff0: 72 2e 20 20 54 68 69 73 20 69 73 20 74 68 65 20  r.  This is the 
f000: 22 74 6f 70 20 6c 65 76 65 6c 22 0a 2a 2a 20 74  "top level".** t
f010: 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 20  rigger context. 
f020: 20 49 66 20 61 20 74 72 69 67 67 65 72 20 66 69   If a trigger fi
f030: 72 65 73 20 66 72 6f 6d 20 74 68 65 20 74 6f 70  res from the top
f040: 20 6c 65 76 65 6c 2c 20 61 0a 2a 2a 20 6e 65 77   level, a.** new
f050: 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74   trigger context
f060: 20 69 73 20 65 6e 74 65 72 65 64 20 66 6f 72 20   is entered for 
f070: 74 68 65 20 64 75 72 61 74 69 6f 6e 20 6f 66 20  the duration of 
f080: 74 68 61 74 20 6f 6e 65 0a 2a 2a 20 74 72 69 67  that one.** trig
f090: 67 65 72 2e 20 20 53 75 62 74 72 69 67 67 65 72  ger.  Subtrigger
f0a0: 73 20 63 72 65 61 74 65 20 73 75 62 63 6f 6e 74  s create subcont
f0b0: 65 78 74 73 20 66 6f 72 20 74 68 65 69 72 20 64  exts for their d
f0c0: 75 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 43  uration..**.** C
f0d0: 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
f0e0: 65 78 65 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69  exec()] or [sqli
f0f0: 74 65 33 5f 73 74 65 70 28 29 5d 20 72 65 63 75  te3_step()] recu
f100: 72 73 69 76 65 6c 79 20 64 6f 65 73 0a 2a 2a 20  rsively does.** 
f110: 6e 6f 74 20 63 72 65 61 74 65 20 61 20 6e 65 77  not create a new
f120: 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74   trigger context
f130: 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e  ..**.** This fun
f140: 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68  ction returns th
f150: 65 20 6e 75 6d 62 65 72 20 6f 66 20 64 69 72 65  e number of dire
f160: 63 74 20 72 6f 77 20 63 68 61 6e 67 65 73 20 69  ct row changes i
f170: 6e 20 74 68 65 0a 2a 2a 20 6d 6f 73 74 20 72 65  n the.** most re
f180: 63 65 6e 74 20 49 4e 53 45 52 54 2c 20 55 50 44  cent INSERT, UPD
f190: 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 20 73  ATE, or DELETE s
f1a0: 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20  tatement within 
f1b0: 74 68 65 20 73 61 6d 65 0a 2a 2a 20 74 72 69 67  the same.** trig
f1c0: 67 65 72 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a  ger context..**.
f1d0: 2a 2a 20 54 68 75 73 2c 20 77 68 65 6e 20 63 61  ** Thus, when ca
f1e0: 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 74 6f  lled from the to
f1f0: 70 20 6c 65 76 65 6c 2c 20 74 68 69 73 20 66 75  p level, this fu
f200: 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74  nction returns t
f210: 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20  he.** number of 
f220: 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 6d  changes in the m
f230: 6f 73 74 20 72 65 63 65 6e 74 20 49 4e 53 45 52  ost recent INSER
f240: 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45  T, UPDATE, or DE
f250: 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20 61 6c 73  LETE.** that als
f260: 6f 20 6f 63 63 75 72 72 65 64 20 61 74 20 74 68  o occurred at th
f270: 65 20 74 6f 70 20 6c 65 76 65 6c 2e 20 20 57 69  e top level.  Wi
f280: 74 68 69 6e 20 74 68 65 20 62 6f 64 79 20 6f 66  thin the body of
f290: 20 61 20 74 72 69 67 67 65 72 2c 0a 2a 2a 20 74   a trigger,.** t
f2a0: 68 65 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  he sqlite3_chang
f2b0: 65 73 28 29 20 69 6e 74 65 72 66 61 63 65 20 63  es() interface c
f2c0: 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 74 6f 20  an be called to 
f2d0: 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20  find the number 
f2e0: 6f 66 0a 2a 2a 20 63 68 61 6e 67 65 73 20 69 6e  of.** changes in
f2f0: 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
f300: 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20 49 4e 53  ly completed INS
f310: 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20  ERT, UPDATE, or 
f320: 44 45 4c 45 54 45 0a 2a 2a 20 73 74 61 74 65 6d  DELETE.** statem
f330: 65 6e 74 20 77 69 74 68 69 6e 20 74 68 65 20 62  ent within the b
f340: 6f 64 79 20 6f 66 20 74 68 65 20 73 61 6d 65 20  ody of the same 
f350: 74 72 69 67 67 65 72 2e 0a 2a 2a 20 48 6f 77 65  trigger..** Howe
f360: 76 65 72 2c 20 74 68 65 20 6e 75 6d 62 65 72 20  ver, the number 
f370: 72 65 74 75 72 6e 65 64 20 64 6f 65 73 20 6e 6f  returned does no
f380: 74 20 69 6e 63 6c 75 64 65 20 63 68 61 6e 67 65  t include change
f390: 73 0a 2a 2a 20 63 61 75 73 65 64 20 62 79 20 73  s.** caused by s
f3a0: 75 62 74 72 69 67 67 65 72 73 20 73 69 6e 63 65  ubtriggers since
f3b0: 20 74 68 6f 73 65 20 68 61 76 65 20 74 68 65 69   those have thei
f3c0: 72 20 6f 77 6e 20 63 6f 6e 74 65 78 74 2e 0a 2a  r own context..*
f3d0: 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6d 70 6c  *.** SQLite impl
f3e0: 65 6d 65 6e 74 73 20 74 68 65 20 63 6f 6d 6d 61  ements the comma
f3f0: 6e 64 20 22 44 45 4c 45 54 45 20 46 52 4f 4d 20  nd "DELETE FROM 
f400: 74 61 62 6c 65 22 20 77 69 74 68 6f 75 74 20 61  table" without a
f410: 20 57 48 45 52 45 20 63 6c 61 75 73 65 0a 2a 2a   WHERE clause.**
f420: 20 62 79 20 64 72 6f 70 70 69 6e 67 20 61 6e 64   by dropping and
f430: 20 72 65 63 72 65 61 74 69 6e 67 20 74 68 65 20   recreating the 
f440: 74 61 62 6c 65 2e 20 20 28 54 68 69 73 20 69 73  table.  (This is
f450: 20 6d 75 63 68 20 66 61 73 74 65 72 20 74 68 61   much faster tha
f460: 6e 20 67 6f 69 6e 67 0a 2a 2a 20 74 68 72 6f 75  n going.** throu
f470: 67 68 20 61 6e 64 20 64 65 6c 65 74 69 6e 67 20  gh and deleting 
f480: 69 6e 64 69 76 69 64 75 61 6c 20 65 6c 65 6d 65  individual eleme
f490: 6e 74 73 20 66 72 6f 6d 20 74 68 65 20 74 61 62  nts from the tab
f4a0: 6c 65 2e 29 20 20 42 65 63 61 75 73 65 20 6f 66  le.)  Because of
f4b0: 20 74 68 69 73 0a 2a 2a 20 6f 70 74 69 6d 69 7a   this.** optimiz
f4c0: 61 74 69 6f 6e 2c 20 74 68 65 20 64 65 6c 65 74  ation, the delet
f4d0: 69 6f 6e 73 20 69 6e 20 22 44 45 4c 45 54 45 20  ions in "DELETE 
f4e0: 46 52 4f 4d 20 74 61 62 6c 65 22 20 61 72 65 20  FROM table" are 
f4f0: 6e 6f 74 20 72 6f 77 20 63 68 61 6e 67 65 73 20  not row changes 
f500: 61 6e 64 0a 2a 2a 20 77 69 6c 6c 20 6e 6f 74 20  and.** will not 
f510: 62 65 20 63 6f 75 6e 74 65 64 20 62 79 20 74 68  be counted by th
f520: 65 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65  e sqlite3_change
f530: 73 28 29 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  s() or [sqlite3_
f540: 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d  total_changes()]
f550: 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 2c 20 72  .** functions, r
f560: 65 67 61 72 64 6c 65 73 73 20 6f 66 20 74 68 65  egardless of the
f570: 20 6e 75 6d 62 65 72 20 6f 66 20 65 6c 65 6d 65   number of eleme
f580: 6e 74 73 20 74 68 61 74 20 77 65 72 65 20 6f 72  nts that were or
f590: 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 69 6e 20 74  iginally.** in t
f5a0: 68 65 20 74 61 62 6c 65 2e 20 20 54 6f 20 67 65  he table.  To ge
f5b0: 74 20 61 6e 20 61 63 63 75 72 61 74 65 20 63 6f  t an accurate co
f5c0: 75 6e 74 20 6f 66 20 74 68 65 20 6e 75 6d 62 65  unt of the numbe
f5d0: 72 20 6f 66 20 72 6f 77 73 20 64 65 6c 65 74 65  r of rows delete
f5e0: 64 2c 20 75 73 65 0a 2a 2a 20 22 44 45 4c 45 54  d, use.** "DELET
f5f0: 45 20 46 52 4f 4d 20 74 61 62 6c 65 20 57 48 45  E FROM table WHE
f600: 52 45 20 31 22 20 69 6e 73 74 65 61 64 2e 0a 2a  RE 1" instead..*
f610: 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
f620: 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 34 31 7d 20  .**.** {H12241} 
f630: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61  The [sqlite3_cha
f640: 6e 67 65 73 28 29 5d 20 66 75 6e 63 74 69 6f 6e  nges()] function
f650: 20 73 68 61 6c 6c 20 72 65 74 75 72 6e 20 74 68   shall return th
f660: 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 20  e number of.**  
f670: 20 20 20 20 20 20 20 20 72 6f 77 20 63 68 61 6e          row chan
f680: 67 65 73 20 63 61 75 73 65 64 20 62 79 20 74 68  ges caused by th
f690: 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 49 4e  e most recent IN
f6a0: 53 45 52 54 2c 20 55 50 44 41 54 45 2c 0a 2a 2a  SERT, UPDATE,.**
f6b0: 20 20 20 20 20 20 20 20 20 20 6f 72 20 44 45 4c            or DEL
f6c0: 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20 6f 6e  ETE statement on
f6d0: 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61   the same databa
f6e0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 61 6e  se connection an
f6f0: 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 69  d.**          wi
f700: 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20 6f 72  thin the same or
f710: 20 68 69 67 68 65 72 20 74 72 69 67 67 65 72 20   higher trigger 
f720: 63 6f 6e 74 65 78 74 2c 20 6f 72 20 7a 65 72 6f  context, or zero
f730: 20 69 66 20 74 68 65 72 65 20 68 61 76 65 0a 2a   if there have.*
f740: 2a 20 20 20 20 20 20 20 20 20 20 6e 6f 74 20 62  *          not b
f750: 65 65 6e 20 61 6e 79 20 71 75 61 6c 69 66 79 69  een any qualifyi
f760: 6e 67 20 72 6f 77 20 63 68 61 6e 67 65 73 2e 0a  ng row changes..
f770: 2a 2a 0a 2a 2a 20 7b 48 31 32 32 34 33 7d 20 53  **.** {H12243} S
f780: 74 61 74 65 6d 65 6e 74 73 20 6f 66 20 74 68 65  tatements of the
f790: 20 66 6f 72 6d 20 22 44 45 4c 45 54 45 20 46 52   form "DELETE FR
f7a0: 4f 4d 20 74 61 62 6c 65 6e 61 6d 65 22 20 77 69  OM tablename" wi
f7b0: 74 68 20 6e 6f 0a 2a 2a 20 20 20 20 20 20 20 20  th no.**        
f7c0: 20 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 73    WHERE clause s
f7d0: 68 61 6c 6c 20 63 61 75 73 65 20 73 75 62 73 65  hall cause subse
f7e0: 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 0a 2a  quent calls to.*
f7f0: 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
f800: 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 74  te3_changes()] t
f810: 6f 20 72 65 74 75 72 6e 20 7a 65 72 6f 2c 20 72  o return zero, r
f820: 65 67 61 72 64 6c 65 73 73 20 6f 66 20 74 68 65  egardless of the
f830: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 75 6d  .**          num
f840: 62 65 72 20 6f 66 20 72 6f 77 73 20 6f 72 69 67  ber of rows orig
f850: 69 6e 61 6c 6c 79 20 69 6e 20 74 68 65 20 74 61  inally in the ta
f860: 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 41 53 53 55 4d  ble..**.** ASSUM
f870: 50 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 41  PTIONS:.**.** {A
f880: 31 32 32 35 32 7d 20 49 66 20 61 20 73 65 70 61  12252} If a sepa
f890: 72 61 74 65 20 74 68 72 65 61 64 20 6d 61 6b 65  rate thread make
f8a0: 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65  s changes on the
f8b0: 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63   same database c
f8c0: 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 20 20 20  onnection.**    
f8d0: 20 20 20 20 20 20 77 68 69 6c 65 20 5b 73 71 6c        while [sql
f8e0: 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20  ite3_changes()] 
f8f0: 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20  is running then 
f900: 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
f910: 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  ed.**          i
f920: 73 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20  s unpredictable 
f930: 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66  and not meaningf
f940: 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ul..*/.int sqlit
f950: 65 33 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 74  e3_changes(sqlit
f960: 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  e3*);../*.** CAP
f970: 49 33 52 45 46 3a 20 54 6f 74 61 6c 20 4e 75 6d  I3REF: Total Num
f980: 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69  ber Of Rows Modi
f990: 66 69 65 64 20 7b 48 31 32 32 36 30 7d 20 3c 53  fied {H12260} <S
f9a0: 31 30 36 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69  10600>.**.** Thi
f9b0: 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  s function retur
f9c0: 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
f9d0: 20 72 6f 77 20 63 68 61 6e 67 65 73 20 63 61 75   row changes cau
f9e0: 73 65 64 20 62 79 20 49 4e 53 45 52 54 2c 0a 2a  sed by INSERT,.*
f9f0: 2a 20 55 50 44 41 54 45 20 6f 72 20 44 45 4c 45  * UPDATE or DELE
fa00: 54 45 20 73 74 61 74 65 6d 65 6e 74 73 20 73 69  TE statements si
fa10: 6e 63 65 20 74 68 65 20 5b 64 61 74 61 62 61 73  nce the [databas
fa20: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 61  e connection] wa
fa30: 73 20 6f 70 65 6e 65 64 2e 0a 2a 2a 20 54 68 65  s opened..** The
fa40: 20 63 6f 75 6e 74 20 69 6e 63 6c 75 64 65 73 20   count includes 
fa50: 61 6c 6c 20 63 68 61 6e 67 65 73 20 66 72 6f 6d  all changes from
fa60: 20 61 6c 6c 20 74 72 69 67 67 65 72 20 63 6f 6e   all trigger con
fa70: 74 65 78 74 73 2e 20 20 48 6f 77 65 76 65 72 2c  texts.  However,
fa80: 0a 2a 2a 20 74 68 65 20 63 6f 75 6e 74 20 64 6f  .** the count do
fa90: 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 63  es not include c
faa0: 68 61 6e 67 65 73 20 75 73 65 64 20 74 6f 20 69  hanges used to i
fab0: 6d 70 6c 65 6d 65 6e 74 20 52 45 50 4c 41 43 45  mplement REPLACE
fac0: 20 63 6f 6e 73 74 72 61 69 6e 74 73 2c 0a 2a 2a   constraints,.**
fad0: 20 64 6f 20 72 6f 6c 6c 62 61 63 6b 73 20 6f 72   do rollbacks or
fae0: 20 41 42 4f 52 54 20 70 72 6f 63 65 73 73 69 6e   ABORT processin
faf0: 67 2c 20 6f 72 20 44 52 4f 50 20 74 61 62 6c 65  g, or DROP table
fb00: 20 70 72 6f 63 65 73 73 69 6e 67 2e 0a 2a 2a 20   processing..** 
fb10: 54 68 65 20 63 68 61 6e 67 65 73 20 61 72 65 20  The changes are 
fb20: 63 6f 75 6e 74 65 64 20 61 73 20 73 6f 6f 6e 20  counted as soon 
fb30: 61 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  as the statement
fb40: 20 74 68 61 74 20 6d 61 6b 65 73 20 74 68 65 6d   that makes them
fb50: 20 69 73 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 64   is.** completed
fb60: 20 28 77 68 65 6e 20 74 68 65 20 73 74 61 74 65   (when the state
fb70: 6d 65 6e 74 20 68 61 6e 64 6c 65 20 69 73 20 70  ment handle is p
fb80: 61 73 73 65 64 20 74 6f 20 5b 73 71 6c 69 74 65  assed to [sqlite
fb90: 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a  3_reset()] or.**
fba0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
fbb0: 7a 65 28 29 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 51  ze()])..**.** SQ
fbc0: 4c 69 74 65 20 69 6d 70 6c 65 6d 65 6e 74 73 20  Lite implements 
fbd0: 74 68 65 20 63 6f 6d 6d 61 6e 64 20 22 44 45 4c  the command "DEL
fbe0: 45 54 45 20 46 52 4f 4d 20 74 61 62 6c 65 22 20  ETE FROM table" 
fbf0: 77 69 74 68 6f 75 74 20 61 20 57 48 45 52 45 20  without a WHERE 
fc00: 63 6c 61 75 73 65 0a 2a 2a 20 62 79 20 64 72 6f  clause.** by dro
fc10: 70 70 69 6e 67 20 61 6e 64 20 72 65 63 72 65 61  pping and recrea
fc20: 74 69 6e 67 20 74 68 65 20 74 61 62 6c 65 2e 20  ting the table. 
fc30: 20 28 54 68 69 73 20 69 73 20 6d 75 63 68 20 66   (This is much f
fc40: 61 73 74 65 72 20 74 68 61 6e 20 67 6f 69 6e 67  aster than going
fc50: 0a 2a 2a 20 74 68 72 6f 75 67 68 20 61 6e 64 20  .** through and 
fc60: 64 65 6c 65 74 69 6e 67 20 69 6e 64 69 76 69 64  deleting individ
fc70: 75 61 6c 20 65 6c 65 6d 65 6e 74 73 20 66 72 6f  ual elements fro
fc80: 6d 20 74 68 65 20 74 61 62 6c 65 2e 29 20 20 42  m the table.)  B
fc90: 65 63 61 75 73 65 20 6f 66 20 74 68 69 73 0a 2a  ecause of this.*
fca0: 2a 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 2c 20  * optimization, 
fcb0: 74 68 65 20 64 65 6c 65 74 69 6f 6e 73 20 69 6e  the deletions in
fcc0: 20 22 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 61   "DELETE FROM ta
fcd0: 62 6c 65 22 20 61 72 65 20 6e 6f 74 20 72 6f 77  ble" are not row
fce0: 20 63 68 61 6e 67 65 73 20 61 6e 64 0a 2a 2a 20   changes and.** 
fcf0: 77 69 6c 6c 20 6e 6f 74 20 62 65 20 63 6f 75 6e  will not be coun
fd00: 74 65 64 20 62 79 20 74 68 65 20 73 71 6c 69 74  ted by the sqlit
fd10: 65 33 5f 63 68 61 6e 67 65 73 28 29 20 6f 72 20  e3_changes() or 
fd20: 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63  [sqlite3_total_c
fd30: 68 61 6e 67 65 73 28 29 5d 0a 2a 2a 20 66 75 6e  hanges()].** fun
fd40: 63 74 69 6f 6e 73 2c 20 72 65 67 61 72 64 6c 65  ctions, regardle
fd50: 73 73 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72  ss of the number
fd60: 20 6f 66 20 65 6c 65 6d 65 6e 74 73 20 74 68 61   of elements tha
fd70: 74 20 77 65 72 65 20 6f 72 69 67 69 6e 61 6c 6c  t were originall
fd80: 79 0a 2a 2a 20 69 6e 20 74 68 65 20 74 61 62 6c  y.** in the tabl
fd90: 65 2e 20 20 54 6f 20 67 65 74 20 61 6e 20 61 63  e.  To get an ac
fda0: 63 75 72 61 74 65 20 63 6f 75 6e 74 20 6f 66 20  curate count of 
fdb0: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f  the number of ro
fdc0: 77 73 20 64 65 6c 65 74 65 64 2c 20 75 73 65 0a  ws deleted, use.
fdd0: 2a 2a 20 22 44 45 4c 45 54 45 20 46 52 4f 4d 20  ** "DELETE FROM 
fde0: 74 61 62 6c 65 20 57 48 45 52 45 20 31 22 20 69  table WHERE 1" i
fdf0: 6e 73 74 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 53 65  nstead..**.** Se
fe00: 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69  e also the [sqli
fe10: 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 69  te3_changes()] i
fe20: 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  nterface..**.** 
fe30: 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
fe40: 2a 20 7b 48 31 32 32 36 31 7d 20 54 68 65 20 5b  * {H12261} The [
fe50: 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68  sqlite3_total_ch
fe60: 61 6e 67 65 73 28 29 5d 20 72 65 74 75 72 6e 73  anges()] returns
fe70: 20 74 68 65 20 74 6f 74 61 6c 20 6e 75 6d 62 65   the total numbe
fe80: 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66  r.**          of
fe90: 20 72 6f 77 20 63 68 61 6e 67 65 73 20 63 61 75   row changes cau
fea0: 73 65 64 20 62 79 20 49 4e 53 45 52 54 2c 20 55  sed by INSERT, U
feb0: 50 44 41 54 45 2c 20 61 6e 64 2f 6f 72 20 44 45  PDATE, and/or DE
fec0: 4c 45 54 45 0a 2a 2a 20 20 20 20 20 20 20 20 20  LETE.**         
fed0: 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 6e 20 74   statements on t
fee0: 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73  he same [databas
fef0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20 69  e connection], i
ff00: 6e 20 61 6e 79 0a 2a 2a 20 20 20 20 20 20 20 20  n any.**        
ff10: 20 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78    trigger contex
ff20: 74 2c 20 73 69 6e 63 65 20 74 68 65 20 64 61 74  t, since the dat
ff30: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
ff40: 20 77 61 73 20 63 72 65 61 74 65 64 2e 0a 2a 2a   was created..**
ff50: 0a 2a 2a 20 7b 48 31 32 32 36 33 7d 20 53 74 61  .** {H12263} Sta
ff60: 74 65 6d 65 6e 74 73 20 6f 66 20 74 68 65 20 66  tements of the f
ff70: 6f 72 6d 20 22 44 45 4c 45 54 45 20 46 52 4f 4d  orm "DELETE FROM
ff80: 20 74 61 62 6c 65 6e 61 6d 65 22 20 77 69 74 68   tablename" with
ff90: 20 6e 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   no.**          
ffa0: 57 48 45 52 45 20 63 6c 61 75 73 65 20 73 68 61  WHERE clause sha
ffb0: 6c 6c 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68  ll not change th
ffc0: 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
ffd0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 79 20  .**          by 
ffe0: 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63  [sqlite3_total_c
fff0: 68 61 6e 67 65 73 28 29 5d 2e 0a 2a 2a 0a 2a 2a  hanges()]..**.**
10000 20 41 53 53 55 4d 50 54 49 4f 4e 53 3a 0a 2a 2a   ASSUMPTIONS:.**
10010 0a 2a 2a 20 7b 41 31 32 32 36 34 7d 20 49 66 20  .** {A12264} If 
10020 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61  a separate threa
10030 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20  d makes changes 
10040 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74 61  on the same data
10050 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a  base connection.
10060 2a 2a 20 20 20 20 20 20 20 20 20 20 77 68 69 6c  **          whil
10070 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c  e [sqlite3_total
10080 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 73 20 72  _changes()] is r
10090 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 20  unning then the 
100a0 76 61 6c 75 65 0a 2a 2a 20 20 20 20 20 20 20 20  value.**        
100b0 20 20 72 65 74 75 72 6e 65 64 20 69 73 20 75 6e    returned is un
100c0 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20  predictable and 
100d0 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a  not meaningful..
100e0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 74  */.int sqlite3_t
100f0 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 73 71 6c  otal_changes(sql
10100 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ite3*);../*.** C
10110 41 50 49 33 52 45 46 3a 20 49 6e 74 65 72 72 75  API3REF: Interru
10120 70 74 20 41 20 4c 6f 6e 67 2d 52 75 6e 6e 69 6e  pt A Long-Runnin
10130 67 20 51 75 65 72 79 20 7b 48 31 32 32 37 30 7d  g Query {H12270}
10140 20 3c 53 33 30 35 30 30 3e 0a 2a 2a 0a 2a 2a 20   <S30500>.**.** 
10150 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 63 61  This function ca
10160 75 73 65 73 20 61 6e 79 20 70 65 6e 64 69 6e 67  uses any pending
10170 20 64 61 74 61 62 61 73 65 20 6f 70 65 72 61 74   database operat
10180 69 6f 6e 20 74 6f 20 61 62 6f 72 74 20 61 6e 64  ion to abort and
10190 0a 2a 2a 20 72 65 74 75 72 6e 20 61 74 20 69 74  .** return at it
101a0 73 20 65 61 72 6c 69 65 73 74 20 6f 70 70 6f 72  s earliest oppor
101b0 74 75 6e 69 74 79 2e 20 54 68 69 73 20 72 6f 75  tunity. This rou
101c0 74 69 6e 65 20 69 73 20 74 79 70 69 63 61 6c 6c  tine is typicall
101d0 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 69 6e 20 72  y.** called in r
101e0 65 73 70 6f 6e 73 65 20 74 6f 20 61 20 75 73 65  esponse to a use
101f0 72 20 61 63 74 69 6f 6e 20 73 75 63 68 20 61 73  r action such as
10200 20 70 72 65 73 73 69 6e 67 20 22 43 61 6e 63 65   pressing "Cance
10210 6c 22 0a 2a 2a 20 6f 72 20 43 74 72 6c 2d 43 20  l".** or Ctrl-C 
10220 77 68 65 72 65 20 74 68 65 20 75 73 65 72 20 77  where the user w
10230 61 6e 74 73 20 61 20 6c 6f 6e 67 20 71 75 65 72  ants a long quer
10240 79 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 68  y operation to h
10250 61 6c 74 0a 2a 2a 20 69 6d 6d 65 64 69 61 74 65  alt.** immediate
10260 6c 79 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73 20  ly..**.** It is 
10270 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69  safe to call thi
10280 73 20 72 6f 75 74 69 6e 65 20 66 72 6f 6d 20 61  s routine from a
10290 20 74 68 72 65 61 64 20 64 69 66 66 65 72 65 6e   thread differen
102a0 74 20 66 72 6f 6d 20 74 68 65 0a 2a 2a 20 74 68  t from the.** th
102b0 72 65 61 64 20 74 68 61 74 20 69 73 20 63 75 72  read that is cur
102c0 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 20 74  rently running t
102d0 68 65 20 64 61 74 61 62 61 73 65 20 6f 70 65 72  he database oper
102e0 61 74 69 6f 6e 2e 20 20 42 75 74 20 69 74 0a 2a  ation.  But it.*
102f0 2a 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f  * is not safe to
10300 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69   call this routi
10310 6e 65 20 77 69 74 68 20 61 20 5b 64 61 74 61 62  ne with a [datab
10320 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
10330 74 68 61 74 0a 2a 2a 20 69 73 20 63 6c 6f 73 65  that.** is close
10340 64 20 6f 72 20 6d 69 67 68 74 20 63 6c 6f 73 65  d or might close
10350 20 62 65 66 6f 72 65 20 73 71 6c 69 74 65 33 5f   before sqlite3_
10360 69 6e 74 65 72 72 75 70 74 28 29 20 72 65 74 75  interrupt() retu
10370 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e  rns..**.** If an
10380 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69   SQL operation i
10390 73 20 76 65 72 79 20 6e 65 61 72 6c 79 20 66 69  s very nearly fi
103a0 6e 69 73 68 65 64 20 61 74 20 74 68 65 20 74 69  nished at the ti
103b0 6d 65 20 77 68 65 6e 0a 2a 2a 20 73 71 6c 69 74  me when.** sqlit
103c0 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 69  e3_interrupt() i
103d0 73 20 63 61 6c 6c 65 64 2c 20 74 68 65 6e 20 69  s called, then i
103e0 74 20 6d 69 67 68 74 20 6e 6f 74 20 68 61 76 65  t might not have
103f0 20 61 6e 20 6f 70 70 6f 72 74 75 6e 69 74 79 0a   an opportunity.
10400 2a 2a 20 74 6f 20 62 65 20 69 6e 74 65 72 72 75  ** to be interru
10410 70 74 65 64 20 61 6e 64 20 6d 69 67 68 74 20 63  pted and might c
10420 6f 6e 74 69 6e 75 65 20 74 6f 20 63 6f 6d 70 6c  ontinue to compl
10430 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20  etion..**.** An 
10440 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 74 68  SQL operation th
10450 61 74 20 69 73 20 69 6e 74 65 72 72 75 70 74 65  at is interrupte
10460 64 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53  d will return [S
10470 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d  QLITE_INTERRUPT]
10480 2e 0a 2a 2a 20 49 66 20 74 68 65 20 69 6e 74 65  ..** If the inte
10490 72 72 75 70 74 65 64 20 53 51 4c 20 6f 70 65 72  rrupted SQL oper
104a0 61 74 69 6f 6e 20 69 73 20 61 6e 20 49 4e 53 45  ation is an INSE
104b0 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44  RT, UPDATE, or D
104c0 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20 69 73  ELETE.** that is
104d0 20 69 6e 73 69 64 65 20 61 6e 20 65 78 70 6c 69   inside an expli
104e0 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c  cit transaction,
104f0 20 74 68 65 6e 20 74 68 65 20 65 6e 74 69 72 65   then the entire
10500 20 74 72 61 6e 73 61 63 74 69 6f 6e 0a 2a 2a 20   transaction.** 
10510 77 69 6c 6c 20 62 65 20 72 6f 6c 6c 65 64 20 62  will be rolled b
10520 61 63 6b 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  ack automaticall
10530 79 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20  y..**.** A call 
10540 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  to sqlite3_inter
10550 72 75 70 74 28 29 20 68 61 73 20 6e 6f 20 65 66  rupt() has no ef
10560 66 65 63 74 20 6f 6e 20 53 51 4c 20 73 74 61 74  fect on SQL stat
10570 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61  ements.** that a
10580 72 65 20 73 74 61 72 74 65 64 20 61 66 74 65 72  re started after
10590 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
105a0 70 74 28 29 20 72 65 74 75 72 6e 73 2e 0a 2a 2a  pt() returns..**
105b0 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
105c0 2a 2a 0a 2a 2a 20 7b 48 31 32 32 37 31 7d 20 54  **.** {H12271} T
105d0 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65  he [sqlite3_inte
105e0 72 72 75 70 74 28 29 5d 20 69 6e 74 65 72 66 61  rrupt()] interfa
105f0 63 65 20 77 69 6c 6c 20 66 6f 72 63 65 20 61 6c  ce will force al
10600 6c 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 20 20 20  l running.**    
10610 20 20 20 20 20 20 53 51 4c 20 73 74 61 74 65 6d        SQL statem
10620 65 6e 74 73 20 61 73 73 6f 63 69 61 74 65 64 20  ents associated 
10630 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 64 61  with the same da
10640 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
10650 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f  n.**          to
10660 20 68 61 6c 74 20 61 66 74 65 72 20 70 72 6f 63   halt after proc
10670 65 73 73 69 6e 67 20 61 74 20 6d 6f 73 74 20 6f  essing at most o
10680 6e 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 72 6f  ne additional ro
10690 77 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a  w of data..**.**
106a0 20 7b 48 31 32 32 37 32 7d 20 41 6e 79 20 53 51   {H12272} Any SQ
106b0 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74  L statement that
106c0 20 69 73 20 69 6e 74 65 72 72 75 70 74 65 64 20   is interrupted 
106d0 62 79 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65  by [sqlite3_inte
106e0 72 72 75 70 74 28 29 5d 0a 2a 2a 20 20 20 20 20  rrupt()].**     
106f0 20 20 20 20 20 77 69 6c 6c 20 72 65 74 75 72 6e       will return
10700 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55   [SQLITE_INTERRU
10710 50 54 5d 2e 0a 2a 2a 0a 2a 2a 20 41 53 53 55 4d  PT]..**.** ASSUM
10720 50 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 41  PTIONS:.**.** {A
10730 31 32 32 37 39 7d 20 49 66 20 74 68 65 20 64 61  12279} If the da
10740 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
10750 6e 20 63 6c 6f 73 65 73 20 77 68 69 6c 65 20 5b  n closes while [
10760 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
10770 74 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  t()].**         
10780 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e   is running then
10790 20 62 61 64 20 74 68 69 6e 67 73 20 77 69 6c 6c   bad things will
107a0 20 6c 69 6b 65 6c 79 20 68 61 70 70 65 6e 2e 0a   likely happen..
107b0 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  */.void sqlite3_
107c0 69 6e 74 65 72 72 75 70 74 28 73 71 6c 69 74 65  interrupt(sqlite
107d0 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  3*);../*.** CAPI
107e0 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20  3REF: Determine 
107f0 49 66 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d  If An SQL Statem
10800 65 6e 74 20 49 73 20 43 6f 6d 70 6c 65 74 65 20  ent Is Complete 
10810 7b 48 31 30 35 31 30 7d 20 3c 53 37 30 32 30 30  {H10510} <S70200
10820 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  >.**.** These ro
10830 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 66 75  utines are usefu
10840 6c 20 66 6f 72 20 63 6f 6d 6d 61 6e 64 2d 6c 69  l for command-li
10850 6e 65 20 69 6e 70 75 74 20 74 6f 20 64 65 74 65  ne input to dete
10860 72 6d 69 6e 65 20 69 66 20 74 68 65 0a 2a 2a 20  rmine if the.** 
10870 63 75 72 72 65 6e 74 6c 79 20 65 6e 74 65 72 65  currently entere
10880 64 20 74 65 78 74 20 73 65 65 6d 73 20 74 6f 20  d text seems to 
10890 66 6f 72 6d 20 63 6f 6d 70 6c 65 74 65 20 61 20  form complete a 
108a0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 6f 72  SQL statement or
108b0 0a 2a 2a 20 69 66 20 61 64 64 69 74 69 6f 6e 61  .** if additiona
108c0 6c 20 69 6e 70 75 74 20 69 73 20 6e 65 65 64 65  l input is neede
108d0 64 20 62 65 66 6f 72 65 20 73 65 6e 64 69 6e 67  d before sending
108e0 20 74 68 65 20 74 65 78 74 20 69 6e 74 6f 0a 2a   the text into.*
108f0 2a 20 53 51 4c 69 74 65 20 66 6f 72 20 70 61 72  * SQLite for par
10900 73 69 6e 67 2e 20 20 54 68 65 73 65 20 72 6f 75  sing.  These rou
10910 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 72 75  tines return tru
10920 65 20 69 66 20 74 68 65 20 69 6e 70 75 74 20 73  e if the input s
10930 74 72 69 6e 67 0a 2a 2a 20 61 70 70 65 61 72 73  tring.** appears
10940 20 74 6f 20 62 65 20 61 20 63 6f 6d 70 6c 65 74   to be a complet
10950 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e  e SQL statement.
10960 20 20 41 20 73 74 61 74 65 6d 65 6e 74 20 69 73    A statement is
10970 20 6a 75 64 67 65 64 20 74 6f 20 62 65 0a 2a 2a   judged to be.**
10980 20 63 6f 6d 70 6c 65 74 65 20 69 66 20 69 74 20   complete if it 
10990 65 6e 64 73 20 77 69 74 68 20 61 20 73 65 6d 69  ends with a semi
109a0 63 6f 6c 6f 6e 20 74 6f 6b 65 6e 20 61 6e 64 20  colon token and 
109b0 69 73 20 6e 6f 74 20 61 20 66 72 61 67 6d 65 6e  is not a fragmen
109c0 74 20 6f 66 20 61 0a 2a 2a 20 43 52 45 41 54 45  t of a.** CREATE
109d0 20 54 52 49 47 47 45 52 20 73 74 61 74 65 6d 65   TRIGGER stateme
109e0 6e 74 2e 20 20 53 65 6d 69 63 6f 6c 6f 6e 73 20  nt.  Semicolons 
109f0 74 68 61 74 20 61 72 65 20 65 6d 62 65 64 64 65  that are embedde
10a00 64 20 77 69 74 68 69 6e 0a 2a 2a 20 73 74 72 69  d within.** stri
10a10 6e 67 20 6c 69 74 65 72 61 6c 73 20 6f 72 20 71  ng literals or q
10a20 75 6f 74 65 64 20 69 64 65 6e 74 69 66 69 65 72  uoted identifier
10a30 20 6e 61 6d 65 73 20 6f 72 20 63 6f 6d 6d 65 6e   names or commen
10a40 74 73 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 69 6e  ts are not.** in
10a50 64 65 70 65 6e 64 65 6e 74 20 74 6f 6b 65 6e 73  dependent tokens
10a60 20 28 74 68 65 79 20 61 72 65 20 70 61 72 74 20   (they are part 
10a70 6f 66 20 74 68 65 20 74 6f 6b 65 6e 20 69 6e 20  of the token in 
10a80 77 68 69 63 68 20 74 68 65 79 20 61 72 65 0a 2a  which they are.*
10a90 2a 20 65 6d 62 65 64 64 65 64 29 20 61 6e 64 20  * embedded) and 
10aa0 74 68 75 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e  thus do not coun
10ab0 74 20 61 73 20 61 20 73 74 61 74 65 6d 65 6e 74  t as a statement
10ac0 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 0a   terminator..**.
10ad0 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
10ae0 73 20 64 6f 20 6e 6f 74 20 70 61 72 73 65 20 74  s do not parse t
10af0 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
10b00 73 20 74 68 75 73 0a 2a 2a 20 77 69 6c 6c 20 6e  s thus.** will n
10b10 6f 74 20 64 65 74 65 63 74 20 73 79 6e 74 61 63  ot detect syntac
10b20 74 69 63 61 6c 6c 79 20 69 6e 63 6f 72 72 65 63  tically incorrec
10b30 74 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56  t SQL..**.** INV
10b40 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
10b50 48 31 30 35 31 31 7d 20 41 20 73 75 63 63 65 73  H10511} A succes
10b60 73 66 75 6c 20 65 76 61 6c 75 61 74 69 6f 6e 20  sful evaluation 
10b70 6f 66 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70  of [sqlite3_comp
10b80 6c 65 74 65 28 29 5d 20 6f 72 0a 2a 2a 20 20 20  lete()] or.**   
10b90 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
10ba0 63 6f 6d 70 6c 65 74 65 31 36 28 29 5d 20 66 75  complete16()] fu
10bb0 6e 63 74 69 6f 6e 73 20 73 68 61 6c 6c 0a 2a 2a  nctions shall.**
10bc0 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e            return
10bd0 20 61 20 6e 75 6d 65 72 69 63 20 31 20 69 66 20   a numeric 1 if 
10be0 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68 65 20  and only if the 
10bf0 6c 61 73 74 20 6e 6f 6e 2d 77 68 69 74 65 73 70  last non-whitesp
10c00 61 63 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ace.**          
10c10 74 6f 6b 65 6e 20 69 6e 20 74 68 65 69 72 20 69  token in their i
10c20 6e 70 75 74 20 69 73 20 61 20 73 65 6d 69 63 6f  nput is a semico
10c30 6c 6f 6e 20 74 68 61 74 20 69 73 20 6e 6f 74 20  lon that is not 
10c40 69 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 20 20  in between.**   
10c50 20 20 20 20 20 20 20 74 68 65 20 42 45 47 49 4e         the BEGIN
10c60 20 61 6e 64 20 45 4e 44 20 6f 66 20 61 20 43 52   and END of a CR
10c70 45 41 54 45 20 54 52 49 47 47 45 52 20 73 74 61  EATE TRIGGER sta
10c80 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48  tement..**.** {H
10c90 31 30 35 31 32 7d 20 49 66 20 61 20 6d 65 6d 6f  10512} If a memo
10ca0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72  ry allocation er
10cb0 72 6f 72 20 6f 63 63 75 72 73 20 64 75 72 69 6e  ror occurs durin
10cc0 67 20 61 6e 20 69 6e 76 6f 63 61 74 69 6f 6e 0a  g an invocation.
10cd0 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20 5b  **          of [
10ce0 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
10cf0 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
10d00 63 6f 6d 70 6c 65 74 65 31 36 28 29 5d 20 74 68  complete16()] th
10d10 65 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  en the.**       
10d20 20 20 20 72 6f 75 74 69 6e 65 20 73 68 61 6c 6c     routine shall
10d30 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
10d40 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 41 53  NOMEM]..**.** AS
10d50 53 55 4d 50 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a  SUMPTIONS:.**.**
10d60 20 7b 41 31 30 35 31 32 7d 20 54 68 65 20 69 6e   {A10512} The in
10d70 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  put to [sqlite3_
10d80 63 6f 6d 70 6c 65 74 65 28 29 5d 20 6d 75 73 74  complete()] must
10d90 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69   be a zero-termi
10da0 6e 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 20 20  nated.**        
10db0 20 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2e 0a    UTF-8 string..
10dc0 2a 2a 0a 2a 2a 20 7b 41 31 30 35 31 33 7d 20 54  **.** {A10513} T
10dd0 68 65 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c  he input to [sql
10de0 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28  ite3_complete16(
10df0 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 65 72  )] must be a zer
10e00 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20  o-terminated.** 
10e10 20 20 20 20 20 20 20 20 20 55 54 46 2d 31 36 20           UTF-16 
10e20 73 74 72 69 6e 67 20 69 6e 20 6e 61 74 69 76 65  string in native
10e30 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2f 0a   byte order..*/.
10e40 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  int sqlite3_comp
10e50 6c 65 74 65 28 63 6f 6e 73 74 20 63 68 61 72 20  lete(const char 
10e60 2a 73 71 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74  *sql);.int sqlit
10e70 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 63 6f  e3_complete16(co
10e80 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 29 3b 0a  nst void *sql);.
10e90 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
10ea0 20 52 65 67 69 73 74 65 72 20 41 20 43 61 6c 6c   Register A Call
10eb0 62 61 63 6b 20 54 6f 20 48 61 6e 64 6c 65 20 53  back To Handle S
10ec0 51 4c 49 54 45 5f 42 55 53 59 20 45 72 72 6f 72  QLITE_BUSY Error
10ed0 73 20 7b 48 31 32 33 31 30 7d 20 3c 53 34 30 34  s {H12310} <S404
10ee0 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72  00>.**.** This r
10ef0 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20 63 61  outine sets a ca
10f00 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
10f10 74 68 61 74 20 6d 69 67 68 74 20 62 65 20 69 6e  that might be in
10f20 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 0a 2a  voked whenever.*
10f30 2a 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73 20  * an attempt is 
10f40 6d 61 64 65 20 74 6f 20 6f 70 65 6e 20 61 20 64  made to open a d
10f50 61 74 61 62 61 73 65 20 74 61 62 6c 65 20 74 68  atabase table th
10f60 61 74 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61  at another threa
10f70 64 0a 2a 2a 20 6f 72 20 70 72 6f 63 65 73 73 20  d.** or process 
10f80 68 61 73 20 6c 6f 63 6b 65 64 2e 0a 2a 2a 0a 2a  has locked..**.*
10f90 2a 20 49 66 20 74 68 65 20 62 75 73 79 20 63 61  * If the busy ca
10fa0 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2c 20  llback is NULL, 
10fb0 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53  then [SQLITE_BUS
10fc0 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f  Y] or [SQLITE_IO
10fd0 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20  ERR_BLOCKED].** 
10fe0 69 73 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65  is returned imme
10ff0 64 69 61 74 65 6c 79 20 75 70 6f 6e 20 65 6e 63  diately upon enc
11000 6f 75 6e 74 65 72 69 6e 67 20 74 68 65 20 6c 6f  ountering the lo
11010 63 6b 2e 20 49 66 20 74 68 65 20 62 75 73 79 20  ck. If the busy 
11020 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 6e  callback.** is n
11030 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68  ot NULL, then th
11040 65 20 63 61 6c 6c 62 61 63 6b 20 77 69 6c 6c 20  e callback will 
11050 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20  be invoked with 
11060 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a  two arguments..*
11070 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61  *.** The first a
11080 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 68  rgument to the h
11090 61 6e 64 6c 65 72 20 69 73 20 61 20 63 6f 70 79  andler is a copy
110a0 20 6f 66 20 74 68 65 20 76 6f 69 64 2a 20 70 6f   of the void* po
110b0 69 6e 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69  inter which.** i
110c0 73 20 74 68 65 20 74 68 69 72 64 20 61 72 67 75  s the third argu
110d0 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
110e0 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 2e 20  busy_handler(). 
110f0 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   The second argu
11100 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74 68 65 20 68  ment to.** the h
11110 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20  andler callback 
11120 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  is the number of
11130 20 74 69 6d 65 73 20 74 68 61 74 20 74 68 65 20   times that the 
11140 62 75 73 79 20 68 61 6e 64 6c 65 72 20 68 61 73  busy handler has
11150 0a 2a 2a 20 62 65 65 6e 20 69 6e 76 6f 6b 65 64  .** been invoked
11160 20 66 6f 72 20 74 68 69 73 20 6c 6f 63 6b 69 6e   for this lockin
11170 67 20 65 76 65 6e 74 2e 20 20 49 66 20 74 68 65  g event.  If the
11180 0a 2a 2a 20 62 75 73 79 20 63 61 6c 6c 62 61 63  .** busy callbac
11190 6b 20 72 65 74 75 72 6e 73 20 30 2c 20 74 68 65  k returns 0, the
111a0 6e 20 6e 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20  n no additional 
111b0 61 74 74 65 6d 70 74 73 20 61 72 65 20 6d 61 64  attempts are mad
111c0 65 20 74 6f 0a 2a 2a 20 61 63 63 65 73 73 20 74  e to.** access t
111d0 68 65 20 64 61 74 61 62 61 73 65 20 61 6e 64 20  he database and 
111e0 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72  [SQLITE_BUSY] or
111f0 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42   [SQLITE_IOERR_B
11200 4c 4f 43 4b 45 44 5d 20 69 73 20 72 65 74 75 72  LOCKED] is retur
11210 6e 65 64 2e 0a 2a 2a 20 49 66 20 74 68 65 20 63  ned..** If the c
11220 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
11230 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 61  non-zero, then a
11240 6e 6f 74 68 65 72 20 61 74 74 65 6d 70 74 0a 2a  nother attempt.*
11250 2a 20 69 73 20 6d 61 64 65 20 74 6f 20 6f 70 65  * is made to ope
11260 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  n the database f
11270 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 74  or reading and t
11280 68 65 20 63 79 63 6c 65 20 72 65 70 65 61 74 73  he cycle repeats
11290 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 65 73  ..**.** The pres
112a0 65 6e 63 65 20 6f 66 20 61 20 62 75 73 79 20 68  ence of a busy h
112b0 61 6e 64 6c 65 72 20 64 6f 65 73 20 6e 6f 74 20  andler does not 
112c0 67 75 61 72 61 6e 74 65 65 20 74 68 61 74 20 69  guarantee that i
112d0 74 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65  t will be invoke
112e0 64 0a 2a 2a 20 77 68 65 6e 20 74 68 65 72 65 20  d.** when there 
112f0 69 73 20 6c 6f 63 6b 20 63 6f 6e 74 65 6e 74 69  is lock contenti
11300 6f 6e 2e 20 49 66 20 53 51 4c 69 74 65 20 64 65  on. If SQLite de
11310 74 65 72 6d 69 6e 65 73 20 74 68 61 74 20 69 6e  termines that in
11320 76 6f 6b 69 6e 67 20 74 68 65 20 62 75 73 79 0a  voking the busy.
11330 2a 2a 20 68 61 6e 64 6c 65 72 20 63 6f 75 6c 64  ** handler could
11340 20 72 65 73 75 6c 74 20 69 6e 20 61 20 64 65 61   result in a dea
11350 64 6c 6f 63 6b 2c 20 69 74 20 77 69 6c 6c 20 67  dlock, it will g
11360 6f 20 61 68 65 61 64 20 61 6e 64 20 72 65 74 75  o ahead and retu
11370 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  rn [SQLITE_BUSY]
11380 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49  .** or [SQLITE_I
11390 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 69 6e  OERR_BLOCKED] in
113a0 73 74 65 61 64 20 6f 66 20 69 6e 76 6f 6b 69 6e  stead of invokin
113b0 67 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  g the busy handl
113c0 65 72 2e 0a 2a 2a 20 43 6f 6e 73 69 64 65 72 20  er..** Consider 
113d0 61 20 73 63 65 6e 61 72 69 6f 20 77 68 65 72 65  a scenario where
113e0 20 6f 6e 65 20 70 72 6f 63 65 73 73 20 69 73 20   one process is 
113f0 68 6f 6c 64 69 6e 67 20 61 20 72 65 61 64 20 6c  holding a read l
11400 6f 63 6b 20 74 68 61 74 0a 2a 2a 20 69 74 20 69  ock that.** it i
11410 73 20 74 72 79 69 6e 67 20 74 6f 20 70 72 6f 6d  s trying to prom
11420 6f 74 65 20 74 6f 20 61 20 72 65 73 65 72 76 65  ote to a reserve
11430 64 20 6c 6f 63 6b 20 61 6e 64 0a 2a 2a 20 61 20  d lock and.** a 
11440 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 69  second process i
11450 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 73 65  s holding a rese
11460 72 76 65 64 20 6c 6f 63 6b 20 74 68 61 74 20 69  rved lock that i
11470 74 20 69 73 20 74 72 79 69 6e 67 0a 2a 2a 20 74  t is trying.** t
11480 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 6e 20  o promote to an 
11490 65 78 63 6c 75 73 69 76 65 20 6c 6f 63 6b 2e 20  exclusive lock. 
114a0 20 54 68 65 20 66 69 72 73 74 20 70 72 6f 63 65   The first proce
114b0 73 73 20 63 61 6e 6e 6f 74 20 70 72 6f 63 65 65  ss cannot procee
114c0 64 0a 2a 2a 20 62 65 63 61 75 73 65 20 69 74 20  d.** because it 
114d0 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68  is blocked by th
114e0 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 65  e second and the
114f0 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20   second process 
11500 63 61 6e 6e 6f 74 0a 2a 2a 20 70 72 6f 63 65 65  cannot.** procee
11510 64 20 62 65 63 61 75 73 65 20 69 74 20 69 73 20  d because it is 
11520 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20 66  blocked by the f
11530 69 72 73 74 2e 20 20 49 66 20 62 6f 74 68 20 70  irst.  If both p
11540 72 6f 63 65 73 73 65 73 0a 2a 2a 20 69 6e 76 6f  rocesses.** invo
11550 6b 65 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ke the busy hand
11560 6c 65 72 73 2c 20 6e 65 69 74 68 65 72 20 77 69  lers, neither wi
11570 6c 6c 20 6d 61 6b 65 20 61 6e 79 20 70 72 6f 67  ll make any prog
11580 72 65 73 73 2e 20 20 54 68 65 72 65 66 6f 72 65  ress.  Therefore
11590 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 72 65 74 75  ,.** SQLite retu
115a0 72 6e 73 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  rns [SQLITE_BUSY
115b0 5d 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20  ] for the first 
115c0 70 72 6f 63 65 73 73 2c 20 68 6f 70 69 6e 67 20  process, hoping 
115d0 74 68 61 74 20 74 68 69 73 0a 2a 2a 20 77 69 6c  that this.** wil
115e0 6c 20 69 6e 64 75 63 65 20 74 68 65 20 66 69 72  l induce the fir
115f0 73 74 20 70 72 6f 63 65 73 73 20 74 6f 20 72 65  st process to re
11600 6c 65 61 73 65 20 69 74 73 20 72 65 61 64 20 6c  lease its read l
11610 6f 63 6b 20 61 6e 64 20 61 6c 6c 6f 77 0a 2a 2a  ock and allow.**
11620 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63   the second proc
11630 65 73 73 20 74 6f 20 70 72 6f 63 65 65 64 2e 0a  ess to proceed..
11640 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 66 61 75 6c  **.** The defaul
11650 74 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20  t busy callback 
11660 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54  is NULL..**.** T
11670 68 65 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  he [SQLITE_BUSY]
11680 20 65 72 72 6f 72 20 69 73 20 63 6f 6e 76 65 72   error is conver
11690 74 65 64 20 74 6f 20 5b 53 51 4c 49 54 45 5f 49  ted to [SQLITE_I
116a0 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a  OERR_BLOCKED].**
116b0 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20   when SQLite is 
116c0 69 6e 20 74 68 65 20 6d 69 64 64 6c 65 20 6f 66  in the middle of
116d0 20 61 20 6c 61 72 67 65 20 74 72 61 6e 73 61 63   a large transac
116e0 74 69 6f 6e 20 77 68 65 72 65 20 61 6c 6c 20 74  tion where all t
116f0 68 65 0a 2a 2a 20 63 68 61 6e 67 65 73 20 77 69  he.** changes wi
11700 6c 6c 20 6e 6f 74 20 66 69 74 20 69 6e 74 6f 20  ll not fit into 
11710 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79 20 63 61  the in-memory ca
11720 63 68 65 2e 20 20 53 51 4c 69 74 65 20 77 69 6c  che.  SQLite wil
11730 6c 0a 2a 2a 20 61 6c 72 65 61 64 79 20 68 6f 6c  l.** already hol
11740 64 20 61 20 52 45 53 45 52 56 45 44 20 6c 6f 63  d a RESERVED loc
11750 6b 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73  k on the databas
11760 65 20 66 69 6c 65 2c 20 62 75 74 20 69 74 20 6e  e file, but it n
11770 65 65 64 73 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f  eeds.** to promo
11780 74 65 20 74 68 69 73 20 6c 6f 63 6b 20 74 6f 20  te this lock to 
11790 45 58 43 4c 55 53 49 56 45 20 73 6f 20 74 68 61  EXCLUSIVE so tha
117a0 74 20 69 74 20 63 61 6e 20 73 70 69 6c 6c 20 63  t it can spill c
117b0 61 63 68 65 0a 2a 2a 20 70 61 67 65 73 20 69 6e  ache.** pages in
117c0 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 20  to the database 
117d0 66 69 6c 65 20 77 69 74 68 6f 75 74 20 68 61 72  file without har
117e0 6d 20 74 6f 20 63 6f 6e 63 75 72 72 65 6e 74 0a  m to concurrent.
117f0 2a 2a 20 72 65 61 64 65 72 73 2e 20 20 49 66 20  ** readers.  If 
11800 69 74 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  it is unable to 
11810 70 72 6f 6d 6f 74 65 20 74 68 65 20 6c 6f 63 6b  promote the lock
11820 2c 20 74 68 65 6e 20 74 68 65 20 69 6e 2d 6d 65  , then the in-me
11830 6d 6f 72 79 0a 2a 2a 20 63 61 63 68 65 20 77 69  mory.** cache wi
11840 6c 6c 20 62 65 20 6c 65 66 74 20 69 6e 20 61 6e  ll be left in an
11850 20 69 6e 63 6f 6e 73 69 73 74 65 6e 74 20 73 74   inconsistent st
11860 61 74 65 20 61 6e 64 20 73 6f 20 74 68 65 20 65  ate and so the e
11870 72 72 6f 72 0a 2a 2a 20 63 6f 64 65 20 69 73 20  rror.** code is 
11880 70 72 6f 6d 6f 74 65 64 20 66 72 6f 6d 20 74 68  promoted from th
11890 65 20 72 65 6c 61 74 69 76 65 6c 79 20 62 65 6e  e relatively ben
118a0 69 67 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  ign [SQLITE_BUSY
118b0 5d 20 74 6f 0a 2a 2a 20 74 68 65 20 6d 6f 72 65  ] to.** the more
118c0 20 73 65 76 65 72 65 20 5b 53 51 4c 49 54 45 5f   severe [SQLITE_
118d0 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e 20  IOERR_BLOCKED]. 
118e0 20 54 68 69 73 20 65 72 72 6f 72 20 63 6f 64 65   This error code
118f0 20 70 72 6f 6d 6f 74 69 6f 6e 0a 2a 2a 20 66 6f   promotion.** fo
11900 72 63 65 73 20 61 6e 20 61 75 74 6f 6d 61 74 69  rces an automati
11910 63 20 72 6f 6c 6c 62 61 63 6b 20 6f 66 20 74 68  c rollback of th
11920 65 20 63 68 61 6e 67 65 73 2e 20 20 53 65 65 20  e changes.  See 
11930 74 68 65 0a 2a 2a 20 3c 61 20 68 72 65 66 3d 22  the.** <a href="
11940 2f 63 76 73 74 72 61 63 2f 77 69 6b 69 3f 70 3d  /cvstrac/wiki?p=
11950 43 6f 72 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77  CorruptionFollow
11960 69 6e 67 42 75 73 79 45 72 72 6f 72 22 3e 0a 2a  ingBusyError">.*
11970 2a 20 43 6f 72 72 75 70 74 69 6f 6e 46 6f 6c 6c  * CorruptionFoll
11980 6f 77 69 6e 67 42 75 73 79 45 72 72 6f 72 3c 2f  owingBusyError</
11990 61 3e 20 77 69 6b 69 20 70 61 67 65 20 66 6f 72  a> wiki page for
119a0 20 61 20 64 69 73 63 75 73 73 69 6f 6e 20 6f 66   a discussion of
119b0 20 77 68 79 0a 2a 2a 20 74 68 69 73 20 69 73 20   why.** this is 
119c0 69 6d 70 6f 72 74 61 6e 74 2e 0a 2a 2a 0a 2a 2a  important..**.**
119d0 20 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20   There can only 
119e0 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73 79  be a single busy
119f0 20 68 61 6e 64 6c 65 72 20 64 65 66 69 6e 65 64   handler defined
11a00 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 5b 64 61   for each.** [da
11a10 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
11a20 6e 5d 2e 20 20 53 65 74 74 69 6e 67 20 61 20 6e  n].  Setting a n
11a30 65 77 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  ew busy handler 
11a40 63 6c 65 61 72 73 20 61 6e 79 0a 2a 2a 20 70 72  clears any.** pr
11a50 65 76 69 6f 75 73 6c 79 20 73 65 74 20 68 61 6e  eviously set han
11a60 64 6c 65 72 2e 20 20 4e 6f 74 65 20 74 68 61 74  dler.  Note that
11a70 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   calling [sqlite
11a80 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29  3_busy_timeout()
11a90 5d 0a 2a 2a 20 77 69 6c 6c 20 61 6c 73 6f 20 73  ].** will also s
11aa0 65 74 20 6f 72 20 63 6c 65 61 72 20 74 68 65 20  et or clear the 
11ab0 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a  busy handler..**
11ac0 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
11ad0 2a 2a 0a 2a 2a 20 7b 48 31 32 33 31 31 7d 20 54  **.** {H12311} T
11ae0 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79  he [sqlite3_busy
11af0 5f 68 61 6e 64 6c 65 72 28 44 2c 43 2c 41 29 5d  _handler(D,C,A)]
11b00 20 66 75 6e 63 74 69 6f 6e 20 73 68 61 6c 6c 20   function shall 
11b10 72 65 70 6c 61 63 65 0a 2a 2a 20 20 20 20 20 20  replace.**      
11b20 20 20 20 20 62 75 73 79 20 63 61 6c 6c 62 61 63      busy callbac
11b30 6b 20 69 6e 20 74 68 65 20 5b 64 61 74 61 62 61  k in the [databa
11b40 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44  se connection] D
11b50 20 77 69 74 68 20 61 20 6e 65 77 0a 2a 2a 20 20   with a new.**  
11b60 20 20 20 20 20 20 20 20 61 20 6e 65 77 20 62 75          a new bu
11b70 73 79 20 68 61 6e 64 6c 65 72 20 43 20 61 6e 64  sy handler C and
11b80 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74   application dat
11b90 61 20 70 6f 69 6e 74 65 72 20 41 2e 0a 2a 2a 0a  a pointer A..**.
11ba0 2a 2a 20 7b 48 31 32 33 31 32 7d 20 4e 65 77 6c  ** {H12312} Newl
11bb0 79 20 63 72 65 61 74 65 64 20 5b 64 61 74 61 62  y created [datab
11bc0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d  ase connections]
11bd0 20 73 68 61 6c 6c 20 68 61 76 65 20 61 20 62 75   shall have a bu
11be0 73 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 68  sy.**          h
11bf0 61 6e 64 6c 65 72 20 6f 66 20 4e 55 4c 4c 2e 0a  andler of NULL..
11c00 2a 2a 0a 2a 2a 20 7b 48 31 32 33 31 34 7d 20 57  **.** {H12314} W
11c10 68 65 6e 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20  hen two or more 
11c20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
11c30 74 69 6f 6e 73 5d 20 73 68 61 72 65 20 61 0a 2a  tions] share a.*
11c40 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
11c50 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65  te3_enable_share
11c60 64 5f 63 61 63 68 65 20 7c 20 63 6f 6d 6d 6f 6e  d_cache | common
11c70 20 63 61 63 68 65 5d 2c 0a 2a 2a 20 20 20 20 20   cache],.**     
11c80 20 20 20 20 20 74 68 65 20 62 75 73 79 20 68 61       the busy ha
11c90 6e 64 6c 65 72 20 66 6f 72 20 74 68 65 20 64 61  ndler for the da
11ca0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
11cb0 6e 20 63 75 72 72 65 6e 74 6c 79 20 75 73 69 6e  n currently usin
11cc0 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  g.**          th
11cd0 65 20 63 61 63 68 65 20 73 68 61 6c 6c 20 62 65  e cache shall be
11ce0 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 74 68   invoked when th
11cf0 65 20 63 61 63 68 65 20 65 6e 63 6f 75 6e 74 65  e cache encounte
11d00 72 73 20 61 20 6c 6f 63 6b 2e 0a 2a 2a 0a 2a 2a  rs a lock..**.**
11d10 20 7b 48 31 32 33 31 36 7d 20 49 66 20 61 20 62   {H12316} If a b
11d20 75 73 79 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c  usy handler call
11d30 62 61 63 6b 20 72 65 74 75 72 6e 73 20 7a 65 72  back returns zer
11d40 6f 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c 69  o, then the SQLi
11d50 74 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  te interface.** 
11d60 20 20 20 20 20 20 20 20 20 74 68 61 74 20 70 72           that pr
11d70 6f 76 6f 6b 65 64 20 74 68 65 20 6c 6f 63 6b 69  ovoked the locki
11d80 6e 67 20 65 76 65 6e 74 20 73 68 61 6c 6c 20 72  ng event shall r
11d90 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55  eturn [SQLITE_BU
11da0 53 59 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33  SY]..**.** {H123
11db0 31 38 7d 20 53 51 4c 69 74 65 20 73 68 61 6c 6c  18} SQLite shall
11dc0 20 69 6e 76 6f 6b 65 73 20 74 68 65 20 62 75 73   invokes the bus
11dd0 79 20 68 61 6e 64 6c 65 72 20 77 69 74 68 20 74  y handler with t
11de0 77 6f 20 61 72 67 75 6d 65 6e 74 73 20 77 68 69  wo arguments whi
11df0 63 68 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  ch.**          a
11e00 72 65 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  re a copy of the
11e10 20 70 6f 69 6e 74 65 72 20 73 75 70 70 6c 69 65   pointer supplie
11e20 64 20 62 79 20 74 68 65 20 33 72 64 20 70 61 72  d by the 3rd par
11e30 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 20 20 20  ameter to.**    
11e40 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 62        [sqlite3_b
11e50 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 5d 20 61  usy_handler()] a
11e60 6e 64 20 61 20 63 6f 75 6e 74 20 6f 66 20 74 68  nd a count of th
11e70 65 20 6e 75 6d 62 65 72 20 6f 66 20 70 72 69 6f  e number of prio
11e80 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e  r.**          in
11e90 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65  vocations of the
11ea0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 66 6f   busy handler fo
11eb0 72 20 74 68 65 20 73 61 6d 65 20 6c 6f 63 6b 69  r the same locki
11ec0 6e 67 20 65 76 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  ng event..**.** 
11ed0 41 53 53 55 4d 50 54 49 4f 4e 53 3a 0a 2a 2a 0a  ASSUMPTIONS:.**.
11ee0 2a 2a 20 7b 41 31 32 33 31 39 7d 20 41 20 62 75  ** {A12319} A bu
11ef0 73 79 20 68 61 6e 64 6c 65 72 20 6d 75 73 74 20  sy handler must 
11f00 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65 20 64 61  not close the da
11f10 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
11f20 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72  n.**          or
11f30 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
11f40 6d 65 6e 74 5d 20 74 68 61 74 20 69 6e 76 6f 6b  ment] that invok
11f50 65 64 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ed the busy hand
11f60 6c 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ler..*/.int sqli
11f70 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72  te3_busy_handler
11f80 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28 2a  (sqlite3*, int(*
11f90 29 28 76 6f 69 64 2a 2c 69 6e 74 29 2c 20 76 6f  )(void*,int), vo
11fa0 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  id*);../*.** CAP
11fb0 49 33 52 45 46 3a 20 53 65 74 20 41 20 42 75 73  I3REF: Set A Bus
11fc0 79 20 54 69 6d 65 6f 75 74 20 7b 48 31 32 33 34  y Timeout {H1234
11fd0 30 7d 20 3c 53 34 30 34 31 30 3e 0a 2a 2a 0a 2a  0} <S40410>.**.*
11fe0 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73  * This routine s
11ff0 65 74 73 20 61 20 5b 73 71 6c 69 74 65 33 5f 62  ets a [sqlite3_b
12000 75 73 79 5f 68 61 6e 64 6c 65 72 20 7c 20 62 75  usy_handler | bu
12010 73 79 20 68 61 6e 64 6c 65 72 5d 20 74 68 61 74  sy handler] that
12020 20 73 6c 65 65 70 73 0a 2a 2a 20 66 6f 72 20 61   sleeps.** for a
12030 20 73 70 65 63 69 66 69 65 64 20 61 6d 6f 75 6e   specified amoun
12040 74 20 6f 66 20 74 69 6d 65 20 77 68 65 6e 20 61  t of time when a
12050 20 74 61 62 6c 65 20 69 73 20 6c 6f 63 6b 65 64   table is locked
12060 2e 20 20 54 68 65 20 68 61 6e 64 6c 65 72 0a 2a  .  The handler.*
12070 2a 20 77 69 6c 6c 20 73 6c 65 65 70 20 6d 75 6c  * will sleep mul
12080 74 69 70 6c 65 20 74 69 6d 65 73 20 75 6e 74 69  tiple times unti
12090 6c 20 61 74 20 6c 65 61 73 74 20 22 6d 73 22 20  l at least "ms" 
120a0 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20  milliseconds of 
120b0 73 6c 65 65 70 69 6e 67 0a 2a 2a 20 68 61 76 65  sleeping.** have
120c0 20 61 63 63 75 6d 75 6c 61 74 65 64 2e 20 7b 48   accumulated. {H
120d0 31 32 33 34 33 7d 20 41 66 74 65 72 20 22 6d 73  12343} After "ms
120e0 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f  " milliseconds o
120f0 66 20 73 6c 65 65 70 69 6e 67 2c 0a 2a 2a 20 74  f sleeping,.** t
12100 68 65 20 68 61 6e 64 6c 65 72 20 72 65 74 75 72  he handler retur
12110 6e 73 20 30 20 77 68 69 63 68 20 63 61 75 73 65  ns 0 which cause
12120 73 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  s [sqlite3_step(
12130 29 5d 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20  )] to return.** 
12140 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72  [SQLITE_BUSY] or
12150 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42   [SQLITE_IOERR_B
12160 4c 4f 43 4b 45 44 5d 2e 0a 2a 2a 0a 2a 2a 20 43  LOCKED]..**.** C
12170 61 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f 75 74  alling this rout
12180 69 6e 65 20 77 69 74 68 20 61 6e 20 61 72 67 75  ine with an argu
12190 6d 65 6e 74 20 6c 65 73 73 20 74 68 61 6e 20 6f  ment less than o
121a0 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 0a  r equal to zero.
121b0 2a 2a 20 74 75 72 6e 73 20 6f 66 66 20 61 6c 6c  ** turns off all
121c0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2e 0a   busy handlers..
121d0 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 63 61 6e 20  **.** There can 
121e0 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65  only be a single
121f0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 66 6f   busy handler fo
12200 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a  r a particular.*
12210 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
12220 65 63 74 69 6f 6e 5d 20 61 6e 79 20 61 6e 79 20  ection] any any 
12230 67 69 76 65 6e 20 6d 6f 6d 65 6e 74 2e 20 20 49  given moment.  I
12240 66 20 61 6e 6f 74 68 65 72 20 62 75 73 79 20 68  f another busy h
12250 61 6e 64 6c 65 72 0a 2a 2a 20 77 61 73 20 64 65  andler.** was de
12260 66 69 6e 65 64 20 20 28 75 73 69 6e 67 20 5b 73  fined  (using [s
12270 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64  qlite3_busy_hand
12280 6c 65 72 28 29 5d 29 20 70 72 69 6f 72 20 74 6f  ler()]) prior to
12290 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 74 68 69 73   calling.** this
122a0 20 72 6f 75 74 69 6e 65 2c 20 74 68 61 74 20 6f   routine, that o
122b0 74 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c 65  ther busy handle
122c0 72 20 69 73 20 63 6c 65 61 72 65 64 2e 0a 2a 2a  r is cleared..**
122d0 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
122e0 2a 2a 0a 2a 2a 20 7b 48 31 32 33 34 31 7d 20 54  **.** {H12341} T
122f0 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79  he [sqlite3_busy
12300 5f 74 69 6d 65 6f 75 74 28 29 5d 20 66 75 6e 63  _timeout()] func
12310 74 69 6f 6e 20 73 68 61 6c 6c 20 6f 76 65 72 72  tion shall overr
12320 69 64 65 20 61 6e 79 20 70 72 69 6f 72 0a 2a 2a  ide any prior.**
12330 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
12340 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28  e3_busy_timeout(
12350 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 62  )] or [sqlite3_b
12360 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 5d 20 73  usy_handler()] s
12370 65 74 74 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20  etting.**       
12380 20 20 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b     on the same [
12390 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
123a0 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  ion]..**.** {H12
123b0 33 34 33 7d 20 49 66 20 74 68 65 20 32 6e 64 20  343} If the 2nd 
123c0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71  parameter to [sq
123d0 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f  lite3_busy_timeo
123e0 75 74 28 29 5d 20 69 73 20 6c 65 73 73 20 74 68  ut()] is less th
123f0 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  an.**          o
12400 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 2c  r equal to zero,
12410 20 74 68 65 6e 20 74 68 65 20 62 75 73 79 20 68   then the busy h
12420 61 6e 64 6c 65 72 20 73 68 61 6c 6c 20 62 65 20  andler shall be 
12430 63 6c 65 61 72 65 64 20 73 6f 20 74 68 61 74 0a  cleared so that.
12440 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6c 6c 20  **          all 
12450 73 75 62 73 65 71 75 65 6e 74 20 6c 6f 63 6b 69  subsequent locki
12460 6e 67 20 65 76 65 6e 74 73 20 69 6d 6d 65 64 69  ng events immedi
12470 61 74 65 6c 79 20 72 65 74 75 72 6e 20 5b 53 51  ately return [SQ
12480 4c 49 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a 0a 2a  LITE_BUSY]..**.*
12490 2a 20 7b 48 31 32 33 34 34 7d 20 49 66 20 74 68  * {H12344} If th
124a0 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20  e 2nd parameter 
124b0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79  to [sqlite3_busy
124c0 5f 74 69 6d 65 6f 75 74 28 29 5d 20 69 73 20 61  _timeout()] is a
124d0 20 70 6f 73 69 74 69 76 65 0a 2a 2a 20 20 20 20   positive.**    
124e0 20 20 20 20 20 20 6e 75 6d 62 65 72 20 4e 2c 20        number N, 
124f0 74 68 65 6e 20 61 20 62 75 73 79 20 68 61 6e 64  then a busy hand
12500 6c 65 72 20 73 68 61 6c 6c 20 62 65 20 73 65 74  ler shall be set
12510 20 74 68 61 74 20 72 65 70 65 61 74 65 64 6c 79   that repeatedly
12520 20 63 61 6c 6c 73 0a 2a 2a 20 20 20 20 20 20 20   calls.**       
12530 20 20 20 74 68 65 20 78 53 6c 65 65 70 28 29 20     the xSleep() 
12540 6d 65 74 68 6f 64 20 69 6e 20 74 68 65 20 5b 73  method in the [s
12550 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 56 46 53  qlite3_vfs | VFS
12560 20 69 6e 74 65 72 66 61 63 65 5d 20 75 6e 74 69   interface] unti
12570 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 65 69  l.**          ei
12580 74 68 65 72 20 74 68 65 20 6c 6f 63 6b 20 63 6c  ther the lock cl
12590 65 61 72 73 20 6f 72 20 75 6e 74 69 6c 20 74 68  ears or until th
125a0 65 20 63 75 6d 75 6c 61 74 69 76 65 20 73 6c 65  e cumulative sle
125b0 65 70 20 74 69 6d 65 0a 2a 2a 20 20 20 20 20 20  ep time.**      
125c0 20 20 20 20 72 65 70 6f 72 74 65 64 20 62 61 63      reported bac
125d0 6b 20 62 79 20 78 53 6c 65 65 70 28 29 20 65 78  k by xSleep() ex
125e0 63 65 65 64 73 20 4e 20 6d 69 6c 6c 69 73 65 63  ceeds N millisec
125f0 6f 6e 64 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  onds..*/.int sql
12600 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75  ite3_busy_timeou
12610 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20  t(sqlite3*, int 
12620 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ms);../*.** CAPI
12630 33 52 45 46 3a 20 43 6f 6e 76 65 6e 69 65 6e 63  3REF: Convenienc
12640 65 20 52 6f 75 74 69 6e 65 73 20 46 6f 72 20 52  e Routines For R
12650 75 6e 6e 69 6e 67 20 51 75 65 72 69 65 73 20 7b  unning Queries {
12660 48 31 32 33 37 30 7d 20 3c 53 31 30 30 30 30 3e  H12370} <S10000>
12670 0a 2a 2a 0a 2a 2a 20 44 65 66 69 6e 69 74 69 6f  .**.** Definitio
12680 6e 3a 20 41 20 3c 62 3e 72 65 73 75 6c 74 20 74  n: A <b>result t
12690 61 62 6c 65 3c 2f 62 3e 20 69 73 20 6d 65 6d 6f  able</b> is memo
126a0 72 79 20 64 61 74 61 20 73 74 72 75 63 74 75 72  ry data structur
126b0 65 20 63 72 65 61 74 65 64 20 62 79 20 74 68 65  e created by the
126c0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 67 65 74  .** [sqlite3_get
126d0 5f 74 61 62 6c 65 28 29 5d 20 69 6e 74 65 72 66  _table()] interf
126e0 61 63 65 2e 20 20 41 20 72 65 73 75 6c 74 20 74  ace.  A result t
126f0 61 62 6c 65 20 72 65 63 6f 72 64 73 20 74 68 65  able records the
12700 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 71 75 65  .** complete que
12710 72 79 20 72 65 73 75 6c 74 73 20 66 72 6f 6d 20  ry results from 
12720 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 71 75 65 72  one or more quer
12730 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74  ies..**.** The t
12740 61 62 6c 65 20 63 6f 6e 63 65 70 74 75 61 6c 6c  able conceptuall
12750 79 20 68 61 73 20 61 20 6e 75 6d 62 65 72 20 6f  y has a number o
12760 66 20 72 6f 77 73 20 61 6e 64 20 63 6f 6c 75 6d  f rows and colum
12770 6e 73 2e 20 20 42 75 74 0a 2a 2a 20 74 68 65 73  ns.  But.** thes
12780 65 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6e 6f  e numbers are no
12790 74 20 70 61 72 74 20 6f 66 20 74 68 65 20 72 65  t part of the re
127a0 73 75 6c 74 20 74 61 62 6c 65 20 69 74 73 65 6c  sult table itsel
127b0 66 2e 20 20 54 68 65 73 65 0a 2a 2a 20 6e 75 6d  f.  These.** num
127c0 62 65 72 73 20 61 72 65 20 6f 62 74 61 69 6e 65  bers are obtaine
127d0 64 20 73 65 70 61 72 61 74 65 6c 79 2e 20 20 4c  d separately.  L
127e0 65 74 20 4e 20 62 65 20 74 68 65 20 6e 75 6d 62  et N be the numb
127f0 65 72 20 6f 66 20 72 6f 77 73 0a 2a 2a 20 61 6e  er of rows.** an
12800 64 20 4d 20 62 65 20 74 68 65 20 6e 75 6d 62 65  d M be the numbe
12810 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a  r of columns..**
12820 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62  .** A result tab
12830 6c 65 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f  le is an array o
12840 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 7a 65  f pointers to ze
12850 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54  ro-terminated UT
12860 46 2d 38 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20  F-8 strings..** 
12870 54 68 65 72 65 20 61 72 65 20 28 4e 2b 31 29 2a  There are (N+1)*
12880 4d 20 65 6c 65 6d 65 6e 74 73 20 69 6e 20 74 68  M elements in th
12890 65 20 61 72 72 61 79 2e 20 20 54 68 65 20 66 69  e array.  The fi
128a0 72 73 74 20 4d 20 70 6f 69 6e 74 65 72 73 20 70  rst M pointers p
128b0 6f 69 6e 74 0a 2a 2a 20 74 6f 20 7a 65 72 6f 2d  oint.** to zero-
128c0 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e  terminated strin
128d0 67 73 20 74 68 61 74 20 20 63 6f 6e 74 61 69 6e  gs that  contain
128e0 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 74 68   the names of th
128f0 65 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20 54 68  e columns..** Th
12900 65 20 72 65 6d 61 69 6e 69 6e 67 20 65 6e 74 72  e remaining entr
12910 69 65 73 20 61 6c 6c 20 70 6f 69 6e 74 20 74 6f  ies all point to
12920 20 71 75 65 72 79 20 72 65 73 75 6c 74 73 2e 20   query results. 
12930 20 4e 55 4c 4c 20 76 61 6c 75 65 73 20 72 65 73   NULL values res
12940 75 6c 74 0a 2a 2a 20 69 6e 20 4e 55 4c 4c 20 70  ult.** in NULL p
12950 6f 69 6e 74 65 72 73 2e 20 20 41 6c 6c 20 6f 74  ointers.  All ot
12960 68 65 72 20 76 61 6c 75 65 73 20 61 72 65 20 69  her values are i
12970 6e 20 74 68 65 69 72 20 55 54 46 2d 38 20 7a 65  n their UTF-8 ze
12980 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a  ro-terminated.**
12990 20 73 74 72 69 6e 67 20 72 65 70 72 65 73 65 6e   string represen
129a0 74 61 74 69 6f 6e 20 61 73 20 72 65 74 75 72 6e  tation as return
129b0 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63  ed by [sqlite3_c
129c0 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a  olumn_text()]..*
129d0 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61  *.** A result ta
129e0 62 6c 65 20 6d 69 67 68 74 20 63 6f 6e 73 69 73  ble might consis
129f0 74 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  t of one or more
12a00 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
12a10 6f 6e 73 2e 0a 2a 2a 20 49 74 20 69 73 20 6e 6f  ons..** It is no
12a20 74 20 73 61 66 65 20 74 6f 20 70 61 73 73 20 61  t safe to pass a
12a30 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 64 69   result table di
12a40 72 65 63 74 6c 79 20 74 6f 20 5b 73 71 6c 69 74  rectly to [sqlit
12a50 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 20 41  e3_free()]..** A
12a60 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 73 68   result table sh
12a70 6f 75 6c 64 20 62 65 20 64 65 61 6c 6c 6f 63 61  ould be dealloca
12a80 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ted using [sqlit
12a90 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d  e3_free_table()]
12aa0 2e 0a 2a 2a 0a 2a 2a 20 41 73 20 61 6e 20 65 78  ..**.** As an ex
12ab0 61 6d 70 6c 65 20 6f 66 20 74 68 65 20 72 65 73  ample of the res
12ac0 75 6c 74 20 74 61 62 6c 65 20 66 6f 72 6d 61 74  ult table format
12ad0 2c 20 73 75 70 70 6f 73 65 20 61 20 71 75 65 72  , suppose a quer
12ae0 79 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 61  y result.** is a
12af0 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a  s follows:.**.**
12b00 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
12b10 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20 4e 61 6d  e>.**        Nam
12b20 65 20 20 20 20 20 20 20 20 7c 20 41 67 65 0a 2a  e        | Age.*
12b30 2a 20 20 20 20 20 20 20 20 2d 2d 2d 2d 2d 2d 2d  *        -------
12b40 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
12b50 0a 2a 2a 20 20 20 20 20 20 20 20 41 6c 69 63 65  .**        Alice
12b60 20 20 20 20 20 20 20 7c 20 34 33 0a 2a 2a 20 20         | 43.**  
12b70 20 20 20 20 20 20 42 6f 62 20 20 20 20 20 20 20        Bob       
12b80 20 20 7c 20 32 38 0a 2a 2a 20 20 20 20 20 20 20    | 28.**       
12b90 20 43 69 6e 64 79 20 20 20 20 20 20 20 7c 20 32   Cindy       | 2
12ba0 31 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  1.** </pre></blo
12bb0 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54  ckquote>.**.** T
12bc0 68 65 72 65 20 61 72 65 20 74 77 6f 20 63 6f 6c  here are two col
12bd0 75 6d 6e 20 28 4d 3d 3d 32 29 20 61 6e 64 20 74  umn (M==2) and t
12be0 68 72 65 65 20 72 6f 77 73 20 28 4e 3d 3d 33 29  hree rows (N==3)
12bf0 2e 20 20 54 68 75 73 20 74 68 65 0a 2a 2a 20 72  .  Thus the.** r
12c00 65 73 75 6c 74 20 74 61 62 6c 65 20 68 61 73 20  esult table has 
12c10 38 20 65 6e 74 72 69 65 73 2e 20 20 53 75 70 70  8 entries.  Supp
12c20 6f 73 65 20 74 68 65 20 72 65 73 75 6c 74 20 74  ose the result t
12c30 61 62 6c 65 20 69 73 20 73 74 6f 72 65 64 0a 2a  able is stored.*
12c40 2a 20 69 6e 20 61 6e 20 61 72 72 61 79 20 6e 61  * in an array na
12c50 6d 65 73 20 61 7a 52 65 73 75 6c 74 2e 20 20 54  mes azResult.  T
12c60 68 65 6e 20 61 7a 52 65 73 75 6c 74 20 68 6f 6c  hen azResult hol
12c70 64 73 20 74 68 69 73 20 63 6f 6e 74 65 6e 74 3a  ds this content:
12c80 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
12c90 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20  te><pre>.**     
12ca0 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
12cb0 30 5d 20 3d 20 22 4e 61 6d 65 22 3b 0a 2a 2a 20  0] = "Name";.** 
12cc0 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
12cd0 23 39 31 3b 31 5d 20 3d 20 22 41 67 65 22 3b 0a  #91;1] = "Age";.
12ce0 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
12cf0 6c 74 26 23 39 31 3b 32 5d 20 3d 20 22 41 6c 69  lt&#91;2] = "Ali
12d00 63 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  ce";.**        a
12d10 7a 52 65 73 75 6c 74 26 23 39 31 3b 33 5d 20 3d  zResult&#91;3] =
12d20 20 22 34 33 22 3b 0a 2a 2a 20 20 20 20 20 20 20   "43";.**       
12d30 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 34 5d   azResult&#91;4]
12d40 20 3d 20 22 42 6f 62 22 3b 0a 2a 2a 20 20 20 20   = "Bob";.**    
12d50 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
12d60 3b 35 5d 20 3d 20 22 32 38 22 3b 0a 2a 2a 20 20  ;5] = "28";.**  
12d70 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
12d80 39 31 3b 36 5d 20 3d 20 22 43 69 6e 64 79 22 3b  91;6] = "Cindy";
12d90 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
12da0 75 6c 74 26 23 39 31 3b 37 5d 20 3d 20 22 32 31  ult&#91;7] = "21
12db0 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  ";.** </pre></bl
12dc0 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
12dd0 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  The sqlite3_get_
12de0 74 61 62 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e  table() function
12df0 20 65 76 61 6c 75 61 74 65 73 20 6f 6e 65 20 6f   evaluates one o
12e00 72 20 6d 6f 72 65 0a 2a 2a 20 73 65 6d 69 63 6f  r more.** semico
12e10 6c 6f 6e 2d 73 65 70 61 72 61 74 65 64 20 53 51  lon-separated SQ
12e20 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69 6e 20  L statements in 
12e30 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  the zero-termina
12e40 74 65 64 20 55 54 46 2d 38 0a 2a 2a 20 73 74 72  ted UTF-8.** str
12e50 69 6e 67 20 6f 66 20 69 74 73 20 32 6e 64 20 70  ing of its 2nd p
12e60 61 72 61 6d 65 74 65 72 2e 20 20 49 74 20 72 65  arameter.  It re
12e70 74 75 72 6e 73 20 61 20 72 65 73 75 6c 74 20 74  turns a result t
12e80 61 62 6c 65 20 74 6f 20 74 68 65 0a 2a 2a 20 70  able to the.** p
12e90 6f 69 6e 74 65 72 20 67 69 76 65 6e 20 69 6e 20  ointer given in 
12ea0 69 74 73 20 33 72 64 20 70 61 72 61 6d 65 74 65  its 3rd paramete
12eb0 72 2e 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 74  r..**.** After t
12ec0 68 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74  he calling funct
12ed0 69 6f 6e 20 68 61 73 20 66 69 6e 69 73 68 65 64  ion has finished
12ee0 20 75 73 69 6e 67 20 74 68 65 20 72 65 73 75 6c   using the resul
12ef0 74 2c 20 69 74 20 73 68 6f 75 6c 64 0a 2a 2a 20  t, it should.** 
12f00 70 61 73 73 20 74 68 65 20 70 6f 69 6e 74 65 72  pass the pointer
12f10 20 74 6f 20 74 68 65 20 72 65 73 75 6c 74 20 74   to the result t
12f20 61 62 6c 65 20 74 6f 20 73 71 6c 69 74 65 33 5f  able to sqlite3_
12f30 66 72 65 65 5f 74 61 62 6c 65 28 29 20 69 6e 20  free_table() in 
12f40 6f 72 64 65 72 20 74 6f 0a 2a 2a 20 72 65 6c 65  order to.** rele
12f50 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 74  ase the memory t
12f60 68 61 74 20 77 61 73 20 6d 61 6c 6c 6f 63 65 64  hat was malloced
12f70 2e 20 20 42 65 63 61 75 73 65 20 6f 66 20 74 68  .  Because of th
12f80 65 20 77 61 79 20 74 68 65 0a 2a 2a 20 5b 73 71  e way the.** [sq
12f90 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
12fa0 68 61 70 70 65 6e 73 20 77 69 74 68 69 6e 20 73  happens within s
12fb0 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
12fc0 28 29 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 0a  (), the calling.
12fd0 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74  ** function must
12fe0 20 6e 6f 74 20 74 72 79 20 74 6f 20 63 61 6c 6c   not try to call
12ff0 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
13000 5d 20 64 69 72 65 63 74 6c 79 2e 20 20 4f 6e 6c  ] directly.  Onl
13010 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72  y.** [sqlite3_fr
13020 65 65 5f 74 61 62 6c 65 28 29 5d 20 69 73 20 61  ee_table()] is a
13030 62 6c 65 20 74 6f 20 72 65 6c 65 61 73 65 20 74  ble to release t
13040 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 70 65 72  he memory proper
13050 6c 79 20 61 6e 64 20 73 61 66 65 6c 79 2e 0a 2a  ly and safely..*
13060 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
13070 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 69 6e 74  _get_table() int
13080 65 72 66 61 63 65 20 69 73 20 69 6d 70 6c 65 6d  erface is implem
13090 65 6e 74 65 64 20 61 73 20 61 20 77 72 61 70 70  ented as a wrapp
130a0 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71  er around.** [sq
130b0 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2e 20 20  lite3_exec()].  
130c0 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  The sqlite3_get_
130d0 74 61 62 6c 65 28 29 20 72 6f 75 74 69 6e 65 20  table() routine 
130e0 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 61 63  does not have ac
130f0 63 65 73 73 0a 2a 2a 20 74 6f 20 61 6e 79 20 69  cess.** to any i
13100 6e 74 65 72 6e 61 6c 20 64 61 74 61 20 73 74 72  nternal data str
13110 75 63 74 75 72 65 73 20 6f 66 20 53 51 4c 69 74  uctures of SQLit
13120 65 2e 20 20 49 74 20 75 73 65 73 20 6f 6e 6c 79  e.  It uses only
13130 20 74 68 65 20 70 75 62 6c 69 63 0a 2a 2a 20 69   the public.** i
13140 6e 74 65 72 66 61 63 65 20 64 65 66 69 6e 65 64  nterface defined
13150 20 68 65 72 65 2e 20 20 41 73 20 61 20 63 6f 6e   here.  As a con
13160 73 65 71 75 65 6e 63 65 2c 20 65 72 72 6f 72 73  sequence, errors
13170 20 74 68 61 74 20 6f 63 63 75 72 20 69 6e 20 74   that occur in t
13180 68 65 0a 2a 2a 20 77 72 61 70 70 65 72 20 6c 61  he.** wrapper la
13190 79 65 72 20 6f 75 74 73 69 64 65 20 6f 66 20 74  yer outside of t
131a0 68 65 20 69 6e 74 65 72 6e 61 6c 20 5b 73 71 6c  he internal [sql
131b0 69 74 65 33 5f 65 78 65 63 28 29 5d 20 63 61 6c  ite3_exec()] cal
131c0 6c 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 65 66  l are not.** ref
131d0 6c 65 63 74 65 64 20 69 6e 20 73 75 62 73 65 71  lected in subseq
131e0 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73  uent calls to [s
131f0 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29  qlite3_errcode()
13200 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65 72  ] or [sqlite3_er
13210 72 6d 73 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49  rmsg()]..**.** I
13220 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
13230 20 7b 48 31 32 33 37 31 7d 20 49 66 20 61 20 5b   {H12371} If a [
13240 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
13250 65 28 29 5d 20 66 61 69 6c 73 20 61 20 6d 65 6d  e()] fails a mem
13260 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20  ory allocation, 
13270 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  then.**         
13280 20 69 74 20 73 68 61 6c 6c 20 66 72 65 65 20 74   it shall free t
13290 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20  he result table 
132a0 75 6e 64 65 72 20 63 6f 6e 73 74 72 75 63 74 69  under constructi
132b0 6f 6e 2c 20 61 62 6f 72 74 20 74 68 65 0a 2a 2a  on, abort the.**
132c0 20 20 20 20 20 20 20 20 20 20 71 75 65 72 79 20            query 
132d0 69 6e 20 70 72 6f 63 65 73 73 2c 20 73 6b 69 70  in process, skip
132e0 20 61 6e 79 20 73 75 62 73 65 71 75 65 6e 74 20   any subsequent 
132f0 71 75 65 72 69 65 73 2c 20 73 65 74 20 74 68 65  queries, set the
13300 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 2a 70 61  .**          *pa
13310 7a 52 65 73 75 6c 74 20 6f 75 74 70 75 74 20 70  zResult output p
13320 6f 69 6e 74 65 72 20 74 6f 20 4e 55 4c 4c 20 61  ointer to NULL a
13330 6e 64 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  nd return [SQLIT
13340 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20  E_NOMEM]..**.** 
13350 7b 48 31 32 33 37 33 7d 20 49 66 20 74 68 65 20  {H12373} If the 
13360 70 6e 43 6f 6c 75 6d 6e 20 70 61 72 61 6d 65 74  pnColumn paramet
13370 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 67  er to [sqlite3_g
13380 65 74 5f 74 61 62 6c 65 28 29 5d 20 69 73 20 6e  et_table()] is n
13390 6f 74 20 4e 55 4c 4c 0a 2a 2a 20 20 20 20 20 20  ot NULL.**      
133a0 20 20 20 20 74 68 65 6e 20 61 20 73 75 63 63 65      then a succe
133b0 73 73 66 75 6c 20 69 6e 76 6f 63 61 74 69 6f 6e  ssful invocation
133c0 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 67 65 74   of [sqlite3_get
133d0 5f 74 61 62 6c 65 28 29 5d 20 73 68 61 6c 6c 0a  _table()] shall.
133e0 2a 2a 20 20 20 20 20 20 20 20 20 20 77 72 69 74  **          writ
133f0 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  e the number of 
13400 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 0a 2a  columns in the.*
13410 2a 20 20 20 20 20 20 20 20 20 20 72 65 73 75 6c  *          resul
13420 74 20 73 65 74 20 6f 66 20 74 68 65 20 71 75 65  t set of the que
13430 72 79 20 69 6e 74 6f 20 2a 70 6e 43 6f 6c 75 6d  ry into *pnColum
13440 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33 37 34  n..**.** {H12374
13450 7d 20 49 66 20 74 68 65 20 70 6e 52 6f 77 20 70  } If the pnRow p
13460 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c  arameter to [sql
13470 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
13480 5d 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 0a 2a 2a  ] is not NULL.**
13490 20 20 20 20 20 20 20 20 20 20 74 68 65 6e 20 61            then a
134a0 20 73 75 63 63 65 73 73 66 75 6c 20 69 6e 76 6f   successful invo
134b0 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74  cation of [sqlit
134c0 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20  e3_get_table()] 
134d0 73 68 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20  shall.**        
134e0 20 20 77 72 69 74 65 73 20 74 68 65 20 6e 75 6d    writes the num
134f0 62 65 72 20 6f 66 20 72 6f 77 73 20 69 6e 20 74  ber of rows in t
13500 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72  he.**          r
13510 65 73 75 6c 74 20 73 65 74 20 6f 66 20 74 68 65  esult set of the
13520 20 71 75 65 72 79 20 69 6e 74 6f 20 2a 70 6e 52   query into *pnR
13530 6f 77 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33 37  ow..**.** {H1237
13540 36 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c 20  6} A successful 
13550 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73  invocation of [s
13560 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
13570 28 29 5d 20 74 68 61 74 20 63 6f 6d 70 75 74 65  ()] that compute
13580 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 20  s.**          N 
13590 72 6f 77 73 20 6f 66 20 72 65 73 75 6c 74 20 77  rows of result w
135a0 69 74 68 20 43 20 63 6f 6c 75 6d 6e 73 20 70 65  ith C columns pe
135b0 72 20 72 6f 77 20 73 68 61 6c 6c 20 6d 61 6b 65  r row shall make
135c0 20 2a 70 61 7a 52 65 73 75 6c 74 0a 2a 2a 20 20   *pazResult.**  
135d0 20 20 20 20 20 20 20 20 70 6f 69 6e 74 20 74 6f          point to
135e0 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69   an array of poi
135f0 6e 74 65 72 73 20 74 6f 20 28 4e 2b 31 29 2a 43  nters to (N+1)*C
13600 20 73 74 72 69 6e 67 73 20 77 68 65 72 65 20 74   strings where t
13610 68 65 20 66 69 72 73 74 0a 2a 2a 20 20 20 20 20  he first.**     
13620 20 20 20 20 20 43 20 73 74 72 69 6e 67 73 20 61       C strings a
13630 72 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 73 20  re column names 
13640 61 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  as obtained from
13650 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
13660 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
13670 65 28 29 5d 20 61 6e 64 20 74 68 65 20 72 65 73  e()] and the res
13680 74 20 61 72 65 20 63 6f 6c 75 6d 6e 20 72 65 73  t are column res
13690 75 6c 74 20 76 61 6c 75 65 73 0a 2a 2a 20 20 20  ult values.**   
136a0 20 20 20 20 20 20 20 6f 62 74 61 69 6e 65 64 20         obtained 
136b0 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f  from [sqlite3_co
136c0 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a  lumn_text()]..**
136d0 0a 2a 2a 20 7b 48 31 32 33 37 39 7d 20 54 68 65  .** {H12379} The
136e0 20 76 61 6c 75 65 73 20 69 6e 20 74 68 65 20 70   values in the p
136f0 61 7a 52 65 73 75 6c 74 20 61 72 72 61 79 20 72  azResult array r
13700 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69  eturned by [sqli
13710 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d  te3_get_table()]
13720 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 68 61  .**          sha
13730 6c 6c 20 72 65 6d 61 69 6e 20 76 61 6c 69 64 20  ll remain valid 
13740 75 6e 74 69 6c 20 63 6c 65 61 72 65 64 20 62 79  until cleared by
13750 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74   [sqlite3_free_t
13760 61 62 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b  able()]..**.** {
13770 48 31 32 33 38 32 7d 20 57 68 65 6e 20 61 6e 20  H12382} When an 
13780 65 72 72 6f 72 20 6f 63 63 75 72 73 20 64 75 72  error occurs dur
13790 69 6e 67 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f  ing evaluation o
137a0 66 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  f [sqlite3_get_t
137b0 61 62 6c 65 28 29 5d 0a 2a 2a 20 20 20 20 20 20  able()].**      
137c0 20 20 20 20 74 68 65 20 66 75 6e 63 74 69 6f 6e      the function
137d0 20 73 68 61 6c 6c 20 73 65 74 20 2a 70 61 7a 52   shall set *pazR
137e0 65 73 75 6c 74 20 74 6f 20 4e 55 4c 4c 2c 20 77  esult to NULL, w
137f0 72 69 74 65 20 61 6e 20 65 72 72 6f 72 20 6d 65  rite an error me
13800 73 73 61 67 65 0a 2a 2a 20 20 20 20 20 20 20 20  ssage.**        
13810 20 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62    into memory ob
13820 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c  tained from [sql
13830 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20  ite3_malloc()], 
13840 6d 61 6b 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  make.**         
13850 20 2a 2a 70 7a 45 72 72 6d 73 67 20 70 6f 69 6e   **pzErrmsg poin
13860 74 20 74 6f 20 74 68 61 74 20 65 72 72 6f 72 20  t to that error 
13870 6d 65 73 73 61 67 65 2c 20 61 6e 64 20 72 65 74  message, and ret
13880 75 72 6e 20 61 0a 2a 2a 20 20 20 20 20 20 20 20  urn a.**        
13890 20 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65    appropriate [e
138a0 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2f 0a 69  rror code]..*/.i
138b0 6e 74 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  nt sqlite3_get_t
138c0 61 62 6c 65 28 0a 20 20 73 71 6c 69 74 65 33 20  able(.  sqlite3 
138d0 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 2f 2a  *db,          /*
138e0 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73   An open databas
138f0 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
13900 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 2f 2a 20  r *zSql,     /* 
13910 53 51 4c 20 74 6f 20 62 65 20 65 76 61 6c 75 61  SQL to be evalua
13920 74 65 64 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a  ted */.  char **
13930 2a 70 61 7a 52 65 73 75 6c 74 2c 20 20 20 20 2f  *pazResult,    /
13940 2a 20 52 65 73 75 6c 74 73 20 6f 66 20 74 68 65  * Results of the
13950 20 71 75 65 72 79 20 2a 2f 0a 20 20 69 6e 74 20   query */.  int 
13960 2a 70 6e 52 6f 77 2c 20 20 20 20 20 20 20 20 20  *pnRow,         
13970 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72    /* Number of r
13980 65 73 75 6c 74 20 72 6f 77 73 20 77 72 69 74 74  esult rows writt
13990 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 69 6e 74  en here */.  int
139a0 20 2a 70 6e 43 6f 6c 75 6d 6e 2c 20 20 20 20 20   *pnColumn,     
139b0 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20     /* Number of 
139c0 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 73 20 77  result columns w
139d0 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20  ritten here */. 
139e0 20 63 68 61 72 20 2a 2a 70 7a 45 72 72 6d 73 67   char **pzErrmsg
139f0 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 20         /* Error 
13a00 6d 73 67 20 77 72 69 74 74 65 6e 20 68 65 72 65  msg written here
13a10 20 2a 2f 0a 29 3b 0a 76 6f 69 64 20 73 71 6c 69   */.);.void sqli
13a20 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 63  te3_free_table(c
13a30 68 61 72 20 2a 2a 72 65 73 75 6c 74 29 3b 0a 0a  har **result);..
13a40 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
13a50 46 6f 72 6d 61 74 74 65 64 20 53 74 72 69 6e 67  Formatted String
13a60 20 50 72 69 6e 74 69 6e 67 20 46 75 6e 63 74 69   Printing Functi
13a70 6f 6e 73 20 7b 48 31 37 34 30 30 7d 20 3c 53 37  ons {H17400} <S7
13a80 30 30 30 30 3e 3c 53 32 30 30 30 30 3e 0a 2a 2a  0000><S20000>.**
13a90 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
13aa0 65 73 20 61 72 65 20 77 6f 72 6b 61 6c 69 6b 65  es are workalike
13ab0 73 20 6f 66 20 74 68 65 20 22 70 72 69 6e 74 66  s of the "printf
13ac0 28 29 22 20 66 61 6d 69 6c 79 20 6f 66 20 66 75  ()" family of fu
13ad0 6e 63 74 69 6f 6e 73 0a 2a 2a 20 66 72 6f 6d 20  nctions.** from 
13ae0 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c  the standard C l
13af0 69 62 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 54 68  ibrary..**.** Th
13b00 65 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74  e sqlite3_mprint
13b10 66 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  f() and sqlite3_
13b20 76 6d 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69  vmprintf() routi
13b30 6e 65 73 20 77 72 69 74 65 20 74 68 65 69 72 0a  nes write their.
13b40 2a 2a 20 72 65 73 75 6c 74 73 20 69 6e 74 6f 20  ** results into 
13b50 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20  memory obtained 
13b60 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61  from [sqlite3_ma
13b70 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a 20 54 68 65 20  lloc()]..** The 
13b80 73 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64  strings returned
13b90 20 62 79 20 74 68 65 73 65 20 74 77 6f 20 72 6f   by these two ro
13ba0 75 74 69 6e 65 73 20 73 68 6f 75 6c 64 20 62 65  utines should be
13bb0 0a 2a 2a 20 72 65 6c 65 61 73 65 64 20 62 79 20  .** released by 
13bc0 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
13bd0 2e 20 20 42 6f 74 68 20 72 6f 75 74 69 6e 65 73  .  Both routines
13be0 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 4e 55 4c   return a.** NUL
13bf0 4c 20 70 6f 69 6e 74 65 72 20 69 66 20 5b 73 71  L pointer if [sq
13c00 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
13c10 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c  is unable to all
13c20 6f 63 61 74 65 20 65 6e 6f 75 67 68 0a 2a 2a 20  ocate enough.** 
13c30 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74  memory to hold t
13c40 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72  he resulting str
13c50 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 73 71  ing..**.** In sq
13c60 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
13c70 20 72 6f 75 74 69 6e 65 20 69 73 20 73 69 6d 69   routine is simi
13c80 6c 61 72 20 74 6f 20 22 73 6e 70 72 69 6e 74 66  lar to "snprintf
13c90 28 29 22 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20  ()" from.** the 
13ca0 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61  standard C libra
13cb0 72 79 2e 20 20 54 68 65 20 72 65 73 75 6c 74 20  ry.  The result 
13cc0 69 73 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20  is written into 
13cd0 74 68 65 0a 2a 2a 20 62 75 66 66 65 72 20 73 75  the.** buffer su
13ce0 70 70 6c 69 65 64 20 61 73 20 74 68 65 20 73 65  pplied as the se
13cf0 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 77  cond parameter w
13d00 68 6f 73 65 20 73 69 7a 65 20 69 73 20 67 69 76  hose size is giv
13d10 65 6e 20 62 79 0a 2a 2a 20 74 68 65 20 66 69 72  en by.** the fir
13d20 73 74 20 70 61 72 61 6d 65 74 65 72 2e 20 4e 6f  st parameter. No
13d30 74 65 20 74 68 61 74 20 74 68 65 20 6f 72 64 65  te that the orde
13d40 72 20 6f 66 20 74 68 65 0a 2a 2a 20 66 69 72 73  r of the.** firs
13d50 74 20 74 77 6f 20 70 61 72 61 6d 65 74 65 72 73  t two parameters
13d60 20 69 73 20 72 65 76 65 72 73 65 64 20 66 72 6f   is reversed fro
13d70 6d 20 73 6e 70 72 69 6e 74 66 28 29 2e 20 20 54  m snprintf().  T
13d80 68 69 73 20 69 73 20 61 6e 0a 2a 2a 20 68 69 73  his is an.** his
13d90 74 6f 72 69 63 61 6c 20 61 63 63 69 64 65 6e 74  torical accident
13da0 20 74 68 61 74 20 63 61 6e 6e 6f 74 20 62 65 20   that cannot be 
13db0 66 69 78 65 64 20 77 69 74 68 6f 75 74 20 62 72  fixed without br
13dc0 65 61 6b 69 6e 67 0a 2a 2a 20 62 61 63 6b 77 61  eaking.** backwa
13dd0 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  rds compatibilit
13de0 79 2e 20 20 4e 6f 74 65 20 61 6c 73 6f 20 74 68  y.  Note also th
13df0 61 74 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  at sqlite3_snpri
13e00 6e 74 66 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73  ntf().** returns
13e10 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 69 74   a pointer to it
13e20 73 20 62 75 66 66 65 72 20 69 6e 73 74 65 61 64  s buffer instead
13e30 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   of the number o
13e40 66 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20  f.** characters 
13e50 61 63 74 75 61 6c 6c 79 20 77 72 69 74 74 65 6e  actually written
13e60 20 69 6e 74 6f 20 74 68 65 20 62 75 66 66 65 72   into the buffer
13e70 2e 20 20 57 65 20 61 64 6d 69 74 20 74 68 61 74  .  We admit that
13e80 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  .** the number o
13e90 66 20 63 68 61 72 61 63 74 65 72 73 20 77 72 69  f characters wri
13ea0 74 74 65 6e 20 77 6f 75 6c 64 20 62 65 20 61 20  tten would be a 
13eb0 6d 6f 72 65 20 75 73 65 66 75 6c 20 72 65 74 75  more useful retu
13ec0 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 62 75 74 20  rn.** value but 
13ed0 77 65 20 63 61 6e 6e 6f 74 20 63 68 61 6e 67 65  we cannot change
13ee0 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   the implementat
13ef0 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 73  ion of sqlite3_s
13f00 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 6e 6f 77  nprintf().** now
13f10 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e   without breakin
13f20 67 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e  g compatibility.
13f30 0a 2a 2a 0a 2a 2a 20 41 73 20 6c 6f 6e 67 20 61  .**.** As long a
13f40 73 20 74 68 65 20 62 75 66 66 65 72 20 73 69 7a  s the buffer siz
13f50 65 20 69 73 20 67 72 65 61 74 65 72 20 74 68 61  e is greater tha
13f60 6e 20 7a 65 72 6f 2c 20 73 71 6c 69 74 65 33 5f  n zero, sqlite3_
13f70 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 67 75  snprintf().** gu
13f80 61 72 61 6e 74 65 65 73 20 74 68 61 74 20 74 68  arantees that th
13f90 65 20 62 75 66 66 65 72 20 69 73 20 61 6c 77 61  e buffer is alwa
13fa0 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  ys zero-terminat
13fb0 65 64 2e 20 20 54 68 65 20 66 69 72 73 74 0a 2a  ed.  The first.*
13fc0 2a 20 70 61 72 61 6d 65 74 65 72 20 22 6e 22 20  * parameter "n" 
13fd0 69 73 20 74 68 65 20 74 6f 74 61 6c 20 73 69 7a  is the total siz
13fe0 65 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 2c  e of the buffer,
13ff0 20 69 6e 63 6c 75 64 69 6e 67 20 73 70 61 63 65   including space
14000 20 66 6f 72 0a 2a 2a 20 74 68 65 20 7a 65 72 6f   for.** the zero
14010 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 53 6f   terminator.  So
14020 20 74 68 65 20 6c 6f 6e 67 65 73 74 20 73 74 72   the longest str
14030 69 6e 67 20 74 68 61 74 20 63 61 6e 20 62 65 20  ing that can be 
14040 63 6f 6d 70 6c 65 74 65 6c 79 0a 2a 2a 20 77 72  completely.** wr
14050 69 74 74 65 6e 20 77 69 6c 6c 20 62 65 20 6e 2d  itten will be n-
14060 31 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a  1 characters..**
14070 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
14080 65 73 20 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74  es all implement
14090 20 73 6f 6d 65 20 61 64 64 69 74 69 6f 6e 61 6c   some additional
140a0 20 66 6f 72 6d 61 74 74 69 6e 67 0a 2a 2a 20 6f   formatting.** o
140b0 70 74 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20  ptions that are 
140c0 75 73 65 66 75 6c 20 66 6f 72 20 63 6f 6e 73 74  useful for const
140d0 72 75 63 74 69 6e 67 20 53 51 4c 20 73 74 61 74  ructing SQL stat
140e0 65 6d 65 6e 74 73 2e 0a 2a 2a 20 41 6c 6c 20 6f  ements..** All o
140f0 66 20 74 68 65 20 75 73 75 61 6c 20 70 72 69 6e  f the usual prin
14100 74 66 28 29 20 66 6f 72 6d 61 74 74 69 6e 67 20  tf() formatting 
14110 6f 70 74 69 6f 6e 73 20 61 70 70 6c 79 2e 20 20  options apply.  
14120 49 6e 20 61 64 64 69 74 69 6f 6e 2c 20 74 68 65  In addition, the
14130 72 65 0a 2a 2a 20 69 73 20 61 72 65 20 22 25 71  re.** is are "%q
14140 22 2c 20 22 25 51 22 2c 20 61 6e 64 20 22 25 7a  ", "%Q", and "%z
14150 22 20 6f 70 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a  " options..**.**
14160 20 54 68 65 20 25 71 20 6f 70 74 69 6f 6e 20 77   The %q option w
14170 6f 72 6b 73 20 6c 69 6b 65 20 25 73 20 69 6e 20  orks like %s in 
14180 74 68 61 74 20 69 74 20 73 75 62 73 74 69 74 75  that it substitu
14190 74 65 73 20 61 20 6e 75 6c 6c 2d 74 65 72 6d 69  tes a null-termi
141a0 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20  nated.** string 
141b0 66 72 6f 6d 20 74 68 65 20 61 72 67 75 6d 65 6e  from the argumen
141c0 74 20 6c 69 73 74 2e 20 20 42 75 74 20 25 71 20  t list.  But %q 
141d0 61 6c 73 6f 20 64 6f 75 62 6c 65 73 20 65 76 65  also doubles eve
141e0 72 79 20 27 5c 27 27 20 63 68 61 72 61 63 74 65  ry '\'' characte
141f0 72 2e 0a 2a 2a 20 25 71 20 69 73 20 64 65 73 69  r..** %q is desi
14200 67 6e 65 64 20 66 6f 72 20 75 73 65 20 69 6e 73  gned for use ins
14210 69 64 65 20 61 20 73 74 72 69 6e 67 20 6c 69 74  ide a string lit
14220 65 72 61 6c 2e 20 20 42 79 20 64 6f 75 62 6c 69  eral.  By doubli
14230 6e 67 20 65 61 63 68 20 27 5c 27 27 0a 2a 2a 20  ng each '\''.** 
14240 63 68 61 72 61 63 74 65 72 20 69 74 20 65 73 63  character it esc
14250 61 70 65 73 20 74 68 61 74 20 63 68 61 72 61 63  apes that charac
14260 74 65 72 20 61 6e 64 20 61 6c 6c 6f 77 73 20 69  ter and allows i
14270 74 20 74 6f 20 62 65 20 69 6e 73 65 72 74 65 64  t to be inserted
14280 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 73 74 72   into.** the str
14290 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65  ing..**.** For e
142a0 78 61 6d 70 6c 65 2c 20 61 73 73 75 6d 65 20 74  xample, assume t
142b0 68 65 20 73 74 72 69 6e 67 20 76 61 72 69 61 62  he string variab
142c0 6c 65 20 7a 54 65 78 74 20 63 6f 6e 74 61 69 6e  le zText contain
142d0 73 20 74 65 78 74 20 61 73 20 66 6f 6c 6c 6f 77  s text as follow
142e0 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  s:.**.** <blockq
142f0 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63  uote><pre>.**  c
14300 68 61 72 20 2a 7a 54 65 78 74 20 3d 20 22 49 74  har *zText = "It
14310 27 73 20 61 20 68 61 70 70 79 20 64 61 79 21 22  's a happy day!"
14320 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ;.** </pre></blo
14330 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 4f  ckquote>.**.** O
14340 6e 65 20 63 61 6e 20 75 73 65 20 74 68 69 73 20  ne can use this 
14350 74 65 78 74 20 69 6e 20 61 6e 20 53 51 4c 20 73  text in an SQL s
14360 74 61 74 65 6d 65 6e 74 20 61 73 20 66 6f 6c 6c  tatement as foll
14370 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  ows:.**.** <bloc
14380 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
14390 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71   char *zSQL = sq
143a0 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49  lite3_mprintf("I
143b0 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65  NSERT INTO table
143c0 20 56 41 4c 55 45 53 28 27 25 71 27 29 22 2c 20   VALUES('%q')", 
143d0 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69  zText);.**  sqli
143e0 74 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51  te3_exec(db, zSQ
143f0 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20  L, 0, 0, 0);.** 
14400 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53   sqlite3_free(zS
14410 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  QL);.** </pre></
14420 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
14430 2a 20 42 65 63 61 75 73 65 20 74 68 65 20 25 71  * Because the %q
14440 20 66 6f 72 6d 61 74 20 73 74 72 69 6e 67 20 69   format string i
14450 73 20 75 73 65 64 2c 20 74 68 65 20 27 5c 27 27  s used, the '\''
14460 20 63 68 61 72 61 63 74 65 72 20 69 6e 20 7a 54   character in zT
14470 65 78 74 0a 2a 2a 20 69 73 20 65 73 63 61 70 65  ext.** is escape
14480 64 20 61 6e 64 20 74 68 65 20 53 51 4c 20 67 65  d and the SQL ge
14490 6e 65 72 61 74 65 64 20 69 73 20 61 73 20 66 6f  nerated is as fo
144a0 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  llows:.**.** <bl
144b0 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
144c0 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 74  *  INSERT INTO t
144d0 61 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49 74  able1 VALUES('It
144e0 27 27 73 20 61 20 68 61 70 70 79 20 64 61 79 21  ''s a happy day!
144f0 27 29 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  ').** </pre></bl
14500 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
14510 54 68 69 73 20 69 73 20 63 6f 72 72 65 63 74 2e  This is correct.
14520 20 20 48 61 64 20 77 65 20 75 73 65 64 20 25 73    Had we used %s
14530 20 69 6e 73 74 65 61 64 20 6f 66 20 25 71 2c 20   instead of %q, 
14540 74 68 65 20 67 65 6e 65 72 61 74 65 64 20 53 51  the generated SQ
14550 4c 0a 2a 2a 20 77 6f 75 6c 64 20 68 61 76 65 20  L.** would have 
14560 6c 6f 6f 6b 65 64 20 6c 69 6b 65 20 74 68 69 73  looked like this
14570 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
14580 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e  ote><pre>.**  IN
14590 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31  SERT INTO table1
145a0 20 56 41 4c 55 45 53 28 27 49 74 27 73 20 61 20   VALUES('It's a 
145b0 68 61 70 70 79 20 64 61 79 21 27 29 3b 0a 2a 2a  happy day!');.**
145c0 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
145d0 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ote>.**.** This 
145e0 73 65 63 6f 6e 64 20 65 78 61 6d 70 6c 65 20 69  second example i
145f0 73 20 61 6e 20 53 51 4c 20 73 79 6e 74 61 78 20  s an SQL syntax 
14600 65 72 72 6f 72 2e 20 20 41 73 20 61 20 67 65 6e  error.  As a gen
14610 65 72 61 6c 20 72 75 6c 65 20 79 6f 75 20 73 68  eral rule you sh
14620 6f 75 6c 64 0a 2a 2a 20 61 6c 77 61 79 73 20 75  ould.** always u
14630 73 65 20 25 71 20 69 6e 73 74 65 61 64 20 6f 66  se %q instead of
14640 20 25 73 20 77 68 65 6e 20 69 6e 73 65 72 74 69   %s when inserti
14650 6e 67 20 74 65 78 74 20 69 6e 74 6f 20 61 20 73  ng text into a s
14660 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 0a 2a  tring literal..*
14670 2a 0a 2a 2a 20 54 68 65 20 25 51 20 6f 70 74 69  *.** The %Q opti
14680 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 71  on works like %q
14690 20 65 78 63 65 70 74 20 69 74 20 61 6c 73 6f 20   except it also 
146a0 61 64 64 73 20 73 69 6e 67 6c 65 20 71 75 6f 74  adds single quot
146b0 65 73 20 61 72 6f 75 6e 64 0a 2a 2a 20 74 68 65  es around.** the
146c0 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65 20   outside of the 
146d0 74 6f 74 61 6c 20 73 74 72 69 6e 67 2e 20 20 41  total string.  A
146e0 64 64 69 74 69 6f 6e 61 6c 6c 79 2c 20 69 66 20  dditionally, if 
146f0 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 6e  the parameter in
14700 20 74 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74   the.** argument
14710 20 6c 69 73 74 20 69 73 20 61 20 4e 55 4c 4c 20   list is a NULL 
14720 70 6f 69 6e 74 65 72 2c 20 25 51 20 73 75 62 73  pointer, %Q subs
14730 74 69 74 75 74 65 73 20 74 68 65 20 74 65 78 74  titutes the text
14740 20 22 4e 55 4c 4c 22 20 28 77 69 74 68 6f 75 74   "NULL" (without
14750 0a 2a 2a 20 73 69 6e 67 6c 65 20 71 75 6f 74 65  .** single quote
14760 73 29 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 74  s) in place of t
14770 68 65 20 25 51 20 6f 70 74 69 6f 6e 2e 20 20 53  he %Q option.  S
14780 6f 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20  o, for example, 
14790 6f 6e 65 20 63 6f 75 6c 64 20 73 61 79 3a 0a 2a  one could say:.*
147a0 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
147b0 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20  ><pre>.**  char 
147c0 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f  *zSQL = sqlite3_
147d0 6d 70 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20  mprintf("INSERT 
147e0 49 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45  INTO table VALUE
147f0 53 28 25 51 29 22 2c 20 7a 54 65 78 74 29 3b 0a  S(%Q)", zText);.
14800 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 78 65 63  **  sqlite3_exec
14810 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c  (db, zSQL, 0, 0,
14820 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33   0);.**  sqlite3
14830 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20  _free(zSQL);.** 
14840 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
14850 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f  te>.**.** The co
14860 64 65 20 61 62 6f 76 65 20 77 69 6c 6c 20 72 65  de above will re
14870 6e 64 65 72 20 61 20 63 6f 72 72 65 63 74 20 53  nder a correct S
14880 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20  QL statement in 
14890 74 68 65 20 7a 53 51 4c 0a 2a 2a 20 76 61 72 69  the zSQL.** vari
148a0 61 62 6c 65 20 65 76 65 6e 20 69 66 20 74 68 65  able even if the
148b0 20 7a 54 65 78 74 20 76 61 72 69 61 62 6c 65 20   zText variable 
148c0 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
148d0 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 22 25 7a  r..**.** The "%z
148e0 22 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74  " formatting opt
148f0 69 6f 6e 20 77 6f 72 6b 73 20 65 78 61 63 74 6c  ion works exactl
14900 79 20 6c 69 6b 65 20 22 25 73 22 20 77 69 74 68  y like "%s" with
14910 20 74 68 65 0a 2a 2a 20 61 64 64 69 74 69 6f 6e   the.** addition
14920 20 74 68 61 74 20 61 66 74 65 72 20 74 68 65 20   that after the 
14930 73 74 72 69 6e 67 20 68 61 73 20 62 65 65 6e 20  string has been 
14940 72 65 61 64 20 61 6e 64 20 63 6f 70 69 65 64 20  read and copied 
14950 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 72 65 73 75  into.** the resu
14960 6c 74 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  lt, [sqlite3_fre
14970 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 6f  e()] is called o
14980 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69  n the input stri
14990 6e 67 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20  ng. {END}.**.** 
149a0 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
149b0 2a 20 7b 48 31 37 34 30 33 7d 20 20 54 68 65 20  * {H17403}  The 
149c0 5b 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66  [sqlite3_mprintf
149d0 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
149e0 5f 76 6d 70 72 69 6e 74 66 28 29 5d 20 69 6e 74  _vmprintf()] int
149f0 65 72 66 61 63 65 73 0a 2a 2a 20 20 20 20 20 20  erfaces.**      
14a00 20 20 20 20 20 72 65 74 75 72 6e 20 65 69 74 68       return eith
14a10 65 72 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 7a  er pointers to z
14a20 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55  ero-terminated U
14a30 54 46 2d 38 20 73 74 72 69 6e 67 73 20 68 65 6c  TF-8 strings hel
14a40 64 20 69 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  d in.**         
14a50 20 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65    memory obtaine
14a60 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
14a70 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 4e 55 4c  malloc()] or NUL
14a80 4c 20 70 6f 69 6e 74 65 72 73 20 69 66 0a 2a 2a  L pointers if.**
14a90 20 20 20 20 20 20 20 20 20 20 20 61 20 63 61 6c             a cal
14aa0 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61  l to [sqlite3_ma
14ab0 6c 6c 6f 63 28 29 5d 20 66 61 69 6c 73 2e 0a 2a  lloc()] fails..*
14ac0 2a 0a 2a 2a 20 7b 48 31 37 34 30 36 7d 20 20 54  *.** {H17406}  T
14ad0 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72  he [sqlite3_snpr
14ae0 69 6e 74 66 28 29 5d 20 69 6e 74 65 72 66 61 63  intf()] interfac
14af0 65 20 77 72 69 74 65 73 20 61 20 7a 65 72 6f 2d  e writes a zero-
14b00 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 20 20  terminated.**   
14b10 20 20 20 20 20 20 20 20 55 54 46 2d 38 20 73 74          UTF-8 st
14b20 72 69 6e 67 20 69 6e 74 6f 20 74 68 65 20 62 75  ring into the bu
14b30 66 66 65 72 20 70 6f 69 6e 74 65 64 20 74 6f 20  ffer pointed to 
14b40 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61  by the second pa
14b50 72 61 6d 65 74 65 72 0a 2a 2a 20 20 20 20 20 20  rameter.**      
14b60 20 20 20 20 20 70 72 6f 76 69 64 65 64 20 74 68       provided th
14b70 61 74 20 74 68 65 20 66 69 72 73 74 20 70 61 72  at the first par
14b80 61 6d 65 74 65 72 20 69 73 20 67 72 65 61 74 65  ameter is greate
14b90 72 20 74 68 61 6e 20 7a 65 72 6f 2e 0a 2a 2a 0a  r than zero..**.
14ba0 2a 2a 20 7b 48 31 37 34 30 37 7d 20 20 54 68 65  ** {H17407}  The
14bb0 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e   [sqlite3_snprin
14bc0 74 66 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  tf()] interface 
14bd0 64 6f 65 73 20 6e 6f 74 20 77 72 69 74 65 20 73  does not write s
14be0 6c 6f 74 73 20 6f 66 0a 2a 2a 20 20 20 20 20 20  lots of.**      
14bf0 20 20 20 20 20 69 74 73 20 6f 75 74 70 75 74 20       its output 
14c00 62 75 66 66 65 72 20 28 74 68 65 20 73 65 63 6f  buffer (the seco
14c10 6e 64 20 70 61 72 61 6d 65 74 65 72 29 20 6f 75  nd parameter) ou
14c20 74 73 69 64 65 20 74 68 65 20 72 61 6e 67 65 0a  tside the range.
14c30 2a 2a 20 20 20 20 20 20 20 20 20 20 20 6f 66 20  **           of 
14c40 30 20 74 68 72 6f 75 67 68 20 4e 2d 31 20 28 77  0 through N-1 (w
14c50 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 66 69  here N is the fi
14c60 72 73 74 20 70 61 72 61 6d 65 74 65 72 29 0a 2a  rst parameter).*
14c70 2a 20 20 20 20 20 20 20 20 20 20 20 72 65 67 61  *           rega
14c80 72 64 6c 65 73 73 20 6f 66 20 74 68 65 20 6c 65  rdless of the le
14c90 6e 67 74 68 20 6f 66 20 74 68 65 20 73 74 72 69  ngth of the stri
14ca0 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  ng.**           
14cb0 72 65 71 75 65 73 74 65 64 20 62 79 20 74 68 65  requested by the
14cc0 20 66 6f 72 6d 61 74 20 73 70 65 63 69 66 69 63   format specific
14cd0 61 74 69 6f 6e 2e 0a 2a 2f 0a 63 68 61 72 20 2a  ation..*/.char *
14ce0 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28  sqlite3_mprintf(
14cf0 63 6f 6e 73 74 20 63 68 61 72 2a 2c 2e 2e 2e 29  const char*,...)
14d00 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  ;.char *sqlite3_
14d10 76 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63  vmprintf(const c
14d20 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a  har*, va_list);.
14d30 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 6e  char *sqlite3_sn
14d40 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a  printf(int,char*
14d50 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 2e 2e  ,const char*, ..
14d60 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
14d70 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f  REF: Memory Allo
14d80 63 61 74 69 6f 6e 20 53 75 62 73 79 73 74 65 6d  cation Subsystem
14d90 20 7b 48 31 37 33 30 30 7d 20 3c 53 32 30 30 30   {H17300} <S2000
14da0 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c  0>.**.** The SQL
14db0 69 74 65 20 63 6f 72 65 20 20 75 73 65 73 20 74  ite core  uses t
14dc0 68 65 73 65 20 74 68 72 65 65 20 72 6f 75 74 69  hese three routi
14dd0 6e 65 73 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69  nes for all of i
14de0 74 73 20 6f 77 6e 0a 2a 2a 20 69 6e 74 65 72 6e  ts own.** intern
14df0 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  al memory alloca
14e00 74 69 6f 6e 20 6e 65 65 64 73 2e 20 22 43 6f 72  tion needs. "Cor
14e10 65 22 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f  e" in the previo
14e20 75 73 20 73 65 6e 74 65 6e 63 65 0a 2a 2a 20 64  us sentence.** d
14e30 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20  oes not include 
14e40 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 74 65 6d  operating-system
14e50 20 73 70 65 63 69 66 69 63 20 56 46 53 20 69 6d   specific VFS im
14e60 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 54  plementation.  T
14e70 68 65 0a 2a 2a 20 57 69 6e 64 6f 77 73 20 56 46  he.** Windows VF
14e80 53 20 75 73 65 73 20 6e 61 74 69 76 65 20 6d 61  S uses native ma
14e90 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28  lloc() and free(
14ea0 29 20 66 6f 72 20 73 6f 6d 65 20 6f 70 65 72 61  ) for some opera
14eb0 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  tions..**.** The
14ec0 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
14ed0 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ) routine return
14ee0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
14ef0 20 62 6c 6f 63 6b 0a 2a 2a 20 6f 66 20 6d 65 6d   block.** of mem
14f00 6f 72 79 20 61 74 20 6c 65 61 73 74 20 4e 20 62  ory at least N b
14f10 79 74 65 73 20 69 6e 20 6c 65 6e 67 74 68 2c 20  ytes in length, 
14f20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 70  where N is the p
14f30 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 49 66 20  arameter..** If 
14f40 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
14f50 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 6f 62   is unable to ob
14f60 74 61 69 6e 20 73 75 66 66 69 63 69 65 6e 74 20  tain sufficient 
14f70 66 72 65 65 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20  free.** memory, 
14f80 69 74 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c  it returns a NUL
14f90 4c 20 70 6f 69 6e 74 65 72 2e 20 20 49 66 20 74  L pointer.  If t
14fa0 68 65 20 70 61 72 61 6d 65 74 65 72 20 4e 20 74  he parameter N t
14fb0 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c  o.** sqlite3_mal
14fc0 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f 20 6f 72  loc() is zero or
14fd0 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 73   negative then s
14fe0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
14ff0 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20 4e 55 4c  returns.** a NUL
15000 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a  L pointer..**.**
15010 20 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33   Calling sqlite3
15020 5f 66 72 65 65 28 29 20 77 69 74 68 20 61 20 70  _free() with a p
15030 6f 69 6e 74 65 72 20 70 72 65 76 69 6f 75 73 6c  ointer previousl
15040 79 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79  y returned.** by
15050 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
15060 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61  ) or sqlite3_rea
15070 6c 6c 6f 63 28 29 20 72 65 6c 65 61 73 65 73 20  lloc() releases 
15080 74 68 61 74 20 6d 65 6d 6f 72 79 20 73 6f 0a 2a  that memory so.*
15090 2a 20 74 68 61 74 20 69 74 20 6d 69 67 68 74 20  * that it might 
150a0 62 65 20 72 65 75 73 65 64 2e 20 20 54 68 65 20  be reused.  The 
150b0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 72  sqlite3_free() r
150c0 6f 75 74 69 6e 65 20 69 73 0a 2a 2a 20 61 20 6e  outine is.** a n
150d0 6f 2d 6f 70 20 69 66 20 69 73 20 63 61 6c 6c 65  o-op if is calle
150e0 64 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f  d with a NULL po
150f0 69 6e 74 65 72 2e 20 20 50 61 73 73 69 6e 67 20  inter.  Passing 
15100 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a  a NULL pointer.*
15110 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 65  * to sqlite3_fre
15120 65 28 29 20 69 73 20 68 61 72 6d 6c 65 73 73 2e  e() is harmless.
15130 20 20 41 66 74 65 72 20 62 65 69 6e 67 20 66 72    After being fr
15140 65 65 64 2c 20 6d 65 6d 6f 72 79 0a 2a 2a 20 73  eed, memory.** s
15150 68 6f 75 6c 64 20 6e 65 69 74 68 65 72 20 62 65  hould neither be
15160 20 72 65 61 64 20 6e 6f 72 20 77 72 69 74 74 65   read nor writte
15170 6e 2e 20 20 45 76 65 6e 20 72 65 61 64 69 6e 67  n.  Even reading
15180 20 70 72 65 76 69 6f 75 73 6c 79 20 66 72 65 65   previously free
15190 64 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6d 69 67 68  d.** memory migh
151a0 74 20 72 65 73 75 6c 74 20 69 6e 20 61 20 73 65  t result in a se
151b0 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74  gmentation fault
151c0 20 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72 65   or other severe
151d0 20 65 72 72 6f 72 2e 0a 2a 2a 20 4d 65 6d 6f 72   error..** Memor
151e0 79 20 63 6f 72 72 75 70 74 69 6f 6e 2c 20 61 20  y corruption, a 
151f0 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75  segmentation fau
15200 6c 74 2c 20 6f 72 20 6f 74 68 65 72 20 73 65 76  lt, or other sev
15210 65 72 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 69 67  ere error.** mig
15220 68 74 20 72 65 73 75 6c 74 20 69 66 20 73 71 6c  ht result if sql
15230 69 74 65 33 5f 66 72 65 65 28 29 20 69 73 20 63  ite3_free() is c
15240 61 6c 6c 65 64 20 77 69 74 68 20 61 20 6e 6f 6e  alled with a non
15250 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68  -NULL pointer th
15260 61 74 0a 2a 2a 20 77 61 73 20 6e 6f 74 20 6f 62  at.** was not ob
15270 74 61 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69  tained from sqli
15280 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20  te3_malloc() or 
15290 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 2e 0a  sqlite3_free()..
152a0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
152b0 33 5f 72 65 61 6c 6c 6f 63 28 29 20 69 6e 74 65  3_realloc() inte
152c0 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74  rface attempts t
152d0 6f 20 72 65 73 69 7a 65 20 61 0a 2a 2a 20 70 72  o resize a.** pr
152e0 69 6f 72 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ior memory alloc
152f0 61 74 69 6f 6e 20 74 6f 20 62 65 20 61 74 20 6c  ation to be at l
15300 65 61 73 74 20 4e 20 62 79 74 65 73 2c 20 77 68  east N bytes, wh
15310 65 72 65 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20  ere N is the.** 
15320 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
15330 2e 20 20 54 68 65 20 6d 65 6d 6f 72 79 20 61 6c  .  The memory al
15340 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 62 65 20 72  location to be r
15350 65 73 69 7a 65 64 20 69 73 20 74 68 65 20 66 69  esized is the fi
15360 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  rst.** parameter
15370 2e 20 20 49 66 20 74 68 65 20 66 69 72 73 74 20  .  If the first 
15380 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
15390 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a  ite3_realloc().*
153a0 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  * is a NULL poin
153b0 74 65 72 20 74 68 65 6e 20 69 74 73 20 62 65 68  ter then its beh
153c0 61 76 69 6f 72 20 69 73 20 69 64 65 6e 74 69 63  avior is identic
153d0 61 6c 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a  al to calling.**
153e0 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
153f0 4e 29 20 77 68 65 72 65 20 4e 20 69 73 20 74 68  N) where N is th
15400 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
15410 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65  er to sqlite3_re
15420 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 49 66 20 74  alloc()..** If t
15430 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
15440 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72  ter to sqlite3_r
15450 65 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f  ealloc() is zero
15460 20 6f 72 0a 2a 2a 20 6e 65 67 61 74 69 76 65 20   or.** negative 
15470 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f  then the behavio
15480 72 20 69 73 20 65 78 61 63 74 6c 79 20 74 68 65  r is exactly the
15490 20 73 61 6d 65 20 61 73 20 63 61 6c 6c 69 6e 67   same as calling
154a0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66 72 65 65  .** sqlite3_free
154b0 28 50 29 20 77 68 65 72 65 20 50 20 69 73 20 74  (P) where P is t
154c0 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
154d0 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65  er to sqlite3_re
154e0 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 73 71 6c 69  alloc()..** sqli
154f0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65  te3_realloc() re
15500 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
15510 74 6f 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  to a memory allo
15520 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 61 74 20  cation.** of at 
15530 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e  least N bytes in
15540 20 73 69 7a 65 20 6f 72 20 4e 55 4c 4c 20 69 66   size or NULL if
15550 20 73 75 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f   sufficient memo
15560 72 79 20 69 73 20 75 6e 61 76 61 69 6c 61 62 6c  ry is unavailabl
15570 65 2e 0a 2a 2a 20 49 66 20 4d 20 69 73 20 74 68  e..** If M is th
15580 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 70 72  e size of the pr
15590 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20  ior allocation, 
155a0 74 68 65 6e 20 6d 69 6e 28 4e 2c 4d 29 20 62 79  then min(N,M) by
155b0 74 65 73 0a 2a 2a 20 6f 66 20 74 68 65 20 70 72  tes.** of the pr
155c0 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61  ior allocation a
155d0 72 65 20 63 6f 70 69 65 64 20 69 6e 74 6f 20 74  re copied into t
155e0 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20  he beginning of 
155f0 62 75 66 66 65 72 20 72 65 74 75 72 6e 65 64 0a  buffer returned.
15600 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 72 65  ** by sqlite3_re
15610 61 6c 6c 6f 63 28 29 20 61 6e 64 20 74 68 65 20  alloc() and the 
15620 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e  prior allocation
15630 20 69 73 20 66 72 65 65 64 2e 0a 2a 2a 20 49 66   is freed..** If
15640 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
15650 28 29 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 2c  () returns NULL,
15660 20 74 68 65 6e 20 74 68 65 20 70 72 69 6f 72 20   then the prior 
15670 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 69 73  allocation.** is
15680 20 6e 6f 74 20 66 72 65 65 64 2e 0a 2a 2a 0a 2a   not freed..**.*
15690 2a 20 54 68 65 20 6d 65 6d 6f 72 79 20 72 65 74  * The memory ret
156a0 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
156b0 5f 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 73 71  _malloc() and sq
156c0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 0a  lite3_realloc().
156d0 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61 6c 69  ** is always ali
156e0 67 6e 65 64 20 74 6f 20 61 74 20 6c 65 61 73 74  gned to at least
156f0 20 61 6e 20 38 20 62 79 74 65 20 62 6f 75 6e 64   an 8 byte bound
15700 61 72 79 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a  ary. {END}.**.**
15710 20 54 68 65 20 64 65 66 61 75 6c 74 20 69 6d 70   The default imp
15720 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74  lementation of t
15730 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
15740 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 20 75  tion subsystem u
15750 73 65 73 0a 2a 2a 20 74 68 65 20 6d 61 6c 6c 6f  ses.** the mallo
15760 63 28 29 2c 20 72 65 61 6c 6c 6f 63 28 29 20 61  c(), realloc() a
15770 6e 64 20 66 72 65 65 28 29 20 70 72 6f 76 69 64  nd free() provid
15780 65 64 20 62 79 20 74 68 65 20 73 74 61 6e 64 61  ed by the standa
15790 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a  rd C library..**
157a0 20 7b 48 31 37 33 38 32 7d 20 48 6f 77 65 76 65   {H17382} Howeve
157b0 72 2c 20 69 66 20 53 51 4c 69 74 65 20 69 73 20  r, if SQLite is 
157c0 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68  compiled with th
157d0 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 4d 45 4d 4f  e.** SQLITE_MEMO
157e0 52 59 5f 53 49 5a 45 3d 3c 69 3e 4e 4e 4e 3c 2f  RY_SIZE=<i>NNN</
157f0 69 3e 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f  i> C preprocesso
15800 72 20 6d 61 63 72 6f 20 28 77 68 65 72 65 20 3c  r macro (where <
15810 69 3e 4e 4e 4e 3c 2f 69 3e 0a 2a 2a 20 69 73 20  i>NNN</i>.** is 
15820 61 6e 20 69 6e 74 65 67 65 72 29 2c 20 74 68 65  an integer), the
15830 6e 20 53 51 4c 69 74 65 20 63 72 65 61 74 65 20  n SQLite create 
15840 61 20 73 74 61 74 69 63 20 61 72 72 61 79 20 6f  a static array o
15850 66 20 61 74 20 6c 65 61 73 74 0a 2a 2a 20 3c 69  f at least.** <i
15860 3e 4e 4e 4e 3c 2f 69 3e 20 62 79 74 65 73 20 69  >NNN</i> bytes i
15870 6e 20 73 69 7a 65 20 61 6e 64 20 75 73 65 73 20  n size and uses 
15880 74 68 61 74 20 61 72 72 61 79 20 66 6f 72 20 61  that array for a
15890 6c 6c 20 6f 66 20 69 74 73 20 64 79 6e 61 6d 69  ll of its dynami
158a0 63 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  c.** memory allo
158b0 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 20 7b 45  cation needs. {E
158c0 4e 44 7d 20 20 41 64 64 69 74 69 6f 6e 61 6c 20  ND}  Additional 
158d0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
158e0 20 6f 70 74 69 6f 6e 73 0a 2a 2a 20 6d 61 79 20   options.** may 
158f0 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75  be added in futu
15900 72 65 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2a 0a  re releases..**.
15910 2a 2a 20 49 6e 20 53 51 4c 69 74 65 20 76 65 72  ** In SQLite ver
15920 73 69 6f 6e 20 33 2e 35 2e 30 20 61 6e 64 20 33  sion 3.5.0 and 3
15930 2e 35 2e 31 2c 20 69 74 20 77 61 73 20 70 6f 73  .5.1, it was pos
15940 73 69 62 6c 65 20 74 6f 20 64 65 66 69 6e 65 0a  sible to define.
15950 2a 2a 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 4d  ** the SQLITE_OM
15960 49 54 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f 43 41  IT_MEMORY_ALLOCA
15970 54 49 4f 4e 20 77 68 69 63 68 20 77 6f 75 6c 64  TION which would
15980 20 63 61 75 73 65 20 74 68 65 20 62 75 69 6c 74   cause the built
15990 2d 69 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  -in.** implement
159a0 61 74 69 6f 6e 20 6f 66 20 74 68 65 73 65 20 72  ation of these r
159b0 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 6f 6d  outines to be om
159c0 69 74 74 65 64 2e 20 20 54 68 61 74 20 63 61 70  itted.  That cap
159d0 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 6e 6f  ability.** is no
159e0 20 6c 6f 6e 67 65 72 20 70 72 6f 76 69 64 65 64   longer provided
159f0 2e 20 20 4f 6e 6c 79 20 62 75 69 6c 74 2d 69 6e  .  Only built-in
15a00 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
15a10 72 73 20 63 61 6e 20 62 65 20 75 73 65 64 2e 0a  rs can be used..
15a20 2a 2a 0a 2a 2a 20 54 68 65 20 57 69 6e 64 6f 77  **.** The Window
15a30 73 20 4f 53 20 69 6e 74 65 72 66 61 63 65 20 6c  s OS interface l
15a40 61 79 65 72 20 63 61 6c 6c 73 0a 2a 2a 20 74 68  ayer calls.** th
15a50 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28  e system malloc(
15a60 29 20 61 6e 64 20 66 72 65 65 28 29 20 64 69 72  ) and free() dir
15a70 65 63 74 6c 79 20 77 68 65 6e 20 63 6f 6e 76 65  ectly when conve
15a80 72 74 69 6e 67 0a 2a 2a 20 66 69 6c 65 6e 61 6d  rting.** filenam
15a90 65 73 20 62 65 74 77 65 65 6e 20 74 68 65 20 55  es between the U
15aa0 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 75 73  TF-8 encoding us
15ab0 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20  ed by SQLite.** 
15ac0 61 6e 64 20 77 68 61 74 65 76 65 72 20 66 69 6c  and whatever fil
15ad0 65 6e 61 6d 65 20 65 6e 63 6f 64 69 6e 67 20 69  ename encoding i
15ae0 73 20 75 73 65 64 20 62 79 20 74 68 65 20 70 61  s used by the pa
15af0 72 74 69 63 75 6c 61 72 20 57 69 6e 64 6f 77 73  rticular Windows
15b00 0a 2a 2a 20 69 6e 73 74 61 6c 6c 61 74 69 6f 6e  .** installation
15b10 2e 20 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  .  Memory alloca
15b20 74 69 6f 6e 20 65 72 72 6f 72 73 20 61 72 65 20  tion errors are 
15b30 64 65 74 65 63 74 65 64 2c 20 62 75 74 0a 2a 2a  detected, but.**
15b40 20 74 68 65 79 20 61 72 65 20 72 65 70 6f 72 74   they are report
15b50 65 64 20 62 61 63 6b 20 61 73 20 5b 53 51 4c 49  ed back as [SQLI
15b60 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 6f 72 0a  TE_CANTOPEN] or.
15b70 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  ** [SQLITE_IOERR
15b80 5d 20 72 61 74 68 65 72 20 74 68 61 6e 20 5b 53  ] rather than [S
15b90 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a  QLITE_NOMEM]..**
15ba0 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
15bb0 2a 2a 0a 2a 2a 20 7b 48 31 37 33 30 33 7d 20 20  **.** {H17303}  
15bc0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  The [sqlite3_mal
15bd0 6c 6f 63 28 4e 29 5d 20 69 6e 74 65 72 66 61 63  loc(N)] interfac
15be0 65 20 72 65 74 75 72 6e 73 20 65 69 74 68 65 72  e returns either
15bf0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a   a pointer to.**
15c00 20 20 20 20 20 20 20 20 20 20 20 61 20 6e 65 77             a new
15c10 6c 79 20 63 68 65 63 6b 65 64 2d 6f 75 74 20 62  ly checked-out b
15c20 6c 6f 63 6b 20 6f 66 20 61 74 20 6c 65 61 73 74  lock of at least
15c30 20 4e 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f   N bytes of memo
15c40 72 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  ry.**           
15c50 74 68 61 74 20 69 73 20 38 2d 62 79 74 65 20 61  that is 8-byte a
15c60 6c 69 67 6e 65 64 2c 20 6f 72 20 69 74 20 72 65  ligned, or it re
15c70 74 75 72 6e 73 20 4e 55 4c 4c 20 69 66 20 69 74  turns NULL if it
15c80 20 69 73 20 75 6e 61 62 6c 65 0a 2a 2a 20 20 20   is unable.**   
15c90 20 20 20 20 20 20 20 20 74 6f 20 66 75 6c 66 69          to fulfi
15ca0 6c 6c 20 74 68 65 20 72 65 71 75 65 73 74 2e 0a  ll the request..
15cb0 2a 2a 0a 2a 2a 20 7b 48 31 37 33 30 34 7d 20 20  **.** {H17304}  
15cc0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  The [sqlite3_mal
15cd0 6c 6f 63 28 4e 29 5d 20 69 6e 74 65 72 66 61 63  loc(N)] interfac
15ce0 65 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c  e returns a NULL
15cf0 20 70 6f 69 6e 74 65 72 20 69 66 0a 2a 2a 20 20   pointer if.**  
15d00 20 20 20 20 20 20 20 20 20 4e 20 69 73 20 6c 65           N is le
15d10 73 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c  ss than or equal
15d20 20 74 6f 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20   to zero..**.** 
15d30 7b 48 31 37 33 30 35 7d 20 20 54 68 65 20 5b 73  {H17305}  The [s
15d40 71 6c 69 74 65 33 5f 66 72 65 65 28 50 29 5d 20  qlite3_free(P)] 
15d50 69 6e 74 65 72 66 61 63 65 20 72 65 6c 65 61 73  interface releas
15d60 65 73 20 6d 65 6d 6f 72 79 20 70 72 65 76 69 6f  es memory previo
15d70 75 73 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20 20  usly.**         
15d80 20 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 20    returned from 
15d90 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
15da0 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72  )] or [sqlite3_r
15db0 65 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 20 20  ealloc()],.**   
15dc0 20 20 20 20 20 20 20 20 6d 61 6b 69 6e 67 20 69          making i
15dd0 74 20 61 76 61 69 6c 61 62 6c 65 20 66 6f 72 20  t available for 
15de0 72 65 75 73 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  reuse..**.** {H1
15df0 37 33 30 36 7d 20 20 41 20 63 61 6c 6c 20 74 6f  7306}  A call to
15e00 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 4e   [sqlite3_free(N
15e10 55 4c 4c 29 5d 20 69 73 20 61 20 68 61 72 6d 6c  ULL)] is a harml
15e20 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2a 0a 2a 2a  ess no-op..**.**
15e30 20 7b 48 31 37 33 31 30 7d 20 20 41 20 63 61 6c   {H17310}  A cal
15e40 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65  l to [sqlite3_re
15e50 61 6c 6c 6f 63 28 30 2c 4e 29 5d 20 69 73 20 65  alloc(0,N)] is e
15e60 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 61 20 63  quivalent to a c
15e70 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  all.**          
15e80 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c   to [sqlite3_mal
15e90 6c 6f 63 28 4e 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b  loc(N)]..**.** {
15ea0 48 31 37 33 31 32 7d 20 20 41 20 63 61 6c 6c 20  H17312}  A call 
15eb0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c  to [sqlite3_real
15ec0 6c 6f 63 28 50 2c 30 29 5d 20 69 73 20 65 71 75  loc(P,0)] is equ
15ed0 69 76 61 6c 65 6e 74 20 74 6f 20 61 20 63 61 6c  ivalent to a cal
15ee0 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 74  l.**           t
15ef0 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  o [sqlite3_free(
15f00 50 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33  P)]..**.** {H173
15f10 31 35 7d 20 20 54 68 65 20 53 51 4c 69 74 65 20  15}  The SQLite 
15f20 63 6f 72 65 20 75 73 65 73 20 5b 73 71 6c 69 74  core uses [sqlit
15f30 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73  e3_malloc()], [s
15f40 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
15f50 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  ],.**           
15f60 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  and [sqlite3_fre
15f70 65 28 29 5d 20 66 6f 72 20 61 6c 6c 20 6f 66 20  e()] for all of 
15f80 69 74 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  its memory alloc
15f90 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 20 20 20  ation and.**    
15fa0 20 20 20 20 20 20 20 64 65 61 6c 6c 6f 63 61 74         deallocat
15fb0 69 6f 6e 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a  ion needs..**.**
15fc0 20 7b 48 31 37 33 31 38 7d 20 20 54 68 65 20 5b   {H17318}  The [
15fd0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
15fe0 50 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20  P,N)] interface 
15ff0 72 65 74 75 72 6e 73 20 65 69 74 68 65 72 20 61  returns either a
16000 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 20 20 20 20   pointer.**     
16010 20 20 20 20 20 20 74 6f 20 61 20 62 6c 6f 63 6b        to a block
16020 20 6f 66 20 63 68 65 63 6b 65 64 2d 6f 75 74 20   of checked-out 
16030 6d 65 6d 6f 72 79 20 6f 66 20 61 74 20 6c 65 61  memory of at lea
16040 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69  st N bytes in si
16050 7a 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  ze.**           
16060 74 68 61 74 20 69 73 20 38 2d 62 79 74 65 20 61  that is 8-byte a
16070 6c 69 67 6e 65 64 2c 20 6f 72 20 61 20 4e 55 4c  ligned, or a NUL
16080 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a  L pointer..**.**
16090 20 7b 48 31 37 33 32 31 7d 20 20 57 68 65 6e 20   {H17321}  When 
160a0 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  [sqlite3_realloc
160b0 28 50 2c 4e 29 5d 20 72 65 74 75 72 6e 73 20 61  (P,N)] returns a
160c0 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65   non-NULL pointe
160d0 72 2c 20 69 74 20 66 69 72 73 74 0a 2a 2a 20 20  r, it first.**  
160e0 20 20 20 20 20 20 20 20 20 63 6f 70 69 65 73 20           copies 
160f0 74 68 65 20 66 69 72 73 74 20 4b 20 62 79 74 65  the first K byte
16100 73 20 6f 66 20 63 6f 6e 74 65 6e 74 20 66 72 6f  s of content fro
16110 6d 20 50 20 69 6e 74 6f 20 74 68 65 20 6e 65 77  m P into the new
16120 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  ly.**           
16130 61 6c 6c 6f 63 61 74 65 64 20 62 6c 6f 63 6b 2c  allocated block,
16140 20 77 68 65 72 65 20 4b 20 69 73 20 74 68 65 20   where K is the 
16150 6c 65 73 73 65 72 20 6f 66 20 4e 20 61 6e 64 20  lesser of N and 
16160 74 68 65 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 20  the size of.**  
16170 20 20 20 20 20 20 20 20 20 74 68 65 20 62 75 66           the buf
16180 66 65 72 20 50 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  fer P..**.** {H1
16190 37 33 32 32 7d 20 20 57 68 65 6e 20 5b 73 71 6c  7322}  When [sql
161a0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 50 2c 4e  ite3_realloc(P,N
161b0 29 5d 20 72 65 74 75 72 6e 73 20 61 20 6e 6f 6e  )] returns a non
161c0 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69  -NULL pointer, i
161d0 74 20 66 69 72 73 74 0a 2a 2a 20 20 20 20 20 20  t first.**      
161e0 20 20 20 20 20 72 65 6c 65 61 73 65 73 20 74 68       releases th
161f0 65 20 62 75 66 66 65 72 20 50 2e 0a 2a 2a 0a 2a  e buffer P..**.*
16200 2a 20 7b 48 31 37 33 32 33 7d 20 20 57 68 65 6e  * {H17323}  When
16210 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   [sqlite3_reallo
16220 63 28 50 2c 4e 29 5d 20 72 65 74 75 72 6e 73 20  c(P,N)] returns 
16230 4e 55 4c 4c 2c 20 74 68 65 20 62 75 66 66 65 72  NULL, the buffer
16240 20 50 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20   P is.**        
16250 20 20 20 6e 6f 74 20 6d 6f 64 69 66 69 65 64 20     not modified 
16260 6f 72 20 72 65 6c 65 61 73 65 64 2e 0a 2a 2a 0a  or released..**.
16270 2a 2a 20 41 53 53 55 4d 50 54 49 4f 4e 53 3a 0a  ** ASSUMPTIONS:.
16280 2a 2a 0a 2a 2a 20 7b 41 31 37 33 35 30 7d 20 20  **.** {A17350}  
16290 54 68 65 20 70 6f 69 6e 74 65 72 20 61 72 67 75  The pointer argu
162a0 6d 65 6e 74 73 20 74 6f 20 5b 73 71 6c 69 74 65  ments to [sqlite
162b0 33 5f 66 72 65 65 28 29 5d 20 61 6e 64 20 5b 73  3_free()] and [s
162c0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
162d0 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 6d  ].**           m
162e0 75 73 74 20 62 65 20 65 69 74 68 65 72 20 4e 55  ust be either NU
162f0 4c 4c 20 6f 72 20 65 6c 73 65 20 70 6f 69 6e 74  LL or else point
16300 65 72 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ers obtained fro
16310 6d 20 61 20 70 72 69 6f 72 0a 2a 2a 20 20 20 20  m a prior.**    
16320 20 20 20 20 20 20 20 69 6e 76 6f 63 61 74 69 6f         invocatio
16330 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61  n of [sqlite3_ma
16340 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69  lloc()] or [sqli
16350 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 74  te3_realloc()] t
16360 68 61 74 20 68 61 76 65 0a 2a 2a 20 20 20 20 20  hat have.**     
16370 20 20 20 20 20 20 6e 6f 74 20 79 65 74 20 62 65        not yet be
16380 65 6e 20 72 65 6c 65 61 73 65 64 2e 0a 2a 2a 0a  en released..**.
16390 2a 2a 20 7b 41 31 37 33 35 31 7d 20 20 54 68 65  ** {A17351}  The
163a0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
163b0 74 20 6e 6f 74 20 72 65 61 64 20 6f 72 20 77 72  t not read or wr
163c0 69 74 65 20 61 6e 79 20 70 61 72 74 20 6f 66 0a  ite any part of.
163d0 2a 2a 20 20 20 20 20 20 20 20 20 20 20 61 20 62  **           a b
163e0 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 61  lock of memory a
163f0 66 74 65 72 20 69 74 20 68 61 73 20 62 65 65 6e  fter it has been
16400 20 72 65 6c 65 61 73 65 64 20 75 73 69 6e 67 0a   released using.
16410 2a 2a 20 20 20 20 20 20 20 20 20 20 20 5b 73 71  **           [sq
16420 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 6f 72  lite3_free()] or
16430 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   [sqlite3_reallo
16440 63 28 29 5d 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73  c()]..*/.void *s
16450 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 69 6e  qlite3_malloc(in
16460 74 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65  t);.void *sqlite
16470 33 5f 72 65 61 6c 6c 6f 63 28 76 6f 69 64 2a 2c  3_realloc(void*,
16480 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69   int);.void sqli
16490 74 65 33 5f 66 72 65 65 28 76 6f 69 64 2a 29 3b  te3_free(void*);
164a0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
164b0 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74  : Memory Allocat
164c0 6f 72 20 53 74 61 74 69 73 74 69 63 73 20 7b 48  or Statistics {H
164d0 31 37 33 37 30 7d 20 3c 53 33 30 32 31 30 3e 0a  17370} <S30210>.
164e0 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 70 72 6f  **.** SQLite pro
164f0 76 69 64 65 73 20 74 68 65 73 65 20 74 77 6f 20  vides these two 
16500 69 6e 74 65 72 66 61 63 65 73 20 66 6f 72 20 72  interfaces for r
16510 65 70 6f 72 74 69 6e 67 20 6f 6e 20 74 68 65 20  eporting on the 
16520 73 74 61 74 75 73 0a 2a 2a 20 6f 66 20 74 68 65  status.** of the
16530 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
16540 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72  ()], [sqlite3_fr
16550 65 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69  ee()], and [sqli
16560 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a  te3_realloc()].*
16570 2a 20 72 6f 75 74 69 6e 65 73 2c 20 77 68 69 63  * routines, whic
16580 68 20 66 6f 72 6d 20 74 68 65 20 62 75 69 6c 74  h form the built
16590 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  -in memory alloc
165a0 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 2e  ation subsystem.
165b0 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
165c0 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33 37 31  S:.**.** {H17371
165d0 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  } The [sqlite3_m
165e0 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 72 6f  emory_used()] ro
165f0 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68  utine returns th
16600 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
16610 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66  s.**          of
16620 20 6d 65 6d 6f 72 79 20 63 75 72 72 65 6e 74 6c   memory currentl
16630 79 20 6f 75 74 73 74 61 6e 64 69 6e 67 20 28 6d  y outstanding (m
16640 61 6c 6c 6f 63 65 64 20 62 75 74 20 6e 6f 74 20  alloced but not 
16650 66 72 65 65 64 29 2e 0a 2a 2a 0a 2a 2a 20 7b 48  freed)..**.** {H
16660 31 37 33 37 33 7d 20 54 68 65 20 5b 73 71 6c 69  17373} The [sqli
16670 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77  te3_memory_highw
16680 61 74 65 72 28 29 5d 20 72 6f 75 74 69 6e 65 20  ater()] routine 
16690 72 65 74 75 72 6e 73 20 74 68 65 20 6d 61 78 69  returns the maxi
166a0 6d 75 6d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  mum.**          
166b0 76 61 6c 75 65 20 6f 66 20 5b 73 71 6c 69 74 65  value of [sqlite
166c0 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d  3_memory_used()]
166d0 20 73 69 6e 63 65 20 74 68 65 20 68 69 67 68 2d   since the high-
166e0 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 20 20  water mark.**   
166f0 20 20 20 20 20 20 20 77 61 73 20 6c 61 73 74 20         was last 
16700 72 65 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  reset..**.** {H1
16710 37 33 37 34 7d 20 54 68 65 20 76 61 6c 75 65 73  7374} The values
16720 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71   returned by [sq
16730 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65  lite3_memory_use
16740 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 20 20 20 20  d()] and.**     
16750 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 6d 65       [sqlite3_me
16760 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29  mory_highwater()
16770 5d 20 69 6e 63 6c 75 64 65 20 61 6e 79 20 6f 76  ] include any ov
16780 65 72 68 65 61 64 0a 2a 2a 20 20 20 20 20 20 20  erhead.**       
16790 20 20 20 61 64 64 65 64 20 62 79 20 53 51 4c 69     added by SQLi
167a0 74 65 20 69 6e 20 69 74 73 20 69 6d 70 6c 65 6d  te in its implem
167b0 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c  entation of [sql
167c0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 0a  ite3_malloc()],.
167d0 2a 2a 20 20 20 20 20 20 20 20 20 20 62 75 74 20  **          but 
167e0 6e 6f 74 20 6f 76 65 72 68 65 61 64 20 61 64 64  not overhead add
167f0 65 64 20 62 79 20 74 68 65 20 61 6e 79 20 75 6e  ed by the any un
16800 64 65 72 6c 79 69 6e 67 20 73 79 73 74 65 6d 20  derlying system 
16810 6c 69 62 72 61 72 79 0a 2a 2a 20 20 20 20 20 20  library.**      
16820 20 20 20 20 72 6f 75 74 69 6e 65 73 20 74 68 61      routines tha
16830 74 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  t [sqlite3_mallo
16840 63 28 29 5d 20 6d 61 79 20 63 61 6c 6c 2e 0a 2a  c()] may call..*
16850 2a 0a 2a 2a 20 7b 48 31 37 33 37 35 7d 20 54 68  *.** {H17375} Th
16860 65 20 6d 65 6d 6f 72 79 20 68 69 67 68 2d 77 61  e memory high-wa
16870 74 65 72 20 6d 61 72 6b 20 69 73 20 72 65 73 65  ter mark is rese
16880 74 20 74 6f 20 74 68 65 20 63 75 72 72 65 6e 74  t to the current
16890 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 20 20 20   value of.**    
168a0 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 6d        [sqlite3_m
168b0 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 69 66  emory_used()] if
168c0 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68 65   and only if the
168d0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
168e0 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
168f0 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61  e3_memory_highwa
16900 74 65 72 28 29 5d 20 69 73 20 74 72 75 65 2e 20  ter()] is true. 
16910 20 54 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   The value retur
16920 6e 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ned.**          
16930 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  by [sqlite3_memo
16940 72 79 5f 68 69 67 68 77 61 74 65 72 28 31 29 5d  ry_highwater(1)]
16950 20 69 73 20 74 68 65 20 68 69 67 68 2d 77 61 74   is the high-wat
16960 65 72 20 6d 61 72 6b 0a 2a 2a 20 20 20 20 20 20  er mark.**      
16970 20 20 20 20 70 72 69 6f 72 20 74 6f 20 74 68 65      prior to the
16980 20 72 65 73 65 74 2e 0a 2a 2f 0a 73 71 6c 69 74   reset..*/.sqlit
16990 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e3_int64 sqlite3
169a0 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 76 6f 69  _memory_used(voi
169b0 64 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36  d);.sqlite3_int6
169c0 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79  4 sqlite3_memory
169d0 5f 68 69 67 68 77 61 74 65 72 28 69 6e 74 20 72  _highwater(int r
169e0 65 73 65 74 46 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a  esetFlag);../*.*
169f0 2a 20 43 41 50 49 33 52 45 46 3a 20 50 73 65 75  * CAPI3REF: Pseu
16a00 64 6f 2d 52 61 6e 64 6f 6d 20 4e 75 6d 62 65 72  do-Random Number
16a10 20 47 65 6e 65 72 61 74 6f 72 20 7b 48 31 37 33   Generator {H173
16a20 39 30 7d 20 3c 53 32 30 30 30 30 3e 0a 2a 2a 0a  90} <S20000>.**.
16a30 2a 2a 20 53 51 4c 69 74 65 20 63 6f 6e 74 61 69  ** SQLite contai
16a40 6e 73 20 61 20 68 69 67 68 2d 71 75 61 6c 69 74  ns a high-qualit
16a50 79 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 20  y pseudo-random 
16a60 6e 75 6d 62 65 72 20 67 65 6e 65 72 61 74 6f 72  number generator
16a70 20 28 50 52 4e 47 29 20 75 73 65 64 20 74 6f 0a   (PRNG) used to.
16a80 2a 2a 20 73 65 6c 65 63 74 20 72 61 6e 64 6f 6d  ** select random
16a90 20 52 4f 57 49 44 73 20 77 68 65 6e 20 69 6e 73   ROWIDs when ins
16aa0 65 72 74 69 6e 67 20 6e 65 77 20 72 65 63 6f 72  erting new recor
16ab0 64 73 20 69 6e 74 6f 20 61 20 74 61 62 6c 65 20  ds into a table 
16ac0 74 68 61 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20  that.** already 
16ad0 75 73 65 73 20 74 68 65 20 6c 61 72 67 65 73 74  uses the largest
16ae0 20 70 6f 73 73 69 62 6c 65 20 52 4f 57 49 44 2e   possible ROWID.
16af0 20 20 54 68 65 20 50 52 4e 47 20 69 73 20 61 6c    The PRNG is al
16b00 73 6f 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74  so used for.** t
16b10 68 65 20 62 75 69 6c 64 2d 69 6e 20 72 61 6e 64  he build-in rand
16b20 6f 6d 28 29 20 61 6e 64 20 72 61 6e 64 6f 6d 62  om() and randomb
16b30 6c 6f 62 28 29 20 53 51 4c 20 66 75 6e 63 74 69  lob() SQL functi
16b40 6f 6e 73 2e 20 20 54 68 69 73 20 69 6e 74 65 72  ons.  This inter
16b50 66 61 63 65 20 61 6c 6c 6f 77 73 0a 2a 2a 20 61  face allows.** a
16b60 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 6f 20 61  pplications to a
16b70 63 63 65 73 73 20 74 68 65 20 73 61 6d 65 20 50  ccess the same P
16b80 52 4e 47 20 66 6f 72 20 6f 74 68 65 72 20 70 75  RNG for other pu
16b90 72 70 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 41 20  rposes..**.** A 
16ba0 63 61 6c 6c 20 74 6f 20 74 68 69 73 20 72 6f 75  call to this rou
16bb0 74 69 6e 65 20 73 74 6f 72 65 73 20 4e 20 62 79  tine stores N by
16bc0 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73  tes of randomnes
16bd0 73 20 69 6e 74 6f 20 62 75 66 66 65 72 20 50 2e  s into buffer P.
16be0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  .**.** The first
16bf0 20 74 69 6d 65 20 74 68 69 73 20 72 6f 75 74 69   time this routi
16c00 6e 65 20 69 73 20 69 6e 76 6f 6b 65 64 20 28 65  ne is invoked (e
16c10 69 74 68 65 72 20 69 6e 74 65 72 6e 61 6c 6c 79  ither internally
16c20 20 6f 72 20 62 79 0a 2a 2a 20 74 68 65 20 61 70   or by.** the ap
16c30 70 6c 69 63 61 74 69 6f 6e 29 20 74 68 65 20 50  plication) the P
16c40 52 4e 47 20 69 73 20 73 65 65 64 65 64 20 75 73  RNG is seeded us
16c50 69 6e 67 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f  ing randomness o
16c60 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20  btained.** from 
16c70 74 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 20  the xRandomness 
16c80 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 64 65  method of the de
16c90 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76  fault [sqlite3_v
16ca0 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 4f  fs] object..** O
16cb0 6e 20 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74  n all subsequent
16cc0 20 69 6e 76 6f 63 61 74 69 6f 6e 73 2c 20 74 68   invocations, th
16cd0 65 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 6e  e pseudo-randomn
16ce0 65 73 73 20 69 73 20 67 65 6e 65 72 61 74 65 64  ess is generated
16cf0 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 6c 79 20 61  .** internally a
16d00 6e 64 20 77 69 74 68 6f 75 74 20 72 65 63 6f 75  nd without recou
16d10 72 73 65 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  rse to the [sqli
16d20 74 65 33 5f 76 66 73 5d 20 78 52 61 6e 64 6f 6d  te3_vfs] xRandom
16d30 6e 65 73 73 0a 2a 2a 20 6d 65 74 68 6f 64 2e 0a  ness.** method..
16d40 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
16d50 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33 39 32 7d  :.**.** {H17392}
16d60 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 61   The [sqlite3_ra
16d70 6e 64 6f 6d 6e 65 73 73 28 4e 2c 50 29 5d 20 69  ndomness(N,P)] i
16d80 6e 74 65 72 66 61 63 65 20 77 72 69 74 65 73 20  nterface writes 
16d90 4e 20 62 79 74 65 73 20 6f 66 0a 2a 2a 20 20 20  N bytes of.**   
16da0 20 20 20 20 20 20 20 68 69 67 68 2d 71 75 61 6c         high-qual
16db0 69 74 79 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f  ity pseudo-rando
16dc0 6d 6e 65 73 73 20 69 6e 74 6f 20 62 75 66 66 65  mness into buffe
16dd0 72 20 50 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c  r P..*/.void sql
16de0 69 74 65 33 5f 72 61 6e 64 6f 6d 6e 65 73 73 28  ite3_randomness(
16df0 69 6e 74 20 4e 2c 20 76 6f 69 64 20 2a 50 29 3b  int N, void *P);
16e00 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
16e10 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 41  : Compile-Time A
16e20 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 43 61 6c  uthorization Cal
16e30 6c 62 61 63 6b 73 20 7b 48 31 32 35 30 30 7d 20  lbacks {H12500} 
16e40 3c 53 37 30 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 54  <S70100>.**.** T
16e50 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 67 69  his routine regi
16e60 73 74 65 72 73 20 61 20 61 75 74 68 6f 72 69 7a  sters a authoriz
16e70 65 72 20 63 61 6c 6c 62 61 63 6b 20 77 69 74 68  er callback with
16e80 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a   a particular.**
16e90 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
16ea0 63 74 69 6f 6e 5d 2c 20 73 75 70 70 6c 69 65 64  ction], supplied
16eb0 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72   in the first ar
16ec0 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 61  gument..** The a
16ed0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
16ee0 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 73  ck is invoked as
16ef0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
16f00 61 72 65 20 62 65 69 6e 67 20 63 6f 6d 70 69 6c  are being compil
16f10 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65  ed.** by [sqlite
16f20 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20  3_prepare()] or 
16f30 69 74 73 20 76 61 72 69 61 6e 74 73 20 5b 73 71  its variants [sq
16f40 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
16f50 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
16f60 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 61 6e  _prepare16()] an
16f70 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  d [sqlite3_prepa
16f80 72 65 31 36 5f 76 32 28 29 5d 2e 20 20 41 74 20  re16_v2()].  At 
16f90 76 61 72 69 6f 75 73 0a 2a 2a 20 70 6f 69 6e 74  various.** point
16fa0 73 20 64 75 72 69 6e 67 20 74 68 65 20 63 6f 6d  s during the com
16fb0 70 69 6c 61 74 69 6f 6e 20 70 72 6f 63 65 73 73  pilation process
16fc0 2c 20 61 73 20 6c 6f 67 69 63 20 69 73 20 62 65  , as logic is be
16fd0 69 6e 67 20 63 72 65 61 74 65 64 0a 2a 2a 20 74  ing created.** t
16fe0 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f 75  o perform variou
16ff0 73 20 61 63 74 69 6f 6e 73 2c 20 74 68 65 20 61  s actions, the a
17000 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
17010 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f  ck is invoked to
17020 0a 2a 2a 20 73 65 65 20 69 66 20 74 68 6f 73 65  .** see if those
17030 20 61 63 74 69 6f 6e 73 20 61 72 65 20 61 6c 6c   actions are all
17040 6f 77 65 64 2e 20 20 54 68 65 20 61 75 74 68 6f  owed.  The autho
17050 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 73  rizer callback s
17060 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20  hould.** return 
17070 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 74 6f 20 61  [SQLITE_OK] to a
17080 6c 6c 6f 77 20 74 68 65 20 61 63 74 69 6f 6e 2c  llow the action,
17090 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d   [SQLITE_IGNORE]
170a0 20 74 6f 20 64 69 73 61 6c 6c 6f 77 20 74 68 65   to disallow the
170b0 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 61 63 74  .** specific act
170c0 69 6f 6e 20 62 75 74 20 61 6c 6c 6f 77 20 74 68  ion but allow th
170d0 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
170e0 74 6f 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62  to continue to b
170f0 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 2c 20 6f  e.** compiled, o
17100 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 20  r [SQLITE_DENY] 
17110 74 6f 20 63 61 75 73 65 20 74 68 65 20 65 6e 74  to cause the ent
17120 69 72 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ire SQL statemen
17130 74 20 74 6f 20 62 65 0a 2a 2a 20 72 65 6a 65 63  t to be.** rejec
17140 74 65 64 20 77 69 74 68 20 61 6e 20 65 72 72 6f  ted with an erro
17150 72 2e 20 20 49 66 20 74 68 65 20 61 75 74 68 6f  r.  If the autho
17160 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72  rizer callback r
17170 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 76 61  eturns.** any va
17180 6c 75 65 20 6f 74 68 65 72 20 74 68 61 6e 20 5b  lue other than [
17190 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 2c 20  SQLITE_IGNORE], 
171a0 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20  [SQLITE_OK], or 
171b0 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 0a 2a 2a  [SQLITE_DENY].**
171c0 20 74 68 65 6e 20 74 68 65 20 5b 73 71 6c 69 74   then the [sqlit
171d0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
171e0 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63   or equivalent c
171f0 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65 72  all that trigger
17200 65 64 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72  ed.** the author
17210 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77  izer will fail w
17220 69 74 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73  ith an error mes
17230 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e  sage..**.** When
17240 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65   the callback re
17250 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b  turns [SQLITE_OK
17260 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68  ], that means th
17270 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 72  e operation.** r
17280 65 71 75 65 73 74 65 64 20 69 73 20 6f 6b 2e 20  equested is ok. 
17290 20 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61   When the callba
172a0 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  ck returns [SQLI
172b0 54 45 5f 44 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a  TE_DENY], the.**
172c0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
172d0 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76  e_v2()] or equiv
172e0 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20  alent call that 
172f0 74 72 69 67 67 65 72 65 64 20 74 68 65 0a 2a 2a  triggered the.**
17300 20 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c   authorizer will
17310 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72   fail with an er
17320 72 6f 72 20 6d 65 73 73 61 67 65 20 65 78 70 6c  ror message expl
17330 61 69 6e 69 6e 67 20 74 68 61 74 0a 2a 2a 20 61  aining that.** a
17340 63 63 65 73 73 20 69 73 20 64 65 6e 69 65 64 2e  ccess is denied.
17350 20 20 49 66 20 74 68 65 20 61 75 74 68 6f 72 69    If the authori
17360 7a 65 72 20 63 6f 64 65 20 69 73 20 5b 53 51 4c  zer code is [SQL
17370 49 54 45 5f 52 45 41 44 5d 0a 2a 2a 20 61 6e 64  ITE_READ].** and
17380 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65   the callback re
17390 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 49 47  turns [SQLITE_IG
173a0 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 0a 2a  NORE] then the.*
173b0 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  * [prepared stat
173c0 65 6d 65 6e 74 5d 20 73 74 61 74 65 6d 65 6e 74  ement] statement
173d0 20 69 73 20 63 6f 6e 73 74 72 75 63 74 65 64 20   is constructed 
173e0 74 6f 20 73 75 62 73 74 69 74 75 74 65 0a 2a 2a  to substitute.**
173f0 20 61 20 4e 55 4c 4c 20 76 61 6c 75 65 20 69 6e   a NULL value in
17400 20 70 6c 61 63 65 20 6f 66 20 74 68 65 20 74 61   place of the ta
17410 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20  ble column that 
17420 77 6f 75 6c 64 20 68 61 76 65 0a 2a 2a 20 62 65  would have.** be
17430 65 6e 20 72 65 61 64 20 69 66 20 5b 53 51 4c 49  en read if [SQLI
17440 54 45 5f 4f 4b 5d 20 68 61 64 20 62 65 65 6e 20  TE_OK] had been 
17450 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 5b  returned.  The [
17460 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 0a 2a  SQLITE_IGNORE].*
17470 2a 20 72 65 74 75 72 6e 20 63 61 6e 20 62 65 20  * return can be 
17480 75 73 65 64 20 74 6f 20 64 65 6e 79 20 61 6e 20  used to deny an 
17490 75 6e 74 72 75 73 74 65 64 20 75 73 65 72 20 61  untrusted user a
174a0 63 63 65 73 73 20 74 6f 20 69 6e 64 69 76 69 64  ccess to individ
174b0 75 61 6c 0a 2a 2a 20 63 6f 6c 75 6d 6e 73 20 6f  ual.** columns o
174c0 66 20 61 20 74 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a  f a table..**.**
174d0 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   The first param
174e0 65 74 65 72 20 74 6f 20 74 68 65 20 61 75 74 68  eter to the auth
174f0 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
17500 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  is a copy of the
17510 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65   third.** parame
17520 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ter to the sqlit
17530 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
17540 72 28 29 20 69 6e 74 65 72 66 61 63 65 2e 20 54  r() interface. T
17550 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
17560 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61  ter.** to the ca
17570 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74  llback is an int
17580 65 67 65 72 20 5b 53 51 4c 49 54 45 5f 43 4f 50  eger [SQLITE_COP
17590 59 20 7c 20 61 63 74 69 6f 6e 20 63 6f 64 65 5d  Y | action code]
175a0 20 74 68 61 74 20 73 70 65 63 69 66 69 65 73 0a   that specifies.
175b0 2a 2a 20 74 68 65 20 70 61 72 74 69 63 75 6c 61  ** the particula
175c0 72 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61  r action to be a
175d0 75 74 68 6f 72 69 7a 65 64 2e 20 54 68 65 20 74  uthorized. The t
175e0 68 69 72 64 20 74 68 72 6f 75 67 68 20 73 69 78  hird through six
175f0 74 68 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a  th parameters.**
17600 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   to the callback
17610 20 61 72 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e   are zero-termin
17620 61 74 65 64 20 73 74 72 69 6e 67 73 20 74 68 61  ated strings tha
17630 74 20 63 6f 6e 74 61 69 6e 20 61 64 64 69 74 69  t contain additi
17640 6f 6e 61 6c 0a 2a 2a 20 64 65 74 61 69 6c 73 20  onal.** details 
17650 61 62 6f 75 74 20 74 68 65 20 61 63 74 69 6f 6e  about the action
17660 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65   to be authorize
17670 64 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74 68  d..**.** An auth
17680 6f 72 69 7a 65 72 20 69 73 20 75 73 65 64 20 77  orizer is used w
17690 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  hen [sqlite3_pre
176a0 70 61 72 65 20 7c 20 70 72 65 70 61 72 69 6e 67  pare | preparing
176b0 5d 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65  ].** SQL stateme
176c0 6e 74 73 20 66 72 6f 6d 20 61 6e 20 75 6e 74 72  nts from an untr
176d0 75 73 74 65 64 20 73 6f 75 72 63 65 2c 20 74 6f  usted source, to
176e0 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68 65   ensure that the
176f0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a   SQL statements.
17700 2a 2a 20 64 6f 20 6e 6f 74 20 74 72 79 20 74 6f  ** do not try to
17710 20 61 63 63 65 73 73 20 64 61 74 61 20 74 68 65   access data the
17720 79 20 61 72 65 20 6e 6f 74 20 61 6c 6c 6f 77 65  y are not allowe
17730 64 20 74 6f 20 73 65 65 2c 20 6f 72 20 74 68 61  d to see, or tha
17740 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a  t they do not.**
17750 20 74 72 79 20 74 6f 20 65 78 65 63 75 74 65 20   try to execute 
17760 6d 61 6c 69 63 69 6f 75 73 20 73 74 61 74 65 6d  malicious statem
17770 65 6e 74 73 20 74 68 61 74 20 64 61 6d 61 67 65  ents that damage
17780 20 74 68 65 20 64 61 74 61 62 61 73 65 2e 20 20   the database.  
17790 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20  For.** example, 
177a0 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  an application m
177b0 61 79 20 61 6c 6c 6f 77 20 61 20 75 73 65 72 20  ay allow a user 
177c0 74 6f 20 65 6e 74 65 72 20 61 72 62 69 74 72 61  to enter arbitra
177d0 72 79 0a 2a 2a 20 53 51 4c 20 71 75 65 72 69 65  ry.** SQL querie
177e0 73 20 66 6f 72 20 65 76 61 6c 75 61 74 69 6f 6e  s for evaluation
177f0 20 62 79 20 61 20 64 61 74 61 62 61 73 65 2e 20   by a database. 
17800 20 42 75 74 20 74 68 65 20 61 70 70 6c 69 63 61   But the applica
17810 74 69 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74  tion does.** not
17820 20 77 61 6e 74 20 74 68 65 20 75 73 65 72 20 74   want the user t
17830 6f 20 62 65 20 61 62 6c 65 20 74 6f 20 6d 61 6b  o be able to mak
17840 65 20 61 72 62 69 74 72 61 72 79 20 63 68 61 6e  e arbitrary chan
17850 67 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61  ges to the.** da
17860 74 61 62 61 73 65 2e 20 20 41 6e 20 61 75 74 68  tabase.  An auth
17870 6f 72 69 7a 65 72 20 63 6f 75 6c 64 20 74 68 65  orizer could the
17880 6e 20 62 65 20 70 75 74 20 69 6e 20 70 6c 61 63  n be put in plac
17890 65 20 77 68 69 6c 65 20 74 68 65 0a 2a 2a 20 75  e while the.** u
178a0 73 65 72 2d 65 6e 74 65 72 65 64 20 53 51 4c 20  ser-entered SQL 
178b0 69 73 20 62 65 69 6e 67 20 5b 73 71 6c 69 74 65  is being [sqlite
178c0 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65 70  3_prepare | prep
178d0 61 72 65 64 5d 20 74 68 61 74 0a 2a 2a 20 64 69  ared] that.** di
178e0 73 61 6c 6c 6f 77 73 20 65 76 65 72 79 74 68 69  sallows everythi
178f0 6e 67 20 65 78 63 65 70 74 20 5b 53 45 4c 45 43  ng except [SELEC
17900 54 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a  T] statements..*
17910 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e  *.** Application
17920 73 20 74 68 61 74 20 6e 65 65 64 20 74 6f 20 70  s that need to p
17930 72 6f 63 65 73 73 20 53 51 4c 20 66 72 6f 6d 20  rocess SQL from 
17940 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63 65  untrusted source
17950 73 0a 2a 2a 20 6d 69 67 68 74 20 61 6c 73 6f 20  s.** might also 
17960 63 6f 6e 73 69 64 65 72 20 6c 6f 77 65 72 69 6e  consider lowerin
17970 67 20 72 65 73 6f 75 72 63 65 20 6c 69 6d 69 74  g resource limit
17980 73 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  s using [sqlite3
17990 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 61 6e 64  _limit()].** and
179a0 20 6c 69 6d 69 74 69 6e 67 20 64 61 74 61 62 61   limiting databa
179b0 73 65 20 73 69 7a 65 20 75 73 69 6e 67 20 74 68  se size using th
179c0 65 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e  e [max_page_coun
179d0 74 5d 20 5b 50 52 41 47 4d 41 5d 0a 2a 2a 20 69  t] [PRAGMA].** i
179e0 6e 20 61 64 64 69 74 69 6f 6e 20 74 6f 20 75 73  n addition to us
179f0 69 6e 67 20 61 6e 20 61 75 74 68 6f 72 69 7a 65  ing an authorize
17a00 72 2e 0a 2a 2a 0a 2a 2a 20 4f 6e 6c 79 20 61 20  r..**.** Only a 
17a10 73 69 6e 67 6c 65 20 61 75 74 68 6f 72 69 7a 65  single authorize
17a20 72 20 63 61 6e 20 62 65 20 69 6e 20 70 6c 61 63  r can be in plac
17a30 65 20 6f 6e 20 61 20 64 61 74 61 62 61 73 65 20  e on a database 
17a40 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 61 74  connection.** at
17a50 20 61 20 74 69 6d 65 2e 20 20 45 61 63 68 20 63   a time.  Each c
17a60 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  all to sqlite3_s
17a70 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 6f 76  et_authorizer ov
17a80 65 72 72 69 64 65 73 20 74 68 65 0a 2a 2a 20 70  errides the.** p
17a90 72 65 76 69 6f 75 73 20 63 61 6c 6c 2e 20 20 44  revious call.  D
17aa0 69 73 61 62 6c 65 20 74 68 65 20 61 75 74 68 6f  isable the autho
17ab0 72 69 7a 65 72 20 62 79 20 69 6e 73 74 61 6c 6c  rizer by install
17ac0 69 6e 67 20 61 20 4e 55 4c 4c 20 63 61 6c 6c 62  ing a NULL callb
17ad0 61 63 6b 2e 0a 2a 2a 20 54 68 65 20 61 75 74 68  ack..** The auth
17ae0 6f 72 69 7a 65 72 20 69 73 20 64 69 73 61 62 6c  orizer is disabl
17af0 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a  ed by default..*
17b00 2a 0a 2a 2a 20 57 68 65 6e 20 5b 73 71 6c 69 74  *.** When [sqlit
17b10 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
17b20 20 69 73 20 75 73 65 64 20 74 6f 20 70 72 65 70   is used to prep
17b30 61 72 65 20 61 20 73 74 61 74 65 6d 65 6e 74 2c  are a statement,
17b40 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e   the.** statemen
17b50 74 20 6d 69 67 68 74 20 62 65 20 72 65 70 72 65  t might be repre
17b60 70 61 72 65 64 20 64 75 72 69 6e 67 20 5b 73 71  pared during [sq
17b70 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 64 75  lite3_step()] du
17b80 65 20 74 6f 20 61 20 0a 2a 2a 20 73 63 68 65 6d  e to a .** schem
17b90 61 20 63 68 61 6e 67 65 2e 20 20 48 65 6e 63 65  a change.  Hence
17ba0 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  , the applicatio
17bb0 6e 20 73 68 6f 75 6c 64 20 65 6e 73 75 72 65 20  n should ensure 
17bc0 74 68 61 74 20 74 68 65 0a 2a 2a 20 63 6f 72 72  that the.** corr
17bd0 65 63 74 20 61 75 74 68 6f 72 69 7a 65 72 20 63  ect authorizer c
17be0 61 6c 6c 62 61 63 6b 20 72 65 6d 61 69 6e 73 20  allback remains 
17bf0 69 6e 20 70 6c 61 63 65 20 64 75 72 69 6e 67 20  in place during 
17c00 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  the [sqlite3_ste
17c10 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65  p()]..**.** Note
17c20 20 74 68 61 74 20 74 68 65 20 61 75 74 68 6f 72   that the author
17c30 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73  izer callback is
17c40 20 69 6e 76 6f 6b 65 64 20 6f 6e 6c 79 20 64 75   invoked only du
17c50 72 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ring.** [sqlite3
17c60 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69  _prepare()] or i
17c70 74 73 20 76 61 72 69 61 6e 74 73 2e 20 20 41 75  ts variants.  Au
17c80 74 68 6f 72 69 7a 61 74 69 6f 6e 20 69 73 20 6e  thorization is n
17c90 6f 74 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20  ot.** performed 
17ca0 64 75 72 69 6e 67 20 73 74 61 74 65 6d 65 6e 74  during statement
17cb0 20 65 76 61 6c 75 61 74 69 6f 6e 20 69 6e 20 5b   evaluation in [
17cc0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e  sqlite3_step()].
17cd0 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
17ce0 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 30 31  S:.**.** {H12501
17cf0 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  } The [sqlite3_s
17d00 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 44 2c  et_authorizer(D,
17d10 2e 2e 2e 29 5d 20 69 6e 74 65 72 66 61 63 65 20  ...)] interface 
17d20 72 65 67 69 73 74 65 72 73 20 61 0a 2a 2a 20 20  registers a.**  
17d30 20 20 20 20 20 20 20 20 61 75 74 68 6f 72 69 7a          authoriz
17d40 65 72 20 63 61 6c 6c 62 61 63 6b 20 77 69 74 68  er callback with
17d50 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
17d60 74 69 6f 6e 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 48  tion D..**.** {H
17d70 31 32 35 30 32 7d 20 54 68 65 20 61 75 74 68 6f  12502} The autho
17d80 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  rizer callback i
17d90 73 20 69 6e 76 6f 6b 65 64 20 61 73 20 53 51 4c  s invoked as SQL
17da0 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 0a   statements are.
17db0 2a 2a 20 20 20 20 20 20 20 20 20 20 62 65 69 6e  **          bein
17dc0 67 20 70 61 72 73 65 65 64 20 61 6e 64 20 63 6f  g parseed and co
17dd0 6d 70 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48  mpiled..**.** {H
17de0 31 32 35 30 33 7d 20 49 66 20 74 68 65 20 61 75  12503} If the au
17df0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
17e00 6b 20 72 65 74 75 72 6e 73 20 61 6e 79 20 76 61  k returns any va
17e10 6c 75 65 20 6f 74 68 65 72 20 74 68 61 6e 0a 2a  lue other than.*
17e20 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49  *          [SQLI
17e30 54 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53 51 4c  TE_IGNORE], [SQL
17e40 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 51 4c  ITE_OK], or [SQL
17e50 49 54 45 5f 44 45 4e 59 5d 2c 20 74 68 65 6e 0a  ITE_DENY], then.
17e60 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
17e70 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 6e 74 65  application inte
17e80 72 66 61 63 65 20 63 61 6c 6c 20 74 68 61 74 20  rface call that 
17e90 63 61 75 73 65 64 0a 2a 2a 20 20 20 20 20 20 20  caused.**       
17ea0 20 20 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65     the authorize
17eb0 72 20 63 61 6c 6c 62 61 63 6b 20 74 6f 20 72 75  r callback to ru
17ec0 6e 20 73 68 61 6c 6c 20 66 61 69 6c 20 77 69 74  n shall fail wit
17ed0 68 20 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  h an.**         
17ee0 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
17ef0 65 72 72 6f 72 20 63 6f 64 65 20 61 6e 64 20 61  error code and a
17f00 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20 65 72  n appropriate er
17f10 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a  ror message..**.
17f20 2a 2a 20 7b 48 31 32 35 30 34 7d 20 57 68 65 6e  ** {H12504} When
17f30 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
17f40 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
17f50 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68   [SQLITE_OK], th
17f60 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 20  e operation.**  
17f70 20 20 20 20 20 20 20 20 64 65 73 63 72 69 62 65          describe
17f80 64 20 69 73 20 70 72 6f 63 65 73 73 65 64 20 6e  d is processed n
17f90 6f 72 6d 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 7b  ormally..**.** {
17fa0 48 31 32 35 30 35 7d 20 57 68 65 6e 20 74 68 65  H12505} When the
17fb0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
17fc0 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51  back returns [SQ
17fd0 4c 49 54 45 5f 44 45 4e 59 5d 2c 20 74 68 65 0a  LITE_DENY], the.
17fe0 2a 2a 20 20 20 20 20 20 20 20 20 20 61 70 70 6c  **          appl
17ff0 69 63 61 74 69 6f 6e 20 69 6e 74 65 72 66 61 63  ication interfac
18000 65 20 63 61 6c 6c 20 74 68 61 74 20 63 61 75 73  e call that caus
18010 65 64 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  ed the.**       
18020 20 20 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61     authorizer ca
18030 6c 6c 62 61 63 6b 20 74 6f 20 72 75 6e 20 73 68  llback to run sh
18040 61 6c 6c 20 66 61 69 6c 0a 2a 2a 20 20 20 20 20  all fail.**     
18050 20 20 20 20 20 77 69 74 68 20 61 6e 20 5b 53 51       with an [SQ
18060 4c 49 54 45 5f 45 52 52 4f 52 5d 20 65 72 72 6f  LITE_ERROR] erro
18070 72 20 63 6f 64 65 20 61 6e 64 20 61 6e 20 65 72  r code and an er
18080 72 6f 72 20 6d 65 73 73 61 67 65 0a 2a 2a 20 20  ror message.**  
18090 20 20 20 20 20 20 20 20 65 78 70 6c 61 69 6e 69          explaini
180a0 6e 67 20 74 68 61 74 20 61 63 63 65 73 73 20 69  ng that access i
180b0 73 20 64 65 6e 69 65 64 2e 0a 2a 2a 0a 2a 2a 20  s denied..**.** 
180c0 7b 48 31 32 35 30 36 7d 20 49 66 20 74 68 65 20  {H12506} If the 
180d0 61 75 74 68 6f 72 69 7a 65 72 20 63 6f 64 65 20  authorizer code 
180e0 28 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74  (the 2nd paramet
180f0 65 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72  er to the author
18100 69 7a 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  izer.**         
18110 20 63 61 6c 6c 62 61 63 6b 29 20 69 73 20 5b 53   callback) is [S
18120 51 4c 49 54 45 5f 52 45 41 44 5d 20 61 6e 64 20  QLITE_READ] and 
18130 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
18140 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a  allback returns.
18150 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c  **          [SQL
18160 49 54 45 5f 49 47 4e 4f 52 45 5d 2c 20 74 68 65  ITE_IGNORE], the
18170 6e 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73  n the prepared s
18180 74 61 74 65 6d 65 6e 74 20 69 73 20 63 6f 6e 73  tatement is cons
18190 74 72 75 63 74 65 64 20 74 6f 0a 2a 2a 20 20 20  tructed to.**   
181a0 20 20 20 20 20 20 20 69 6e 73 65 72 74 20 61 20         insert a 
181b0 4e 55 4c 4c 20 76 61 6c 75 65 20 69 6e 20 70 6c  NULL value in pl
181c0 61 63 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65  ace of the table
181d0 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 77 6f 75   column that wou
181e0 6c 64 20 68 61 76 65 0a 2a 2a 20 20 20 20 20 20  ld have.**      
181f0 20 20 20 20 62 65 65 6e 20 72 65 61 64 20 69 66      been read if
18200 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 68 61 64   [SQLITE_OK] had
18210 20 62 65 65 6e 20 72 65 74 75 72 6e 65 64 2e 0a   been returned..
18220 2a 2a 0a 2a 2a 20 7b 48 31 32 35 30 37 7d 20 49  **.** {H12507} I
18230 66 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  f the authorizer
18240 20 63 6f 64 65 20 28 74 68 65 20 32 6e 64 20 70   code (the 2nd p
18250 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
18260 61 75 74 68 6f 72 69 7a 65 72 0a 2a 2a 20 20 20  authorizer.**   
18270 20 20 20 20 20 20 20 63 61 6c 6c 62 61 63 6b 29         callback)
18280 20 69 73 20 61 6e 79 74 68 69 6e 67 20 6f 74 68   is anything oth
18290 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
182a0 52 45 41 44 5d 2c 20 74 68 65 6e 0a 2a 2a 20 20  READ], then.**  
182b0 20 20 20 20 20 20 20 20 61 20 72 65 74 75 72 6e          a return
182c0 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f   of [SQLITE_IGNO
182d0 52 45 5d 20 68 61 73 20 74 68 65 20 73 61 6d 65  RE] has the same
182e0 20 65 66 66 65 63 74 20 61 73 20 5b 53 51 4c 49   effect as [SQLI
182f0 54 45 5f 44 45 4e 59 5d 2e 0a 2a 2a 0a 2a 2a 20  TE_DENY]..**.** 
18300 7b 48 31 32 35 31 30 7d 20 54 68 65 20 66 69 72  {H12510} The fir
18310 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
18320 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
18330 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70  allback is a cop
18340 79 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20  y of.**         
18350 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d   the third param
18360 65 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c  eter to the [sql
18370 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
18380 7a 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65  zer()] interface
18390 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 31 31 7d  ..**.** {H12511}
183a0 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   The second para
183b0 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 61 6c  meter to the cal
183c0 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65  lback is an inte
183d0 67 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ger.**          
183e0 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20 61  [SQLITE_COPY | a
183f0 63 74 69 6f 6e 20 63 6f 64 65 5d 20 74 68 61 74  ction code] that
18400 20 73 70 65 63 69 66 69 65 73 20 74 68 65 20 70   specifies the p
18410 61 72 74 69 63 75 6c 61 72 20 61 63 74 69 6f 6e  articular action
18420 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20  .**          to 
18430 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 0a 2a  be authorized..*
18440 2a 0a 2a 2a 20 7b 48 31 32 35 31 32 7d 20 54 68  *.** {H12512} Th
18450 65 20 74 68 69 72 64 20 74 68 72 6f 75 67 68 20  e third through 
18460 73 69 78 74 68 20 70 61 72 61 6d 65 74 65 72 73  sixth parameters
18470 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   to the callback
18480 20 61 72 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   are.**         
18490 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
184a0 20 73 74 72 69 6e 67 73 20 74 68 61 74 20 63 6f   strings that co
184b0 6e 74 61 69 6e 0a 2a 2a 20 20 20 20 20 20 20 20  ntain.**        
184c0 20 20 61 64 64 69 74 69 6f 6e 61 6c 20 64 65 74    additional det
184d0 61 69 6c 73 20 61 62 6f 75 74 20 74 68 65 20 61  ails about the a
184e0 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68  ction to be auth
184f0 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48  orized..**.** {H
18500 31 32 35 32 30 7d 20 45 61 63 68 20 63 61 6c 6c  12520} Each call
18510 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 65 74   to [sqlite3_set
18520 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 20 6f  _authorizer()] o
18530 76 65 72 72 69 64 65 73 0a 2a 2a 20 20 20 20 20  verrides.**     
18540 20 20 20 20 20 61 6e 79 20 70 72 65 76 69 6f 75       any previou
18550 73 6c 79 20 69 6e 73 74 61 6c 6c 65 64 20 61 75  sly installed au
18560 74 68 6f 72 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20  thorizer..**.** 
18570 7b 48 31 32 35 32 31 7d 20 41 20 4e 55 4c 4c 20  {H12521} A NULL 
18580 61 75 74 68 6f 72 69 7a 65 72 20 6d 65 61 6e 73  authorizer means
18590 20 74 68 61 74 20 6e 6f 20 61 75 74 68 6f 72 69   that no authori
185a0 7a 61 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20  zation.**       
185b0 20 20 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69     callback is i
185c0 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48  nvoked..**.** {H
185d0 31 32 35 32 32 7d 20 54 68 65 20 64 65 66 61 75  12522} The defau
185e0 6c 74 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73  lt authorizer is
185f0 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 71   NULL..*/.int sq
18600 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
18610 69 7a 65 72 28 0a 20 20 73 71 6c 69 74 65 33 2a  izer(.  sqlite3*
18620 2c 0a 20 20 69 6e 74 20 28 2a 78 41 75 74 68 29  ,.  int (*xAuth)
18630 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74  (void*,int,const
18640 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61   char*,const cha
18650 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63  r*,const char*,c
18660 6f 6e 73 74 20 63 68 61 72 2a 29 2c 0a 20 20 76  onst char*),.  v
18670 6f 69 64 20 2a 70 55 73 65 72 44 61 74 61 0a 29  oid *pUserData.)
18680 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
18690 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 52 65  F: Authorizer Re
186a0 74 75 72 6e 20 43 6f 64 65 73 20 7b 48 31 32 35  turn Codes {H125
186b0 39 30 7d 20 3c 48 31 32 35 30 30 3e 0a 2a 2a 0a  90} <H12500>.**.
186c0 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** The [sqlite3_
186d0 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c  set_authorizer |
186e0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
186f0 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 5d 20 6d  back function] m
18700 75 73 74 0a 2a 2a 20 72 65 74 75 72 6e 20 65 69  ust.** return ei
18710 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  ther [SQLITE_OK]
18720 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 73 65   or one of these
18730 20 74 77 6f 20 63 6f 6e 73 74 61 6e 74 73 20 69   two constants i
18740 6e 20 6f 72 64 65 72 0a 2a 2a 20 74 6f 20 73 69  n order.** to si
18750 67 6e 61 6c 20 53 51 4c 69 74 65 20 77 68 65 74  gnal SQLite whet
18760 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 61  her or not the a
18770 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74  ction is permitt
18780 65 64 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a 20  ed.  See the.** 
18790 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74  [sqlite3_set_aut
187a0 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72  horizer | author
187b0 69 7a 65 72 20 64 6f 63 75 6d 65 6e 74 61 74 69  izer documentati
187c0 6f 6e 5d 20 66 6f 72 20 61 64 64 69 74 69 6f 6e  on] for addition
187d0 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  al.** informatio
187e0 6e 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  n..*/.#define SQ
187f0 4c 49 54 45 5f 44 45 4e 59 20 20 20 31 20 20 20  LITE_DENY   1   
18800 2f 2a 20 41 62 6f 72 74 20 74 68 65 20 53 51 4c  /* Abort the SQL
18810 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 20   statement with 
18820 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66  an error */.#def
18830 69 6e 65 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52  ine SQLITE_IGNOR
18840 45 20 32 20 20 20 2f 2a 20 44 6f 6e 27 74 20 61  E 2   /* Don't a
18850 6c 6c 6f 77 20 61 63 63 65 73 73 2c 20 62 75 74  llow access, but
18860 20 64 6f 6e 27 74 20 67 65 6e 65 72 61 74 65 20   don't generate 
18870 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a  an error */../*.
18880 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75 74  ** CAPI3REF: Aut
18890 68 6f 72 69 7a 65 72 20 41 63 74 69 6f 6e 20 43  horizer Action C
188a0 6f 64 65 73 20 7b 48 31 32 35 35 30 7d 20 3c 48  odes {H12550} <H
188b0 31 32 35 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  12500>.**.** The
188c0 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75   [sqlite3_set_au
188d0 74 68 6f 72 69 7a 65 72 28 29 5d 20 69 6e 74 65  thorizer()] inte
188e0 72 66 61 63 65 20 72 65 67 69 73 74 65 72 73 20  rface registers 
188f0 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  a callback funct
18900 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 69 73 20 69  ion.** that is i
18910 6e 76 6f 6b 65 64 20 74 6f 20 61 75 74 68 6f 72  nvoked to author
18920 69 7a 65 20 63 65 72 74 61 69 6e 20 53 51 4c 20  ize certain SQL 
18930 73 74 61 74 65 6d 65 6e 74 20 61 63 74 69 6f 6e  statement action
18940 73 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e  s.  The.** secon
18950 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  d parameter to t
18960 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  he callback is a
18970 6e 20 69 6e 74 65 67 65 72 20 63 6f 64 65 20 74  n integer code t
18980 68 61 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a  hat specifies.**
18990 20 77 68 61 74 20 61 63 74 69 6f 6e 20 69 73 20   what action is 
189a0 62 65 69 6e 67 20 61 75 74 68 6f 72 69 7a 65 64  being authorized
189b0 2e 20 20 54 68 65 73 65 20 61 72 65 20 74 68 65  .  These are the
189c0 20 69 6e 74 65 67 65 72 20 61 63 74 69 6f 6e 20   integer action 
189d0 63 6f 64 65 73 20 74 68 61 74 0a 2a 2a 20 74 68  codes that.** th
189e0 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
189f0 6c 62 61 63 6b 20 6d 61 79 20 62 65 20 70 61 73  lback may be pas
18a00 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  sed..**.** These
18a10 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 76 61 6c   action code val
18a20 75 65 73 20 73 69 67 6e 69 66 79 20 77 68 61 74  ues signify what
18a30 20 6b 69 6e 64 20 6f 66 20 6f 70 65 72 61 74 69   kind of operati
18a40 6f 6e 20 69 73 20 74 6f 20 62 65 0a 2a 2a 20 61  on is to be.** a
18a50 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 20  uthorized.  The 
18a60 33 72 64 20 61 6e 64 20 34 74 68 20 70 61 72 61  3rd and 4th para
18a70 6d 65 74 65 72 73 20 74 6f 20 74 68 65 20 61 75  meters to the au
18a80 74 68 6f 72 69 7a 61 74 69 6f 6e 0a 2a 2a 20 63  thorization.** c
18a90 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
18aa0 20 77 69 6c 6c 20 62 65 20 70 61 72 61 6d 65 74   will be paramet
18ab0 65 72 73 20 6f 72 20 4e 55 4c 4c 20 64 65 70 65  ers or NULL depe
18ac0 6e 64 69 6e 67 20 6f 6e 20 77 68 69 63 68 20 6f  nding on which o
18ad0 66 20 74 68 65 73 65 0a 2a 2a 20 63 6f 64 65 73  f these.** codes
18ae0 20 69 73 20 75 73 65 64 20 61 73 20 74 68 65 20   is used as the 
18af0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
18b00 2e 20 20 54 68 65 20 35 74 68 20 70 61 72 61 6d  .  The 5th param
18b10 65 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 61  eter to the.** a
18b20 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
18b30 63 6b 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f  ck is the name o
18b40 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 28  f the database (
18b50 22 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c 0a  "main", "temp",.
18b60 2a 2a 20 65 74 63 2e 29 20 69 66 20 61 70 70 6c  ** etc.) if appl
18b70 69 63 61 62 6c 65 2e 20 20 54 68 65 20 36 74 68  icable.  The 6th
18b80 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
18b90 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
18ba0 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 74 68 65 20  lback.** is the 
18bb0 6e 61 6d 65 20 6f 66 20 74 68 65 20 69 6e 6e 65  name of the inne
18bc0 72 2d 6d 6f 73 74 20 74 72 69 67 67 65 72 20 6f  r-most trigger o
18bd0 72 20 76 69 65 77 20 74 68 61 74 20 69 73 20 72  r view that is r
18be0 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 0a 2a  esponsible for.*
18bf0 2a 20 74 68 65 20 61 63 63 65 73 73 20 61 74 74  * the access att
18c00 65 6d 70 74 20 6f 72 20 4e 55 4c 4c 20 69 66 20  empt or NULL if 
18c10 74 68 69 73 20 61 63 63 65 73 73 20 61 74 74 65  this access atte
18c20 6d 70 74 20 69 73 20 64 69 72 65 63 74 6c 79 20  mpt is directly 
18c30 66 72 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65  from.** top-leve
18c40 6c 20 53 51 4c 20 63 6f 64 65 2e 0a 2a 2a 0a 2a  l SQL code..**.*
18c50 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
18c60 0a 2a 2a 20 7b 48 31 32 35 35 31 7d 20 54 68 65  .** {H12551} The
18c70 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
18c80 72 20 74 6f 20 61 6e 0a 2a 2a 20 20 20 20 20 20  r to an.**      
18c90 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 73 65 74      [sqlite3_set
18ca0 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75  _authorizer | au
18cb0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
18cc0 6b 5d 20 73 68 61 6c 6c 20 62 65 20 61 6e 20 69  k] shall be an i
18cd0 6e 74 65 67 65 72 0a 2a 2a 20 20 20 20 20 20 20  nteger.**       
18ce0 20 20 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20     [SQLITE_COPY 
18cf0 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 63 6f 64  | authorizer cod
18d00 65 5d 20 74 68 61 74 20 73 70 65 63 69 66 69 65  e] that specifie
18d10 73 20 77 68 61 74 20 61 63 74 69 6f 6e 0a 2a 2a  s what action.**
18d20 20 20 20 20 20 20 20 20 20 20 69 73 20 62 65 69            is bei
18d30 6e 67 20 61 75 74 68 6f 72 69 7a 65 64 2e 0a 2a  ng authorized..*
18d40 2a 0a 2a 2a 20 7b 48 31 32 35 35 32 7d 20 54 68  *.** {H12552} Th
18d50 65 20 33 72 64 20 61 6e 64 20 34 74 68 20 70 61  e 3rd and 4th pa
18d60 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68 65 0a  rameters to the.
18d70 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
18d80 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
18d90 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 61 74  zer | authorizat
18da0 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 5d 0a 2a 2a  ion callback].**
18db0 20 20 20 20 20 20 20 20 20 20 73 68 61 6c 6c 20            shall 
18dc0 62 65 20 70 61 72 61 6d 65 74 65 72 73 20 6f 72  be parameters or
18dd0 20 4e 55 4c 4c 20 64 65 70 65 6e 64 69 6e 67 20   NULL depending 
18de0 6f 6e 20 77 68 69 63 68 0a 2a 2a 20 20 20 20 20  on which.**     
18df0 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 43 4f 50       [SQLITE_COP
18e00 59 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 63  Y | authorizer c
18e10 6f 64 65 5d 20 69 73 20 75 73 65 64 20 61 73 20  ode] is used as 
18e20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  the second param
18e30 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  eter..**.** {H12
18e40 35 35 33 7d 20 54 68 65 20 35 74 68 20 70 61 72  553} The 5th par
18e50 61 6d 65 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a  ameter to the.**
18e60 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
18e70 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
18e80 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 63  r | authorizer c
18e90 61 6c 6c 62 61 63 6b 5d 20 73 68 61 6c 6c 20 62  allback] shall b
18ea0 65 20 74 68 65 20 6e 61 6d 65 0a 2a 2a 20 20 20  e the name.**   
18eb0 20 20 20 20 20 20 20 6f 66 20 74 68 65 20 64 61         of the da
18ec0 74 61 62 61 73 65 20 28 65 78 61 6d 70 6c 65 3a  tabase (example:
18ed0 20 22 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c   "main", "temp",
18ee0 20 65 74 63 2e 29 20 69 66 20 61 70 70 6c 69 63   etc.) if applic
18ef0 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  able..**.** {H12
18f00 35 35 34 7d 20 54 68 65 20 36 74 68 20 70 61 72  554} The 6th par
18f10 61 6d 65 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a  ameter to the.**
18f20 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
18f30 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
18f40 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 63  r | authorizer c
18f50 61 6c 6c 62 61 63 6b 5d 20 73 68 61 6c 6c 20 62  allback] shall b
18f60 65 20 74 68 65 20 6e 61 6d 65 0a 2a 2a 20 20 20  e the name.**   
18f70 20 20 20 20 20 20 20 6f 66 20 74 68 65 20 69 6e         of the in
18f80 6e 65 72 2d 6d 6f 73 74 20 74 72 69 67 67 65 72  ner-most trigger
18f90 20 6f 72 20 76 69 65 77 20 74 68 61 74 20 69 73   or view that is
18fa0 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72   responsible for
18fb0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
18fc0 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 74 20   access attempt 
18fd0 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 69 73 20  or NULL if this 
18fe0 61 63 63 65 73 73 20 61 74 74 65 6d 70 74 20 69  access attempt i
18ff0 73 20 64 69 72 65 63 74 6c 79 20 66 72 6f 6d 0a  s directly from.
19000 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f 70 2d  **          top-
19010 6c 65 76 65 6c 20 53 51 4c 20 63 6f 64 65 2e 0a  level SQL code..
19020 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  */./************
19030 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
19040 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20  *************** 
19050 33 72 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  3rd ************
19060 20 34 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a   4th ***********
19070 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
19080 5f 43 52 45 41 54 45 5f 49 4e 44 45 58 20 20 20  _CREATE_INDEX   
19090 20 20 20 20 20 20 20 31 20 20 20 2f 2a 20 49 6e         1   /* In
190a0 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61  dex Name      Ta
190b0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
190c0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
190d0 43 52 45 41 54 45 5f 54 41 42 4c 45 20 20 20 20  CREATE_TABLE    
190e0 20 20 20 20 20 20 32 20 20 20 2f 2a 20 54 61 62        2   /* Tab
190f0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
19100 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
19110 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
19120 52 45 41 54 45 5f 54 45 4d 50 5f 49 4e 44 45 58  REATE_TEMP_INDEX
19130 20 20 20 20 20 33 20 20 20 2f 2a 20 49 6e 64 65       3   /* Inde
19140 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c  x Name      Tabl
19150 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
19160 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
19170 45 41 54 45 5f 54 45 4d 50 5f 54 41 42 4c 45 20  EATE_TEMP_TABLE 
19180 20 20 20 20 34 20 20 20 2f 2a 20 54 61 62 6c 65      4   /* Table
19190 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
191a0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
191b0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
191c0 41 54 45 5f 54 45 4d 50 5f 54 52 49 47 47 45 52  ATE_TEMP_TRIGGER
191d0 20 20 20 35 20 20 20 2f 2a 20 54 72 69 67 67 65     5   /* Trigge
191e0 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20  r Name    Table 
191f0 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
19200 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
19210 54 45 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20  TE_TEMP_VIEW    
19220 20 20 36 20 20 20 2f 2a 20 56 69 65 77 20 4e 61    6   /* View Na
19230 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  me       NULL   
19240 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
19250 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
19260 45 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 20  E_TRIGGER       
19270 20 37 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20   7   /* Trigger 
19280 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61  Name    Table Na
19290 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
192a0 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
192b0 5f 56 49 45 57 20 20 20 20 20 20 20 20 20 20 20  _VIEW           
192c0 38 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65  8   /* View Name
192d0 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
192e0 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
192f0 65 20 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 20  e SQLITE_DELETE 
19300 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 39                 9
19310 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
19320 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
19330 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
19340 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 49 4e 44   SQLITE_DROP_IND
19350 45 58 20 20 20 20 20 20 20 20 20 20 20 31 30 20  EX           10 
19360 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20    /* Index Name 
19370 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20       Table Name 
19380 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
19390 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 41 42 4c  SQLITE_DROP_TABL
193a0 45 20 20 20 20 20 20 20 20 20 20 20 31 31 20 20  E           11  
193b0 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
193c0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
193d0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
193e0 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f  QLITE_DROP_TEMP_
193f0 49 4e 44 45 58 20 20 20 20 20 20 31 32 20 20 20  INDEX      12   
19400 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20  /* Index Name   
19410 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
19420 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
19430 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54  LITE_DROP_TEMP_T
19440 41 42 4c 45 20 20 20 20 20 20 31 33 20 20 20 2f  ABLE      13   /
19450 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
19460 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
19470 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
19480 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 52  ITE_DROP_TEMP_TR
19490 49 47 47 45 52 20 20 20 20 31 34 20 20 20 2f 2a  IGGER    14   /*
194a0 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20   Trigger Name   
194b0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
194c0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
194d0 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 56 49 45  TE_DROP_TEMP_VIE
194e0 57 20 20 20 20 20 20 20 31 35 20 20 20 2f 2a 20  W       15   /* 
194f0 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20  View Name       
19500 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
19510 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
19520 45 5f 44 52 4f 50 5f 54 52 49 47 47 45 52 20 20  E_DROP_TRIGGER  
19530 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a 20 54         16   /* T
19540 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54  rigger Name    T
19550 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
19560 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
19570 5f 44 52 4f 50 5f 56 49 45 57 20 20 20 20 20 20  _DROP_VIEW      
19580 20 20 20 20 20 20 31 37 20 20 20 2f 2a 20 56 69        17   /* Vi
19590 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55  ew Name       NU
195a0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
195b0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
195c0 49 4e 53 45 52 54 20 20 20 20 20 20 20 20 20 20  INSERT          
195d0 20 20 20 20 20 31 38 20 20 20 2f 2a 20 54 61 62       18   /* Tab
195e0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
195f0 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
19600 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50  #define SQLITE_P
19610 52 41 47 4d 41 20 20 20 20 20 20 20 20 20 20 20  RAGMA           
19620 20 20 20 20 31 39 20 20 20 2f 2a 20 50 72 61 67      19   /* Prag
19630 6d 61 20 4e 61 6d 65 20 20 20 20 20 31 73 74 20  ma Name     1st 
19640 61 72 67 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 23  arg or NULL */.#
19650 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45  define SQLITE_RE
19660 41 44 20 20 20 20 20 20 20 20 20 20 20 20 20 20  AD              
19670 20 20 20 32 30 20 20 20 2f 2a 20 54 61 62 6c 65     20   /* Table
19680 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d   Name      Colum
19690 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64  n Name     */.#d
196a0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 4c  efine SQLITE_SEL
196b0 45 43 54 20 20 20 20 20 20 20 20 20 20 20 20 20  ECT             
196c0 20 20 32 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20    21   /* NULL  
196d0 20 20 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20            NULL  
196e0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
196f0 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 4e  fine SQLITE_TRAN
19700 53 41 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20  SACTION         
19710 20 32 32 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20   22   /* NULL   
19720 20 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20           NULL   
19730 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
19740 69 6e 65 20 53 51 4c 49 54 45 5f 55 50 44 41 54  ine SQLITE_UPDAT
19750 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  E               
19760 32 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  23   /* Table Na
19770 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e  me      Column N
19780 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  ame     */.#defi
19790 6e 65 20 53 51 4c 49 54 45 5f 41 54 54 41 43 48  ne SQLITE_ATTACH
197a0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
197b0 34 20 20 20 2f 2a 20 46 69 6c 65 6e 61 6d 65 20  4   /* Filename 
197c0 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
197d0 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
197e0 65 20 53 51 4c 49 54 45 5f 44 45 54 41 43 48 20  e SQLITE_DETACH 
197f0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 35                25
19800 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e     /* Database N
19810 61 6d 65 20 20 20 4e 55 4c 4c 20 20 20 20 20 20  ame   NULL      
19820 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
19830 20 53 51 4c 49 54 45 5f 41 4c 54 45 52 5f 54 41   SQLITE_ALTER_TA
19840 42 4c 45 20 20 20 20 20 20 20 20 20 20 32 36 20  BLE          26 
19850 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61    /* Database Na
19860 6d 65 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20  me   Table Name 
19870 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
19880 53 51 4c 49 54 45 5f 52 45 49 4e 44 45 58 20 20  SQLITE_REINDEX  
19890 20 20 20 20 20 20 20 20 20 20 20 20 32 37 20 20              27  
198a0 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20   /* Index Name  
198b0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
198c0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
198d0 51 4c 49 54 45 5f 41 4e 41 4c 59 5a 45 20 20 20  QLITE_ANALYZE   
198e0 20 20 20 20 20 20 20 20 20 20 20 32 38 20 20 20             28   
198f0 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
19900 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
19910 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
19920 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 54 41 42  LITE_CREATE_VTAB
19930 4c 45 20 20 20 20 20 20 20 20 32 39 20 20 20 2f  LE        29   /
19940 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
19950 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20    Module Name   
19960 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
19970 49 54 45 5f 44 52 4f 50 5f 56 54 41 42 4c 45 20  ITE_DROP_VTABLE 
19980 20 20 20 20 20 20 20 20 20 33 30 20 20 20 2f 2a           30   /*
19990 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
199a0 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20   Module Name    
199b0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
199c0 54 45 5f 46 55 4e 43 54 49 4f 4e 20 20 20 20 20  TE_FUNCTION     
199d0 20 20 20 20 20 20 20 20 33 31 20 20 20 2f 2a 20          31   /* 
199e0 46 75 6e 63 74 69 6f 6e 20 4e 61 6d 65 20 20 20  Function Name   
199f0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
19a00 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
19a10 45 5f 43 4f 50 59 20 20 20 20 20 20 20 20 20 20  E_COPY          
19a20 20 20 20 20 20 20 20 20 30 20 20 20 2f 2a 20 4e          0   /* N
19a30 6f 20 6c 6f 6e 67 65 72 20 75 73 65 64 20 2a 2f  o longer used */
19a40 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
19a50 3a 20 54 72 61 63 69 6e 67 20 41 6e 64 20 50 72  : Tracing And Pr
19a60 6f 66 69 6c 69 6e 67 20 46 75 6e 63 74 69 6f 6e  ofiling Function
19a70 73 20 7b 48 31 32 32 38 30 7d 20 3c 53 36 30 34  s {H12280} <S604
19a80 30 30 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e  00>.** EXPERIMEN
19a90 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  TAL.**.** These 
19aa0 72 6f 75 74 69 6e 65 73 20 72 65 67 69 73 74 65  routines registe
19ab0 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  r callback funct
19ac0 69 6f 6e 73 20 74 68 61 74 20 63 61 6e 20 62 65  ions that can be
19ad0 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74 72 61   used for.** tra
19ae0 63 69 6e 67 20 61 6e 64 20 70 72 6f 66 69 6c 69  cing and profili
19af0 6e 67 20 74 68 65 20 65 78 65 63 75 74 69 6f 6e  ng the execution
19b00 20 6f 66 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   of SQL statemen
19b10 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61  ts..**.** The ca
19b20 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
19b30 72 65 67 69 73 74 65 72 65 64 20 62 79 20 73 71  registered by sq
19b40 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 69 73  lite3_trace() is
19b50 20 69 6e 76 6f 6b 65 64 20 61 74 0a 2a 2a 20 76   invoked at.** v
19b60 61 72 69 6f 75 73 20 74 69 6d 65 73 20 77 68 65  arious times whe
19b70 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  n an SQL stateme
19b80 6e 74 20 69 73 20 62 65 69 6e 67 20 72 75 6e 20  nt is being run 
19b90 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  by [sqlite3_step
19ba0 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c  ()]..** The call
19bb0 62 61 63 6b 20 72 65 74 75 72 6e 73 20 61 20 55  back returns a U
19bc0 54 46 2d 38 20 72 65 6e 64 65 72 69 6e 67 20 6f  TF-8 rendering o
19bd0 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  f the SQL statem
19be0 65 6e 74 20 74 65 78 74 0a 2a 2a 20 61 73 20 74  ent text.** as t
19bf0 68 65 20 73 74 61 74 65 6d 65 6e 74 20 66 69 72  he statement fir
19c00 73 74 20 62 65 67 69 6e 73 20 65 78 65 63 75 74  st begins execut
19c10 69 6e 67 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c  ing.  Additional
19c20 20 63 61 6c 6c 62 61 63 6b 73 20 6f 63 63 75 72   callbacks occur
19c30 0a 2a 2a 20 61 73 20 65 61 63 68 20 74 72 69 67  .** as each trig
19c40 67 65 72 65 64 20 73 75 62 70 72 6f 67 72 61 6d  gered subprogram
19c50 20 69 73 20 65 6e 74 65 72 65 64 2e 20 20 54 68   is entered.  Th
19c60 65 20 63 61 6c 6c 62 61 63 6b 73 20 66 6f 72 20  e callbacks for 
19c70 74 72 69 67 67 65 72 73 0a 2a 2a 20 63 6f 6e 74  triggers.** cont
19c80 61 69 6e 20 61 20 55 54 46 2d 38 20 53 51 4c 20  ain a UTF-8 SQL 
19c90 63 6f 6d 6d 65 6e 74 20 74 68 61 74 20 69 64 65  comment that ide
19ca0 6e 74 69 66 69 65 73 20 74 68 65 20 74 72 69 67  ntifies the trig
19cb0 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63  ger..**.** The c
19cc0 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
19cd0 20 72 65 67 69 73 74 65 72 65 64 20 62 79 20 73   registered by s
19ce0 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29  qlite3_profile()
19cf0 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61   is invoked.** a
19d00 73 20 65 61 63 68 20 53 51 4c 20 73 74 61 74 65  s each SQL state
19d10 6d 65 6e 74 20 66 69 6e 69 73 68 65 73 2e 20 20  ment finishes.  
19d20 54 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c  The profile call
19d30 62 61 63 6b 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a  back contains.**
19d40 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74   the original st
19d50 61 74 65 6d 65 6e 74 20 74 65 78 74 20 61 6e 64  atement text and
19d60 20 61 6e 20 65 73 74 69 6d 61 74 65 20 6f 66 20   an estimate of 
19d70 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d 65 0a  wall-clock time.
19d80 2a 2a 20 6f 66 20 68 6f 77 20 6c 6f 6e 67 20 74  ** of how long t
19d90 68 61 74 20 73 74 61 74 65 6d 65 6e 74 20 74 6f  hat statement to
19da0 6f 6b 20 74 6f 20 72 75 6e 2e 0a 2a 2a 0a 2a 2a  ok to run..**.**
19db0 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
19dc0 2a 2a 20 7b 48 31 32 32 38 31 7d 20 54 68 65 20  ** {H12281} The 
19dd0 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
19de0 6e 20 72 65 67 69 73 74 65 72 65 64 20 62 79 20  n registered by 
19df0 5b 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29  [sqlite3_trace()
19e00 5d 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73  ] .**          s
19e10 68 61 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64 0a  hall be invoked.
19e20 2a 2a 20 20 20 20 20 20 20 20 20 20 77 68 65 6e  **          when
19e30 65 76 65 72 20 61 6e 20 53 51 4c 20 73 74 61 74  ever an SQL stat
19e40 65 6d 65 6e 74 20 66 69 72 73 74 20 62 65 67 69  ement first begi
19e50 6e 73 20 74 6f 20 65 78 65 63 75 74 65 20 61 6e  ns to execute an
19e60 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 68  d.**          wh
19e70 65 6e 65 76 65 72 20 61 20 74 72 69 67 67 65 72  enever a trigger
19e80 20 73 75 62 70 72 6f 67 72 61 6d 20 66 69 72 73   subprogram firs
19e90 74 20 62 65 67 69 6e 73 20 74 6f 20 72 75 6e 2e  t begins to run.
19ea0 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 38 32 7d 20  .**.** {H12282} 
19eb0 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 5b 73 71  Each call to [sq
19ec0 6c 69 74 65 33 5f 74 72 61 63 65 28 29 5d 20 73  lite3_trace()] s
19ed0 68 61 6c 6c 20 6f 76 65 72 72 69 64 65 20 74 68  hall override th
19ee0 65 20 70 72 65 76 69 6f 75 73 6c 79 0a 2a 2a 20  e previously.** 
19ef0 20 20 20 20 20 20 20 20 20 72 65 67 69 73 74 65           registe
19f00 72 65 64 20 74 72 61 63 65 20 63 61 6c 6c 62 61  red trace callba
19f10 63 6b 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 38  ck..**.** {H1228
19f20 33 7d 20 41 20 4e 55 4c 4c 20 74 72 61 63 65 20  3} A NULL trace 
19f30 63 61 6c 6c 62 61 63 6b 20 73 68 61 6c 6c 20 64  callback shall d
19f40 69 73 61 62 6c 65 20 74 72 61 63 69 6e 67 2e 0a  isable tracing..
19f50 2a 2a 0a 2a 2a 20 7b 48 31 32 32 38 34 7d 20 54  **.** {H12284} T
19f60 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
19f70 74 20 74 6f 20 74 68 65 20 74 72 61 63 65 20 63  t to the trace c
19f80 61 6c 6c 62 61 63 6b 20 73 68 61 6c 6c 20 62 65  allback shall be
19f90 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 20 20   a copy of.**   
19fa0 20 20 20 20 20 20 20 74 68 65 20 70 6f 69 6e 74         the point
19fb0 65 72 20 77 68 69 63 68 20 77 61 73 20 74 68 65  er which was the
19fc0 20 33 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f   3rd argument to
19fd0 20 5b 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28   [sqlite3_trace(
19fe0 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 38  )]..**.** {H1228
19ff0 35 7d 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72  5} The second ar
1a000 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 74 72  gument to the tr
1a010 61 63 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  ace callback is 
1a020 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 7a 65  a.**          ze
1a030 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54  ro-terminated UT
1a040 46 2d 38 20 73 74 72 69 6e 67 20 63 6f 6e 74 61  F-8 string conta
1a050 69 6e 69 6e 67 20 74 68 65 20 6f 72 69 67 69 6e  ining the origin
1a060 61 6c 20 74 65 78 74 0a 2a 2a 20 20 20 20 20 20  al text.**      
1a070 20 20 20 20 6f 66 20 74 68 65 20 53 51 4c 20 73      of the SQL s
1a080 74 61 74 65 6d 65 6e 74 20 61 73 20 69 74 20 77  tatement as it w
1a090 61 73 20 70 61 73 73 65 64 20 69 6e 74 6f 20 5b  as passed into [
1a0a0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
1a0b0 76 32 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20  v2()].**        
1a0c0 20 20 6f 72 20 74 68 65 20 65 71 75 69 76 61 6c    or the equival
1a0d0 65 6e 74 2c 20 6f 72 20 61 6e 20 53 51 4c 20 63  ent, or an SQL c
1a0e0 6f 6d 6d 65 6e 74 20 69 6e 64 69 63 61 74 69 6e  omment indicatin
1a0f0 67 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 0a  g the beginning.
1a100 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20 61  **          of a
1a110 20 74 72 69 67 67 65 72 20 73 75 62 70 72 6f 67   trigger subprog
1a120 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32  ram..**.** {H122
1a130 38 37 7d 20 54 68 65 20 63 61 6c 6c 62 61 63 6b  87} The callback
1a140 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74   function regist
1a150 65 72 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  ered by [sqlite3
1a160 5f 70 72 6f 66 69 6c 65 28 29 5d 20 69 73 20 69  _profile()] is i
1a170 6e 76 6f 6b 65 64 0a 2a 2a 20 20 20 20 20 20 20  nvoked.**       
1a180 20 20 20 61 73 20 65 61 63 68 20 53 51 4c 20 73     as each SQL s
1a190 74 61 74 65 6d 65 6e 74 20 66 69 6e 69 73 68 65  tatement finishe
1a1a0 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 38 38  s..**.** {H12288
1a1b0 7d 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61  } The first para
1a1c0 6d 65 74 65 72 20 74 6f 20 74 68 65 20 70 72 6f  meter to the pro
1a1d0 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20 69 73  file callback is
1a1e0 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 20 20   a copy of.**   
1a1f0 20 20 20 20 20 20 20 74 68 65 20 33 72 64 20 70         the 3rd p
1a200 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c  arameter to [sql
1a210 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 5d 2e  ite3_profile()].
1a220 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 38 39 7d 20  .**.** {H12289} 
1a230 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
1a240 65 74 65 72 20 74 6f 20 74 68 65 20 70 72 6f 66  eter to the prof
1a250 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  ile callback is 
1a260 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 7a 65  a.**          ze
1a270 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54  ro-terminated UT
1a280 46 2d 38 20 73 74 72 69 6e 67 20 74 68 61 74 20  F-8 string that 
1a290 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 63 6f 6d  contains the com
1a2a0 70 6c 65 74 65 20 74 65 78 74 20 6f 66 0a 2a 2a  plete text of.**
1a2b0 20 20 20 20 20 20 20 20 20 20 74 68 65 20 53 51            the SQ
1a2c0 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 73 20 69  L statement as i
1a2d0 74 20 77 61 73 20 70 72 6f 63 65 73 73 65 64 20  t was processed 
1a2e0 62 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  by [sqlite3_prep
1a2f0 61 72 65 5f 76 32 28 29 5d 0a 2a 2a 20 20 20 20  are_v2()].**    
1a300 20 20 20 20 20 20 6f 72 20 74 68 65 20 65 71 75        or the equ
1a310 69 76 61 6c 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 7b  ivalent..**.** {
1a320 48 31 32 32 39 30 7d 20 54 68 65 20 74 68 69 72  H12290} The thir
1a330 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  d parameter to t
1a340 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62  he profile callb
1a350 61 63 6b 20 69 73 20 61 6e 20 65 73 74 69 6d 61  ack is an estima
1a360 74 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  te.**          o
1a370 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  f the number of 
1a380 6e 61 6e 6f 73 65 63 6f 6e 64 73 20 6f 66 20 77  nanoseconds of w
1a390 61 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d 65 20 72  all-clock time r
1a3a0 65 71 75 69 72 65 64 20 74 6f 0a 2a 2a 20 20 20  equired to.**   
1a3b0 20 20 20 20 20 20 20 72 75 6e 20 74 68 65 20 53         run the S
1a3c0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 66 72 6f  QL statement fro
1a3d0 6d 20 73 74 61 72 74 20 74 6f 20 66 69 6e 69 73  m start to finis
1a3e0 68 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 50  h..*/.SQLITE_EXP
1a3f0 45 52 49 4d 45 4e 54 41 4c 20 76 6f 69 64 20 2a  ERIMENTAL void *
1a400 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 73 71  sqlite3_trace(sq
1a410 6c 69 74 65 33 2a 2c 20 76 6f 69 64 28 2a 78 54  lite3*, void(*xT
1a420 72 61 63 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73  race)(void*,cons
1a430 74 20 63 68 61 72 2a 29 2c 20 76 6f 69 64 2a 29  t char*), void*)
1a440 3b 0a 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d  ;.SQLITE_EXPERIM
1a450 45 4e 54 41 4c 20 76 6f 69 64 20 2a 73 71 6c 69  ENTAL void *sqli
1a460 74 65 33 5f 70 72 6f 66 69 6c 65 28 73 71 6c 69  te3_profile(sqli
1a470 74 65 33 2a 2c 0a 20 20 20 76 6f 69 64 28 2a 78  te3*,.   void(*x
1a480 50 72 6f 66 69 6c 65 29 28 76 6f 69 64 2a 2c 63  Profile)(void*,c
1a490 6f 6e 73 74 20 63 68 61 72 2a 2c 73 71 6c 69 74  onst char*,sqlit
1a4a0 65 33 5f 75 69 6e 74 36 34 29 2c 20 76 6f 69 64  e3_uint64), void
1a4b0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
1a4c0 52 45 46 3a 20 51 75 65 72 79 20 50 72 6f 67 72  REF: Query Progr
1a4d0 65 73 73 20 43 61 6c 6c 62 61 63 6b 73 20 7b 48  ess Callbacks {H
1a4e0 31 32 39 31 30 7d 20 3c 53 36 30 34 30 30 3e 0a  12910} <S60400>.
1a4f0 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69  **.** This routi
1a500 6e 65 20 63 6f 6e 66 69 67 75 72 65 73 20 61 20  ne configures a 
1a510 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
1a520 6e 20 2d 20 74 68 65 0a 2a 2a 20 70 72 6f 67 72  n - the.** progr
1a530 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 2d 20 74  ess callback - t
1a540 68 61 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 70  hat is invoked p
1a550 65 72 69 6f 64 69 63 61 6c 6c 79 20 64 75 72 69  eriodically duri
1a560 6e 67 20 6c 6f 6e 67 0a 2a 2a 20 72 75 6e 6e 69  ng long.** runni
1a570 6e 67 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c  ng calls to [sql
1a580 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 5b 73  ite3_exec()], [s
1a590 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 61  qlite3_step()] a
1a5a0 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 67  nd.** [sqlite3_g
1a5b0 65 74 5f 74 61 62 6c 65 28 29 5d 2e 20 20 41 6e  et_table()].  An
1a5c0 20 65 78 61 6d 70 6c 65 20 75 73 65 20 66 6f 72   example use for
1a5d0 20 74 68 69 73 0a 2a 2a 20 69 6e 74 65 72 66 61   this.** interfa
1a5e0 63 65 20 69 73 20 74 6f 20 6b 65 65 70 20 61 20  ce is to keep a 
1a5f0 47 55 49 20 75 70 64 61 74 65 64 20 64 75 72 69  GUI updated duri
1a600 6e 67 20 61 20 6c 61 72 67 65 20 71 75 65 72 79  ng a large query
1a610 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 70  ..**.** If the p
1a620 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b  rogress callback
1a630 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72   returns non-zer
1a640 6f 2c 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e  o, the operation
1a650 20 69 73 0a 2a 2a 20 69 6e 74 65 72 72 75 70 74   is.** interrupt
1a660 65 64 2e 20 20 54 68 69 73 20 66 65 61 74 75 72  ed.  This featur
1a670 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  e can be used to
1a680 20 69 6d 70 6c 65 6d 65 6e 74 20 61 0a 2a 2a 20   implement a.** 
1a690 22 43 61 6e 63 65 6c 22 20 62 75 74 74 6f 6e 20  "Cancel" button 
1a6a0 6f 6e 20 61 20 47 55 49 20 64 69 61 6c 6f 67 20  on a GUI dialog 
1a6b0 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  box..**.** INVAR
1a6c0 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31  IANTS:.**.** {H1
1a6d0 32 39 31 31 7d 20 54 68 65 20 63 61 6c 6c 62 61  2911} The callba
1a6e0 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69  ck function regi
1a6f0 73 74 65 72 65 64 20 62 79 20 73 71 6c 69 74 65  stered by sqlite
1a700 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c  3_progress_handl
1a710 65 72 28 29 0a 2a 2a 20 20 20 20 20 20 20 20 20  er().**         
1a720 20 69 73 20 69 6e 76 6f 6b 65 64 20 70 65 72 69   is invoked peri
1a730 6f 64 69 63 61 6c 6c 79 20 64 75 72 69 6e 67 20  odically during 
1a740 6c 6f 6e 67 20 72 75 6e 6e 69 6e 67 20 63 61 6c  long running cal
1a750 6c 73 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20  ls to.**        
1a760 20 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28    [sqlite3_step(
1a770 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 31  )]..**.** {H1291
1a780 32 7d 20 54 68 65 20 70 72 6f 67 72 65 73 73 20  2} The progress 
1a790 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
1a7a0 6b 65 64 20 6f 6e 63 65 20 66 6f 72 20 65 76 65  ked once for eve
1a7b0 72 79 20 4e 20 76 69 72 74 75 61 6c 0a 2a 2a 20  ry N virtual.** 
1a7c0 20 20 20 20 20 20 20 20 20 6d 61 63 68 69 6e 65           machine
1a7d0 20 6f 70 63 6f 64 65 73 2c 20 77 68 65 72 65 20   opcodes, where 
1a7e0 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20  N is the second 
1a7f0 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 20  argument to.**  
1a800 20 20 20 20 20 20 20 20 74 68 65 20 5b 73 71 6c          the [sql
1a810 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61  ite3_progress_ha
1a820 6e 64 6c 65 72 28 29 5d 20 63 61 6c 6c 20 74 68  ndler()] call th
1a830 61 74 20 72 65 67 69 73 74 65 72 65 64 0a 2a 2a  at registered.**
1a840 20 20 20 20 20 20 20 20 20 20 74 68 65 20 63 61            the ca
1a850 6c 6c 62 61 63 6b 2e 20 20 49 66 20 4e 20 69 73  llback.  If N is
1a860 20 6c 65 73 73 20 74 68 61 6e 20 31 2c 20 73 71   less than 1, sq
1a870 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68  lite3_progress_h
1a880 61 6e 64 6c 65 72 28 29 0a 2a 2a 20 20 20 20 20  andler().**     
1a890 20 20 20 20 20 61 63 74 73 20 61 73 20 69 66 20       acts as if 
1a8a0 61 20 4e 55 4c 4c 20 70 72 6f 67 72 65 73 73 20  a NULL progress 
1a8b0 68 61 6e 64 6c 65 72 20 68 61 64 20 62 65 65 6e  handler had been
1a8c0 20 73 70 65 63 69 66 69 65 64 2e 0a 2a 2a 0a 2a   specified..**.*
1a8d0 2a 20 7b 48 31 32 39 31 33 7d 20 54 68 65 20 70  * {H12913} The p
1a8e0 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b  rogress callback
1a8f0 20 69 74 73 65 6c 66 20 69 73 20 69 64 65 6e 74   itself is ident
1a900 69 66 69 65 64 20 62 79 20 74 68 65 20 74 68 69  ified by the thi
1a910 72 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  rd.**          a
1a920 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
1a930 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64  e3_progress_hand
1a940 6c 65 72 28 29 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  ler()..**.** {H1
1a950 32 39 31 34 7d 20 54 68 65 20 66 6f 75 72 74 68  2914} The fourth
1a960 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
1a970 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61  ite3_progress_ha
1a980 6e 64 6c 65 72 28 29 20 69 73 20 61 0a 2a 2a 20  ndler() is a.** 
1a990 20 20 20 20 20 20 20 20 20 76 6f 69 64 20 70 6f           void po
1a9a0 69 6e 74 65 72 20 70 61 73 73 65 64 20 74 6f 20  inter passed to 
1a9b0 74 68 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c  the progress cal
1a9c0 6c 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 20 20  lback.**        
1a9d0 20 20 66 75 6e 63 74 69 6f 6e 20 65 61 63 68 20    function each 
1a9e0 74 69 6d 65 20 69 74 20 69 73 20 69 6e 76 6f 6b  time it is invok
1a9f0 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 31  ed..**.** {H1291
1aa00 35 7d 20 49 66 20 61 20 63 61 6c 6c 20 74 6f 20  5} If a call to 
1aa10 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
1aa20 20 72 65 73 75 6c 74 73 20 69 6e 20 66 65 77 65   results in fewe
1aa30 72 20 74 68 61 6e 20 4e 20 6f 70 63 6f 64 65 73  r than N opcodes
1aa40 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 65 69  .**          bei
1aa50 6e 67 20 65 78 65 63 75 74 65 64 2c 20 74 68 65  ng executed, the
1aa60 6e 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 63  n the progress c
1aa70 61 6c 6c 62 61 63 6b 20 69 73 20 6e 65 76 65 72  allback is never
1aa80 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20   invoked..**.** 
1aa90 7b 48 31 32 39 31 36 7d 20 45 76 65 72 79 20 63  {H12916} Every c
1aaa0 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
1aab0 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72  progress_handler
1aac0 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ()].**          
1aad0 6f 76 65 72 77 72 69 74 65 73 20 61 6e 79 20 70  overwrites any p
1aae0 72 65 76 69 6f 75 73 6c 79 20 72 65 67 69 73 74  reviously regist
1aaf0 65 72 65 64 20 70 72 6f 67 72 65 73 73 20 68 61  ered progress ha
1ab00 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  ndler..**.** {H1
1ab10 32 39 31 37 7d 20 49 66 20 74 68 65 20 70 72 6f  2917} If the pro
1ab20 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 63 61  gress handler ca
1ab30 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 20 74  llback is NULL t
1ab40 68 65 6e 20 6e 6f 20 70 72 6f 67 72 65 73 73 0a  hen no progress.
1ab50 2a 2a 20 20 20 20 20 20 20 20 20 20 68 61 6e 64  **          hand
1ab60 6c 65 72 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a  ler is invoked..
1ab70 2a 2a 0a 2a 2a 20 7b 48 31 32 39 31 38 7d 20 49  **.** {H12918} I
1ab80 66 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 63  f the progress c
1ab90 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
1aba0 61 20 72 65 73 75 6c 74 20 6f 74 68 65 72 20 74  a result other t
1abb0 68 61 6e 20 30 2c 20 74 68 65 6e 0a 2a 2a 20 20  han 0, then.**  
1abc0 20 20 20 20 20 20 20 20 74 68 65 20 62 65 68 61          the beha
1abd0 76 69 6f 72 20 69 73 20 61 20 69 66 20 5b 73 71  vior is a if [sq
1abe0 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
1abf0 29 5d 20 68 61 64 20 62 65 65 6e 20 63 61 6c 6c  )] had been call
1ac00 65 64 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ed..**          
1ac10 3c 53 33 30 35 30 30 3e 0a 2a 2f 0a 76 6f 69 64  <S30500>.*/.void
1ac20 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73   sqlite3_progres
1ac30 73 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65  s_handler(sqlite
1ac40 33 2a 2c 20 69 6e 74 2c 20 69 6e 74 28 2a 29 28  3*, int, int(*)(
1ac50 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a  void*), void*);.
1ac60 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1ac70 20 4f 70 65 6e 69 6e 67 20 41 20 4e 65 77 20 44   Opening A New D
1ac80 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69  atabase Connecti
1ac90 6f 6e 20 7b 48 31 32 37 30 30 7d 20 3c 53 34 30  on {H12700} <S40
1aca0 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  200>.**.** These
1acb0 20 72 6f 75 74 69 6e 65 73 20 6f 70 65 6e 20 61   routines open a
1acc0 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62 61 73  n SQLite databas
1acd0 65 20 66 69 6c 65 20 77 68 6f 73 65 20 6e 61 6d  e file whose nam
1ace0 65 20 69 73 20 67 69 76 65 6e 20 62 79 20 74 68  e is given by th
1acf0 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 61 72  e.** filename ar
1ad00 67 75 6d 65 6e 74 2e 20 54 68 65 20 66 69 6c 65  gument. The file
1ad10 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 20 69 73  name argument is
1ad20 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20   interpreted as 
1ad30 55 54 46 2d 38 20 66 6f 72 0a 2a 2a 20 73 71 6c  UTF-8 for.** sql
1ad40 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20  ite3_open() and 
1ad50 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
1ad60 29 20 61 6e 64 20 61 73 20 55 54 46 2d 31 36 20  ) and as UTF-16 
1ad70 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79  in the native by
1ad80 74 65 0a 2a 2a 20 6f 72 64 65 72 20 66 6f 72 20  te.** order for 
1ad90 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
1ada0 2e 20 41 20 5b 64 61 74 61 62 61 73 65 20 63 6f  . A [database co
1adb0 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65  nnection] handle
1adc0 20 69 73 20 75 73 75 61 6c 6c 79 0a 2a 2a 20 72   is usually.** r
1add0 65 74 75 72 6e 65 64 20 69 6e 20 2a 70 70 44 62  eturned in *ppDb
1ade0 2c 20 65 76 65 6e 20 69 66 20 61 6e 20 65 72 72  , even if an err
1adf0 6f 72 20 6f 63 63 75 72 73 2e 20 20 54 68 65 20  or occurs.  The 
1ae00 6f 6e 6c 79 20 65 78 63 65 70 74 69 6f 6e 20 69  only exception i
1ae10 73 20 74 68 61 74 0a 2a 2a 20 69 66 20 53 51 4c  s that.** if SQL
1ae20 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f  ite is unable to
1ae30 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79   allocate memory
1ae40 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 5b 73 71   to hold the [sq
1ae50 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2c 0a 2a  lite3] object,.*
1ae60 2a 20 61 20 4e 55 4c 4c 20 77 69 6c 6c 20 62 65  * a NULL will be
1ae70 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70   written into *p
1ae80 70 44 62 20 69 6e 73 74 65 61 64 20 6f 66 20 61  pDb instead of a
1ae90 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
1aea0 5b 73 71 6c 69 74 65 33 5d 0a 2a 2a 20 6f 62 6a  [sqlite3].** obj
1aeb0 65 63 74 2e 20 49 66 20 74 68 65 20 64 61 74 61  ect. If the data
1aec0 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 28  base is opened (
1aed0 61 6e 64 2f 6f 72 20 63 72 65 61 74 65 64 29 20  and/or created) 
1aee0 73 75 63 63 65 73 73 66 75 6c 6c 79 2c 20 74 68  successfully, th
1aef0 65 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b  en.** [SQLITE_OK
1af00 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20  ] is returned.  
1af10 4f 74 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72  Otherwise an [er
1af20 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74  ror code] is ret
1af30 75 72 6e 65 64 2e 20 20 54 68 65 0a 2a 2a 20 5b  urned.  The.** [
1af40 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29  sqlite3_errmsg()
1af50 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65 72  ] or [sqlite3_er
1af60 72 6d 73 67 31 36 28 29 5d 20 72 6f 75 74 69 6e  rmsg16()] routin
1af70 65 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  es can be used t
1af80 6f 20 6f 62 74 61 69 6e 0a 2a 2a 20 61 6e 20 45  o obtain.** an E
1af90 6e 67 6c 69 73 68 20 6c 61 6e 67 75 61 67 65 20  nglish language 
1afa0 64 65 73 63 72 69 70 74 69 6f 6e 20 6f 66 20 74  description of t
1afb0 68 65 20 65 72 72 6f 72 2e 0a 2a 2a 0a 2a 2a 20  he error..**.** 
1afc0 54 68 65 20 64 65 66 61 75 6c 74 20 65 6e 63 6f  The default enco
1afd0 64 69 6e 67 20 66 6f 72 20 74 68 65 20 64 61 74  ding for the dat
1afe0 61 62 61 73 65 20 77 69 6c 6c 20 62 65 20 55 54  abase will be UT
1aff0 46 2d 38 20 69 66 0a 2a 2a 20 73 71 6c 69 74 65  F-8 if.** sqlite
1b000 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69  3_open() or sqli
1b010 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73  te3_open_v2() is
1b020 20 63 61 6c 6c 65 64 20 61 6e 64 0a 2a 2a 20 55   called and.** U
1b030 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74  TF-16 in the nat
1b040 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 69  ive byte order i
1b050 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36  f sqlite3_open16
1b060 28 29 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a  () is used..**.*
1b070 2a 20 57 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  * Whether or not
1b080 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73   an error occurs
1b090 20 77 68 65 6e 20 69 74 20 69 73 20 6f 70 65 6e   when it is open
1b0a0 65 64 2c 20 72 65 73 6f 75 72 63 65 73 0a 2a 2a  ed, resources.**
1b0b0 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
1b0c0 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
1b0d0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c  onnection] handl
1b0e0 65 20 73 68 6f 75 6c 64 20 62 65 20 72 65 6c 65  e should be rele
1b0f0 61 73 65 64 20 62 79 0a 2a 2a 20 70 61 73 73 69  ased by.** passi
1b100 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65  ng it to [sqlite
1b110 33 5f 63 6c 6f 73 65 28 29 5d 20 77 68 65 6e 20  3_close()] when 
1b120 69 74 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20  it is no longer 
1b130 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20  required..**.** 
1b140 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  The sqlite3_open
1b150 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65 20  _v2() interface 
1b160 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74  works like sqlit
1b170 65 33 5f 6f 70 65 6e 28 29 0a 2a 2a 20 65 78 63  e3_open().** exc
1b180 65 70 74 20 74 68 61 74 20 69 74 20 61 63 63 65  ept that it acce
1b190 70 74 73 20 74 77 6f 20 61 64 64 69 74 69 6f 6e  pts two addition
1b1a0 61 6c 20 70 61 72 61 6d 65 74 65 72 73 20 66 6f  al parameters fo
1b1b0 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 63 6f 6e  r additional con
1b1c0 74 72 6f 6c 0a 2a 2a 20 6f 76 65 72 20 74 68 65  trol.** over the
1b1d0 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 6f   new database co
1b1e0 6e 6e 65 63 74 69 6f 6e 2e 20 20 54 68 65 20 66  nnection.  The f
1b1f0 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 63  lags parameter c
1b200 61 6e 20 74 61 6b 65 20 6f 6e 65 20 6f 66 0a 2a  an take one of.*
1b210 2a 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  * the following 
1b220 74 68 72 65 65 20 76 61 6c 75 65 73 2c 20 6f 70  three values, op
1b230 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65  tionally combine
1b240 64 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 5b  d with the .** [
1b250 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55  SQLITE_OPEN_NOMU
1b260 54 45 58 5d 20 66 6c 61 67 3a 0a 2a 2a 0a 2a 2a  TEX] flag:.**.**
1b270 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 5b 53 51   <dl>.** <dt>[SQ
1b280 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e  LITE_OPEN_READON
1b290 4c 59 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  LY]</dt>.** <dd>
1b2a0 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  The database is 
1b2b0 6f 70 65 6e 65 64 20 69 6e 20 72 65 61 64 2d 6f  opened in read-o
1b2c0 6e 6c 79 20 6d 6f 64 65 2e 20 20 49 66 20 74 68  nly mode.  If th
1b2d0 65 20 64 61 74 61 62 61 73 65 20 64 6f 65 73 20  e database does 
1b2e0 6e 6f 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20 65  not.** already e
1b2f0 78 69 73 74 2c 20 61 6e 20 65 72 72 6f 72 20 69  xist, an error i
1b300 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e  s returned.</dd>
1b310 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 5b 53 51 4c 49  .**.** <dt>[SQLI
1b320 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54  TE_OPEN_READWRIT
1b330 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  E]</dt>.** <dd>T
1b340 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f  he database is o
1b350 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e  pened for readin
1b360 67 20 61 6e 64 20 77 72 69 74 69 6e 67 20 69 66  g and writing if
1b370 20 70 6f 73 73 69 62 6c 65 2c 20 6f 72 20 72 65   possible, or re
1b380 61 64 69 6e 67 0a 2a 2a 20 6f 6e 6c 79 20 69 66  ading.** only if
1b390 20 74 68 65 20 66 69 6c 65 20 69 73 20 77 72 69   the file is wri
1b3a0 74 65 20 70 72 6f 74 65 63 74 65 64 20 62 79 20  te protected by 
1b3b0 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79  the operating sy
1b3c0 73 74 65 6d 2e 20 20 49 6e 20 65 69 74 68 65 72  stem.  In either
1b3d0 0a 2a 2a 20 63 61 73 65 20 74 68 65 20 64 61 74  .** case the dat
1b3e0 61 62 61 73 65 20 6d 75 73 74 20 61 6c 72 65 61  abase must alrea
1b3f0 64 79 20 65 78 69 73 74 2c 20 6f 74 68 65 72 77  dy exist, otherw
1b400 69 73 65 20 61 6e 20 65 72 72 6f 72 20 69 73 20  ise an error is 
1b410 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 0a 2a  returned.</dd>.*
1b420 2a 0a 2a 2a 20 3c 64 74 3e 5b 53 51 4c 49 54 45  *.** <dt>[SQLITE
1b430 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d  _OPEN_READWRITE]
1b440 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f   | [SQLITE_OPEN_
1b450 43 52 45 41 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20  CREATE]</dt>.** 
1b460 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 65  <dd>The database
1b470 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72   is opened for r
1b480 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69  eading and writi
1b490 6e 67 2c 20 61 6e 64 20 69 73 20 63 72 65 61 74  ng, and is creat
1b4a0 65 73 20 69 74 20 69 66 0a 2a 2a 20 69 74 20 64  es it if.** it d
1b4b0 6f 65 73 20 6e 6f 74 20 61 6c 72 65 61 64 79 20  oes not already 
1b4c0 65 78 69 73 74 2e 20 54 68 69 73 20 69 73 20 74  exist. This is t
1b4d0 68 65 20 62 65 68 61 76 69 6f 72 20 74 68 61 74  he behavior that
1b4e0 20 69 73 20 61 6c 77 61 79 73 20 75 73 65 64 20   is always used 
1b4f0 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f  for.** sqlite3_o
1b500 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65  pen() and sqlite
1b510 33 5f 6f 70 65 6e 31 36 28 29 2e 3c 2f 64 64 3e  3_open16().</dd>
1b520 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </dl>.**.** 
1b530 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d  If the 3rd param
1b540 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
1b550 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74  open_v2() is not
1b560 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 63   one of the.** c
1b570 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 73 68 6f 77  ombinations show
1b580 6e 20 61 62 6f 76 65 20 6f 72 20 6f 6e 65 20 6f  n above or one o
1b590 66 20 74 68 65 20 63 6f 6d 62 69 6e 61 74 69 6f  f the combinatio
1b5a0 6e 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 63  ns shown above c
1b5b0 6f 6d 62 69 6e 65 64 0a 2a 2a 20 77 69 74 68 20  ombined.** with 
1b5c0 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  the [SQLITE_OPEN
1b5d0 5f 4e 4f 4d 55 54 45 58 5d 20 66 6c 61 67 2c 20  _NOMUTEX] flag, 
1b5e0 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f  then the behavio
1b5f0 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  r is undefined..
1b600 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 5b 53 51  **.** If the [SQ
1b610 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45  LITE_OPEN_NOMUTE
1b620 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74 2c 20  X] flag is set, 
1b630 74 68 65 6e 20 6d 75 74 65 78 65 73 20 6f 6e 20  then mutexes on 
1b640 74 68 65 0a 2a 2a 20 6f 70 65 6e 65 64 20 5b 64  the.** opened [d
1b650 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1b660 6f 6e 5d 20 61 72 65 20 64 69 73 61 62 6c 65 64  on] are disabled
1b670 20 61 6e 64 20 74 68 65 20 61 70 70 6c 69 61 74   and the appliat
1b680 69 6f 6e 20 6d 75 73 74 0a 2a 2a 20 69 6e 73 75  ion must.** insu
1b690 72 65 20 74 68 61 74 20 61 63 63 65 73 73 20 74  re that access t
1b6a0 6f 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  o the [database 
1b6b0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20  connection] and 
1b6c0 69 74 73 20 61 73 73 6f 63 69 61 74 65 64 0a 2a  its associated.*
1b6d0 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  * [prepared stat
1b6e0 65 6d 65 6e 74 73 5d 20 69 73 20 73 65 72 69 61  ements] is seria
1b6f0 6c 69 7a 65 64 2e 20 20 54 68 65 20 5b 53 51 4c  lized.  The [SQL
1b700 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58  ITE_OPEN_NOMUTEX
1b710 5d 20 66 6c 61 67 0a 2a 2a 20 69 73 20 74 68 65  ] flag.** is the
1b720 20 64 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f   default behavio
1b730 72 20 69 73 20 53 51 4c 69 74 65 20 69 73 20 63  r is SQLite is c
1b740 6f 6e 66 69 67 75 72 65 64 20 75 73 69 6e 67 20  onfigured using 
1b750 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43  the.** [SQLITE_C
1b760 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41  ONFIG_MULTITHREA
1b770 44 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f  D] or [SQLITE_CO
1b780 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41  NFIG_SINGLETHREA
1b790 44 5d 20 6f 70 74 69 6f 6e 73 0a 2a 2a 20 74 6f  D] options.** to
1b7a0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
1b7b0 28 29 5d 2e 20 20 54 68 65 20 5b 53 51 4c 49 54  ()].  The [SQLIT
1b7c0 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20  E_OPEN_NOMUTEX] 
1b7d0 66 6c 61 67 20 6f 6e 6c 79 20 6d 61 6b 65 73 20  flag only makes 
1b7e0 61 0a 2a 2a 20 64 69 66 66 65 72 65 6e 63 65 20  a.** difference 
1b7f0 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 69  when SQLite is i
1b800 6e 20 69 74 73 20 64 65 66 61 75 6c 74 20 5b 53  n its default [S
1b810 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52  QLITE_CONFIG_SER
1b820 49 41 4c 49 5a 45 44 5d 20 6d 6f 64 65 2e 0a 2a  IALIZED] mode..*
1b830 2a 0a 2a 2a 20 49 66 20 74 68 65 20 66 69 6c 65  *.** If the file
1b840 6e 61 6d 65 20 69 73 20 22 3a 6d 65 6d 6f 72 79  name is ":memory
1b850 3a 22 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61  :", then a priva
1b860 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 20 69 6e  te, temporary in
1b870 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65  -memory database
1b880 0a 2a 2a 20 69 73 20 63 72 65 61 74 65 64 20 66  .** is created f
1b890 6f 72 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f  or the connectio
1b8a0 6e 2e 20 20 54 68 69 73 20 69 6e 2d 6d 65 6d 6f  n.  This in-memo
1b8b0 72 79 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c  ry database will
1b8c0 20 76 61 6e 69 73 68 20 77 68 65 6e 0a 2a 2a 20   vanish when.** 
1b8d0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
1b8e0 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65  nection is close
1b8f0 64 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69  d.  Future versi
1b900 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69  ons of SQLite mi
1b910 67 68 74 0a 2a 2a 20 6d 61 6b 65 20 75 73 65 20  ght.** make use 
1b920 6f 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 70  of additional sp
1b930 65 63 69 61 6c 20 66 69 6c 65 6e 61 6d 65 73 20  ecial filenames 
1b940 74 68 61 74 20 62 65 67 69 6e 20 77 69 74 68 20  that begin with 
1b950 74 68 65 20 22 3a 22 20 63 68 61 72 61 63 74 65  the ":" characte
1b960 72 2e 0a 2a 2a 20 49 74 20 69 73 20 72 65 63 6f  r..** It is reco
1b970 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 77 68 65  mmended that whe
1b980 6e 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c  n a database fil
1b990 65 6e 61 6d 65 20 61 63 74 75 61 6c 6c 79 20 64  ename actually d
1b9a0 6f 65 73 20 62 65 67 69 6e 20 77 69 74 68 0a 2a  oes begin with.*
1b9b0 2a 20 61 20 22 3a 22 20 63 68 61 72 61 63 74 65  * a ":" characte
1b9c0 72 20 79 6f 75 20 73 68 6f 75 6c 64 20 70 72 65  r you should pre
1b9d0 66 69 78 20 74 68 65 20 66 69 6c 65 6e 61 6d 65  fix the filename
1b9e0 20 77 69 74 68 20 61 20 70 61 74 68 6e 61 6d 65   with a pathname
1b9f0 20 73 75 63 68 20 61 73 0a 2a 2a 20 22 2e 2f 22   such as.** "./"
1ba00 20 74 6f 20 61 76 6f 69 64 20 61 6d 62 69 67 75   to avoid ambigu
1ba10 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  ity..**.** If th
1ba20 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 61 6e  e filename is an
1ba30 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 74   empty string, t
1ba40 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74  hen a private, t
1ba50 65 6d 70 6f 72 61 72 79 0a 2a 2a 20 6f 6e 2d 64  emporary.** on-d
1ba60 69 73 6b 20 64 61 74 61 62 61 73 65 20 77 69 6c  isk database wil
1ba70 6c 20 62 65 20 63 72 65 61 74 65 64 2e 20 20 54  l be created.  T
1ba80 68 69 73 20 70 72 69 76 61 74 65 20 64 61 74 61  his private data
1ba90 62 61 73 65 20 77 69 6c 6c 20 62 65 0a 2a 2a 20  base will be.** 
1baa0 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65  automatically de
1bab0 6c 65 74 65 64 20 61 73 20 73 6f 6f 6e 20 61 73  leted as soon as
1bac0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
1bad0 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73  nnection is clos
1bae0 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f  ed..**.** The fo
1baf0 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74  urth parameter t
1bb00 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  o sqlite3_open_v
1bb10 32 28 29 20 69 73 20 74 68 65 20 6e 61 6d 65 20  2() is the name 
1bb20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  of the.** [sqlit
1bb30 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 74  e3_vfs] object t
1bb40 68 61 74 20 64 65 66 69 6e 65 73 20 74 68 65 20  hat defines the 
1bb50 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d  operating system
1bb60 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 0a   interface that.
1bb70 2a 2a 20 74 68 65 20 6e 65 77 20 64 61 74 61 62  ** the new datab
1bb80 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73  ase connection s
1bb90 68 6f 75 6c 64 20 75 73 65 2e 20 20 49 66 20 74  hould use.  If t
1bba0 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
1bbb0 74 65 72 20 69 73 0a 2a 2a 20 61 20 4e 55 4c 4c  ter is.** a NULL
1bbc0 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 74 68   pointer then th
1bbd0 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74  e default [sqlit
1bbe0 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 69  e3_vfs] object i
1bbf0 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62  s used..**.** <b
1bc00 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77 73  >Note to Windows
1bc10 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65   users:</b>  The
1bc20 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 66   encoding used f
1bc30 6f 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  or the filename 
1bc40 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 6f 66 20 73  argument.** of s
1bc50 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e  qlite3_open() an
1bc60 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  d sqlite3_open_v
1bc70 32 28 29 20 6d 75 73 74 20 62 65 20 55 54 46 2d  2() must be UTF-
1bc80 38 2c 20 6e 6f 74 20 77 68 61 74 65 76 65 72 0a  8, not whatever.
1bc90 2a 2a 20 63 6f 64 65 70 61 67 65 20 69 73 20 63  ** codepage is c
1bca0 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64  urrently defined
1bcb0 2e 20 20 46 69 6c 65 6e 61 6d 65 73 20 63 6f 6e  .  Filenames con
1bcc0 74 61 69 6e 69 6e 67 20 69 6e 74 65 72 6e 61 74  taining internat
1bcd0 69 6f 6e 61 6c 0a 2a 2a 20 63 68 61 72 61 63 74  ional.** charact
1bce0 65 72 73 20 6d 75 73 74 20 62 65 20 63 6f 6e 76  ers must be conv
1bcf0 65 72 74 65 64 20 74 6f 20 55 54 46 2d 38 20 70  erted to UTF-8 p
1bd00 72 69 6f 72 20 74 6f 20 70 61 73 73 69 6e 67 20  rior to passing 
1bd10 74 68 65 6d 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c  them into.** sql
1bd20 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73  ite3_open() or s
1bd30 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
1bd40 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  ..**.** INVARIAN
1bd50 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 30  TS:.**.** {H1270
1bd60 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  1} The [sqlite3_
1bd70 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65  open()], [sqlite
1bd80 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 61 6e 64  3_open16()], and
1bd90 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
1bda0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
1bdb0 20 69 6e 74 65 72 66 61 63 65 73 20 63 72 65 61   interfaces crea
1bdc0 74 65 20 61 20 6e 65 77 0a 2a 2a 20 20 20 20 20  te a new.**     
1bdd0 20 20 20 20 20 5b 64 61 74 61 62 61 73 65 20 63       [database c
1bde0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 73 73 6f 63  onnection] assoc
1bdf0 69 61 74 65 64 20 77 69 74 68 0a 2a 2a 20 20 20  iated with.**   
1be00 20 20 20 20 20 20 20 74 68 65 20 64 61 74 61 62         the datab
1be10 61 73 65 20 66 69 6c 65 20 67 69 76 65 6e 20 69  ase file given i
1be20 6e 20 74 68 65 69 72 20 66 69 72 73 74 20 70 61  n their first pa
1be30 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b  rameter..**.** {
1be40 48 31 32 37 30 32 7d 20 54 68 65 20 66 69 6c 65  H12702} The file
1be50 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 20 69 73  name argument is
1be60 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20   interpreted as 
1be70 55 54 46 2d 38 0a 2a 2a 20 20 20 20 20 20 20 20  UTF-8.**        
1be80 20 20 66 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f    for [sqlite3_o
1be90 70 65 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  pen()] and [sqli
1bea0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 61  te3_open_v2()] a
1beb0 6e 64 20 61 73 20 55 54 46 2d 31 36 0a 2a 2a 20  nd as UTF-16.** 
1bec0 20 20 20 20 20 20 20 20 20 69 6e 20 74 68 65 20           in the 
1bed0 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
1bee0 72 20 66 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f  r for [sqlite3_o
1bef0 70 65 6e 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  pen16()]..**.** 
1bf00 7b 48 31 32 37 30 33 7d 20 41 20 73 75 63 63 65  {H12703} A succe
1bf10 73 73 66 75 6c 20 69 6e 76 6f 63 61 74 69 6f 6e  ssful invocation
1bf20 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   of [sqlite3_ope
1bf30 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f  n()], [sqlite3_o
1bf40 70 65 6e 31 36 28 29 5d 2c 0a 2a 2a 20 20 20 20  pen16()],.**    
1bf50 20 20 20 20 20 20 6f 72 20 5b 73 71 6c 69 74 65        or [sqlite
1bf60 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 77 72 69  3_open_v2()] wri
1bf70 74 65 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  tes a pointer to
1bf80 20 61 20 6e 65 77 0a 2a 2a 20 20 20 20 20 20 20   a new.**       
1bf90 20 20 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e     [database con
1bfa0 6e 65 63 74 69 6f 6e 5d 20 69 6e 74 6f 20 2a 70  nection] into *p
1bfb0 70 44 62 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37  pDb..**.** {H127
1bfc0 30 34 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  04} The [sqlite3
1bfd0 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74  _open()], [sqlit
1bfe0 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 61 6e  e3_open16()], an
1bff0 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  d.**          [s
1c000 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
1c010 5d 20 69 6e 74 65 72 66 61 63 65 73 20 72 65 74  ] interfaces ret
1c020 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  urn [SQLITE_OK] 
1c030 75 70 6f 6e 20 73 75 63 63 65 73 73 2c 0a 2a 2a  upon success,.**
1c040 20 20 20 20 20 20 20 20 20 20 6f 72 20 61 6e 20            or an 
1c050 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72  appropriate [err
1c060 6f 72 20 63 6f 64 65 5d 20 6f 6e 20 66 61 69 6c  or code] on fail
1c070 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37  ure..**.** {H127
1c080 30 36 7d 20 54 68 65 20 64 65 66 61 75 6c 74 20  06} The default 
1c090 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 66 6f  text encoding fo
1c0a0 72 20 61 20 6e 65 77 20 64 61 74 61 62 61 73 65  r a new database
1c0b0 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 0a 2a   created using.*
1c0c0 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
1c0d0 74 65 33 5f 6f 70 65 6e 28 29 5d 20 6f 72 20 5b  te3_open()] or [
1c0e0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
1c0f0 29 5d 20 77 69 6c 6c 20 62 65 20 55 54 46 2d 38  )] will be UTF-8
1c100 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 30 37 7d  ..**.** {H12707}
1c110 20 54 68 65 20 64 65 66 61 75 6c 74 20 74 65 78   The default tex
1c120 74 20 65 6e 63 6f 64 69 6e 67 20 66 6f 72 20 61  t encoding for a
1c130 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 72   new database cr
1c140 65 61 74 65 64 20 75 73 69 6e 67 0a 2a 2a 20 20  eated using.**  
1c150 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
1c160 5f 6f 70 65 6e 31 36 28 29 5d 20 77 69 6c 6c 20  _open16()] will 
1c170 62 65 20 55 54 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a  be UTF-16..**.**
1c180 20 7b 48 31 32 37 30 39 7d 20 54 68 65 20 5b 73   {H12709} The [s
1c190 71 6c 69 74 65 33 5f 6f 70 65 6e 28 46 2c 44 29  qlite3_open(F,D)
1c1a0 5d 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 65  ] interface is e
1c1b0 71 75 69 76 61 6c 65 6e 74 20 74 6f 0a 2a 2a 20  quivalent to.** 
1c1c0 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
1c1d0 33 5f 6f 70 65 6e 5f 76 32 28 46 2c 44 2c 47 2c  3_open_v2(F,D,G,
1c1e0 30 29 5d 20 77 68 65 72 65 20 74 68 65 20 47 20  0)] where the G 
1c1f0 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20  parameter is.** 
1c200 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45           [SQLITE
1c210 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d  _OPEN_READWRITE]
1c220 7c 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52  |[SQLITE_OPEN_CR
1c230 45 41 54 45 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  EATE]..**.** {H1
1c240 32 37 31 31 7d 20 49 66 20 74 68 65 20 47 20 70  2711} If the G p
1c250 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c  arameter to [sql
1c260 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 46 2c 44  ite3_open_v2(F,D
1c270 2c 47 2c 56 29 5d 20 63 6f 6e 74 61 69 6e 73 20  ,G,V)] contains 
1c280 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
1c290 62 69 74 20 76 61 6c 75 65 20 5b 53 51 4c 49 54  bit value [SQLIT
1c2a0 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d  E_OPEN_READONLY]
1c2b0 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61   then the databa
1c2c0 73 65 20 69 73 20 6f 70 65 6e 65 64 0a 2a 2a 20  se is opened.** 
1c2d0 20 20 20 20 20 20 20 20 20 66 6f 72 20 72 65 61           for rea
1c2e0 64 69 6e 67 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a  ding only..**.**
1c2f0 20 7b 48 31 32 37 31 32 7d 20 49 66 20 74 68 65   {H12712} If the
1c300 20 47 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20   G parameter to 
1c310 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
1c320 28 46 2c 44 2c 47 2c 56 29 5d 20 63 6f 6e 74 61  (F,D,G,V)] conta
1c330 69 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  ins the.**      
1c340 20 20 20 20 62 69 74 20 76 61 6c 75 65 20 5b 53      bit value [S
1c350 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57  QLITE_OPEN_READW
1c360 52 49 54 45 5d 20 74 68 65 6e 20 74 68 65 20 64  RITE] then the d
1c370 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65  atabase is opene
1c380 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65  d.**          re
1c390 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e  ading and writin
1c3a0 67 20 69 66 20 70 6f 73 73 69 62 6c 65 2c 20 6f  g if possible, o
1c3b0 72 20 66 6f 72 20 72 65 61 64 69 6e 67 20 6f 6e  r for reading on
1c3c0 6c 79 20 69 66 20 74 68 65 0a 2a 2a 20 20 20 20  ly if the.**    
1c3d0 20 20 20 20 20 20 66 69 6c 65 20 69 73 20 77 72        file is wr
1c3e0 69 74 65 20 70 72 6f 74 65 63 74 65 64 20 62 79  ite protected by
1c3f0 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73   the operating s
1c400 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  ystem..**.** {H1
1c410 32 37 31 33 7d 20 49 66 20 74 68 65 20 47 20 70  2713} If the G p
1c420 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c  arameter to [sql
1c430 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 46 2c 44  ite3_open_v2(F,D
1c440 2c 47 2c 56 29 5d 20 6f 6d 69 74 73 20 74 68 65  ,G,V)] omits the
1c450 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 69 74  .**          bit
1c460 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 4f   value [SQLITE_O
1c470 50 45 4e 5f 43 52 45 41 54 45 5d 20 61 6e 64 20  PEN_CREATE] and 
1c480 74 68 65 20 64 61 74 61 62 61 73 65 20 64 6f 65  the database doe
1c490 73 20 6e 6f 74 0a 2a 2a 20 20 20 20 20 20 20 20  s not.**        
1c4a0 20 20 70 72 65 76 69 6f 75 73 6c 79 20 65 78 69    previously exi
1c4b0 73 74 2c 20 61 6e 20 65 72 72 6f 72 20 69 73 20  st, an error is 
1c4c0 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
1c4d0 7b 48 31 32 37 31 34 7d 20 49 66 20 74 68 65 20  {H12714} If the 
1c4e0 47 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  G parameter to [
1c4f0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
1c500 46 2c 44 2c 47 2c 56 29 5d 20 63 6f 6e 74 61 69  F,D,G,V)] contai
1c510 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  ns the.**       
1c520 20 20 20 62 69 74 20 76 61 6c 75 65 20 5b 53 51     bit value [SQ
1c530 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45  LITE_OPEN_CREATE
1c540 5d 20 61 6e 64 20 74 68 65 20 64 61 74 61 62 61  ] and the databa
1c550 73 65 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 20  se does not.**  
1c560 20 20 20 20 20 20 20 20 70 72 65 76 69 6f 75 73          previous
1c570 6c 79 20 65 78 69 73 74 2c 20 74 68 65 6e 20 61  ly exist, then a
1c580 6e 20 61 74 74 65 6d 70 74 20 69 73 20 6d 61 64  n attempt is mad
1c590 65 20 74 6f 20 63 72 65 61 74 65 20 61 6e 64 0a  e to create and.
1c5a0 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 69 74  **          init
1c5b0 69 61 6c 69 7a 65 20 74 68 65 20 64 61 74 61 62  ialize the datab
1c5c0 61 73 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37  ase..**.** {H127
1c5d0 31 37 7d 20 49 66 20 74 68 65 20 66 69 6c 65 6e  17} If the filen
1c5e0 61 6d 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ame argument to 
1c5f0 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
1c600 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  , [sqlite3_open1
1c610 36 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20  6()],.**        
1c620 20 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70    or [sqlite3_op
1c630 65 6e 5f 76 32 28 29 5d 20 69 73 20 22 3a 6d 65  en_v2()] is ":me
1c640 6d 6f 72 79 3a 22 2c 20 74 68 65 6e 20 61 6e 20  mory:", then an 
1c650 70 72 69 76 61 74 65 2c 0a 2a 2a 20 20 20 20 20  private,.**     
1c660 20 20 20 20 20 65 70 68 65 6d 65 72 61 6c 2c 20       ephemeral, 
1c670 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61  in-memory databa
1c680 73 65 20 69 73 20 63 72 65 61 74 65 64 20 66 6f  se is created fo
1c690 72 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  r the connection
1c6a0 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 3c 74  ..**          <t
1c6b0 6f 64 6f 3e 49 73 20 53 51 4c 49 54 45 5f 4f 50  odo>Is SQLITE_OP
1c6c0 45 4e 5f 43 52 45 41 54 45 7c 53 51 4c 49 54 45  EN_CREATE|SQLITE
1c6d0 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20  _OPEN_READWRITE 
1c6e0 72 65 71 75 69 72 65 64 0a 2a 2a 20 20 20 20 20  required.**     
1c6f0 20 20 20 20 20 69 6e 20 73 71 6c 69 74 65 33 5f       in sqlite3_
1c700 6f 70 65 6e 5f 76 32 28 29 3f 3c 2f 74 6f 64 6f  open_v2()?</todo
1c710 3e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 31 39 7d  >.**.** {H12719}
1c720 20 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65   If the filename
1c730 20 69 73 20 4e 55 4c 4c 20 6f 72 20 61 6e 20 65   is NULL or an e
1c740 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 74 68 65  mpty string, the
1c750 6e 20 61 20 70 72 69 76 61 74 65 2c 0a 2a 2a 20  n a private,.** 
1c760 20 20 20 20 20 20 20 20 20 65 70 68 65 6d 65 72           ephemer
1c770 61 6c 20 6f 6e 2d 64 69 73 6b 20 64 61 74 61 62  al on-disk datab
1c780 61 73 65 20 77 69 6c 6c 20 62 65 20 63 72 65 61  ase will be crea
1c790 74 65 64 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20  ted..**         
1c7a0 20 3c 74 6f 64 6f 3e 49 73 20 53 51 4c 49 54 45   <todo>Is SQLITE
1c7b0 5f 4f 50 45 4e 5f 43 52 45 41 54 45 7c 53 51 4c  _OPEN_CREATE|SQL
1c7c0 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49  ITE_OPEN_READWRI
1c7d0 54 45 20 72 65 71 75 69 72 65 64 0a 2a 2a 20 20  TE required.**  
1c7e0 20 20 20 20 20 20 20 20 69 6e 20 73 71 6c 69 74          in sqlit
1c7f0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 3f 3c 2f 74  e3_open_v2()?</t
1c800 6f 64 6f 3e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37  odo>.**.** {H127
1c810 32 31 7d 20 54 68 65 20 5b 64 61 74 61 62 61 73  21} The [databas
1c820 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 63 72  e connection] cr
1c830 65 61 74 65 64 20 62 79 20 5b 73 71 6c 69 74 65  eated by [sqlite
1c840 33 5f 6f 70 65 6e 5f 76 32 28 46 2c 44 2c 47 2c  3_open_v2(F,D,G,
1c850 56 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  V)].**          
1c860 77 69 6c 6c 20 75 73 65 20 74 68 65 20 5b 73 71  will use the [sq
1c870 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63  lite3_vfs] objec
1c880 74 20 69 64 65 6e 74 69 66 69 65 64 20 62 79 20  t identified by 
1c890 74 68 65 20 56 20 70 61 72 61 6d 65 74 65 72 2c  the V parameter,
1c8a0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20  .**          or 
1c8b0 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c  the default [sql
1c8c0 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74  ite3_vfs] object
1c8d0 20 69 66 20 56 20 69 73 20 61 20 4e 55 4c 4c 20   if V is a NULL 
1c8e0 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b  pointer..**.** {
1c8f0 48 31 32 37 32 33 7d 20 54 77 6f 20 5b 64 61 74  H12723} Two [dat
1c900 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1c910 73 5d 20 77 69 6c 6c 20 73 68 61 72 65 20 61 20  s] will share a 
1c920 63 6f 6d 6d 6f 6e 20 63 61 63 68 65 20 69 66 20  common cache if 
1c930 62 6f 74 68 20 77 65 72 65 0a 2a 2a 20 20 20 20  both were.**    
1c940 20 20 20 20 20 20 6f 70 65 6e 65 64 20 77 69 74        opened wit
1c950 68 20 74 68 65 20 73 61 6d 65 20 56 46 53 20 77  h the same VFS w
1c960 68 69 6c 65 20 5b 73 68 61 72 65 64 20 63 61 63  hile [shared cac
1c970 68 65 20 6d 6f 64 65 5d 20 77 61 73 20 65 6e 61  he mode] was ena
1c980 62 6c 65 64 20 61 6e 64 0a 2a 2a 20 20 20 20 20  bled and.**     
1c990 20 20 20 20 20 69 66 20 62 6f 74 68 20 66 69 6c       if both fil
1c9a0 65 6e 61 6d 65 73 20 63 6f 6d 70 61 72 65 20 65  enames compare e
1c9b0 71 75 61 6c 20 75 73 69 6e 67 20 6d 65 6d 63 6d  qual using memcm
1c9c0 70 28 29 20 61 66 74 65 72 20 68 61 76 69 6e 67  p() after having
1c9d0 20 62 65 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20   been.**        
1c9e0 20 20 70 72 6f 63 65 73 73 65 64 20 62 79 20 74    processed by t
1c9f0 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 20  he [sqlite3_vfs 
1ca00 7c 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 5d  | xFullPathname]
1ca10 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 56   method of the V
1ca20 46 53 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  FS..*/.int sqlit
1ca30 65 33 5f 6f 70 65 6e 28 0a 20 20 63 6f 6e 73 74  e3_open(.  const
1ca40 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c   char *filename,
1ca50 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66     /* Database f
1ca60 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20  ilename (UTF-8) 
1ca70 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70  */.  sqlite3 **p
1ca80 70 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20  pDb          /* 
1ca90 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68  OUT: SQLite db h
1caa0 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20  andle */.);.int 
1cab0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 0a  sqlite3_open16(.
1cac0 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 66 69    const void *fi
1cad0 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74  lename,   /* Dat
1cae0 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28  abase filename (
1caf0 55 54 46 2d 31 36 29 20 2a 2f 0a 20 20 73 71 6c  UTF-16) */.  sql
1cb00 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20  ite3 **ppDb     
1cb10 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c       /* OUT: SQL
1cb20 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f  ite db handle */
1cb30 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
1cb40 6f 70 65 6e 5f 76 32 28 0a 20 20 63 6f 6e 73 74  open_v2(.  const
1cb50 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c   char *filename,
1cb60 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66     /* Database f
1cb70 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20  ilename (UTF-8) 
1cb80 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70  */.  sqlite3 **p
1cb90 70 44 62 2c 20 20 20 20 20 20 20 20 20 2f 2a 20  pDb,         /* 
1cba0 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68  OUT: SQLite db h
1cbb0 61 6e 64 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 66  andle */.  int f
1cbc0 6c 61 67 73 2c 20 20 20 20 20 20 20 20 20 20 20  lags,           
1cbd0 20 20 20 2f 2a 20 46 6c 61 67 73 20 2a 2f 0a 20     /* Flags */. 
1cbe0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 56 66   const char *zVf
1cbf0 73 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65  s        /* Name
1cc00 20 6f 66 20 56 46 53 20 6d 6f 64 75 6c 65 20 74   of VFS module t
1cc10 6f 20 75 73 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a  o use */.);../*.
1cc20 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 72 72  ** CAPI3REF: Err
1cc30 6f 72 20 43 6f 64 65 73 20 41 6e 64 20 4d 65 73  or Codes And Mes
1cc40 73 61 67 65 73 20 7b 48 31 32 38 30 30 7d 20 3c  sages {H12800} <
1cc50 53 36 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68  S60200>.**.** Th
1cc60 65 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64  e sqlite3_errcod
1cc70 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  e() interface re
1cc80 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 65 72 69  turns the numeri
1cc90 63 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 20  c [result code] 
1cca0 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20  or.** [extended 
1ccb0 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 66 6f 72  result code] for
1ccc0 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
1ccd0 20 66 61 69 6c 65 64 20 73 71 6c 69 74 65 33 5f   failed sqlite3_
1cce0 2a 20 41 50 49 20 63 61 6c 6c 0a 2a 2a 20 61 73  * API call.** as
1ccf0 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 61 20  sociated with a 
1cd00 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
1cd10 74 69 6f 6e 5d 2e 20 49 66 20 61 20 70 72 69 6f  tion]. If a prio
1cd20 72 20 41 50 49 20 63 61 6c 6c 20 66 61 69 6c 65  r API call faile
1cd30 64 0a 2a 2a 20 62 75 74 20 74 68 65 20 6d 6f 73  d.** but the mos
1cd40 74 20 72 65 63 65 6e 74 20 41 50 49 20 63 61 6c  t recent API cal
1cd50 6c 20 73 75 63 63 65 65 64 65 64 2c 20 74 68 65  l succeeded, the
1cd60 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72   return value fr
1cd70 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 72  om.** sqlite3_er
1cd80 72 63 6f 64 65 28 29 20 69 73 20 75 6e 64 65 66  rcode() is undef
1cd90 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ined..**.** The 
1cda0 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29  sqlite3_errmsg()
1cdb0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 65 72 72   and sqlite3_err
1cdc0 6d 73 67 31 36 28 29 20 72 65 74 75 72 6e 20 45  msg16() return E
1cdd0 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65 0a  nglish-language.
1cde0 2a 2a 20 74 65 78 74 20 74 68 61 74 20 64 65 73  ** text that des
1cdf0 63 72 69 62 65 73 20 74 68 65 20 65 72 72 6f 72  cribes the error
1ce00 2c 20 61 73 20 65 69 74 68 65 72 20 55 54 46 2d  , as either UTF-
1ce10 38 20 6f 72 20 55 54 46 2d 31 36 20 72 65 73 70  8 or UTF-16 resp
1ce20 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 4d 65 6d  ectively..** Mem
1ce30 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20  ory to hold the 
1ce40 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74  error message st
1ce50 72 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 64 20  ring is managed 
1ce60 69 6e 74 65 72 6e 61 6c 6c 79 2e 0a 2a 2a 20 54  internally..** T
1ce70 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  he application d
1ce80 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20  oes not need to 
1ce90 77 6f 72 72 79 20 61 62 6f 75 74 20 66 72 65 65  worry about free
1cea0 69 6e 67 20 74 68 65 20 72 65 73 75 6c 74 2e 0a  ing the result..
1ceb0 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74 68 65 20  ** However, the 
1cec0 65 72 72 6f 72 20 73 74 72 69 6e 67 20 6d 69 67  error string mig
1ced0 68 74 20 62 65 20 6f 76 65 72 77 72 69 74 74 65  ht be overwritte
1cee0 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 65 64  n or deallocated
1cef0 20 62 79 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e   by.** subsequen
1cf00 74 20 63 61 6c 6c 73 20 74 6f 20 6f 74 68 65 72  t calls to other
1cf10 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
1cf20 65 20 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 0a  e functions..**.
1cf30 2a 2a 20 49 66 20 61 6e 20 69 6e 74 65 72 66 61  ** If an interfa
1cf40 63 65 20 66 61 69 6c 73 20 77 69 74 68 20 53 51  ce fails with SQ
1cf50 4c 49 54 45 5f 4d 49 53 55 53 45 2c 20 74 68 61  LITE_MISUSE, tha
1cf60 74 20 6d 65 61 6e 73 20 74 68 65 20 69 6e 74 65  t means the inte
1cf70 72 66 61 63 65 0a 2a 2a 20 77 61 73 20 69 6e 76  rface.** was inv
1cf80 6f 6b 65 64 20 69 6e 63 6f 72 72 65 63 74 6c 79  oked incorrectly
1cf90 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 74   by the applicat
1cfa0 69 6f 6e 2e 20 20 49 6e 20 74 68 61 74 20 63 61  ion.  In that ca
1cfb0 73 65 2c 20 74 68 65 0a 2a 2a 20 65 72 72 6f 72  se, the.** error
1cfc0 20 63 6f 64 65 20 61 6e 64 20 6d 65 73 73 61 67   code and messag
1cfd0 65 20 6d 61 79 20 6f 72 20 6d 61 79 20 6e 6f 74  e may or may not
1cfe0 20 62 65 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 49   be set..**.** I
1cff0 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
1d000 20 7b 48 31 32 38 30 31 7d 20 54 68 65 20 5b 73   {H12801} The [s
1d010 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 44  qlite3_errcode(D
1d020 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  )] interface ret
1d030 75 72 6e 73 20 74 68 65 20 6e 75 6d 65 72 69 63  urns the numeric
1d040 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 72 65  .**          [re
1d050 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 20 5b 65  sult code] or [e
1d060 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
1d070 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 6d 6f 73  ode] for the mos
1d080 74 20 72 65 63 65 6e 74 6c 79 0a 2a 2a 20 20 20  t recently.**   
1d090 20 20 20 20 20 20 20 66 61 69 6c 65 64 20 69 6e         failed in
1d0a0 74 65 72 66 61 63 65 20 63 61 6c 6c 20 61 73 73  terface call ass
1d0b0 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65  ociated with the
1d0c0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
1d0d0 63 74 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20  ction] D..**.** 
1d0e0 7b 48 31 32 38 30 33 7d 20 54 68 65 20 5b 73 71  {H12803} The [sq
1d0f0 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 44 29 5d  lite3_errmsg(D)]
1d100 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 65 72   and [sqlite3_er
1d110 72 6d 73 67 31 36 28 44 29 5d 0a 2a 2a 20 20 20  rmsg16(D)].**   
1d120 20 20 20 20 20 20 20 69 6e 74 65 72 66 61 63 65         interface
1d130 73 20 72 65 74 75 72 6e 20 45 6e 67 6c 69 73 68  s return English
1d140 2d 6c 61 6e 67 75 61 67 65 20 74 65 78 74 20 74  -language text t
1d150 68 61 74 20 64 65 73 63 72 69 62 65 73 0a 2a 2a  hat describes.**
1d160 20 20 20 20 20 20 20 20 20 20 74 68 65 20 65 72            the er
1d170 72 6f 72 20 69 6e 20 74 68 65 20 6d 6f 73 74 6c  ror in the mostl
1d180 79 20 72 65 63 65 6e 74 6c 79 20 66 61 69 6c 65  y recently faile
1d190 64 20 69 6e 74 65 72 66 61 63 65 20 63 61 6c 6c  d interface call
1d1a0 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 65 6e  ,.**          en
1d1b0 63 6f 64 65 64 20 61 73 20 65 69 74 68 65 72 20  coded as either 
1d1c0 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20  UTF-8 or UTF-16 
1d1d0 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a  respectively..**
1d1e0 0a 2a 2a 20 7b 48 31 32 38 30 37 7d 20 54 68 65  .** {H12807} The
1d1f0 20 73 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65   strings returne
1d200 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 65 72  d by [sqlite3_er
1d210 72 6d 73 67 28 29 5d 20 61 6e 64 20 5b 73 71 6c  rmsg()] and [sql
1d220 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 5d  ite3_errmsg16()]
1d230 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 72 65  .**          are
1d240 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 74 68 65   valid until the
1d250 20 6e 65 78 74 20 53 51 4c 69 74 65 20 69 6e 74   next SQLite int
1d260 65 72 66 61 63 65 20 63 61 6c 6c 2e 0a 2a 2a 0a  erface call..**.
1d270 2a 2a 20 7b 48 31 32 38 30 38 7d 20 43 61 6c 6c  ** {H12808} Call
1d280 73 20 74 6f 20 41 50 49 20 72 6f 75 74 69 6e 65  s to API routine
1d290 73 20 74 68 61 74 20 64 6f 20 6e 6f 74 20 72 65  s that do not re
1d2a0 74 75 72 6e 20 61 6e 20 65 72 72 6f 72 20 63 6f  turn an error co
1d2b0 64 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 28  de.**          (
1d2c0 65 78 61 6d 70 6c 65 3a 20 5b 73 71 6c 69 74 65  example: [sqlite
1d2d0 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 29 5d 29  3_data_count()])
1d2e0 20 64 6f 20 6e 6f 74 0a 2a 2a 20 20 20 20 20 20   do not.**      
1d2f0 20 20 20 20 63 68 61 6e 67 65 20 74 68 65 20 65      change the e
1d300 72 72 6f 72 20 63 6f 64 65 20 6f 72 20 6d 65 73  rror code or mes
1d310 73 61 67 65 20 72 65 74 75 72 6e 65 64 20 62 79  sage returned by
1d320 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
1d330 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d  lite3_errcode()]
1d340 2c 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  , [sqlite3_errms
1d350 67 28 29 5d 2c 20 6f 72 20 5b 73 71 6c 69 74 65  g()], or [sqlite
1d360 33 5f 65 72 72 6d 73 67 31 36 28 29 5d 2e 0a 2a  3_errmsg16()]..*
1d370 2a 0a 2a 2a 20 7b 48 31 32 38 30 39 7d 20 49 6e  *.** {H12809} In
1d380 74 65 72 66 61 63 65 73 20 74 68 61 74 20 61 72  terfaces that ar
1d390 65 20 6e 6f 74 20 61 73 73 6f 63 69 61 74 65 64  e not associated
1d3a0 20 77 69 74 68 20 61 20 73 70 65 63 69 66 69 63   with a specific
1d3b0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 64 61  .**          [da
1d3c0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1d3d0 6e 5d 20 28 65 78 61 6d 70 6c 65 73 3a 0a 2a 2a  n] (examples:.**
1d3e0 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
1d3f0 65 33 5f 6d 70 72 69 6e 74 66 28 29 5d 20 6f 72  e3_mprintf()] or
1d400 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65   [sqlite3_enable
1d410 5f 73 68 61 72 65 64 5f 63 61 63 68 65 28 29 5d  _shared_cache()]
1d420 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64 6f 20  .**          do 
1d430 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 76  not change the v
1d440 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20 62  alues returned b
1d450 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  y.**          [s
1d460 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29  qlite3_errcode()
1d470 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d  ], [sqlite3_errm
1d480 73 67 28 29 5d 2c 20 6f 72 20 5b 73 71 6c 69 74  sg()], or [sqlit
1d490 65 33 5f 65 72 72 6d 73 67 31 36 28 29 5d 2e 0a  e3_errmsg16()]..
1d4a0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65  */.int sqlite3_e
1d4b0 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20 2a  rrcode(sqlite3 *
1d4c0 64 62 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20  db);.const char 
1d4d0 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28  *sqlite3_errmsg(
1d4e0 73 71 6c 69 74 65 33 2a 29 3b 0a 63 6f 6e 73 74  sqlite3*);.const
1d4f0 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 65   void *sqlite3_e
1d500 72 72 6d 73 67 31 36 28 73 71 6c 69 74 65 33 2a  rrmsg16(sqlite3*
1d510 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1d520 45 46 3a 20 53 51 4c 20 53 74 61 74 65 6d 65 6e  EF: SQL Statemen
1d530 74 20 4f 62 6a 65 63 74 20 7b 48 31 33 30 30 30  t Object {H13000
1d540 7d 20 3c 48 31 33 30 31 30 3e 0a 2a 2a 20 4b 45  } <H13010>.** KE
1d550 59 57 4f 52 44 53 3a 20 7b 70 72 65 70 61 72 65  YWORDS: {prepare
1d560 64 20 73 74 61 74 65 6d 65 6e 74 7d 20 7b 70 72  d statement} {pr
1d570 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
1d580 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74  s}.**.** An inst
1d590 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a  ance of this obj
1d5a0 65 63 74 20 72 65 70 72 65 73 65 6e 74 73 20 61  ect represents a
1d5b0 20 73 69 6e 67 6c 65 20 53 51 4c 20 73 74 61 74   single SQL stat
1d5c0 65 6d 65 6e 74 2e 0a 2a 2a 20 54 68 69 73 20 6f  ement..** This o
1d5d0 62 6a 65 63 74 20 69 73 20 76 61 72 69 6f 75 73  bject is various
1d5e0 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 61 20 22 70  ly known as a "p
1d5f0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
1d600 74 22 20 6f 72 20 61 0a 2a 2a 20 22 63 6f 6d 70  t" or a.** "comp
1d610 69 6c 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65  iled SQL stateme
1d620 6e 74 22 20 6f 72 20 73 69 6d 70 6c 79 20 61 73  nt" or simply as
1d630 20 61 20 22 73 74 61 74 65 6d 65 6e 74 22 2e 0a   a "statement"..
1d640 2a 2a 0a 2a 2a 20 54 68 65 20 6c 69 66 65 20 6f  **.** The life o
1d650 66 20 61 20 73 74 61 74 65 6d 65 6e 74 20 6f 62  f a statement ob
1d660 6a 65 63 74 20 67 6f 65 73 20 73 6f 6d 65 74 68  ject goes someth
1d670 69 6e 67 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a  ing like this:.*
1d680 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ol>.** <li
1d690 3e 20 43 72 65 61 74 65 20 74 68 65 20 6f 62 6a  > Create the obj
1d6a0 65 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ect using [sqlit
1d6b0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
1d6c0 20 6f 72 20 61 20 72 65 6c 61 74 65 64 0a 2a 2a   or a related.**
1d6d0 20 20 20 20 20 20 66 75 6e 63 74 69 6f 6e 2e 0a        function..
1d6e0 2a 2a 20 3c 6c 69 3e 20 42 69 6e 64 20 76 61 6c  ** <li> Bind val
1d6f0 75 65 73 20 74 6f 20 5b 68 6f 73 74 20 70 61 72  ues to [host par
1d700 61 6d 65 74 65 72 73 5d 20 75 73 69 6e 67 20 74  ameters] using t
1d710 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
1d720 2a 28 29 0a 2a 2a 20 20 20 20 20 20 69 6e 74 65  *().**      inte
1d730 72 66 61 63 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20  rfaces..** <li> 
1d740 52 75 6e 20 74 68 65 20 53 51 4c 20 62 79 20 63  Run the SQL by c
1d750 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
1d760 73 74 65 70 28 29 5d 20 6f 6e 65 20 6f 72 20 6d  step()] one or m
1d770 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c  ore times..** <l
1d780 69 3e 20 52 65 73 65 74 20 74 68 65 20 73 74 61  i> Reset the sta
1d790 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 71  tement using [sq
1d7a0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74  lite3_reset()] t
1d7b0 68 65 6e 20 67 6f 20 62 61 63 6b 0a 2a 2a 20 20  hen go back.**  
1d7c0 20 20 20 20 74 6f 20 73 74 65 70 20 32 2e 20 20      to step 2.  
1d7d0 44 6f 20 74 68 69 73 20 7a 65 72 6f 20 6f 72 20  Do this zero or 
1d7e0 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c  more times..** <
1d7f0 6c 69 3e 20 44 65 73 74 72 6f 79 20 74 68 65 20  li> Destroy the 
1d800 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73 71  object using [sq
1d810 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
1d820 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a  ]..** </ol>.**.*
1d830 2a 20 52 65 66 65 72 20 74 6f 20 64 6f 63 75 6d  * Refer to docum
1d840 65 6e 74 61 74 69 6f 6e 20 6f 6e 20 69 6e 64 69  entation on indi
1d850 76 69 64 75 61 6c 20 6d 65 74 68 6f 64 73 20 61  vidual methods a
1d860 62 6f 76 65 20 66 6f 72 20 61 64 64 69 74 69 6f  bove for additio
1d870 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69  nal.** informati
1d880 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  on..*/.typedef s
1d890 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 73 74  truct sqlite3_st
1d8a0 6d 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 3b  mt sqlite3_stmt;
1d8b0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1d8c0 3a 20 52 75 6e 2d 74 69 6d 65 20 4c 69 6d 69 74  : Run-time Limit
1d8d0 73 20 7b 48 31 32 37 36 30 7d 20 3c 53 32 30 36  s {H12760} <S206
1d8e0 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69  00>.**.** This i
1d8f0 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 20  nterface allows 
1d900 74 68 65 20 73 69 7a 65 20 6f 66 20 76 61 72 69  the size of vari
1d910 6f 75 73 20 63 6f 6e 73 74 72 75 63 74 73 20 74  ous constructs t
1d920 6f 20 62 65 20 6c 69 6d 69 74 65 64 0a 2a 2a 20  o be limited.** 
1d930 6f 6e 20 61 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  on a connection 
1d940 62 79 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61  by connection ba
1d950 73 69 73 2e 20 20 54 68 65 20 66 69 72 73 74 20  sis.  The first 
1d960 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
1d970 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
1d980 6e 6e 65 63 74 69 6f 6e 5d 20 77 68 6f 73 65 20  nnection] whose 
1d990 6c 69 6d 69 74 20 69 73 20 74 6f 20 62 65 20 73  limit is to be s
1d9a0 65 74 20 6f 72 20 71 75 65 72 69 65 64 2e 20 20  et or queried.  
1d9b0 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61  The.** second pa
1d9c0 72 61 6d 65 74 65 72 20 69 73 20 6f 6e 65 20 6f  rameter is one o
1d9d0 66 20 74 68 65 20 5b 6c 69 6d 69 74 20 63 61 74  f the [limit cat
1d9e0 65 67 6f 72 69 65 73 5d 20 74 68 61 74 20 64 65  egories] that de
1d9f0 66 69 6e 65 20 61 0a 2a 2a 20 63 6c 61 73 73 20  fine a.** class 
1da00 6f 66 20 63 6f 6e 73 74 72 75 63 74 73 20 74 6f  of constructs to
1da10 20 62 65 20 73 69 7a 65 20 6c 69 6d 69 74 65 64   be size limited
1da20 2e 20 20 54 68 65 20 74 68 69 72 64 20 70 61 72  .  The third par
1da30 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a  ameter is the.**
1da40 20 6e 65 77 20 6c 69 6d 69 74 20 66 6f 72 20 74   new limit for t
1da50 68 61 74 20 63 6f 6e 73 74 72 75 63 74 2e 20 20  hat construct.  
1da60 54 68 65 20 66 75 6e 63 74 69 6f 6e 20 72 65 74  The function ret
1da70 75 72 6e 73 20 74 68 65 20 6f 6c 64 20 6c 69 6d  urns the old lim
1da80 69 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  it..**.** If the
1da90 20 6e 65 77 20 6c 69 6d 69 74 20 69 73 20 61 20   new limit is a 
1daa0 6e 65 67 61 74 69 76 65 20 6e 75 6d 62 65 72 2c  negative number,
1dab0 20 74 68 65 20 6c 69 6d 69 74 20 69 73 20 75 6e   the limit is un
1dac0 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 46 6f 72 20  changed..** For 
1dad0 74 68 65 20 6c 69 6d 69 74 20 63 61 74 65 67 6f  the limit catego
1dae0 72 79 20 6f 66 20 53 51 4c 49 54 45 5f 4c 49 4d  ry of SQLITE_LIM
1daf0 49 54 5f 58 59 5a 20 74 68 65 72 65 20 69 73 20  IT_XYZ there is 
1db00 61 20 68 61 72 64 20 75 70 70 65 72 0a 2a 2a 20  a hard upper.** 
1db10 62 6f 75 6e 64 20 73 65 74 20 62 79 20 61 20 63  bound set by a c
1db20 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 43 20 70 72  ompile-time C pr
1db30 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f  eprocessor macro
1db40 20 6e 61 6d 65 64 20 53 51 4c 49 54 45 5f 4d 41   named SQLITE_MA
1db50 58 5f 58 59 5a 2e 0a 2a 2a 20 28 54 68 65 20 22  X_XYZ..** (The "
1db60 5f 4c 49 4d 49 54 5f 22 20 69 6e 20 74 68 65 20  _LIMIT_" in the 
1db70 6e 61 6d 65 20 69 73 20 63 68 61 6e 67 65 64 20  name is changed 
1db80 74 6f 20 22 5f 4d 41 58 5f 22 2e 29 0a 2a 2a 20  to "_MAX_".).** 
1db90 41 74 74 65 6d 70 74 73 20 74 6f 20 69 6e 63 72  Attempts to incr
1dba0 65 61 73 65 20 61 20 6c 69 6d 69 74 20 61 62 6f  ease a limit abo
1dbb0 76 65 20 69 74 73 20 68 61 72 64 20 75 70 70 65  ve its hard uppe
1dbc0 72 20 62 6f 75 6e 64 20 61 72 65 0a 2a 2a 20 73  r bound are.** s
1dbd0 69 6c 65 6e 74 6c 79 20 74 72 75 6e 63 61 74 65  ilently truncate
1dbe0 64 20 74 6f 20 74 68 65 20 68 61 72 64 20 75 70  d to the hard up
1dbf0 70 65 72 20 6c 69 6d 69 74 2e 0a 2a 2a 0a 2a 2a  per limit..**.**
1dc00 20 52 75 6e 20 74 69 6d 65 20 6c 69 6d 69 74 73   Run time limits
1dc10 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f   are intended fo
1dc20 72 20 75 73 65 20 69 6e 20 61 70 70 6c 69 63 61  r use in applica
1dc30 74 69 6f 6e 73 20 74 68 61 74 20 6d 61 6e 61 67  tions that manag
1dc40 65 0a 2a 2a 20 62 6f 74 68 20 74 68 65 69 72 20  e.** both their 
1dc50 6f 77 6e 20 69 6e 74 65 72 6e 61 6c 20 64 61 74  own internal dat
1dc60 61 62 61 73 65 20 61 6e 64 20 61 6c 73 6f 20 64  abase and also d
1dc70 61 74 61 62 61 73 65 73 20 74 68 61 74 20 61 72  atabases that ar
1dc80 65 20 63 6f 6e 74 72 6f 6c 6c 65 64 0a 2a 2a 20  e controlled.** 
1dc90 62 79 20 75 6e 74 72 75 73 74 65 64 20 65 78 74  by untrusted ext
1dca0 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 2e 20 20  ernal sources.  
1dcb0 41 6e 20 65 78 61 6d 70 6c 65 20 61 70 70 6c 69  An example appli
1dcc0 63 61 74 69 6f 6e 20 6d 69 67 68 74 20 62 65 20  cation might be 
1dcd0 61 0a 2a 2a 20 77 65 62 62 72 6f 77 73 65 72 20  a.** webbrowser 
1dce0 74 68 61 74 20 68 61 73 20 69 74 73 20 6f 77 6e  that has its own
1dcf0 20 64 61 74 61 62 61 73 65 73 20 66 6f 72 20 73   databases for s
1dd00 74 6f 72 69 6e 67 20 68 69 73 74 6f 72 79 20 61  toring history a
1dd10 6e 64 0a 2a 2a 20 73 65 70 61 72 61 74 65 20 64  nd.** separate d
1dd20 61 74 61 62 61 73 65 73 20 63 6f 6e 74 72 6f 6c  atabases control
1dd30 6c 65 64 20 62 79 20 4a 61 76 61 53 63 72 69 70  led by JavaScrip
1dd40 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 64  t applications d
1dd50 6f 77 6e 6c 6f 61 64 65 64 0a 2a 2a 20 6f 66 66  ownloaded.** off
1dd60 20 74 68 65 20 49 6e 74 65 72 6e 65 74 2e 20 20   the Internet.  
1dd70 54 68 65 20 69 6e 74 65 72 6e 61 6c 20 64 61 74  The internal dat
1dd80 61 62 61 73 65 73 20 63 61 6e 20 62 65 20 67 69  abases can be gi
1dd90 76 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 72 67 65  ven the.** large
1dda0 2c 20 64 65 66 61 75 6c 74 20 6c 69 6d 69 74 73  , default limits
1ddb0 2e 20 20 44 61 74 61 62 61 73 65 73 20 6d 61 6e  .  Databases man
1ddc0 61 67 65 64 20 62 79 20 65 78 74 65 72 6e 61 6c  aged by external
1ddd0 20 73 6f 75 72 63 65 73 20 63 61 6e 0a 2a 2a 20   sources can.** 
1dde0 62 65 20 67 69 76 65 6e 20 6d 75 63 68 20 73 6d  be given much sm
1ddf0 61 6c 6c 65 72 20 6c 69 6d 69 74 73 20 64 65 73  aller limits des
1de00 69 67 6e 65 64 20 74 6f 20 70 72 65 76 65 6e 74  igned to prevent
1de10 20 61 20 64 65 6e 69 61 6c 20 6f 66 20 73 65 72   a denial of ser
1de20 76 69 63 65 0a 2a 2a 20 61 74 74 61 63 6b 2e 20  vice.** attack. 
1de30 20 44 65 76 65 6c 6f 70 65 72 73 20 6d 69 67 68   Developers migh
1de40 74 20 61 6c 73 6f 20 77 61 6e 74 20 74 6f 20 75  t also want to u
1de50 73 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  se the [sqlite3_
1de60 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29  set_authorizer()
1de70 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 74  ].** interface t
1de80 6f 20 66 75 72 74 68 65 72 20 63 6f 6e 74 72 6f  o further contro
1de90 6c 20 75 6e 74 72 75 73 74 65 64 20 53 51 4c 2e  l untrusted SQL.
1dea0 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68    The size of th
1deb0 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 72  e database.** cr
1dec0 65 61 74 65 64 20 62 79 20 61 6e 20 75 6e 74 72  eated by an untr
1ded0 75 73 74 65 64 20 73 63 72 69 70 74 20 63 61 6e  usted script can
1dee0 20 62 65 20 63 6f 6e 74 61 69 6e 65 64 20 75 73   be contained us
1def0 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 6d 61 78 5f  ing the.** [max_
1df00 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41  page_count] [PRA
1df10 47 4d 41 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20  GMA]..**.** New 
1df20 72 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 20 63  run-time limit c
1df30 61 74 65 67 6f 72 69 65 73 20 6d 61 79 20 62 65  ategories may be
1df40 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65   added in future
1df50 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2a 0a 2a 2a   releases..**.**
1df60 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
1df70 2a 2a 20 7b 48 31 32 37 36 32 7d 20 41 20 73 75  ** {H12762} A su
1df80 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f  ccessful call to
1df90 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28   [sqlite3_limit(
1dfa0 44 2c 43 2c 56 29 5d 20 77 68 65 72 65 20 56 20  D,C,V)] where V 
1dfb0 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70  is.**          p
1dfc0 6f 73 69 74 69 76 65 20 63 68 61 6e 67 65 73 20  ositive changes 
1dfd0 74 68 65 20 6c 69 6d 69 74 20 6f 6e 20 74 68 65  the limit on the
1dfe0 20 73 69 7a 65 20 6f 66 20 63 6f 6e 73 74 72 75   size of constru
1dff0 63 74 20 43 20 69 6e 20 74 68 65 0a 2a 2a 20 20  ct C in the.**  
1e000 20 20 20 20 20 20 20 20 5b 64 61 74 61 62 61 73          [databas
1e010 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20  e connection] D 
1e020 74 6f 20 74 68 65 20 6c 65 73 73 65 72 20 6f 66  to the lesser of
1e030 20 56 20 61 6e 64 20 74 68 65 20 68 61 72 64 20   V and the hard 
1e040 75 70 70 65 72 0a 2a 2a 20 20 20 20 20 20 20 20  upper.**        
1e050 20 20 62 6f 75 6e 64 20 6f 6e 20 74 68 65 20 73    bound on the s
1e060 69 7a 65 20 6f 66 20 43 20 74 68 61 74 20 69 73  ize of C that is
1e070 20 73 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d   set at compile-
1e080 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  time..**.** {H12
1e090 37 36 36 7d 20 41 20 73 75 63 63 65 73 73 66 75  766} A successfu
1e0a0 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  l call to [sqlit
1e0b0 65 33 5f 6c 69 6d 69 74 28 44 2c 43 2c 56 29 5d  e3_limit(D,C,V)]
1e0c0 20 77 68 65 72 65 20 56 20 69 73 20 6e 65 67 61   where V is nega
1e0d0 74 69 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  tive.**         
1e0e0 20 6c 65 61 76 65 73 20 74 68 65 20 73 74 61 74   leaves the stat
1e0f0 65 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61  e of the [databa
1e100 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44  se connection] D
1e110 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 0a 2a   unchanged..**.*
1e120 2a 20 7b 48 31 32 37 36 39 7d 20 41 20 73 75 63  * {H12769} A suc
1e130 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20  cessful call to 
1e140 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 44  [sqlite3_limit(D
1e150 2c 43 2c 56 29 5d 20 72 65 74 75 72 6e 73 20 74  ,C,V)] returns t
1e160 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 76  he.**          v
1e170 61 6c 75 65 20 6f 66 20 74 68 65 20 6c 69 6d 69  alue of the limi
1e180 74 20 6f 6e 20 74 68 65 20 73 69 7a 65 20 6f 66  t on the size of
1e190 20 63 6f 6e 73 74 72 75 63 74 20 43 20 69 6e 20   construct C in 
1e1a0 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
1e1b0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
1e1c0 74 69 6f 6e 5d 20 44 20 61 73 20 69 74 20 77 61  tion] D as it wa
1e1d0 73 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20 63  s prior to the c
1e1e0 61 6c 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  all..*/.int sqli
1e1f0 74 65 33 5f 6c 69 6d 69 74 28 73 71 6c 69 74 65  te3_limit(sqlite
1e200 33 2a 2c 20 69 6e 74 20 69 64 2c 20 69 6e 74 20  3*, int id, int 
1e210 6e 65 77 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20  newVal);../*.** 
1e220 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69  CAPI3REF: Run-Ti
1e230 6d 65 20 4c 69 6d 69 74 20 43 61 74 65 67 6f 72  me Limit Categor
1e240 69 65 73 20 7b 48 31 32 37 39 30 7d 20 3c 48 31  ies {H12790} <H1
1e250 32 37 36 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44  2760>.** KEYWORD
1e260 53 3a 20 7b 6c 69 6d 69 74 20 63 61 74 65 67 6f  S: {limit catego
1e270 72 79 7d 20 7b 6c 69 6d 69 74 20 63 61 74 65 67  ry} {limit categ
1e280 6f 72 69 65 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65  ories}.**.** The
1e290 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 64 65 66  se constants def
1e2a0 69 6e 65 20 76 61 72 69 6f 75 73 20 61 73 70 65  ine various aspe
1e2b0 63 74 73 20 6f 66 20 61 20 5b 64 61 74 61 62 61  cts of a [databa
1e2c0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a  se connection].*
1e2d0 2a 20 74 68 61 74 20 63 61 6e 20 62 65 20 6c 69  * that can be li
1e2e0 6d 69 74 65 64 20 69 6e 20 73 69 7a 65 20 62 79  mited in size by
1e2f0 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74   calls to [sqlit
1e300 65 33 5f 6c 69 6d 69 74 28 29 5d 2e 0a 2a 2a 20  e3_limit()]..** 
1e310 54 68 65 20 6d 65 61 6e 69 6e 67 73 20 6f 66 20  The meanings of 
1e320 74 68 65 20 76 61 72 69 6f 75 73 20 6c 69 6d 69  the various limi
1e330 74 73 20 61 72 65 20 61 73 20 66 6f 6c 6c 6f 77  ts are as follow
1e340 73 3a 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a  s:.**.** <dl>.**
1e350 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49   <dt>SQLITE_LIMI
1e360 54 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a  T_LENGTH</dt>.**
1e370 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
1e380 20 73 69 7a 65 20 6f 66 20 61 6e 79 20 73 74 72   size of any str
1e390 69 6e 67 20 6f 72 20 42 4c 4f 42 20 6f 72 20 74  ing or BLOB or t
1e3a0 61 62 6c 65 20 72 6f 77 2e 3c 64 64 3e 0a 2a 2a  able row.<dd>.**
1e3b0 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  .** <dt>SQLITE_L
1e3c0 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 3c  IMIT_SQL_LENGTH<
1e3d0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
1e3e0 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  maximum length o
1e3f0 66 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  f an SQL stateme
1e400 6e 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  nt.</dd>.**.** <
1e410 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
1e420 43 4f 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c  COLUMN</dt>.** <
1e430 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e  dd>The maximum n
1e440 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
1e450 20 69 6e 20 61 20 74 61 62 6c 65 20 64 65 66 69   in a table defi
1e460 6e 69 74 69 6f 6e 20 6f 72 20 69 6e 20 74 68 65  nition or in the
1e470 0a 2a 2a 20 72 65 73 75 6c 74 20 73 65 74 20 6f  .** result set o
1e480 66 20 61 20 53 45 4c 45 43 54 20 6f 72 20 74 68  f a SELECT or th
1e490 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
1e4a0 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61   of columns in a
1e4b0 6e 20 69 6e 64 65 78 0a 2a 2a 20 6f 72 20 69 6e  n index.** or in
1e4c0 20 61 6e 20 4f 52 44 45 52 20 42 59 20 6f 72 20   an ORDER BY or 
1e4d0 47 52 4f 55 50 20 42 59 20 63 6c 61 75 73 65 2e  GROUP BY clause.
1e4e0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
1e4f0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50  SQLITE_LIMIT_EXP
1e500 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20  R_DEPTH</dt>.** 
1e510 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
1e520 64 65 70 74 68 20 6f 66 20 74 68 65 20 70 61 72  depth of the par
1e530 73 65 20 74 72 65 65 20 6f 6e 20 61 6e 79 20 65  se tree on any e
1e540 78 70 72 65 73 73 69 6f 6e 2e 3c 2f 64 64 3e 0a  xpression.</dd>.
1e550 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
1e560 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f  _LIMIT_COMPOUND_
1e570 53 45 4c 45 43 54 3c 2f 64 74 3e 0a 2a 2a 20 3c  SELECT</dt>.** <
1e580 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e  dd>The maximum n
1e590 75 6d 62 65 72 20 6f 66 20 74 65 72 6d 73 20 69  umber of terms i
1e5a0 6e 20 61 20 63 6f 6d 70 6f 75 6e 64 20 53 45 4c  n a compound SEL
1e5b0 45 43 54 20 73 74 61 74 65 6d 65 6e 74 2e 3c 2f  ECT statement.</
1e5c0 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51  dd>.**.** <dt>SQ
1e5d0 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f  LITE_LIMIT_VDBE_
1e5e0 4f 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  OP</dt>.** <dd>T
1e5f0 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
1e600 72 20 6f 66 20 69 6e 73 74 72 75 63 74 69 6f 6e  r of instruction
1e610 73 20 69 6e 20 61 20 76 69 72 74 75 61 6c 20 6d  s in a virtual m
1e620 61 63 68 69 6e 65 20 70 72 6f 67 72 61 6d 0a 2a  achine program.*
1e630 2a 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d  * used to implem
1e640 65 6e 74 20 61 6e 20 53 51 4c 20 73 74 61 74 65  ent an SQL state
1e650 6d 65 6e 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ment.</dd>.**.**
1e660 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49   <dt>SQLITE_LIMI
1e670 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 3c 2f  T_FUNCTION_ARG</
1e680 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
1e690 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
1e6a0 20 61 72 67 75 6d 65 6e 74 73 20 6f 6e 20 61 20   arguments on a 
1e6b0 66 75 6e 63 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a  function.</dd>.*
1e6c0 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
1e6d0 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44 3c 2f  LIMIT_ATTACHED</
1e6e0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
1e6f0 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
1e700 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61   attached databa
1e710 73 65 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ses.</dd>.**.** 
1e720 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
1e730 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45  _LIKE_PATTERN_LE
1e740 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  NGTH</dt>.** <dd
1e750 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e  >The maximum len
1e760 67 74 68 20 6f 66 20 74 68 65 20 70 61 74 74 65  gth of the patte
1e770 72 6e 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  rn argument to t
1e780 68 65 20 4c 49 4b 45 20 6f 72 0a 2a 2a 20 47 4c  he LIKE or.** GL
1e790 4f 42 20 6f 70 65 72 61 74 6f 72 73 2e 3c 2f 64  OB operators.</d
1e7a0 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
1e7b0 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42  ITE_LIMIT_VARIAB
1e7c0 4c 45 5f 4e 55 4d 42 45 52 3c 2f 64 74 3e 0a 2a  LE_NUMBER</dt>.*
1e7d0 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
1e7e0 6d 20 6e 75 6d 62 65 72 20 6f 66 20 76 61 72 69  m number of vari
1e7f0 61 62 6c 65 73 20 69 6e 20 61 6e 20 53 51 4c 20  ables in an SQL 
1e800 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20 63  statement that c
1e810 61 6e 0a 2a 2a 20 62 65 20 62 6f 75 6e 64 2e 3c  an.** be bound.<
1e820 2f 64 64 3e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f  /dd>.** </dl>.*/
1e830 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1e840 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 20 20 20 20  LIMIT_LENGTH    
1e850 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1e860 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
1e870 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54  _LIMIT_SQL_LENGT
1e880 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  H               
1e890 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   1.#define SQLIT
1e8a0 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 20 20  E_LIMIT_COLUMN  
1e8b0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1e8c0 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    2.#define SQLI
1e8d0 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45  TE_LIMIT_EXPR_DE
1e8e0 50 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20  PTH             
1e8f0 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c     3.#define SQL
1e900 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55  ITE_LIMIT_COMPOU
1e910 4e 44 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20  ND_SELECT       
1e920 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51      4.#define SQ
1e930 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f  LITE_LIMIT_VDBE_
1e940 4f 50 20 20 20 20 20 20 20 20 20 20 20 20 20 20  OP              
1e950 20 20 20 20 20 35 0a 23 64 65 66 69 6e 65 20 53       5.#define S
1e960 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43  QLITE_LIMIT_FUNC
1e970 54 49 4f 4e 5f 41 52 47 20 20 20 20 20 20 20 20  TION_ARG        
1e980 20 20 20 20 20 20 36 0a 23 64 65 66 69 6e 65 20        6.#define 
1e990 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54  SQLITE_LIMIT_ATT
1e9a0 41 43 48 45 44 20 20 20 20 20 20 20 20 20 20 20  ACHED           
1e9b0 20 20 20 20 20 20 20 37 0a 23 64 65 66 69 6e 65         7.#define
1e9c0 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49   SQLITE_LIMIT_LI
1e9d0 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54  KE_PATTERN_LENGT
1e9e0 48 20 20 20 20 20 20 20 38 0a 23 64 65 66 69 6e  H       8.#defin
1e9f0 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56  e SQLITE_LIMIT_V
1ea00 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 20 20  ARIABLE_NUMBER  
1ea10 20 20 20 20 20 20 20 20 20 39 0a 0a 2f 2a 0a 2a           9../*.*
1ea20 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70  * CAPI3REF: Comp
1ea30 69 6c 69 6e 67 20 41 6e 20 53 51 4c 20 53 74 61  iling An SQL Sta
1ea40 74 65 6d 65 6e 74 20 7b 48 31 33 30 31 30 7d 20  tement {H13010} 
1ea50 3c 53 31 30 30 30 30 3e 0a 2a 2a 20 4b 45 59 57  <S10000>.** KEYW
1ea60 4f 52 44 53 3a 20 7b 53 51 4c 20 73 74 61 74 65  ORDS: {SQL state
1ea70 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 72 7d 0a 2a  ment compiler}.*
1ea80 2a 0a 2a 2a 20 54 6f 20 65 78 65 63 75 74 65 20  *.** To execute 
1ea90 61 6e 20 53 51 4c 20 71 75 65 72 79 2c 20 69 74  an SQL query, it
1eaa0 20 6d 75 73 74 20 66 69 72 73 74 20 62 65 20 63   must first be c
1eab0 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20 61 20 62  ompiled into a b
1eac0 79 74 65 2d 63 6f 64 65 0a 2a 2a 20 70 72 6f 67  yte-code.** prog
1ead0 72 61 6d 20 75 73 69 6e 67 20 6f 6e 65 20 6f 66  ram using one of
1eae0 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e   these routines.
1eaf0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  .**.** The first
1eb00 20 61 72 67 75 6d 65 6e 74 2c 20 22 64 62 22 2c   argument, "db",
1eb10 20 69 73 20 61 20 5b 64 61 74 61 62 61 73 65 20   is a [database 
1eb20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62 74 61  connection] obta
1eb30 69 6e 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 70  ined from a.** p
1eb40 72 69 6f 72 20 63 61 6c 6c 20 74 6f 20 5b 73 71  rior call to [sq
1eb50 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b  lite3_open()], [
1eb60 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
1eb70 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f  )] or [sqlite3_o
1eb80 70 65 6e 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  pen16()]..**.** 
1eb90 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  The second argum
1eba0 65 6e 74 2c 20 22 7a 53 71 6c 22 2c 20 69 73 20  ent, "zSql", is 
1ebb0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 74 6f  the statement to
1ebc0 20 62 65 20 63 6f 6d 70 69 6c 65 64 2c 20 65 6e   be compiled, en
1ebd0 63 6f 64 65 64 0a 2a 2a 20 61 73 20 65 69 74 68  coded.** as eith
1ebe0 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d  er UTF-8 or UTF-
1ebf0 31 36 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33  16.  The sqlite3
1ec00 5f 70 72 65 70 61 72 65 28 29 20 61 6e 64 20 73  _prepare() and s
1ec10 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
1ec20 32 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  2().** interface
1ec30 73 20 75 73 65 20 55 54 46 2d 38 2c 20 61 6e 64  s use UTF-8, and
1ec40 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
1ec50 31 36 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  16() and sqlite3
1ec60 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 0a  _prepare16_v2().
1ec70 2a 2a 20 75 73 65 20 55 54 46 2d 31 36 2e 0a 2a  ** use UTF-16..*
1ec80 2a 0a 2a 2a 20 49 66 20 74 68 65 20 6e 42 79 74  *.** If the nByt
1ec90 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6c 65  e argument is le
1eca0 73 73 20 74 68 61 6e 20 7a 65 72 6f 2c 20 74 68  ss than zero, th
1ecb0 65 6e 20 7a 53 71 6c 20 69 73 20 72 65 61 64 20  en zSql is read 
1ecc0 75 70 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 72  up to the.** fir
1ecd0 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74  st zero terminat
1ece0 6f 72 2e 20 49 66 20 6e 42 79 74 65 20 69 73 20  or. If nByte is 
1ecf0 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68  non-negative, th
1ed00 65 6e 20 69 74 20 69 73 20 74 68 65 20 6d 61 78  en it is the max
1ed10 69 6d 75 6d 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f  imum.** number o
1ed20 66 20 20 62 79 74 65 73 20 72 65 61 64 20 66 72  f  bytes read fr
1ed30 6f 6d 20 7a 53 71 6c 2e 20 20 57 68 65 6e 20 6e  om zSql.  When n
1ed40 42 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61  Byte is non-nega
1ed50 74 69 76 65 2c 20 74 68 65 0a 2a 2a 20 7a 53 71  tive, the.** zSq
1ed60 6c 20 73 74 72 69 6e 67 20 65 6e 64 73 20 61 74  l string ends at
1ed70 20 65 69 74 68 65 72 20 74 68 65 20 66 69 72 73   either the firs
1ed80 74 20 27 5c 30 30 30 27 20 6f 72 20 27 5c 75 30  t '\000' or '\u0
1ed90 30 30 30 27 20 63 68 61 72 61 63 74 65 72 20 6f  000' character o
1eda0 72 0a 2a 2a 20 74 68 65 20 6e 42 79 74 65 2d 74  r.** the nByte-t
1edb0 68 20 62 79 74 65 2c 20 77 68 69 63 68 65 76 65  h byte, whicheve
1edc0 72 20 63 6f 6d 65 73 20 66 69 72 73 74 2e 20 49  r comes first. I
1edd0 66 20 74 68 65 20 63 61 6c 6c 65 72 20 6b 6e 6f  f the caller kno
1ede0 77 73 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 73  ws.** that the s
1edf0 75 70 70 6c 69 65 64 20 73 74 72 69 6e 67 20 69  upplied string i
1ee00 73 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64  s nul-terminated
1ee10 2c 20 74 68 65 6e 20 74 68 65 72 65 20 69 73 20  , then there is 
1ee20 61 20 73 6d 61 6c 6c 0a 2a 2a 20 70 65 72 66 6f  a small.** perfo
1ee30 72 6d 61 6e 63 65 20 61 64 76 61 6e 74 61 67 65  rmance advantage
1ee40 20 74 6f 20 62 65 20 67 61 69 6e 65 64 20 62 79   to be gained by
1ee50 20 70 61 73 73 69 6e 67 20 61 6e 20 6e 42 79 74   passing an nByt
1ee60 65 20 70 61 72 61 6d 65 74 65 72 20 74 68 61 74  e parameter that
1ee70 0a 2a 2a 20 69 73 20 65 71 75 61 6c 20 74 6f 20  .** is equal to 
1ee80 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
1ee90 74 65 73 20 69 6e 20 74 68 65 20 69 6e 70 75 74  tes in the input
1eea0 20 73 74 72 69 6e 67 20 3c 69 3e 69 6e 63 6c 75   string <i>inclu
1eeb0 64 69 6e 67 3c 2f 69 3e 0a 2a 2a 20 74 68 65 20  ding</i>.** the 
1eec0 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 6f 72 20 62  nul-terminator b
1eed0 79 74 65 73 2e 0a 2a 2a 0a 2a 2a 20 2a 70 7a 54  ytes..**.** *pzT
1eee0 61 69 6c 20 69 73 20 6d 61 64 65 20 74 6f 20 70  ail is made to p
1eef0 6f 69 6e 74 20 74 6f 20 74 68 65 20 66 69 72 73  oint to the firs
1ef00 74 20 62 79 74 65 20 70 61 73 74 20 74 68 65 20  t byte past the 
1ef10 65 6e 64 20 6f 66 20 74 68 65 0a 2a 2a 20 66 69  end of the.** fi
1ef20 72 73 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  rst SQL statemen
1ef30 74 20 69 6e 20 7a 53 71 6c 2e 20 20 54 68 65 73  t in zSql.  Thes
1ef40 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e 6c 79 20  e routines only 
1ef50 63 6f 6d 70 69 6c 65 20 74 68 65 20 66 69 72 73  compile the firs
1ef60 74 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 69  t.** statement i
1ef70 6e 20 7a 53 71 6c 2c 20 73 6f 20 2a 70 7a 54 61  n zSql, so *pzTa
1ef80 69 6c 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74  il is left point
1ef90 69 6e 67 20 74 6f 20 77 68 61 74 20 72 65 6d 61  ing to what rema
1efa0 69 6e 73 0a 2a 2a 20 75 6e 63 6f 6d 70 69 6c 65  ins.** uncompile
1efb0 64 2e 0a 2a 2a 0a 2a 2a 20 2a 70 70 53 74 6d 74  d..**.** *ppStmt
1efc0 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e   is left pointin
1efd0 67 20 74 6f 20 61 20 63 6f 6d 70 69 6c 65 64 20  g to a compiled 
1efe0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
1eff0 65 6e 74 5d 20 74 68 61 74 20 63 61 6e 20 62 65  ent] that can be
1f000 0a 2a 2a 20 65 78 65 63 75 74 65 64 20 75 73 69  .** executed usi
1f010 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ng [sqlite3_step
1f020 28 29 5d 2e 20 20 49 66 20 74 68 65 72 65 20 69  ()].  If there i
1f030 73 20 61 6e 20 65 72 72 6f 72 2c 20 2a 70 70 53  s an error, *ppS
1f040 74 6d 74 20 69 73 20 73 65 74 0a 2a 2a 20 74 6f  tmt is set.** to
1f050 20 4e 55 4c 4c 2e 20 20 49 66 20 74 68 65 20 69   NULL.  If the i
1f060 6e 70 75 74 20 74 65 78 74 20 63 6f 6e 74 61 69  nput text contai
1f070 6e 73 20 6e 6f 20 53 51 4c 20 28 69 66 20 74 68  ns no SQL (if th
1f080 65 20 69 6e 70 75 74 20 69 73 20 61 6e 20 65 6d  e input is an em
1f090 70 74 79 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 72  pty.** string or
1f0a0 20 61 20 63 6f 6d 6d 65 6e 74 29 20 74 68 65 6e   a comment) then
1f0b0 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74 20   *ppStmt is set 
1f0c0 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 7b 41 31 33  to NULL..** {A13
1f0d0 30 31 38 7d 20 54 68 65 20 63 61 6c 6c 69 6e 67  018} The calling
1f0e0 20 70 72 6f 63 65 64 75 72 65 20 69 73 20 72 65   procedure is re
1f0f0 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 64 65  sponsible for de
1f100 6c 65 74 69 6e 67 20 74 68 65 20 63 6f 6d 70 69  leting the compi
1f110 6c 65 64 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65  led.** SQL state
1f120 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c 69  ment using [sqli
1f130 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
1f140 61 66 74 65 72 20 69 74 20 68 61 73 20 66 69 6e  after it has fin
1f150 69 73 68 65 64 20 77 69 74 68 20 69 74 2e 0a 2a  ished with it..*
1f160 2a 0a 2a 2a 20 4f 6e 20 73 75 63 63 65 73 73 2c  *.** On success,
1f170 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20   [SQLITE_OK] is 
1f180 72 65 74 75 72 6e 65 64 2c 20 6f 74 68 65 72 77  returned, otherw
1f190 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f  ise an [error co
1f1a0 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e  de] is returned.
1f1b0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
1f1c0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20  e3_prepare_v2() 
1f1d0 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70  and sqlite3_prep
1f1e0 61 72 65 31 36 5f 76 32 28 29 20 69 6e 74 65 72  are16_v2() inter
1f1f0 66 61 63 65 73 20 61 72 65 0a 2a 2a 20 72 65 63  faces are.** rec
1f200 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 61 6c 6c  ommended for all
1f210 20 6e 65 77 20 70 72 6f 67 72 61 6d 73 2e 20 54   new programs. T
1f220 68 65 20 74 77 6f 20 6f 6c 64 65 72 20 69 6e 74  he two older int
1f230 65 72 66 61 63 65 73 20 61 72 65 20 72 65 74 61  erfaces are reta
1f240 69 6e 65 64 0a 2a 2a 20 66 6f 72 20 62 61 63 6b  ined.** for back
1f250 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c  wards compatibil
1f260 69 74 79 2c 20 62 75 74 20 74 68 65 69 72 20 75  ity, but their u
1f270 73 65 20 69 73 20 64 69 73 63 6f 75 72 61 67 65  se is discourage
1f280 64 2e 0a 2a 2a 20 49 6e 20 74 68 65 20 22 76 32  d..** In the "v2
1f290 22 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68  " interfaces, th
1f2a0 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  e prepared state
1f2b0 6d 65 6e 74 0a 2a 2a 20 74 68 61 74 20 69 73 20  ment.** that is 
1f2c0 72 65 74 75 72 6e 65 64 20 28 74 68 65 20 5b 73  returned (the [s
1f2d0 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a  qlite3_stmt] obj
1f2e0 65 63 74 29 20 63 6f 6e 74 61 69 6e 73 20 61 20  ect) contains a 
1f2f0 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 6f  copy of the.** o
1f300 72 69 67 69 6e 61 6c 20 53 51 4c 20 74 65 78 74  riginal SQL text
1f310 2e 20 54 68 69 73 20 63 61 75 73 65 73 20 74 68  . This causes th
1f320 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  e [sqlite3_step(
1f330 29 5d 20 69 6e 74 65 72 66 61 63 65 20 74 6f 0a  )] interface to.
1f340 2a 2a 20 62 65 68 61 76 65 20 61 20 64 69 66 66  ** behave a diff
1f350 65 72 65 6e 74 6c 79 20 69 6e 20 74 77 6f 20 77  erently in two w
1f360 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a  ays:.**.** <ol>.
1f370 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 49 66 20 74 68  ** <li>.** If th
1f380 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d  e database schem
1f390 61 20 63 68 61 6e 67 65 73 2c 20 69 6e 73 74 65  a changes, inste
1f3a0 61 64 20 6f 66 20 72 65 74 75 72 6e 69 6e 67 20  ad of returning 
1f3b0 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20  [SQLITE_SCHEMA] 
1f3c0 61 73 20 69 74 0a 2a 2a 20 61 6c 77 61 79 73 20  as it.** always 
1f3d0 75 73 65 64 20 74 6f 20 64 6f 2c 20 5b 73 71 6c  used to do, [sql
1f3e0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c  ite3_step()] wil
1f3f0 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  l automatically 
1f400 72 65 63 6f 6d 70 69 6c 65 20 74 68 65 20 53 51  recompile the SQ
1f410 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 61  L.** statement a
1f420 6e 64 20 74 72 79 20 74 6f 20 72 75 6e 20 69 74  nd try to run it
1f430 20 61 67 61 69 6e 2e 20 20 49 66 20 74 68 65 20   again.  If the 
1f440 73 63 68 65 6d 61 20 68 61 73 20 63 68 61 6e 67  schema has chang
1f450 65 64 20 69 6e 0a 2a 2a 20 61 20 77 61 79 20 74  ed in.** a way t
1f460 68 61 74 20 6d 61 6b 65 73 20 74 68 65 20 73 74  hat makes the st
1f470 61 74 65 6d 65 6e 74 20 6e 6f 20 6c 6f 6e 67 65  atement no longe
1f480 72 20 76 61 6c 69 64 2c 20 5b 73 71 6c 69 74 65  r valid, [sqlite
1f490 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 73  3_step()] will s
1f4a0 74 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b  till.** return [
1f4b0 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 2e 20  SQLITE_SCHEMA]. 
1f4c0 20 42 75 74 20 75 6e 6c 69 6b 65 20 74 68 65 20   But unlike the 
1f4d0 6c 65 67 61 63 79 20 62 65 68 61 76 69 6f 72 2c  legacy behavior,
1f4e0 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d   [SQLITE_SCHEMA]
1f4f0 20 69 73 0a 2a 2a 20 6e 6f 77 20 61 20 66 61 74   is.** now a fat
1f500 61 6c 20 65 72 72 6f 72 2e 20 20 43 61 6c 6c 69  al error.  Calli
1f510 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ng [sqlite3_prep
1f520 61 72 65 5f 76 32 28 29 5d 20 61 67 61 69 6e 20  are_v2()] again 
1f530 77 69 6c 6c 20 6e 6f 74 20 6d 61 6b 65 20 74 68  will not make th
1f540 65 0a 2a 2a 20 65 72 72 6f 72 20 67 6f 20 61 77  e.** error go aw
1f550 61 79 2e 20 20 4e 6f 74 65 3a 20 75 73 65 20 5b  ay.  Note: use [
1f560 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29  sqlite3_errmsg()
1f570 5d 20 74 6f 20 66 69 6e 64 20 74 68 65 20 74 65  ] to find the te
1f580 78 74 0a 2a 2a 20 6f 66 20 74 68 65 20 70 61 72  xt.** of the par
1f590 73 69 6e 67 20 65 72 72 6f 72 20 74 68 61 74 20  sing error that 
1f5a0 72 65 73 75 6c 74 73 20 69 6e 20 61 6e 20 5b 53  results in an [S
1f5b0 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20 72 65  QLITE_SCHEMA] re
1f5c0 74 75 72 6e 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a  turn..** </li>.*
1f5d0 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 57 68 65  *.** <li>.** Whe
1f5e0 6e 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72  n an error occur
1f5f0 73 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  s, [sqlite3_step
1f600 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  ()] will return 
1f610 6f 6e 65 20 6f 66 20 74 68 65 20 64 65 74 61 69  one of the detai
1f620 6c 65 64 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f  led.** [error co
1f630 64 65 73 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65  des] or [extende
1f640 64 20 65 72 72 6f 72 20 63 6f 64 65 73 5d 2e 20  d error codes]. 
1f650 20 54 68 65 20 6c 65 67 61 63 79 20 62 65 68 61   The legacy beha
1f660 76 69 6f 72 20 77 61 73 20 74 68 61 74 0a 2a 2a  vior was that.**
1f670 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
1f680 5d 20 77 6f 75 6c 64 20 6f 6e 6c 79 20 72 65 74  ] would only ret
1f690 75 72 6e 20 61 20 67 65 6e 65 72 69 63 20 5b 53  urn a generic [S
1f6a0 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 72 65 73  QLITE_ERROR] res
1f6b0 75 6c 74 20 63 6f 64 65 0a 2a 2a 20 61 6e 64 20  ult code.** and 
1f6c0 79 6f 75 20 77 6f 75 6c 64 20 68 61 76 65 20 74  you would have t
1f6d0 6f 20 6d 61 6b 65 20 61 20 73 65 63 6f 6e 64 20  o make a second 
1f6e0 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
1f6f0 5f 72 65 73 65 74 28 29 5d 20 69 6e 20 6f 72 64  _reset()] in ord
1f700 65 72 0a 2a 2a 20 74 6f 20 66 69 6e 64 20 74 68  er.** to find th
1f710 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 63 61 75  e underlying cau
1f720 73 65 20 6f 66 20 74 68 65 20 70 72 6f 62 6c 65  se of the proble
1f730 6d 2e 20 57 69 74 68 20 74 68 65 20 22 76 32 22  m. With the "v2"
1f740 20 70 72 65 70 61 72 65 0a 2a 2a 20 69 6e 74 65   prepare.** inte
1f750 72 66 61 63 65 73 2c 20 74 68 65 20 75 6e 64 65  rfaces, the unde
1f760 72 6c 79 69 6e 67 20 72 65 61 73 6f 6e 20 66 6f  rlying reason fo
1f770 72 20 74 68 65 20 65 72 72 6f 72 20 69 73 20 72  r the error is r
1f780 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74  eturned immediat
1f790 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a  ely..** </li>.**
1f7a0 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 49 4e 56   </ol>.**.** INV
1f7b0 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
1f7c0 48 31 33 30 31 31 7d 20 54 68 65 20 5b 73 71 6c  H13011} The [sql
1f7d0 69 74 65 33 5f 70 72 65 70 61 72 65 28 64 62 2c  ite3_prepare(db,
1f7e0 7a 53 71 6c 2c 2e 2e 2e 29 5d 20 61 6e 64 0a 2a  zSql,...)] and.*
1f7f0 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
1f800 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 64  te3_prepare_v2(d
1f810 62 2c 7a 53 71 6c 2c 2e 2e 2e 29 5d 20 69 6e 74  b,zSql,...)] int
1f820 65 72 66 61 63 65 73 20 69 6e 74 65 72 70 72 65  erfaces interpre
1f830 74 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  t the.**        
1f840 20 20 74 65 78 74 20 69 6e 20 74 68 65 69 72 20    text in their 
1f850 7a 53 71 6c 20 70 61 72 61 6d 65 74 65 72 20 61  zSql parameter a
1f860 73 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 7b  s UTF-8..**.** {
1f870 48 31 33 30 31 32 7d 20 54 68 65 20 5b 73 71 6c  H13012} The [sql
1f880 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 64  ite3_prepare16(d
1f890 62 2c 7a 53 71 6c 2c 2e 2e 2e 29 5d 20 61 6e 64  b,zSql,...)] and
1f8a0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
1f8b0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
1f8c0 76 32 28 64 62 2c 7a 53 71 6c 2c 2e 2e 2e 29 5d  v2(db,zSql,...)]
1f8d0 20 69 6e 74 65 72 66 61 63 65 73 20 69 6e 74 65   interfaces inte
1f8e0 72 70 72 65 74 20 74 68 65 0a 2a 2a 20 20 20 20  rpret the.**    
1f8f0 20 20 20 20 20 20 74 65 78 74 20 69 6e 20 74 68        text in th
1f900 65 69 72 20 7a 53 71 6c 20 70 61 72 61 6d 65 74  eir zSql paramet
1f910 65 72 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20  er as UTF-16 in 
1f920 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 20  the native byte 
1f930 6f 72 64 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  order..**.** {H1
1f940 33 30 31 33 7d 20 49 66 20 74 68 65 20 6e 42 79  3013} If the nBy
1f950 74 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b  te argument to [
1f960 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
1f970 76 32 28 64 62 2c 7a 53 71 6c 2c 6e 42 79 74 65  v2(db,zSql,nByte
1f980 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20  ,...)].**       
1f990 20 20 20 61 6e 64 20 69 74 73 20 76 61 72 69 61     and its varia
1f9a0 6e 74 73 20 69 73 20 6c 65 73 73 20 74 68 61 6e  nts is less than
1f9b0 20 7a 65 72 6f 2c 20 74 68 65 20 53 51 4c 20 74   zero, the SQL t
1f9c0 65 78 74 20 69 73 0a 2a 2a 20 20 20 20 20 20 20  ext is.**       
1f9d0 20 20 20 72 65 61 64 20 66 72 6f 6d 20 7a 53 71     read from zSq
1f9e0 6c 20 69 73 20 72 65 61 64 20 75 70 20 74 6f 20  l is read up to 
1f9f0 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 74  the first zero t
1fa00 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a  erminator..**.**
1fa10 20 7b 48 31 33 30 31 34 7d 20 49 66 20 74 68 65   {H13014} If the
1fa20 20 6e 42 79 74 65 20 61 72 67 75 6d 65 6e 74 20   nByte argument 
1fa30 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  to [sqlite3_prep
1fa40 61 72 65 5f 76 32 28 64 62 2c 7a 53 71 6c 2c 6e  are_v2(db,zSql,n
1fa50 42 79 74 65 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20  Byte,...)].**   
1fa60 20 20 20 20 20 20 20 61 6e 64 20 69 74 73 20 76         and its v
1fa70 61 72 69 61 6e 74 73 20 69 73 20 6e 6f 6e 2d 6e  ariants is non-n
1fa80 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 61 74  egative, then at
1fa90 20 6d 6f 73 74 20 6e 42 79 74 65 73 20 62 79 74   most nBytes byt
1faa0 65 73 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20  es of.**        
1fab0 20 20 53 51 4c 20 74 65 78 74 20 69 73 20 72 65    SQL text is re
1fac0 61 64 20 66 72 6f 6d 20 7a 53 71 6c 2e 0a 2a 2a  ad from zSql..**
1fad0 0a 2a 2a 20 7b 48 31 33 30 31 35 7d 20 49 6e 20  .** {H13015} In 
1fae0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1faf0 5f 76 32 28 64 62 2c 7a 53 71 6c 2c 4e 2c 50 2c  _v2(db,zSql,N,P,
1fb00 70 7a 54 61 69 6c 29 5d 20 61 6e 64 20 69 74 73  pzTail)] and its
1fb10 20 76 61 72 69 61 6e 74 73 0a 2a 2a 20 20 20 20   variants.**    
1fb20 20 20 20 20 20 20 69 66 20 74 68 65 20 7a 53 71        if the zSq
1fb30 6c 20 69 6e 70 75 74 20 74 65 78 74 20 63 6f 6e  l input text con
1fb40 74 61 69 6e 73 20 6d 6f 72 65 20 74 68 61 6e 20  tains more than 
1fb50 6f 6e 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  one SQL statemen
1fb60 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6e  t.**          an
1fb70 64 20 70 7a 54 61 69 6c 20 69 73 20 6e 6f 74 20  d pzTail is not 
1fb80 4e 55 4c 4c 2c 20 74 68 65 6e 20 2a 70 7a 54 61  NULL, then *pzTa
1fb90 69 6c 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f  il is made to po
1fba0 69 6e 74 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20  int to the.**   
1fbb0 20 20 20 20 20 20 20 66 69 72 73 74 20 62 79 74         first byt
1fbc0 65 20 70 61 73 74 20 74 68 65 20 65 6e 64 20 6f  e past the end o
1fbd0 66 20 74 68 65 20 66 69 72 73 74 20 53 51 4c 20  f the first SQL 
1fbe0 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71  statement in zSq
1fbf0 6c 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 3c  l..**          <
1fc00 74 6f 64 6f 3e 57 68 61 74 20 64 6f 65 73 20 2a  todo>What does *
1fc10 70 7a 54 61 69 6c 20 70 6f 69 6e 74 20 74 6f 20  pzTail point to 
1fc20 69 66 20 74 68 65 72 65 20 69 73 20 6f 6e 65 20  if there is one 
1fc30 73 74 61 74 65 6d 65 6e 74 3f 3c 2f 74 6f 64 6f  statement?</todo
1fc40 3e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 30 31 36 7d  >.**.** {H13016}
1fc50 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 63 61   A successful ca
1fc60 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70  ll to [sqlite3_p
1fc70 72 65 70 61 72 65 5f 76 32 28 64 62 2c 7a 53 71  repare_v2(db,zSq
1fc80 6c 2c 4e 2c 70 70 53 74 6d 74 2c 2e 2e 2e 29 5d  l,N,ppStmt,...)]
1fc90 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20  .**          or 
1fca0 6f 6e 65 20 6f 66 20 69 74 73 20 76 61 72 69 61  one of its varia
1fcb0 6e 74 73 20 77 72 69 74 65 73 20 69 6e 74 6f 20  nts writes into 
1fcc0 2a 70 70 53 74 6d 74 20 61 20 70 6f 69 6e 74 65  *ppStmt a pointe
1fcd0 72 20 74 6f 20 61 20 6e 65 77 0a 2a 2a 20 20 20  r to a new.**   
1fce0 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65 64         [prepared
1fcf0 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 72 20 61   statement] or a
1fd00 20 70 6f 69 6e 74 65 72 20 74 6f 20 4e 55 4c 4c   pointer to NULL
1fd10 20 69 66 20 7a 53 71 6c 20 63 6f 6e 74 61 69 6e   if zSql contain
1fd20 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 6f  s.**          no
1fd30 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61 6e  thing other than
1fd40 20 77 68 69 74 65 73 70 61 63 65 20 6f 72 20 63   whitespace or c
1fd50 6f 6d 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 7b  omments..**.** {
1fd60 48 31 33 30 31 39 7d 20 54 68 65 20 5b 73 71 6c  H13019} The [sql
1fd70 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
1fd80 29 5d 20 69 6e 74 65 72 66 61 63 65 20 61 6e 64  )] interface and
1fd90 20 69 74 73 20 76 61 72 69 61 6e 74 73 20 72 65   its variants re
1fda0 74 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  turn.**         
1fdb0 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20   [SQLITE_OK] or 
1fdc0 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b  an appropriate [
1fdd0 65 72 72 6f 72 20 63 6f 64 65 5d 20 75 70 6f 6e  error code] upon
1fde0 20 66 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a 20   failure..**.** 
1fdf0 7b 48 31 33 30 32 31 7d 20 42 65 66 6f 72 65 20  {H13021} Before 
1fe00 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1fe10 28 64 62 2c 7a 53 71 6c 2c 6e 42 79 74 65 2c 70  (db,zSql,nByte,p
1fe20 70 53 74 6d 74 2c 70 7a 54 61 69 6c 29 5d 20 6f  pStmt,pzTail)] o
1fe30 72 20 69 74 73 0a 2a 2a 20 20 20 20 20 20 20 20  r its.**        
1fe40 20 20 76 61 72 69 61 6e 74 73 20 72 65 74 75 72    variants retur
1fe50 6e 73 20 61 6e 20 65 72 72 6f 72 20 28 61 6e 79  ns an error (any
1fe60 20 76 61 6c 75 65 20 6f 74 68 65 72 20 74 68 61   value other tha
1fe70 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 29 2c 0a  n [SQLITE_OK]),.
1fe80 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 79  **          they
1fe90 20 66 69 72 73 74 20 73 65 74 20 2a 70 70 53 74   first set *ppSt
1fea0 6d 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69  mt to NULL..*/.i
1feb0 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nt sqlite3_prepa
1fec0 72 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  re(.  sqlite3 *d
1fed0 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a  b,            /*
1fee0 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65   Database handle
1fef0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
1ff00 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a   *zSql,       /*
1ff10 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20   SQL statement, 
1ff20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f  UTF-8 encoded */
1ff30 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20  .  int nByte,   
1ff40 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61             /* Ma
1ff50 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20  ximum length of 
1ff60 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a  zSql in bytes. *
1ff70 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  /.  sqlite3_stmt
1ff80 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f   **ppStmt,  /* O
1ff90 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61  UT: Statement ha
1ffa0 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
1ffb0 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20  char **pzTail   
1ffc0 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65    /* OUT: Pointe
1ffd0 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74  r to unused port
1ffe0 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29  ion of zSql */.)
1fff0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72  ;.int sqlite3_pr
20000 65 70 61 72 65 5f 76 32 28 0a 20 20 73 71 6c 69  epare_v2(.  sqli
20010 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
20020 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20      /* Database 
20030 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
20040 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20  t char *zSql,   
20050 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65      /* SQL state
20060 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f  ment, UTF-8 enco
20070 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79  ded */.  int nBy
20080 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  te,             
20090 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67   /* Maximum leng
200a0 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79  th of zSql in by
200b0 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65  tes. */.  sqlite
200c0 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c  3_stmt **ppStmt,
200d0 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d    /* OUT: Statem
200e0 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ent handle */.  
200f0 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54  const char **pzT
20100 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20  ail     /* OUT: 
20110 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65  Pointer to unuse
20120 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71  d portion of zSq
20130 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69  l */.);.int sqli
20140 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 0a 20  te3_prepare16(. 
20150 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
20160 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61           /* Data
20170 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  base handle */. 
20180 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71   const void *zSq
20190 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20  l,       /* SQL 
201a0 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31  statement, UTF-1
201b0 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69  6 encoded */.  i
201c0 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20  nt nByte,       
201d0 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75         /* Maximu
201e0 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c  m length of zSql
201f0 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20   in bytes. */.  
20200 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70  sqlite3_stmt **p
20210 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20  pStmt,  /* OUT: 
20220 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65  Statement handle
20230 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64   */.  const void
20240 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a   **pzTail     /*
20250 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f   OUT: Pointer to
20260 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20   unused portion 
20270 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e  of zSql */.);.in
20280 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  t sqlite3_prepar
20290 65 31 36 5f 76 32 28 0a 20 20 73 71 6c 69 74 65  e16_v2(.  sqlite
202a0 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
202b0 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61    /* Database ha
202c0 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
202d0 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20  void *zSql,     
202e0 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65    /* SQL stateme
202f0 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64  nt, UTF-16 encod
20300 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74  ed */.  int nByt
20310 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  e,              
20320 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  /* Maximum lengt
20330 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74  h of zSql in byt
20340 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  es. */.  sqlite3
20350 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20  _stmt **ppStmt, 
20360 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65   /* OUT: Stateme
20370 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  nt handle */.  c
20380 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61  onst void **pzTa
20390 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50  il     /* OUT: P
203a0 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64  ointer to unused
203b0 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c   portion of zSql
203c0 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.);../*.** CA
203d0 50 49 52 45 46 3a 20 52 65 74 72 69 65 76 69 6e  PIREF: Retrievin
203e0 67 20 53 74 61 74 65 6d 65 6e 74 20 53 51 4c 20  g Statement SQL 
203f0 7b 48 31 33 31 30 30 7d 20 3c 48 31 33 30 30 30  {H13100} <H13000
20400 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74  >.**.** This int
20410 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 73  erface can be us
20420 65 64 20 74 6f 20 72 65 74 72 69 65 76 65 20 61  ed to retrieve a
20430 20 73 61 76 65 64 20 63 6f 70 79 20 6f 66 20 74   saved copy of t
20440 68 65 20 6f 72 69 67 69 6e 61 6c 0a 2a 2a 20 53  he original.** S
20450 51 4c 20 74 65 78 74 20 75 73 65 64 20 74 6f 20  QL text used to 
20460 63 72 65 61 74 65 20 61 20 5b 70 72 65 70 61 72  create a [prepar
20470 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 66  ed statement] if
20480 20 74 68 61 74 20 73 74 61 74 65 6d 65 6e 74 20   that statement 
20490 77 61 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20  was.** compiled 
204a0 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73 71  using either [sq
204b0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
204c0 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
204d0 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e  prepare16_v2()].
204e0 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
204f0 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 31 30 31  S:.**.** {H13101
20500 7d 20 49 66 20 74 68 65 20 5b 70 72 65 70 61 72  } If the [prepar
20510 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 70 61  ed statement] pa
20520 73 73 65 64 20 61 73 20 74 68 65 20 61 72 67 75  ssed as the argu
20530 6d 65 6e 74 20 74 6f 0a 2a 2a 20 20 20 20 20 20  ment to.**      
20540 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 73 71 6c      [sqlite3_sql
20550 28 29 5d 20 77 61 73 20 63 6f 6d 70 69 6c 65 64  ()] was compiled
20560 20 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73   using either [s
20570 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
20580 32 28 29 5d 20 6f 72 0a 2a 2a 20 20 20 20 20 20  2()] or.**      
20590 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 70 72 65      [sqlite3_pre
205a0 70 61 72 65 31 36 5f 76 32 28 29 5d 2c 20 74 68  pare16_v2()], th
205b0 65 6e 20 5b 73 71 6c 69 74 65 33 5f 73 71 6c 28  en [sqlite3_sql(
205c0 29 5d 20 72 65 74 75 72 6e 73 0a 2a 2a 20 20 20  )] returns.**   
205d0 20 20 20 20 20 20 20 61 20 70 6f 69 6e 74 65 72         a pointer
205e0 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69   to a zero-termi
205f0 6e 61 74 65 64 20 73 74 72 69 6e 67 20 63 6f 6e  nated string con
20600 74 61 69 6e 69 6e 67 20 61 20 55 54 46 2d 38 20  taining a UTF-8 
20610 72 65 6e 64 65 72 69 6e 67 0a 2a 2a 20 20 20 20  rendering.**    
20620 20 20 20 20 20 20 6f 66 20 74 68 65 20 6f 72 69        of the ori
20630 67 69 6e 61 6c 20 53 51 4c 20 73 74 61 74 65 6d  ginal SQL statem
20640 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 31  ent..**.** {H131
20650 30 32 7d 20 49 66 20 74 68 65 20 5b 70 72 65 70  02} If the [prep
20660 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
20670 70 61 73 73 65 64 20 61 73 20 74 68 65 20 61 72  passed as the ar
20680 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 20 20 20  gument to.**    
20690 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 73        [sqlite3_s
206a0 71 6c 28 29 5d 20 77 61 73 20 63 6f 6d 70 69 6c  ql()] was compil
206b0 65 64 20 75 73 69 6e 67 20 65 69 74 68 65 72 20  ed using either 
206c0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
206d0 28 29 5d 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20  ()] or.**       
206e0 20 20 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70     [sqlite3_prep
206f0 61 72 65 31 36 28 29 5d 2c 20 74 68 65 6e 20 5b  are16()], then [
20700 73 71 6c 69 74 65 33 5f 73 71 6c 28 29 5d 20 72  sqlite3_sql()] r
20710 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f  eturns a NULL po
20720 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  inter..**.** {H1
20730 33 31 30 33 7d 20 54 68 65 20 73 74 72 69 6e 67  3103} The string
20740 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71   returned by [sq
20750 6c 69 74 65 33 5f 73 71 6c 28 53 29 5d 20 69 73  lite3_sql(S)] is
20760 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 74 68 65   valid until the
20770 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72  .**          [pr
20780 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
20790 5d 20 53 20 69 73 20 64 65 6c 65 74 65 64 20 75  ] S is deleted u
207a0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69  sing [sqlite3_fi
207b0 6e 61 6c 69 7a 65 28 53 29 5d 2e 0a 2a 2f 0a 63  nalize(S)]..*/.c
207c0 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
207d0 65 33 5f 73 71 6c 28 73 71 6c 69 74 65 33 5f 73  e3_sql(sqlite3_s
207e0 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a  tmt *pStmt);../*
207f0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 79  .** CAPI3REF: Dy
20800 6e 61 6d 69 63 61 6c 6c 79 20 54 79 70 65 64 20  namically Typed 
20810 56 61 6c 75 65 20 4f 62 6a 65 63 74 20 7b 48 31  Value Object {H1
20820 35 30 30 30 7d 20 3c 53 32 30 32 30 30 3e 0a 2a  5000} <S20200>.*
20830 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 6f  * KEYWORDS: {pro
20840 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
20850 61 6c 75 65 7d 20 7b 75 6e 70 72 6f 74 65 63 74  alue} {unprotect
20860 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
20870 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75  }.**.** SQLite u
20880 73 65 73 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ses the sqlite3_
20890 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 74 6f 20  value object to 
208a0 72 65 70 72 65 73 65 6e 74 20 61 6c 6c 20 76 61  represent all va
208b0 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e  lues.** that can
208c0 20 62 65 20 73 74 6f 72 65 64 20 69 6e 20 61 20   be stored in a 
208d0 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 2e 20  database table. 
208e0 53 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61  SQLite uses dyna
208f0 6d 69 63 20 74 79 70 69 6e 67 0a 2a 2a 20 66 6f  mic typing.** fo
20900 72 20 74 68 65 20 76 61 6c 75 65 73 20 69 74 20  r the values it 
20910 73 74 6f 72 65 73 2e 20 56 61 6c 75 65 73 20 73  stores. Values s
20920 74 6f 72 65 64 20 69 6e 20 73 71 6c 69 74 65 33  tored in sqlite3
20930 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 0a 2a  _value objects.*
20940 2a 20 63 61 6e 20 62 65 20 69 6e 74 65 67 65 72  * can be integer
20950 73 2c 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e  s, floating poin
20960 74 20 76 61 6c 75 65 73 2c 20 73 74 72 69 6e 67  t values, string
20970 73 2c 20 42 4c 4f 42 73 2c 20 6f 72 20 4e 55 4c  s, BLOBs, or NUL
20980 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 73 71 6c 69  L..**.** An sqli
20990 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
209a0 20 6d 61 79 20 62 65 20 65 69 74 68 65 72 20 22   may be either "
209b0 70 72 6f 74 65 63 74 65 64 22 20 6f 72 20 22 75  protected" or "u
209c0 6e 70 72 6f 74 65 63 74 65 64 22 2e 0a 2a 2a 20  nprotected"..** 
209d0 53 6f 6d 65 20 69 6e 74 65 72 66 61 63 65 73 20  Some interfaces 
209e0 72 65 71 75 69 72 65 20 61 20 70 72 6f 74 65 63  require a protec
209f0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
20a00 65 2e 20 20 4f 74 68 65 72 20 69 6e 74 65 72 66  e.  Other interf
20a10 61 63 65 73 0a 2a 2a 20 77 69 6c 6c 20 61 63 63  aces.** will acc
20a20 65 70 74 20 65 69 74 68 65 72 20 61 20 70 72 6f  ept either a pro
20a30 74 65 63 74 65 64 20 6f 72 20 61 6e 20 75 6e 70  tected or an unp
20a40 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
20a50 5f 76 61 6c 75 65 2e 0a 2a 2a 20 45 76 65 72 79  _value..** Every
20a60 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20   interface that 
20a70 61 63 63 65 70 74 73 20 73 71 6c 69 74 65 33 5f  accepts sqlite3_
20a80 76 61 6c 75 65 20 61 72 67 75 6d 65 6e 74 73 20  value arguments 
20a90 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 65  specifies.** whe
20aa0 74 68 65 72 20 6f 72 20 6e 6f 74 20 69 74 20 72  ther or not it r
20ab0 65 71 75 69 72 65 73 20 61 20 70 72 6f 74 65 63  equires a protec
20ac0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
20ad0 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 65 72  e..**.** The ter
20ae0 6d 73 20 22 70 72 6f 74 65 63 74 65 64 22 20 61  ms "protected" a
20af0 6e 64 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22  nd "unprotected"
20b00 20 72 65 66 65 72 20 74 6f 20 77 68 65 74 68 65   refer to whethe
20b10 72 20 6f 72 20 6e 6f 74 0a 2a 2a 20 61 20 6d 75  r or not.** a mu
20b20 74 65 78 20 69 73 20 68 65 6c 64 2e 20 20 41 20  tex is held.  A 
20b30 69 6e 74 65 72 6e 61 6c 20 6d 75 74 65 78 20 69  internal mutex i
20b40 73 20 68 65 6c 64 20 66 6f 72 20 61 20 70 72 6f  s held for a pro
20b50 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65  tected.** sqlite
20b60 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 62  3_value object b
20b70 75 74 20 6e 6f 20 6d 75 74 65 78 20 69 73 20 68  ut no mutex is h
20b80 65 6c 64 20 66 6f 72 20 61 6e 20 75 6e 70 72 6f  eld for an unpro
20b90 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65  tected.** sqlite
20ba0 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 2e 20  3_value object. 
20bb0 20 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f   If SQLite is co
20bc0 6d 70 69 6c 65 64 20 74 6f 20 62 65 20 73 69 6e  mpiled to be sin
20bd0 67 6c 65 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20  gle-threaded.** 
20be0 28 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 54 48  (with [SQLITE_TH
20bf0 52 45 41 44 53 41 46 45 3d 30 5d 20 61 6e 64 20  READSAFE=0] and 
20c00 77 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 74 68  with [sqlite3_th
20c10 72 65 61 64 73 61 66 65 28 29 5d 20 72 65 74 75  readsafe()] retu
20c20 72 6e 69 6e 67 20 30 29 0a 2a 2a 20 6f 72 20 69  rning 0).** or i
20c30 66 20 53 51 4c 69 74 65 20 69 73 20 72 75 6e 20  f SQLite is run 
20c40 69 6e 20 6f 6e 65 20 6f 66 20 72 65 64 75 63 65  in one of reduce
20c50 64 20 6d 75 74 65 78 20 6d 6f 64 65 73 20 0a 2a  d mutex modes .*
20c60 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  * [SQLITE_CONFIG
20c70 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 20 6f  _SINGLETHREAD] o
20c80 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  r [SQLITE_CONFIG
20c90 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 0a 2a 2a  _MULTITHREAD].**
20ca0 20 74 68 65 6e 20 74 68 65 72 65 20 69 73 20 6e   then there is n
20cb0 6f 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65  o distinction be
20cc0 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64 20  tween protected 
20cd0 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64 0a  and unprotected.
20ce0 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ** sqlite3_value
20cf0 20 6f 62 6a 65 63 74 73 20 61 6e 64 20 74 68 65   objects and the
20d00 79 20 63 61 6e 20 62 65 20 75 73 65 64 20 69 6e  y can be used in
20d10 74 65 72 63 68 61 6e 67 65 61 62 6c 79 2e 20 20  terchangeably.  
20d20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 6f 72 20  However,.** for 
20d30 6d 61 78 69 6d 75 6d 20 63 6f 64 65 20 70 6f 72  maximum code por
20d40 74 61 62 69 6c 69 74 79 20 69 74 20 69 73 20 72  tability it is r
20d50 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20  ecommended that 
20d60 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20  applications.** 
20d70 73 74 69 6c 6c 20 6d 61 6b 65 20 74 68 65 20 64  still make the d
20d80 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65  istinction betwe
20d90 65 6e 20 62 65 74 77 65 65 6e 20 70 72 6f 74 65  en between prote
20da0 63 74 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 65  cted and unprote
20db0 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  cted.** sqlite3_
20dc0 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 65 76  value objects ev
20dd0 65 6e 20 77 68 65 6e 20 6e 6f 74 20 73 74 72 69  en when not stri
20de0 63 74 6c 79 20 72 65 71 75 69 72 65 64 2e 0a 2a  ctly required..*
20df0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
20e00 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 74  _value objects t
20e10 68 61 74 20 61 72 65 20 70 61 73 73 65 64 20 61  hat are passed a
20e20 73 20 70 61 72 61 6d 65 74 65 72 73 20 69 6e 74  s parameters int
20e30 6f 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65  o the.** impleme
20e40 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 61 70 70 6c  ntation of [appl
20e50 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
20e60 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20 61  SQL functions] a
20e70 72 65 20 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a  re protected..**
20e80 20 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c   The sqlite3_val
20e90 75 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e  ue object return
20ea0 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65  ed by.** [sqlite
20eb0 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29  3_column_value()
20ec0 5d 20 69 73 20 75 6e 70 72 6f 74 65 63 74 65 64  ] is unprotected
20ed0 2e 0a 2a 2a 20 55 6e 70 72 6f 74 65 63 74 65 64  ..** Unprotected
20ee0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
20ef0 62 6a 65 63 74 73 20 6d 61 79 20 6f 6e 6c 79 20  bjects may only 
20f00 62 65 20 75 73 65 64 20 77 69 74 68 0a 2a 2a 20  be used with.** 
20f10 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
20f20 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71  value()] and [sq
20f30 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65  lite3_bind_value
20f40 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c  ()]..** The [sql
20f50 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 20  ite3_value_blob 
20f60 7c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  | sqlite3_value_
20f70 74 79 70 65 28 29 5d 20 66 61 6d 69 6c 79 20 6f  type()] family o
20f80 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  f.** interfaces 
20f90 72 65 71 75 69 72 65 20 70 72 6f 74 65 63 74 65  require protecte
20fa0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  d sqlite3_value 
20fb0 6f 62 6a 65 63 74 73 2e 0a 2a 2f 0a 74 79 70 65  objects..*/.type
20fc0 64 65 66 20 73 74 72 75 63 74 20 4d 65 6d 20 73  def struct Mem s
20fd0 71 6c 69 74 65 33 5f 76 61 6c 75 65 3b 0a 0a 2f  qlite3_value;../
20fe0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
20ff0 51 4c 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74  QL Function Cont
21000 65 78 74 20 4f 62 6a 65 63 74 20 7b 48 31 36 30  ext Object {H160
21010 30 31 7d 20 3c 53 32 30 32 30 30 3e 0a 2a 2a 0a  01} <S20200>.**.
21020 2a 2a 20 54 68 65 20 63 6f 6e 74 65 78 74 20 69  ** The context i
21030 6e 20 77 68 69 63 68 20 61 6e 20 53 51 4c 20 66  n which an SQL f
21040 75 6e 63 74 69 6f 6e 20 65 78 65 63 75 74 65 73  unction executes
21050 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20 61 6e   is stored in an
21060 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74  .** sqlite3_cont
21070 65 78 74 20 6f 62 6a 65 63 74 2e 20 20 41 20 70  ext object.  A p
21080 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 73 71 6c  ointer to an sql
21090 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a  ite3_context obj
210a0 65 63 74 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73  ect.** is always
210b0 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
210c0 20 74 6f 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e   to [application
210d0 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
210e0 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 65 20  ctions]..** The 
210f0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
21100 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ned SQL function
21110 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
21120 77 69 6c 6c 20 70 61 73 73 20 74 68 69 73 0a 2a  will pass this.*
21130 2a 20 70 6f 69 6e 74 65 72 20 74 68 72 6f 75 67  * pointer throug
21140 68 20 69 6e 74 6f 20 63 61 6c 6c 73 20 74 6f 20  h into calls to 
21150 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
21160 69 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f 72 65  int | sqlite3_re
21170 73 75 6c 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  sult()],.** [sql
21180 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
21190 6f 6e 74 65 78 74 28 29 5d 2c 20 5b 73 71 6c 69  ontext()], [sqli
211a0 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d  te3_user_data()]
211b0 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  ,.** [sqlite3_co
211c0 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28  ntext_db_handle(
211d0 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 67 65 74  )], [sqlite3_get
211e0 5f 61 75 78 64 61 74 61 28 29 5d 2c 0a 2a 2a 20  _auxdata()],.** 
211f0 61 6e 64 2f 6f 72 20 5b 73 71 6c 69 74 65 33 5f  and/or [sqlite3_
21200 73 65 74 5f 61 75 78 64 61 74 61 28 29 5d 2e 0a  set_auxdata()]..
21210 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
21220 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  t sqlite3_contex
21230 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  t sqlite3_contex
21240 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  t;../*.** CAPI3R
21250 45 46 3a 20 42 69 6e 64 69 6e 67 20 56 61 6c 75  EF: Binding Valu
21260 65 73 20 54 6f 20 50 72 65 70 61 72 65 64 20 53  es To Prepared S
21270 74 61 74 65 6d 65 6e 74 73 20 7b 48 31 33 35 30  tatements {H1350
21280 30 7d 20 3c 53 37 30 33 30 30 3e 0a 2a 2a 20 4b  0} <S70300>.** K
21290 45 59 57 4f 52 44 53 3a 20 7b 68 6f 73 74 20 70  EYWORDS: {host p
212a0 61 72 61 6d 65 74 65 72 7d 20 7b 68 6f 73 74 20  arameter} {host 
212b0 70 61 72 61 6d 65 74 65 72 73 7d 20 7b 68 6f 73  parameters} {hos
212c0 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65  t parameter name
212d0 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  }.** KEYWORDS: {
212e0 53 51 4c 20 70 61 72 61 6d 65 74 65 72 7d 20 7b  SQL parameter} {
212f0 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 7d 20  SQL parameters} 
21300 7b 70 61 72 61 6d 65 74 65 72 20 62 69 6e 64 69  {parameter bindi
21310 6e 67 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65  ng}.**.** In the
21320 20 53 51 4c 20 73 74 72 69 6e 67 73 20 69 6e 70   SQL strings inp
21330 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70  ut to [sqlite3_p
21340 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64  repare_v2()] and
21350 20 69 74 73 20 76 61 72 69 61 6e 74 73 2c 0a 2a   its variants,.*
21360 2a 20 6c 69 74 65 72 61 6c 73 20 6d 61 79 20 62  * literals may b
21370 65 20 72 65 70 6c 61 63 65 64 20 62 79 20 61 20  e replaced by a 
21380 70 61 72 61 6d 65 74 65 72 20 69 6e 20 6f 6e 65  parameter in one
21390 20 6f 66 20 74 68 65 73 65 20 66 6f 72 6d 73 3a   of these forms:
213a0 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
213b0 6c 69 3e 20 20 3f 0a 2a 2a 20 3c 6c 69 3e 20 20  li>  ?.** <li>  
213c0 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20 20 3a 56  ?NNN.** <li>  :V
213d0 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 40 56 56 56  VV.** <li>  @VVV
213e0 0a 2a 2a 20 3c 6c 69 3e 20 20 24 56 56 56 0a 2a  .** <li>  $VVV.*
213f0 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e  * </ul>.**.** In
21400 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 66   the parameter f
21410 6f 72 6d 73 20 73 68 6f 77 6e 20 61 62 6f 76 65  orms shown above
21420 20 4e 4e 4e 20 69 73 20 61 6e 20 69 6e 74 65 67   NNN is an integ
21430 65 72 20 6c 69 74 65 72 61 6c 2c 0a 2a 2a 20 61  er literal,.** a
21440 6e 64 20 56 56 56 20 69 73 20 61 6e 20 61 6c 70  nd VVV is an alp
21450 68 61 2d 6e 75 6d 65 72 69 63 20 70 61 72 61 6d  ha-numeric param
21460 65 74 65 72 20 6e 61 6d 65 2e 20 54 68 65 20 76  eter name. The v
21470 61 6c 75 65 73 20 6f 66 20 74 68 65 73 65 0a 2a  alues of these.*
21480 2a 20 70 61 72 61 6d 65 74 65 72 73 20 28 61 6c  * parameters (al
21490 73 6f 20 63 61 6c 6c 65 64 20 22 68 6f 73 74 20  so called "host 
214a0 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 73 22  parameter names"
214b0 20 6f 72 20 22 53 51 4c 20 70 61 72 61 6d 65 74   or "SQL paramet
214c0 65 72 73 22 29 0a 2a 2a 20 63 61 6e 20 62 65 20  ers").** can be 
214d0 73 65 74 20 75 73 69 6e 67 20 74 68 65 20 73 71  set using the sq
214e0 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72  lite3_bind_*() r
214f0 6f 75 74 69 6e 65 73 20 64 65 66 69 6e 65 64 20  outines defined 
21500 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  here..**.** The 
21510 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
21520 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69  o the sqlite3_bi
21530 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20  nd_*() routines 
21540 69 73 20 61 6c 77 61 79 73 0a 2a 2a 20 61 20 70  is always.** a p
21550 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73  ointer to the [s
21560 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a  qlite3_stmt] obj
21570 65 63 74 20 72 65 74 75 72 6e 65 64 20 66 72 6f  ect returned fro
21580 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  m.** [sqlite3_pr
21590 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 69  epare_v2()] or i
215a0 74 73 20 76 61 72 69 61 6e 74 73 2e 0a 2a 2a 0a  ts variants..**.
215b0 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72  ** The second ar
215c0 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e  gument is the in
215d0 64 65 78 20 6f 66 20 74 68 65 20 53 51 4c 20 70  dex of the SQL p
215e0 61 72 61 6d 65 74 65 72 20 74 6f 20 62 65 20 73  arameter to be s
215f0 65 74 2e 0a 2a 2a 20 54 68 65 20 6c 65 66 74 6d  et..** The leftm
21600 6f 73 74 20 53 51 4c 20 70 61 72 61 6d 65 74 65  ost SQL paramete
21610 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f  r has an index o
21620 66 20 31 2e 20 20 57 68 65 6e 20 74 68 65 20 73  f 1.  When the s
21630 61 6d 65 20 6e 61 6d 65 64 0a 2a 2a 20 53 51 4c  ame named.** SQL
21640 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 75 73   parameter is us
21650 65 64 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63  ed more than onc
21660 65 2c 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75  e, second and su
21670 62 73 65 71 75 65 6e 74 0a 2a 2a 20 6f 63 63 75  bsequent.** occu
21680 72 72 65 6e 63 65 73 20 68 61 76 65 20 74 68 65  rrences have the
21690 20 73 61 6d 65 20 69 6e 64 65 78 20 61 73 20 74   same index as t
216a0 68 65 20 66 69 72 73 74 20 6f 63 63 75 72 72 65  he first occurre
216b0 6e 63 65 2e 0a 2a 2a 20 54 68 65 20 69 6e 64 65  nce..** The inde
216c0 78 20 66 6f 72 20 6e 61 6d 65 64 20 70 61 72 61  x for named para
216d0 6d 65 74 65 72 73 20 63 61 6e 20 62 65 20 6c 6f  meters can be lo
216e0 6f 6b 65 64 20 75 70 20 75 73 69 6e 67 20 74 68  oked up using th
216f0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  e.** [sqlite3_bi
21700 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64  nd_parameter_ind
21710 65 78 28 29 5d 20 41 50 49 20 69 66 20 64 65 73  ex()] API if des
21720 69 72 65 64 2e 20 20 54 68 65 20 69 6e 64 65 78  ired.  The index
21730 0a 2a 2a 20 66 6f 72 20 22 3f 4e 4e 4e 22 20 70  .** for "?NNN" p
21740 61 72 61 6d 65 74 65 72 73 20 69 73 20 74 68 65  arameters is the
21750 20 76 61 6c 75 65 20 6f 66 20 4e 4e 4e 2e 0a 2a   value of NNN..*
21760 2a 20 54 68 65 20 4e 4e 4e 20 76 61 6c 75 65 20  * The NNN value 
21770 6d 75 73 74 20 62 65 20 62 65 74 77 65 65 6e 20  must be between 
21780 31 20 61 6e 64 20 74 68 65 20 5b 73 71 6c 69 74  1 and the [sqlit
21790 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 70  e3_limit()].** p
217a0 61 72 61 6d 65 74 65 72 20 5b 53 51 4c 49 54 45  arameter [SQLITE
217b0 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f  _LIMIT_VARIABLE_
217c0 4e 55 4d 42 45 52 5d 20 28 64 65 66 61 75 6c 74  NUMBER] (default
217d0 20 76 61 6c 75 65 3a 20 39 39 39 29 2e 0a 2a 2a   value: 999)..**
217e0 0a 2a 2a 20 54 68 65 20 74 68 69 72 64 20 61 72  .** The third ar
217f0 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 76 61  gument is the va
21800 6c 75 65 20 74 6f 20 62 69 6e 64 20 74 6f 20 74  lue to bind to t
21810 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  he parameter..**
21820 0a 2a 2a 20 49 6e 20 74 68 6f 73 65 20 72 6f 75  .** In those rou
21830 74 69 6e 65 73 20 74 68 61 74 20 68 61 76 65 20  tines that have 
21840 61 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e  a fourth argumen
21850 74 2c 20 69 74 73 20 76 61 6c 75 65 20 69 73 20  t, its value is 
21860 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66  the.** number of
21870 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 70 61   bytes in the pa
21880 72 61 6d 65 74 65 72 2e 20 20 54 6f 20 62 65 20  rameter.  To be 
21890 63 6c 65 61 72 3a 20 74 68 65 20 76 61 6c 75 65  clear: the value
218a0 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65   is the.** numbe
218b0 72 20 6f 66 20 3c 75 3e 62 79 74 65 73 3c 2f 75  r of <u>bytes</u
218c0 3e 20 69 6e 20 74 68 65 20 76 61 6c 75 65 2c 20  > in the value, 
218d0 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  not the number o
218e0 66 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a  f characters..**
218f0 20 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 70   If the fourth p
21900 61 72 61 6d 65 74 65 72 20 69 73 20 6e 65 67 61  arameter is nega
21910 74 69 76 65 2c 20 74 68 65 20 6c 65 6e 67 74 68  tive, the length
21920 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67 20 69   of the string i
21930 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20  s.** the number 
21940 6f 66 20 62 79 74 65 73 20 75 70 20 74 6f 20 74  of bytes up to t
21950 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65  he first zero te
21960 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20  rminator..**.** 
21970 54 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65  The fifth argume
21980 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69  nt to sqlite3_bi
21990 6e 64 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74  nd_blob(), sqlit
219a0 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 2c 20  e3_bind_text(), 
219b0 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 62  and.** sqlite3_b
219c0 69 6e 64 5f 74 65 78 74 31 36 28 29 20 69 73 20  ind_text16() is 
219d0 61 20 64 65 73 74 72 75 63 74 6f 72 20 75 73 65  a destructor use
219e0 64 20 74 6f 20 64 69 73 70 6f 73 65 20 6f 66 20  d to dispose of 
219f0 74 68 65 20 42 4c 4f 42 20 6f 72 0a 2a 2a 20 73  the BLOB or.** s
21a00 74 72 69 6e 67 20 61 66 74 65 72 20 53 51 4c 69  tring after SQLi
21a10 74 65 20 68 61 73 20 66 69 6e 69 73 68 65 64 20  te has finished 
21a20 77 69 74 68 20 69 74 2e 20 49 66 20 74 68 65 20  with it. If the 
21a30 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 69  fifth argument i
21a40 73 0a 2a 2a 20 74 68 65 20 73 70 65 63 69 61 6c  s.** the special
21a50 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 53   value [SQLITE_S
21a60 54 41 54 49 43 5d 2c 20 74 68 65 6e 20 53 51 4c  TATIC], then SQL
21a70 69 74 65 20 61 73 73 75 6d 65 73 20 74 68 61 74  ite assumes that
21a80 20 74 68 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74   the.** informat
21a90 69 6f 6e 20 69 73 20 69 6e 20 73 74 61 74 69 63  ion is in static
21aa0 2c 20 75 6e 6d 61 6e 61 67 65 64 20 73 70 61 63  , unmanaged spac
21ab0 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 6e  e and does not n
21ac0 65 65 64 20 74 6f 20 62 65 20 66 72 65 65 64 2e  eed to be freed.
21ad0 0a 2a 2a 20 49 66 20 74 68 65 20 66 69 66 74 68  .** If the fifth
21ae0 20 61 72 67 75 6d 65 6e 74 20 68 61 73 20 74 68   argument has th
21af0 65 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f  e value [SQLITE_
21b00 54 52 41 4e 53 49 45 4e 54 5d 2c 20 74 68 65 6e  TRANSIENT], then
21b10 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 61 6b 65 73  .** SQLite makes
21b20 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65   its own private
21b30 20 63 6f 70 79 20 6f 66 20 74 68 65 20 64 61 74   copy of the dat
21b40 61 20 69 6d 6d 65 64 69 61 74 65 6c 79 2c 20 62  a immediately, b
21b50 65 66 6f 72 65 0a 2a 2a 20 74 68 65 20 73 71 6c  efore.** the sql
21b60 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f  ite3_bind_*() ro
21b70 75 74 69 6e 65 20 72 65 74 75 72 6e 73 2e 0a 2a  utine returns..*
21b80 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
21b90 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 29  _bind_zeroblob()
21ba0 20 72 6f 75 74 69 6e 65 20 62 69 6e 64 73 20 61   routine binds a
21bb0 20 42 4c 4f 42 20 6f 66 20 6c 65 6e 67 74 68 20   BLOB of length 
21bc0 4e 20 74 68 61 74 0a 2a 2a 20 69 73 20 66 69 6c  N that.** is fil
21bd0 6c 65 64 20 77 69 74 68 20 7a 65 72 6f 65 73 2e  led with zeroes.
21be0 20 20 41 20 7a 65 72 6f 62 6c 6f 62 20 75 73 65    A zeroblob use
21bf0 73 20 61 20 66 69 78 65 64 20 61 6d 6f 75 6e 74  s a fixed amount
21c00 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a 20 28 6a   of memory.** (j
21c10 75 73 74 20 61 6e 20 69 6e 74 65 67 65 72 20 74  ust an integer t
21c20 6f 20 68 6f 6c 64 20 69 74 73 20 73 69 7a 65 29  o hold its size)
21c30 20 77 68 69 6c 65 20 69 74 20 69 73 20 62 65 69   while it is bei
21c40 6e 67 20 70 72 6f 63 65 73 73 65 64 2e 0a 2a 2a  ng processed..**
21c50 20 5a 65 72 6f 62 6c 6f 62 73 20 61 72 65 20 69   Zeroblobs are i
21c60 6e 74 65 6e 64 65 64 20 74 6f 20 73 65 72 76 65  ntended to serve
21c70 20 61 73 20 70 6c 61 63 65 68 6f 6c 64 65 72 73   as placeholders
21c80 20 66 6f 72 20 42 4c 4f 42 73 20 77 68 6f 73 65   for BLOBs whose
21c90 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 69 73 20 6c  .** content is l
21ca0 61 74 65 72 20 77 72 69 74 74 65 6e 20 75 73 69  ater written usi
21cb0 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  ng.** [sqlite3_b
21cc0 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69 6e 63 72 65  lob_open | incre
21cd0 6d 65 6e 74 61 6c 20 42 4c 4f 42 20 49 2f 4f 5d  mental BLOB I/O]
21ce0 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20 41 20   routines..** A 
21cf0 6e 65 67 61 74 69 76 65 20 76 61 6c 75 65 20 66  negative value f
21d00 6f 72 20 74 68 65 20 7a 65 72 6f 62 6c 6f 62 20  or the zeroblob 
21d10 72 65 73 75 6c 74 73 20 69 6e 20 61 20 7a 65 72  results in a zer
21d20 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 2e 0a 2a  o-length BLOB..*
21d30 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
21d40 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e  _bind_*() routin
21d50 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65  es must be calle
21d60 64 20 61 66 74 65 72 0a 2a 2a 20 5b 73 71 6c 69  d after.** [sqli
21d70 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
21d80 5d 20 28 61 6e 64 20 69 74 73 20 76 61 72 69 61  ] (and its varia
21d90 6e 74 73 29 20 6f 72 20 5b 73 71 6c 69 74 65 33  nts) or [sqlite3
21da0 5f 72 65 73 65 74 28 29 5d 20 61 6e 64 0a 2a 2a  _reset()] and.**
21db0 20 62 65 66 6f 72 65 20 5b 73 71 6c 69 74 65 33   before [sqlite3
21dc0 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 20 42 69 6e  _step()]..** Bin
21dd0 64 69 6e 67 73 20 61 72 65 20 6e 6f 74 20 63 6c  dings are not cl
21de0 65 61 72 65 64 20 62 79 20 74 68 65 20 5b 73 71  eared by the [sq
21df0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 72  lite3_reset()] r
21e00 6f 75 74 69 6e 65 2e 0a 2a 2a 20 55 6e 62 6f 75  outine..** Unbou
21e10 6e 64 20 70 61 72 61 6d 65 74 65 72 73 20 61 72  nd parameters ar
21e20 65 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  e interpreted as
21e30 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65   NULL..**.** The
21e40 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  se routines retu
21e50 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f  rn [SQLITE_OK] o
21e60 6e 20 73 75 63 63 65 73 73 20 6f 72 20 61 6e 20  n success or an 
21e70 65 72 72 6f 72 20 63 6f 64 65 20 69 66 0a 2a 2a  error code if.**
21e80 20 61 6e 79 74 68 69 6e 67 20 67 6f 65 73 20 77   anything goes w
21e90 72 6f 6e 67 2e 20 20 5b 53 51 4c 49 54 45 5f 52  rong.  [SQLITE_R
21ea0 41 4e 47 45 5d 20 69 73 20 72 65 74 75 72 6e 65  ANGE] is returne
21eb0 64 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74  d if the paramet
21ec0 65 72 0a 2a 2a 20 69 6e 64 65 78 20 69 73 20 6f  er.** index is o
21ed0 75 74 20 6f 66 20 72 61 6e 67 65 2e 20 20 5b 53  ut of range.  [S
21ee0 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20 69 73 20  QLITE_NOMEM] is 
21ef0 72 65 74 75 72 6e 65 64 20 69 66 20 6d 61 6c 6c  returned if mall
21f00 6f 63 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 20 5b  oc() fails..** [
21f10 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 6d  SQLITE_MISUSE] m
21f20 69 67 68 74 20 62 65 20 72 65 74 75 72 6e 65 64  ight be returned
21f30 20 69 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   if these routin
21f40 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 6f 6e  es are called on
21f50 20 61 0a 2a 2a 20 76 69 72 74 75 61 6c 20 6d 61   a.** virtual ma
21f60 63 68 69 6e 65 20 74 68 61 74 20 69 73 20 74 68  chine that is th
21f70 65 20 77 72 6f 6e 67 20 73 74 61 74 65 20 6f 72  e wrong state or
21f80 20 77 68 69 63 68 20 68 61 73 20 61 6c 72 65 61   which has alrea
21f90 64 79 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65  dy been finalize
21fa0 64 2e 0a 2a 2a 20 44 65 74 65 63 74 69 6f 6e 20  d..** Detection 
21fb0 6f 66 20 6d 69 73 75 73 65 20 69 73 20 75 6e 72  of misuse is unr
21fc0 65 6c 69 61 62 6c 65 2e 20 20 41 70 70 6c 69 63  eliable.  Applic
21fd0 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 6e 6f  ations should no
21fe0 74 20 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20 53  t depend.** on S
21ff0 51 4c 49 54 45 5f 4d 49 53 55 53 45 20 72 65 74  QLITE_MISUSE ret
22000 75 72 6e 73 2e 20 20 53 51 4c 49 54 45 5f 4d 49  urns.  SQLITE_MI
22010 53 55 53 45 20 69 73 20 69 6e 74 65 6e 64 65 64  SUSE is intended
22020 20 74 6f 20 69 6e 64 69 63 61 74 65 20 61 0a 2a   to indicate a.*
22030 2a 20 61 20 6c 6f 67 69 63 20 65 72 72 6f 72 20  * a logic error 
22040 69 6e 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  in the applicati
22050 6f 6e 2e 20 20 46 75 74 75 72 65 20 76 65 72 73  on.  Future vers
22060 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d  ions of SQLite m
22070 69 67 68 74 0a 2a 2a 20 70 61 6e 69 63 20 72 61  ight.** panic ra
22080 74 68 65 72 20 74 68 61 6e 20 72 65 74 75 72 6e  ther than return
22090 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 2e 0a   SQLITE_MISUSE..
220a0 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
220b0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
220c0 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d  rameter_count()]
220d0 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  ,.** [sqlite3_bi
220e0 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d  nd_parameter_nam
220f0 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74  e()], and [sqlit
22100 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
22110 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2a 0a 2a  r_index()]..**.*
22120 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
22130 0a 2a 2a 20 7b 48 31 33 35 30 36 7d 20 54 68 65  .** {H13506} The
22140 20 5b 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20   [SQL statement 
22150 63 6f 6d 70 69 6c 65 72 5d 20 72 65 63 6f 67 6e  compiler] recogn
22160 69 7a 65 73 20 74 6f 6b 65 6e 73 20 6f 66 20 74  izes tokens of t
22170 68 65 20 66 6f 72 6d 73 0a 2a 2a 20 20 20 20 20  he forms.**     
22180 20 20 20 20 20 22 3f 22 2c 20 22 3f 4e 4e 4e 22       "?", "?NNN"
22190 2c 20 22 24 56 56 56 22 2c 20 22 3a 56 56 56 22  , "$VVV", ":VVV"
221a0 2c 20 61 6e 64 20 22 40 56 56 56 22 20 61 73 20  , and "@VVV" as 
221b0 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 2c 0a  SQL parameters,.
221c0 2a 2a 20 20 20 20 20 20 20 20 20 20 77 68 65 72  **          wher
221d0 65 20 4e 4e 4e 20 69 73 20 61 6e 79 20 73 65 71  e NNN is any seq
221e0 75 65 6e 63 65 20 6f 66 20 6f 6e 65 20 6f 72 20  uence of one or 
221f0 6d 6f 72 65 20 64 69 67 69 74 73 0a 2a 2a 20 20  more digits.**  
22200 20 20 20 20 20 20 20 20 61 6e 64 20 77 68 65 72          and wher
22210 65 20 56 56 56 20 69 73 20 61 6e 79 20 73 65 71  e VVV is any seq
22220 75 65 6e 63 65 20 6f 66 20 6f 6e 65 20 6f 72 20  uence of one or 
22230 6d 6f 72 65 20 61 6c 70 68 61 6e 75 6d 65 72 69  more alphanumeri
22240 63 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 68  c.**          ch
22250 61 72 61 63 74 65 72 73 20 6f 72 20 22 3a 3a 22  aracters or "::"
22260 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 66 6f 6c 6c   optionally foll
22270 6f 77 65 64 20 62 79 20 61 20 73 74 72 69 6e 67  owed by a string
22280 20 63 6f 6e 74 61 69 6e 69 6e 67 0a 2a 2a 20 20   containing.**  
22290 20 20 20 20 20 20 20 20 6e 6f 20 73 70 61 63 65          no space
222a0 73 20 61 6e 64 20 63 6f 6e 74 61 69 6e 65 64 20  s and contained 
222b0 77 69 74 68 69 6e 20 70 61 72 65 6e 74 68 65 73  within parenthes
222c0 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 30  es..**.** {H1350
222d0 39 7d 20 54 68 65 20 69 6e 69 74 69 61 6c 20 76  9} The initial v
222e0 61 6c 75 65 20 6f 66 20 61 6e 20 53 51 4c 20 70  alue of an SQL p
222f0 61 72 61 6d 65 74 65 72 20 69 73 20 4e 55 4c 4c  arameter is NULL
22300 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 31 32 7d  ..**.** {H13512}
22310 20 54 68 65 20 69 6e 64 65 78 20 6f 66 20 61 6e   The index of an
22320 20 22 3f 22 20 53 51 4c 20 70 61 72 61 6d 65 74   "?" SQL paramet
22330 65 72 20 69 73 20 6f 6e 65 20 6c 61 72 67 65 72  er is one larger
22340 20 74 68 61 6e 20 74 68 65 0a 2a 2a 20 20 20 20   than the.**    
22350 20 20 20 20 20 20 6c 61 72 67 65 73 74 20 69 6e        largest in
22360 64 65 78 20 6f 66 20 53 51 4c 20 70 61 72 61 6d  dex of SQL param
22370 65 74 65 72 20 74 6f 20 74 68 65 20 6c 65 66 74  eter to the left
22380 2c 20 6f 72 20 31 20 69 66 0a 2a 2a 20 20 20 20  , or 1 if.**    
22390 20 20 20 20 20 20 74 68 65 20 22 3f 22 20 69 73        the "?" is
223a0 20 74 68 65 20 6c 65 66 74 6d 6f 73 74 20 53 51   the leftmost SQ
223b0 4c 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a  L parameter..**.
223c0 2a 2a 20 7b 48 31 33 35 31 35 7d 20 54 68 65 20  ** {H13515} The 
223d0 69 6e 64 65 78 20 6f 66 20 61 6e 20 22 3f 4e 4e  index of an "?NN
223e0 4e 22 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  N" SQL parameter
223f0 20 69 73 20 74 68 65 20 69 6e 74 65 67 65 72 20   is the integer 
22400 4e 4e 4e 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35  NNN..**.** {H135
22410 31 38 7d 20 54 68 65 20 69 6e 64 65 78 20 6f 66  18} The index of
22420 20 61 6e 20 22 3a 56 56 56 22 2c 20 22 24 56 56   an ":VVV", "$VV
22430 56 22 2c 20 6f 72 20 22 40 56 56 56 22 20 53 51  V", or "@VVV" SQ
22440 4c 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a  L parameter is.*
22450 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 73  *          the s
22460 61 6d 65 20 61 73 20 74 68 65 20 69 6e 64 65 78  ame as the index
22470 20 6f 66 20 6c 65 66 74 6d 6f 73 74 20 6f 63 63   of leftmost occ
22480 75 72 72 65 6e 63 65 73 20 6f 66 20 74 68 65 20  urrences of the 
22490 73 61 6d 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  same.**         
224a0 20 70 61 72 61 6d 65 74 65 72 2c 20 6f 72 20 6f   parameter, or o
224b0 6e 65 20 6d 6f 72 65 20 74 68 61 6e 20 74 68 65  ne more than the
224c0 20 6c 61 72 67 65 73 74 20 69 6e 64 65 78 20 6f   largest index o
224d0 76 65 72 20 61 6c 6c 0a 2a 2a 20 20 20 20 20 20  ver all.**      
224e0 20 20 20 20 70 61 72 61 6d 65 74 65 72 73 20 74      parameters t
224f0 6f 20 74 68 65 20 6c 65 66 74 20 69 66 20 74 68  o the left if th
22500 69 73 20 69 73 20 74 68 65 20 66 69 72 73 74 20  is is the first 
22510 6f 63 63 75 72 72 65 6e 63 65 0a 2a 2a 20 20 20  occurrence.**   
22520 20 20 20 20 20 20 20 6f 66 20 74 68 69 73 20 70         of this p
22530 61 72 61 6d 65 74 65 72 2c 20 6f 72 20 31 20 69  arameter, or 1 i
22540 66 20 74 68 69 73 20 69 73 20 74 68 65 20 6c 65  f this is the le
22550 66 74 6d 6f 73 74 20 70 61 72 61 6d 65 74 65 72  ftmost parameter
22560 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 32 31 7d  ..**.** {H13521}
22570 20 54 68 65 20 5b 53 51 4c 20 73 74 61 74 65 6d   The [SQL statem
22580 65 6e 74 20 63 6f 6d 70 69 6c 65 72 5d 20 66 61  ent compiler] fa
22590 69 6c 73 20 77 69 74 68 20 61 6e 20 5b 53 51 4c  ils with an [SQL
225a0 49 54 45 5f 52 41 4e 47 45 5d 0a 2a 2a 20 20 20  ITE_RANGE].**   
225b0 20 20 20 20 20 20 20 65 72 72 6f 72 20 69 66 20         error if 
225c0 74 68 65 20 69 6e 64 65 78 20 6f 66 20 61 6e 20  the index of an 
225d0 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69 73  SQL parameter is
225e0 20 6c 65 73 73 20 74 68 61 6e 20 31 0a 2a 2a 20   less than 1.** 
225f0 20 20 20 20 20 20 20 20 20 6f 72 20 67 72 65 61           or grea
22600 74 65 72 20 74 68 61 6e 20 74 68 65 20 63 6f 6d  ter than the com
22610 70 69 6c 65 2d 74 69 6d 65 20 53 51 4c 49 54 45  pile-time SQLITE
22620 5f 4d 41 58 5f 56 41 52 49 41 42 4c 45 5f 4e 55  _MAX_VARIABLE_NU
22630 4d 42 45 52 0a 2a 2a 20 20 20 20 20 20 20 20 20  MBER.**         
22640 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a   parameter..**.*
22650 2a 20 7b 48 31 33 35 32 34 7d 20 43 61 6c 6c 73  * {H13524} Calls
22660 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e   to [sqlite3_bin
22670 64 5f 74 65 78 74 20 7c 20 73 71 6c 69 74 65 33  d_text | sqlite3
22680 5f 62 69 6e 64 28 53 2c 4e 2c 56 2c 2e 2e 2e 29  _bind(S,N,V,...)
22690 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 73  ].**          as
226a0 73 6f 63 69 61 74 65 20 74 68 65 20 76 61 6c 75  sociate the valu
226b0 65 20 56 20 77 69 74 68 20 61 6c 6c 20 53 51 4c  e V with all SQL
226c0 20 70 61 72 61 6d 65 74 65 72 73 20 68 61 76 69   parameters havi
226d0 6e 67 20 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20  ng an.**        
226e0 20 20 69 6e 64 65 78 20 6f 66 20 4e 20 69 6e 20    index of N in 
226f0 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
22700 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2a 0a 2a  atement] S..**.*
22710 2a 20 7b 48 31 33 35 32 37 7d 20 43 61 6c 6c 73  * {H13527} Calls
22720 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e   to [sqlite3_bin
22730 64 5f 74 65 78 74 20 7c 20 73 71 6c 69 74 65 33  d_text | sqlite3
22740 5f 62 69 6e 64 28 53 2c 4e 2c 2e 2e 2e 29 5d 0a  _bind(S,N,...)].
22750 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 76 65 72  **          over
22760 72 69 64 65 20 70 72 69 6f 72 20 63 61 6c 6c 73  ride prior calls
22770 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 76   with the same v
22780 61 6c 75 65 73 20 6f 66 20 53 20 61 6e 64 20 4e  alues of S and N
22790 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 33 30 7d  ..**.** {H13530}
227a0 20 42 69 6e 64 69 6e 67 73 20 65 73 74 61 62 6c   Bindings establ
227b0 69 73 68 65 64 20 62 79 20 5b 73 71 6c 69 74 65  ished by [sqlite
227c0 33 5f 62 69 6e 64 5f 74 65 78 74 20 7c 20 73 71  3_bind_text | sq
227d0 6c 69 74 65 33 5f 62 69 6e 64 28 53 2c 2e 2e 2e  lite3_bind(S,...
227e0 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70  )].**          p
227f0 65 72 73 69 73 74 20 61 63 72 6f 73 73 20 63 61  ersist across ca
22800 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
22810 72 65 73 65 74 28 53 29 5d 2e 0a 2a 2a 0a 2a 2a  reset(S)]..**.**
22820 20 7b 48 31 33 35 33 33 7d 20 49 6e 20 63 61 6c   {H13533} In cal
22830 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62  ls to [sqlite3_b
22840 69 6e 64 5f 62 6c 6f 62 28 53 2c 4e 2c 56 2c 4c  ind_blob(S,N,V,L
22850 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20  ,D)],.**        
22860 20 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f    [sqlite3_bind_
22870 74 65 78 74 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d  text(S,N,V,L,D)]
22880 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  , or.**         
22890 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74   [sqlite3_bind_t
228a0 65 78 74 31 36 28 53 2c 4e 2c 56 2c 4c 2c 44 29  ext16(S,N,V,L,D)
228b0 5d 20 53 51 4c 69 74 65 20 62 69 6e 64 73 20 74  ] SQLite binds t
228c0 68 65 20 66 69 72 73 74 20 4c 0a 2a 2a 20 20 20  he first L.**   
228d0 20 20 20 20 20 20 20 62 79 74 65 73 20 6f 66 20         bytes of 
228e0 74 68 65 20 42 4c 4f 42 20 6f 72 20 73 74 72 69  the BLOB or stri
228f0 6e 67 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79  ng pointed to by
22900 20 56 2c 20 77 68 65 6e 20 4c 0a 2a 2a 20 20 20   V, when L.**   
22910 20 20 20 20 20 20 20 69 73 20 6e 6f 6e 2d 6e 65         is non-ne
22920 67 61 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48  gative..**.** {H
22930 31 33 35 33 36 7d 20 49 6e 20 63 61 6c 6c 73 20  13536} In calls 
22940 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  to [sqlite3_bind
22950 5f 74 65 78 74 28 53 2c 4e 2c 56 2c 4c 2c 44 29  _text(S,N,V,L,D)
22960 5d 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  ] or.**         
22970 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74   [sqlite3_bind_t
22980 65 78 74 31 36 28 53 2c 4e 2c 56 2c 4c 2c 44 29  ext16(S,N,V,L,D)
22990 5d 20 53 51 4c 69 74 65 20 62 69 6e 64 73 20 63  ] SQLite binds c
229a0 68 61 72 61 63 74 65 72 73 0a 2a 2a 20 20 20 20  haracters.**    
229b0 20 20 20 20 20 20 66 72 6f 6d 20 56 20 74 68 72        from V thr
229c0 6f 75 67 68 20 74 68 65 20 66 69 72 73 74 20 7a  ough the first z
229d0 65 72 6f 20 63 68 61 72 61 63 74 65 72 20 77 68  ero character wh
229e0 65 6e 20 4c 20 69 73 20 6e 65 67 61 74 69 76 65  en L is negative
229f0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 33 39 7d  ..**.** {H13539}
22a00 20 49 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71   In calls to [sq
22a10 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28  lite3_bind_blob(
22a20 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c 0a 2a 2a 20  S,N,V,L,D)],.** 
22a30 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
22a40 33 5f 62 69 6e 64 5f 74 65 78 74 28 53 2c 4e 2c  3_bind_text(S,N,
22a50 56 2c 4c 2c 44 29 5d 2c 20 6f 72 0a 2a 2a 20 20  V,L,D)], or.**  
22a60 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
22a70 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 53 2c 4e  _bind_text16(S,N
22a80 2c 56 2c 4c 2c 44 29 5d 20 77 68 65 6e 20 44 20  ,V,L,D)] when D 
22a90 69 73 20 74 68 65 20 73 70 65 63 69 61 6c 0a 2a  is the special.*
22aa0 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6e 73 74  *          const
22ab0 61 6e 74 20 5b 53 51 4c 49 54 45 5f 53 54 41 54  ant [SQLITE_STAT
22ac0 49 43 5d 2c 20 53 51 4c 69 74 65 20 61 73 73 75  IC], SQLite assu
22ad0 6d 65 73 20 74 68 61 74 20 74 68 65 20 76 61 6c  mes that the val
22ae0 75 65 20 56 0a 2a 2a 20 20 20 20 20 20 20 20 20  ue V.**         
22af0 20 69 73 20 68 65 6c 64 20 69 6e 20 73 74 61 74   is held in stat
22b00 69 63 20 75 6e 6d 61 6e 61 67 65 64 20 73 70 61  ic unmanaged spa
22b10 63 65 20 74 68 61 74 20 77 69 6c 6c 20 6e 6f 74  ce that will not
22b20 20 63 68 61 6e 67 65 0a 2a 2a 20 20 20 20 20 20   change.**      
22b30 20 20 20 20 64 75 72 69 6e 67 20 74 68 65 20 6c      during the l
22b40 69 66 65 74 69 6d 65 20 6f 66 20 74 68 65 20 62  ifetime of the b
22b50 69 6e 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48  inding..**.** {H
22b60 31 33 35 34 32 7d 20 49 6e 20 63 61 6c 6c 73 20  13542} In calls 
22b70 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  to [sqlite3_bind
22b80 5f 62 6c 6f 62 28 53 2c 4e 2c 56 2c 4c 2c 44 29  _blob(S,N,V,L,D)
22b90 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  ],.**          [
22ba0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
22bb0 74 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c 20 6f  t(S,N,V,L,D)], o
22bc0 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  r.**          [s
22bd0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
22be0 31 36 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 20 77  16(S,N,V,L,D)] w
22bf0 68 65 6e 20 44 20 69 73 20 74 68 65 20 73 70 65  hen D is the spe
22c00 63 69 61 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20  cial.**         
22c10 20 63 6f 6e 73 74 61 6e 74 20 5b 53 51 4c 49 54   constant [SQLIT
22c20 45 5f 54 52 41 4e 53 49 45 4e 54 5d 2c 20 74 68  E_TRANSIENT], th
22c30 65 20 72 6f 75 74 69 6e 65 20 6d 61 6b 65 73 20  e routine makes 
22c40 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70 72  a.**          pr
22c50 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68  ivate copy of th
22c60 65 20 76 61 6c 75 65 20 56 20 62 65 66 6f 72 65  e value V before
22c70 20 69 74 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a   it returns..**.
22c80 2a 2a 20 7b 48 31 33 35 34 35 7d 20 49 6e 20 63  ** {H13545} In c
22c90 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
22ca0 5f 62 69 6e 64 5f 62 6c 6f 62 28 53 2c 4e 2c 56  _bind_blob(S,N,V
22cb0 2c 4c 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20  ,L,D)],.**      
22cc0 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e      [sqlite3_bin
22cd0 64 5f 74 65 78 74 28 53 2c 4e 2c 56 2c 4c 2c 44  d_text(S,N,V,L,D
22ce0 29 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20  )], or.**       
22cf0 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64     [sqlite3_bind
22d00 5f 74 65 78 74 31 36 28 53 2c 4e 2c 56 2c 4c 2c  _text16(S,N,V,L,
22d10 44 29 5d 20 77 68 65 6e 20 44 20 69 73 20 61 20  D)] when D is a 
22d20 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 20 20  pointer to.**   
22d30 20 20 20 20 20 20 20 61 20 66 75 6e 63 74 69 6f         a functio
22d40 6e 2c 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65  n, SQLite invoke
22d50 73 20 74 68 61 74 20 66 75 6e 63 74 69 6f 6e 20  s that function 
22d60 74 6f 20 64 65 73 74 72 6f 79 20 74 68 65 0a 2a  to destroy the.*
22d70 2a 20 20 20 20 20 20 20 20 20 20 76 61 6c 75 65  *          value
22d80 20 56 20 61 66 74 65 72 20 69 74 20 68 61 73 20   V after it has 
22d90 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74  finished using t
22da0 68 65 20 76 61 6c 75 65 20 56 2e 0a 2a 2a 0a 2a  he value V..**.*
22db0 2a 20 7b 48 31 33 35 34 38 7d 20 49 6e 20 63 61  * {H13548} In ca
22dc0 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
22dd0 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 53 2c  bind_zeroblob(S,
22de0 4e 2c 56 2c 4c 29 5d 20 74 68 65 20 76 61 6c 75  N,V,L)] the valu
22df0 65 20 62 6f 75 6e 64 0a 2a 2a 20 20 20 20 20 20  e bound.**      
22e00 20 20 20 20 69 73 20 61 20 42 4c 4f 42 20 6f 66      is a BLOB of
22e10 20 4c 20 62 79 74 65 73 2c 20 6f 72 20 61 20 7a   L bytes, or a z
22e20 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 20  ero-length BLOB 
22e30 69 66 20 4c 20 69 73 20 6e 65 67 61 74 69 76 65  if L is negative
22e40 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 35 31 7d  ..**.** {H13551}
22e50 20 49 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71   In calls to [sq
22e60 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65  lite3_bind_value
22e70 28 53 2c 4e 2c 56 29 5d 20 74 68 65 20 56 20 61  (S,N,V)] the V a
22e80 72 67 75 6d 65 6e 74 20 6d 61 79 0a 2a 2a 20 20  rgument may.**  
22e90 20 20 20 20 20 20 20 20 62 65 20 65 69 74 68 65          be eithe
22ea0 72 20 61 20 5b 70 72 6f 74 65 63 74 65 64 20 73  r a [protected s
22eb0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
22ec0 6a 65 63 74 20 6f 72 20 61 6e 0a 2a 2a 20 20 20  ject or an.**   
22ed0 20 20 20 20 20 20 20 5b 75 6e 70 72 6f 74 65 63         [unprotec
22ee0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
22ef0 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 69 6e  e] object..*/.in
22f00 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62  t sqlite3_bind_b
22f10 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  lob(sqlite3_stmt
22f20 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f  *, int, const vo
22f30 69 64 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64  id*, int n, void
22f40 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74  (*)(void*));.int
22f50 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 64 6f   sqlite3_bind_do
22f60 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  uble(sqlite3_stm
22f70 74 2a 2c 20 69 6e 74 2c 20 64 6f 75 62 6c 65 29  t*, int, double)
22f80 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
22f90 6e 64 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73  nd_int(sqlite3_s
22fa0 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 29 3b  tmt*, int, int);
22fb0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
22fc0 64 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f  d_int64(sqlite3_
22fd0 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69  stmt*, int, sqli
22fe0 74 65 33 5f 69 6e 74 36 34 29 3b 0a 69 6e 74 20  te3_int64);.int 
22ff0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c  sqlite3_bind_nul
23000 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  l(sqlite3_stmt*,
23010 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74   int);.int sqlit
23020 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 73 71 6c  e3_bind_text(sql
23030 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
23040 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e   const char*, in
23050 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69  t n, void(*)(voi
23060 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  d*));.int sqlite
23070 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 73 71  3_bind_text16(sq
23080 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
23090 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
230a0 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64  nt, void(*)(void
230b0 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  *));.int sqlite3
230c0 5f 62 69 6e 64 5f 76 61 6c 75 65 28 73 71 6c 69  _bind_value(sqli
230d0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
230e0 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 76 61  const sqlite3_va
230f0 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  lue*);.int sqlit
23100 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62  e3_bind_zeroblob
23110 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
23120 69 6e 74 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a  int, int n);../*
23130 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75  .** CAPI3REF: Nu
23140 6d 62 65 72 20 4f 66 20 53 51 4c 20 50 61 72 61  mber Of SQL Para
23150 6d 65 74 65 72 73 20 7b 48 31 33 36 30 30 7d 20  meters {H13600} 
23160 3c 53 37 30 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 54  <S70300>.**.** T
23170 68 69 73 20 72 6f 75 74 69 6e 65 20 63 61 6e 20  his routine can 
23180 62 65 20 75 73 65 64 20 74 6f 20 66 69 6e 64 20  be used to find 
23190 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 5b 53  the number of [S
231a0 51 4c 20 70 61 72 61 6d 65 74 65 72 73 5d 0a 2a  QL parameters].*
231b0 2a 20 69 6e 20 61 20 5b 70 72 65 70 61 72 65 64  * in a [prepared
231c0 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 53 51   statement].  SQ
231d0 4c 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65  L parameters are
231e0 20 74 6f 6b 65 6e 73 20 6f 66 20 74 68 65 0a 2a   tokens of the.*
231f0 2a 20 66 6f 72 6d 20 22 3f 22 2c 20 22 3f 4e 4e  * form "?", "?NN
23200 4e 22 2c 20 22 3a 41 41 41 22 2c 20 22 24 41 41  N", ":AAA", "$AA
23210 41 22 2c 20 6f 72 20 22 40 41 41 41 22 20 74 68  A", or "@AAA" th
23220 61 74 20 73 65 72 76 65 20 61 73 0a 2a 2a 20 70  at serve as.** p
23230 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20  laceholders for 
23240 76 61 6c 75 65 73 20 74 68 61 74 20 61 72 65 20  values that are 
23250 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
23260 6f 62 20 7c 20 62 6f 75 6e 64 5d 0a 2a 2a 20 74  ob | bound].** t
23270 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 73  o the parameters
23280 20 61 74 20 61 20 6c 61 74 65 72 20 74 69 6d 65   at a later time
23290 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75  ..**.** This rou
232a0 74 69 6e 65 20 61 63 74 75 61 6c 6c 79 20 72 65  tine actually re
232b0 74 75 72 6e 73 20 74 68 65 20 69 6e 64 65 78 20  turns the index 
232c0 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74 20 28  of the largest (
232d0 72 69 67 68 74 6d 6f 73 74 29 0a 2a 2a 20 70 61  rightmost).** pa
232e0 72 61 6d 65 74 65 72 2e 20 46 6f 72 20 61 6c 6c  rameter. For all
232f0 20 66 6f 72 6d 73 20 65 78 63 65 70 74 20 3f 4e   forms except ?N
23300 4e 4e 2c 20 74 68 69 73 20 77 69 6c 6c 20 63 6f  NN, this will co
23310 72 72 65 73 70 6f 6e 64 20 74 6f 20 74 68 65 0a  rrespond to the.
23320 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 75 6e 69  ** number of uni
23330 71 75 65 20 70 61 72 61 6d 65 74 65 72 73 2e 20  que parameters. 
23340 20 49 66 20 70 61 72 61 6d 65 74 65 72 73 20 6f   If parameters o
23350 66 20 74 68 65 20 3f 4e 4e 4e 20 61 72 65 20 75  f the ?NNN are u
23360 73 65 64 2c 0a 2a 2a 20 74 68 65 72 65 20 6d 61  sed,.** there ma
23370 79 20 62 65 20 67 61 70 73 20 69 6e 20 74 68 65  y be gaps in the
23380 20 6c 69 73 74 2e 0a 2a 2a 0a 2a 2a 20 53 65 65   list..**.** See
23390 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
233a0 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65  bind_blob|sqlite
233b0 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73  3_bind()],.** [s
233c0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
233d0 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61  meter_name()], a
233e0 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  nd.** [sqlite3_b
233f0 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e  ind_parameter_in
23400 64 65 78 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e  dex()]..**.** IN
23410 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
23420 7b 48 31 33 36 30 31 7d 20 54 68 65 20 5b 73 71  {H13601} The [sq
23430 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
23440 65 74 65 72 5f 63 6f 75 6e 74 28 53 29 5d 20 69  eter_count(S)] i
23450 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
23460 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
23470 20 6c 61 72 67 65 73 74 20 69 6e 64 65 78 20 6f   largest index o
23480 66 20 61 6c 6c 20 53 51 4c 20 70 61 72 61 6d 65  f all SQL parame
23490 74 65 72 73 20 69 6e 20 74 68 65 0a 2a 2a 20 20  ters in the.**  
234a0 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65          [prepare
234b0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2c 20  d statement] S, 
234c0 6f 72 20 30 20 69 66 20 53 20 63 6f 6e 74 61 69  or 0 if S contai
234d0 6e 73 20 6e 6f 20 53 51 4c 20 70 61 72 61 6d 65  ns no SQL parame
234e0 74 65 72 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  ters..*/.int sql
234f0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
23500 74 65 72 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65  ter_count(sqlite
23510 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  3_stmt*);../*.**
23520 20 43 41 50 49 33 52 45 46 3a 20 4e 61 6d 65 20   CAPI3REF: Name 
23530 4f 66 20 41 20 48 6f 73 74 20 50 61 72 61 6d 65  Of A Host Parame
23540 74 65 72 20 7b 48 31 33 36 32 30 7d 20 3c 53 37  ter {H13620} <S7
23550 30 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  0300>.**.** This
23560 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
23570 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
23580 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6e 2d  e name of the n-
23590 74 68 0a 2a 2a 20 5b 53 51 4c 20 70 61 72 61 6d  th.** [SQL param
235a0 65 74 65 72 5d 20 69 6e 20 61 20 5b 70 72 65 70  eter] in a [prep
235b0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
235c0 0a 2a 2a 20 53 51 4c 20 70 61 72 61 6d 65 74 65  .** SQL paramete
235d0 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22  rs of the form "
235e0 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20  ?NNN" or ":AAA" 
235f0 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22 24 41  or "@AAA" or "$A
23600 41 41 22 0a 2a 2a 20 68 61 76 65 20 61 20 6e 61  AA".** have a na
23610 6d 65 20 77 68 69 63 68 20 69 73 20 74 68 65 20  me which is the 
23620 73 74 72 69 6e 67 20 22 3f 4e 4e 4e 22 20 6f 72  string "?NNN" or
23630 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41   ":AAA" or "@AAA
23640 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 72  " or "$AAA".** r
23650 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20  espectively..** 
23660 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20  In other words, 
23670 74 68 65 20 69 6e 69 74 69 61 6c 20 22 3a 22 20  the initial ":" 
23680 6f 72 20 22 24 22 20 6f 72 20 22 40 22 20 6f 72  or "$" or "@" or
23690 20 22 3f 22 0a 2a 2a 20 69 73 20 69 6e 63 6c 75   "?".** is inclu
236a0 64 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 74  ded as part of t
236b0 68 65 20 6e 61 6d 65 2e 0a 2a 2a 20 50 61 72 61  he name..** Para
236c0 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f  meters of the fo
236d0 72 6d 20 22 3f 22 20 77 69 74 68 6f 75 74 20 61  rm "?" without a
236e0 20 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 67   following integ
236f0 65 72 20 68 61 76 65 20 6e 6f 20 6e 61 6d 65 0a  er have no name.
23700 2a 2a 20 61 6e 64 20 61 72 65 20 61 6c 73 6f 20  ** and are also 
23710 72 65 66 65 72 72 65 64 20 74 6f 20 61 73 20 22  referred to as "
23720 61 6e 6f 6e 79 6d 6f 75 73 20 70 61 72 61 6d 65  anonymous parame
23730 74 65 72 73 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ters"..**.** The
23740 20 66 69 72 73 74 20 68 6f 73 74 20 70 61 72 61   first host para
23750 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64  meter has an ind
23760 65 78 20 6f 66 20 31 2c 20 6e 6f 74 20 30 2e 0a  ex of 1, not 0..
23770 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 76 61 6c  **.** If the val
23780 75 65 20 6e 20 69 73 20 6f 75 74 20 6f 66 20 72  ue n is out of r
23790 61 6e 67 65 20 6f 72 20 69 66 20 74 68 65 20 6e  ange or if the n
237a0 2d 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73  -th parameter is
237b0 0a 2a 2a 20 6e 61 6d 65 6c 65 73 73 2c 20 74 68  .** nameless, th
237c0 65 6e 20 4e 55 4c 4c 20 69 73 20 72 65 74 75 72  en NULL is retur
237d0 6e 65 64 2e 20 20 54 68 65 20 72 65 74 75 72 6e  ned.  The return
237e0 65 64 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20  ed string is.** 
237f0 61 6c 77 61 79 73 20 69 6e 20 55 54 46 2d 38 20  always in UTF-8 
23800 65 6e 63 6f 64 69 6e 67 20 65 76 65 6e 20 69 66  encoding even if
23810 20 74 68 65 20 6e 61 6d 65 64 20 70 61 72 61 6d   the named param
23820 65 74 65 72 20 77 61 73 0a 2a 2a 20 6f 72 69 67  eter was.** orig
23830 69 6e 61 6c 6c 79 20 73 70 65 63 69 66 69 65 64  inally specified
23840 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 5b 73   as UTF-16 in [s
23850 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
23860 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  ()] or.** [sqlit
23870 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
23880 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  )]..**.** See al
23890 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  so: [sqlite3_bin
238a0 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62  d_blob|sqlite3_b
238b0 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  ind()],.** [sqli
238c0 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
238d0 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64  er_count()], and
238e0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
238f0 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65  d_parameter_inde
23900 78 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  x()]..**.** INVA
23910 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48  RIANTS:.**.** {H
23920 31 33 36 32 31 7d 20 54 68 65 20 5b 73 71 6c 69  13621} The [sqli
23930 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
23940 65 72 5f 6e 61 6d 65 28 53 2c 4e 29 5d 20 69 6e  er_name(S,N)] in
23950 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 0a  terface returns.
23960 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20 55 54  **          a UT
23970 46 2d 38 20 72 65 6e 64 65 72 69 6e 67 20 6f 66  F-8 rendering of
23980 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
23990 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69   SQL parameter i
239a0 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  n.**          th
239b0 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
239c0 65 6d 65 6e 74 5d 20 53 20 68 61 76 69 6e 67 20  ement] S having 
239d0 69 6e 64 65 78 20 4e 2c 20 6f 72 0a 2a 2a 20 20  index N, or.**  
239e0 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 69 66 20          NULL if 
239f0 74 68 65 72 65 20 69 73 20 6e 6f 20 53 51 4c 20  there is no SQL 
23a00 70 61 72 61 6d 65 74 65 72 20 77 69 74 68 20 69  parameter with i
23a10 6e 64 65 78 20 4e 20 6f 72 20 69 66 20 74 68 65  ndex N or if the
23a20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70 61 72  .**          par
23a30 61 6d 65 74 65 72 20 77 69 74 68 20 69 6e 64 65  ameter with inde
23a40 78 20 4e 20 69 73 20 61 6e 20 61 6e 6f 6e 79 6d  x N is an anonym
23a50 6f 75 73 20 70 61 72 61 6d 65 74 65 72 20 22 3f  ous parameter "?
23a60 22 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72  "..*/.const char
23a70 20 2a 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   *sqlite3_bind_p
23a80 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 73 71  arameter_name(sq
23a90 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
23aa0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
23ab0 45 46 3a 20 49 6e 64 65 78 20 4f 66 20 41 20 50  EF: Index Of A P
23ac0 61 72 61 6d 65 74 65 72 20 57 69 74 68 20 41 20  arameter With A 
23ad0 47 69 76 65 6e 20 4e 61 6d 65 20 7b 48 31 33 36  Given Name {H136
23ae0 34 30 7d 20 3c 53 37 30 33 30 30 3e 0a 2a 2a 0a  40} <S70300>.**.
23af0 2a 2a 20 52 65 74 75 72 6e 20 74 68 65 20 69 6e  ** Return the in
23b00 64 65 78 20 6f 66 20 61 6e 20 53 51 4c 20 70 61  dex of an SQL pa
23b10 72 61 6d 65 74 65 72 20 67 69 76 65 6e 20 69 74  rameter given it
23b20 73 20 6e 61 6d 65 2e 20 20 54 68 65 0a 2a 2a 20  s name.  The.** 
23b30 69 6e 64 65 78 20 76 61 6c 75 65 20 72 65 74 75  index value retu
23b40 72 6e 65 64 20 69 73 20 73 75 69 74 61 62 6c 65  rned is suitable
23b50 20 66 6f 72 20 75 73 65 20 61 73 20 74 68 65 20   for use as the 
23b60 73 65 63 6f 6e 64 0a 2a 2a 20 70 61 72 61 6d 65  second.** parame
23b70 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ter to [sqlite3_
23b80 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65  bind_blob|sqlite
23b90 33 5f 62 69 6e 64 28 29 5d 2e 20 20 41 20 7a 65  3_bind()].  A ze
23ba0 72 6f 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65  ro.** is returne
23bb0 64 20 69 66 20 6e 6f 20 6d 61 74 63 68 69 6e 67  d if no matching
23bc0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 66 6f   parameter is fo
23bd0 75 6e 64 2e 20 20 54 68 65 20 70 61 72 61 6d 65  und.  The parame
23be0 74 65 72 0a 2a 2a 20 6e 61 6d 65 20 6d 75 73 74  ter.** name must
23bf0 20 62 65 20 67 69 76 65 6e 20 69 6e 20 55 54 46   be given in UTF
23c00 2d 38 20 65 76 65 6e 20 69 66 20 74 68 65 20 6f  -8 even if the o
23c10 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e  riginal statemen
23c20 74 0a 2a 2a 20 77 61 73 20 70 72 65 70 61 72 65  t.** was prepare
23c30 64 20 66 72 6f 6d 20 55 54 46 2d 31 36 20 74 65  d from UTF-16 te
23c40 78 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  xt using [sqlite
23c50 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
23c60 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  ]..**.** See als
23c70 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  o: [sqlite3_bind
23c80 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69  _blob|sqlite3_bi
23c90 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  nd()],.** [sqlit
23ca0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
23cb0 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a  r_count()], and.
23cc0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
23cd0 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78  _parameter_index
23ce0 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  ()]..**.** INVAR
23cf0 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31  IANTS:.**.** {H1
23d00 33 36 34 31 7d 20 54 68 65 20 5b 73 71 6c 69 74  3641} The [sqlit
23d10 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
23d20 72 5f 69 6e 64 65 78 28 53 2c 4e 29 5d 20 69 6e  r_index(S,N)] in
23d30 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 0a  terface returns.
23d40 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
23d50 69 6e 64 65 78 20 6f 66 20 53 51 4c 20 70 61 72  index of SQL par
23d60 61 6d 65 74 65 72 20 69 6e 20 74 68 65 20 5b 70  ameter in the [p
23d70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
23d80 74 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 53  t].**          S
23d90 20 77 68 6f 73 65 20 6e 61 6d 65 20 6d 61 74 63   whose name matc
23da0 68 65 73 20 74 68 65 20 55 54 46 2d 38 20 73 74  hes the UTF-8 st
23db0 72 69 6e 67 20 4e 2c 20 6f 72 20 30 20 69 66 20  ring N, or 0 if 
23dc0 74 68 65 72 65 20 69 73 0a 2a 2a 20 20 20 20 20  there is.**     
23dd0 20 20 20 20 20 6e 6f 20 6d 61 74 63 68 2e 0a 2a       no match..*
23de0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  /.int sqlite3_bi
23df0 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64  nd_parameter_ind
23e00 65 78 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ex(sqlite3_stmt*
23e10 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
23e20 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ame);../*.** CAP
23e30 49 33 52 45 46 3a 20 52 65 73 65 74 20 41 6c 6c  I3REF: Reset All
23e40 20 42 69 6e 64 69 6e 67 73 20 4f 6e 20 41 20 50   Bindings On A P
23e50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e  repared Statemen
23e60 74 20 7b 48 31 33 36 36 30 7d 20 3c 53 37 30 33  t {H13660} <S703
23e70 30 30 3e 0a 2a 2a 0a 2a 2a 20 43 6f 6e 74 72 61  00>.**.** Contra
23e80 72 79 20 74 6f 20 74 68 65 20 69 6e 74 75 69 74  ry to the intuit
23e90 69 6f 6e 20 6f 66 20 6d 61 6e 79 2c 20 5b 73 71  ion of many, [sq
23ea0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 64  lite3_reset()] d
23eb0 6f 65 73 20 6e 6f 74 20 72 65 73 65 74 0a 2a 2a  oes not reset.**
23ec0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69   the [sqlite3_bi
23ed0 6e 64 5f 62 6c 6f 62 20 7c 20 62 69 6e 64 69 6e  nd_blob | bindin
23ee0 67 73 5d 20 6f 6e 20 61 20 5b 70 72 65 70 61 72  gs] on a [prepar
23ef0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a  ed statement]..*
23f00 2a 20 55 73 65 20 74 68 69 73 20 72 6f 75 74 69  * Use this routi
23f10 6e 65 20 74 6f 20 72 65 73 65 74 20 61 6c 6c 20  ne to reset all 
23f20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 20  host parameters 
23f30 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 49  to NULL..**.** I
23f40 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
23f50 20 7b 48 31 33 36 36 31 7d 20 54 68 65 20 5b 73   {H13661} The [s
23f60 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e  qlite3_clear_bin
23f70 64 69 6e 67 73 28 53 29 5d 20 69 6e 74 65 72 66  dings(S)] interf
23f80 61 63 65 20 72 65 73 65 74 73 20 61 6c 6c 20 53  ace resets all S
23f90 51 4c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70  QL.**          p
23fa0 61 72 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67  arameter binding
23fb0 73 20 69 6e 20 74 68 65 20 5b 70 72 65 70 61 72  s in the [prepar
23fc0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20  ed statement] S 
23fd0 62 61 63 6b 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f  back to NULL..*/
23fe0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 65  .int sqlite3_cle
23ff0 61 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69  ar_bindings(sqli
24000 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a  te3_stmt*);../*.
24010 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d  ** CAPI3REF: Num
24020 62 65 72 20 4f 66 20 43 6f 6c 75 6d 6e 73 20 49  ber Of Columns I
24030 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74 20 7b  n A Result Set {
24040 48 31 33 37 31 30 7d 20 3c 53 31 30 37 30 30 3e  H13710} <S10700>
24050 0a 2a 2a 0a 2a 2a 20 52 65 74 75 72 6e 20 74 68  .**.** Return th
24060 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  e number of colu
24070 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c  mns in the resul
24080 74 20 73 65 74 20 72 65 74 75 72 6e 65 64 20 62  t set returned b
24090 79 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72  y the.** [prepar
240a0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 54  ed statement]. T
240b0 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75  his routine retu
240c0 72 6e 73 20 30 20 69 66 20 70 53 74 6d 74 20 69  rns 0 if pStmt i
240d0 73 20 61 6e 20 53 51 4c 0a 2a 2a 20 73 74 61 74  s an SQL.** stat
240e0 65 6d 65 6e 74 20 74 68 61 74 20 64 6f 65 73 20  ement that does 
240f0 6e 6f 74 20 72 65 74 75 72 6e 20 64 61 74 61 20  not return data 
24100 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 61 6e 20  (for example an 
24110 5b 55 50 44 41 54 45 5d 29 2e 0a 2a 2a 0a 2a 2a  [UPDATE])..**.**
24120 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
24130 2a 2a 20 7b 48 31 33 37 31 31 7d 20 54 68 65 20  ** {H13711} The 
24140 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
24150 63 6f 75 6e 74 28 53 29 5d 20 69 6e 74 65 72 66  count(S)] interf
24160 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ace returns the 
24170 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 20 20 20  number of.**    
24180 20 20 20 20 20 20 63 6f 6c 75 6d 6e 73 20 69 6e        columns in
24190 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20   the result set 
241a0 67 65 6e 65 72 61 74 65 64 20 62 79 20 74 68 65  generated by the
241b0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
241c0 6d 65 6e 74 5d 20 53 2c 0a 2a 2a 20 20 20 20 20  ment] S,.**     
241d0 20 20 20 20 20 6f 72 20 30 20 69 66 20 53 20 64       or 0 if S d
241e0 6f 65 73 20 6e 6f 74 20 67 65 6e 65 72 61 74 65  oes not generate
241f0 20 61 20 72 65 73 75 6c 74 20 73 65 74 2e 0a 2a   a result set..*
24200 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  /.int sqlite3_co
24210 6c 75 6d 6e 5f 63 6f 75 6e 74 28 73 71 6c 69 74  lumn_count(sqlit
24220 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
24230 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
24240 3a 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 73 20 49  : Column Names I
24250 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74 20 7b  n A Result Set {
24260 48 31 33 37 32 30 7d 20 3c 53 31 30 37 30 30 3e  H13720} <S10700>
24270 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
24280 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65  tines return the
24290 20 6e 61 6d 65 20 61 73 73 69 67 6e 65 64 20 74   name assigned t
242a0 6f 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 63  o a particular c
242b0 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e 20 74 68 65 20  olumn.** in the 
242c0 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20  result set of a 
242d0 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65  [SELECT] stateme
242e0 6e 74 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33  nt.  The sqlite3
242f0 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 0a 2a  _column_name().*
24300 2a 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  * interface retu
24310 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
24320 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
24330 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 0a  ed UTF-8 string.
24340 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63  ** and sqlite3_c
24350 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 72  olumn_name16() r
24360 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
24370 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69   to a zero-termi
24380 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20  nated.** UTF-16 
24390 73 74 72 69 6e 67 2e 20 20 54 68 65 20 66 69 72  string.  The fir
243a0 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  st parameter is 
243b0 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
243c0 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 74 68 61 74  atement].** that
243d0 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20   implements the 
243e0 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65  [SELECT] stateme
243f0 6e 74 2e 20 54 68 65 20 73 65 63 6f 6e 64 20 70  nt. The second p
24400 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a  arameter is the.
24410 2a 2a 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72  ** column number
24420 2e 20 20 54 68 65 20 6c 65 66 74 6d 6f 73 74 20  .  The leftmost 
24430 63 6f 6c 75 6d 6e 20 69 73 20 6e 75 6d 62 65 72  column is number
24440 20 30 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 72 65   0..**.** The re
24450 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 70 6f  turned string po
24460 69 6e 74 65 72 20 69 73 20 76 61 6c 69 64 20 75  inter is valid u
24470 6e 74 69 6c 20 65 69 74 68 65 72 20 74 68 65 20  ntil either the 
24480 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
24490 65 6e 74 5d 0a 2a 2a 20 69 73 20 64 65 73 74 72  ent].** is destr
244a0 6f 79 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  oyed by [sqlite3
244b0 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20  _finalize()] or 
244c0 75 6e 74 69 6c 20 74 68 65 20 6e 65 78 74 20 63  until the next c
244d0 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  all to.** sqlite
244e0 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 20  3_column_name() 
244f0 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  or sqlite3_colum
24500 6e 5f 6e 61 6d 65 31 36 28 29 20 6f 6e 20 74 68  n_name16() on th
24510 65 20 73 61 6d 65 20 63 6f 6c 75 6d 6e 2e 0a 2a  e same column..*
24520 2a 0a 2a 2a 20 49 66 20 73 71 6c 69 74 65 33 5f  *.** If sqlite3_
24530 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 20 64  malloc() fails d
24540 75 72 69 6e 67 20 74 68 65 20 70 72 6f 63 65 73  uring the proces
24550 73 69 6e 67 20 6f 66 20 65 69 74 68 65 72 20 72  sing of either r
24560 6f 75 74 69 6e 65 0a 2a 2a 20 28 66 6f 72 20 65  outine.** (for e
24570 78 61 6d 70 6c 65 20 64 75 72 69 6e 67 20 61 20  xample during a 
24580 63 6f 6e 76 65 72 73 69 6f 6e 20 66 72 6f 6d 20  conversion from 
24590 55 54 46 2d 38 20 74 6f 20 55 54 46 2d 31 36 29  UTF-8 to UTF-16)
245a0 20 74 68 65 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20   then a.** NULL 
245b0 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75 72  pointer is retur
245c0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6e  ned..**.** The n
245d0 61 6d 65 20 6f 66 20 61 20 72 65 73 75 6c 74 20  ame of a result 
245e0 63 6f 6c 75 6d 6e 20 69 73 20 74 68 65 20 76 61  column is the va
245f0 6c 75 65 20 6f 66 20 74 68 65 20 22 41 53 22 20  lue of the "AS" 
24600 63 6c 61 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68  clause for.** th
24610 61 74 20 63 6f 6c 75 6d 6e 2c 20 69 66 20 74 68  at column, if th
24620 65 72 65 20 69 73 20 61 6e 20 41 53 20 63 6c 61  ere is an AS cla
24630 75 73 65 2e 20 20 49 66 20 74 68 65 72 65 20 69  use.  If there i
24640 73 20 6e 6f 20 41 53 20 63 6c 61 75 73 65 0a 2a  s no AS clause.*
24650 2a 20 74 68 65 6e 20 74 68 65 20 6e 61 6d 65 20  * then the name 
24660 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69 73  of the column is
24670 20 75 6e 73 70 65 63 69 66 69 65 64 20 61 6e 64   unspecified and
24680 20 6d 61 79 20 63 68 61 6e 67 65 20 66 72 6f 6d   may change from
24690 0a 2a 2a 20 6f 6e 65 20 72 65 6c 65 61 73 65 20  .** one release 
246a0 6f 66 20 53 51 4c 69 74 65 20 74 6f 20 74 68 65  of SQLite to the
246b0 20 6e 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56   next..**.** INV
246c0 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
246d0 48 31 33 37 32 31 7d 20 41 20 73 75 63 63 65 73  H13721} A succes
246e0 73 66 75 6c 20 69 6e 76 6f 63 61 74 69 6f 6e 20  sful invocation 
246f0 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
24700 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 53 2c 4e 29  column_name(S,N)
24710 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e  ].**          in
24720 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
24730 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
24740 4e 74 68 20 63 6f 6c 75 6d 6e 20 28 77 68 65 72  Nth column (wher
24750 65 20 30 20 69 73 0a 2a 2a 20 20 20 20 20 20 20  e 0 is.**       
24760 20 20 20 74 68 65 20 6c 65 66 74 6d 6f 73 74 20     the leftmost 
24770 63 6f 6c 75 6d 6e 29 20 66 6f 72 20 74 68 65 20  column) for the 
24780 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 74 68  result set of th
24790 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70  e.**          [p
247a0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
247b0 74 5d 20 53 20 61 73 20 61 20 7a 65 72 6f 2d 74  t] S as a zero-t
247c0 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20  erminated UTF-8 
247d0 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48  string..**.** {H
247e0 31 33 37 32 33 7d 20 41 20 73 75 63 63 65 73 73  13723} A success
247f0 66 75 6c 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f  ful invocation o
24800 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  f the [sqlite3_c
24810 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 53 2c 4e  olumn_name16(S,N
24820 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  )].**          i
24830 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
24840 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
24850 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 28 77 68 65   Nth column (whe
24860 72 65 20 30 20 69 73 0a 2a 2a 20 20 20 20 20 20  re 0 is.**      
24870 20 20 20 20 74 68 65 20 6c 65 66 74 6d 6f 73 74      the leftmost
24880 20 63 6f 6c 75 6d 6e 29 20 66 6f 72 20 74 68 65   column) for the
24890 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 74   result set of t
248a0 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  he.**          [
248b0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
248c0 6e 74 5d 20 53 20 61 73 20 61 20 7a 65 72 6f 2d  nt] S as a zero-
248d0 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 31  terminated UTF-1
248e0 36 20 73 74 72 69 6e 67 0a 2a 2a 20 20 20 20 20  6 string.**     
248f0 20 20 20 20 20 69 6e 20 74 68 65 20 6e 61 74 69       in the nati
24900 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a  ve byte order..*
24910 2a 0a 2a 2a 20 7b 48 31 33 37 32 34 7d 20 54 68  *.** {H13724} Th
24920 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  e [sqlite3_colum
24930 6e 5f 6e 61 6d 65 28 29 5d 20 61 6e 64 20 5b 73  n_name()] and [s
24940 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
24950 6d 65 31 36 28 29 5d 0a 2a 2a 20 20 20 20 20 20  me16()].**      
24960 20 20 20 20 69 6e 74 65 72 66 61 63 65 73 20 72      interfaces r
24970 65 74 75 72 6e 20 61 20 4e 55 4c 4c 20 70 6f 69  eturn a NULL poi
24980 6e 74 65 72 20 69 66 20 74 68 65 79 20 61 72 65  nter if they are
24990 20 75 6e 61 62 6c 65 20 74 6f 0a 2a 2a 20 20 20   unable to.**   
249a0 20 20 20 20 20 20 20 61 6c 6c 6f 63 61 74 65 20         allocate 
249b0 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74  memory to hold t
249c0 68 65 69 72 20 6e 6f 72 6d 61 6c 20 72 65 74 75  heir normal retu
249d0 72 6e 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 0a 2a  rn strings..**.*
249e0 2a 20 7b 48 31 33 37 32 35 7d 20 49 66 20 74 68  * {H13725} If th
249f0 65 20 4e 20 70 61 72 61 6d 65 74 65 72 20 74 6f  e N parameter to
24a00 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
24a10 5f 6e 61 6d 65 28 53 2c 4e 29 5d 20 6f 72 0a 2a  _name(S,N)] or.*
24a20 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
24a30 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31  te3_column_name1
24a40 36 28 53 2c 4e 29 5d 20 69 73 20 6f 75 74 20 6f  6(S,N)] is out o
24a50 66 20 72 61 6e 67 65 2c 20 74 68 65 6e 20 74 68  f range, then th
24a60 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e  e.**          in
24a70 74 65 72 66 61 63 65 73 20 72 65 74 75 72 6e 20  terfaces return 
24a80 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a  a NULL pointer..
24a90 2a 2a 0a 2a 2a 20 7b 48 31 33 37 32 36 7d 20 54  **.** {H13726} T
24aa0 68 65 20 73 74 72 69 6e 67 73 20 72 65 74 75 72  he strings retur
24ab0 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ned by [sqlite3_
24ac0 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 53 2c 4e 29  column_name(S,N)
24ad0 5d 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20  ] and.**        
24ae0 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d    [sqlite3_colum
24af0 6e 5f 6e 61 6d 65 31 36 28 53 2c 4e 29 5d 20 61  n_name16(S,N)] a
24b00 72 65 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 74  re valid until t
24b10 68 65 20 6e 65 78 74 0a 2a 2a 20 20 20 20 20 20  he next.**      
24b20 20 20 20 20 63 61 6c 6c 20 74 6f 20 65 69 74 68      call to eith
24b30 65 72 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20  er routine with 
24b40 74 68 65 20 73 61 6d 65 20 53 20 61 6e 64 20 4e  the same S and N
24b50 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 20   parameters.**  
24b60 20 20 20 20 20 20 20 20 6f 72 20 75 6e 74 69 6c          or until
24b70 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
24b80 7a 65 28 53 29 5d 20 69 73 20 63 61 6c 6c 65 64  ze(S)] is called
24b90 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 32 37 7d  ..**.** {H13727}
24ba0 20 57 68 65 6e 20 61 20 72 65 73 75 6c 74 20 63   When a result c
24bb0 6f 6c 75 6d 6e 20 6f 66 20 61 20 5b 53 45 4c 45  olumn of a [SELE
24bc0 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 63 6f  CT] statement co
24bd0 6e 74 61 69 6e 73 0a 2a 2a 20 20 20 20 20 20 20  ntains.**       
24be0 20 20 20 61 6e 20 41 53 20 63 6c 61 75 73 65 2c     an AS clause,
24bf0 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 61   the name of tha
24c00 74 20 63 6f 6c 75 6d 6e 20 69 73 20 74 68 65 20  t column is the 
24c10 69 64 65 6e 74 69 66 69 65 72 0a 2a 2a 20 20 20  identifier.**   
24c20 20 20 20 20 20 20 20 74 6f 20 74 68 65 20 72 69         to the ri
24c30 67 68 74 20 6f 66 20 74 68 65 20 41 53 20 6b 65  ght of the AS ke
24c40 79 77 6f 72 64 2e 0a 2a 2f 0a 63 6f 6e 73 74 20  yword..*/.const 
24c50 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
24c60 6c 75 6d 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65  lumn_name(sqlite
24c70 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b  3_stmt*, int N);
24c80 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
24c90 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
24ca0 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
24cb0 2c 20 69 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a  , int N);../*.**
24cc0 20 43 41 50 49 33 52 45 46 3a 20 53 6f 75 72 63   CAPI3REF: Sourc
24cd0 65 20 4f 66 20 44 61 74 61 20 49 6e 20 41 20 51  e Of Data In A Q
24ce0 75 65 72 79 20 52 65 73 75 6c 74 20 7b 48 31 33  uery Result {H13
24cf0 37 34 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 2a  740} <S10700>.**
24d00 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
24d10 65 73 20 70 72 6f 76 69 64 65 20 61 20 6d 65 61  es provide a mea
24d20 6e 73 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20  ns to determine 
24d30 77 68 61 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 77  what column of w
24d40 68 61 74 0a 2a 2a 20 74 61 62 6c 65 20 69 6e 20  hat.** table in 
24d50 77 68 69 63 68 20 64 61 74 61 62 61 73 65 20 61  which database a
24d60 20 72 65 73 75 6c 74 20 6f 66 20 61 20 5b 53 45   result of a [SE
24d70 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20  LECT] statement 
24d80 63 6f 6d 65 73 20 66 72 6f 6d 2e 0a 2a 2a 20 54  comes from..** T
24d90 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64  he name of the d
24da0 61 74 61 62 61 73 65 20 6f 72 20 74 61 62 6c 65  atabase or table
24db0 20 6f 72 20 63 6f 6c 75 6d 6e 20 63 61 6e 20 62   or column can b
24dc0 65 20 72 65 74 75 72 6e 65 64 20 61 73 0a 2a 2a  e returned as.**
24dd0 20 65 69 74 68 65 72 20 61 20 55 54 46 2d 38 20   either a UTF-8 
24de0 6f 72 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67  or UTF-16 string
24df0 2e 20 20 54 68 65 20 5f 64 61 74 61 62 61 73 65  .  The _database
24e00 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  _ routines retur
24e10 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73  n.** the databas
24e20 65 20 6e 61 6d 65 2c 20 74 68 65 20 5f 74 61 62  e name, the _tab
24e30 6c 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74  le_ routines ret
24e40 75 72 6e 20 74 68 65 20 74 61 62 6c 65 20 6e 61  urn the table na
24e50 6d 65 2c 20 61 6e 64 0a 2a 2a 20 74 68 65 20 6f  me, and.** the o
24e60 72 69 67 69 6e 5f 20 72 6f 75 74 69 6e 65 73 20  rigin_ routines 
24e70 72 65 74 75 72 6e 20 74 68 65 20 63 6f 6c 75 6d  return the colum
24e80 6e 20 6e 61 6d 65 2e 0a 2a 2a 20 54 68 65 20 72  n name..** The r
24e90 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69  eturned string i
24ea0 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 74 68  s valid until th
24eb0 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
24ec0 65 6d 65 6e 74 5d 20 69 73 20 64 65 73 74 72 6f  ement] is destro
24ed0 79 65 64 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71  yed.** using [sq
24ee0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
24ef0 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73  ] or until the s
24f00 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  ame information 
24f10 69 73 20 72 65 71 75 65 73 74 65 64 0a 2a 2a 20  is requested.** 
24f20 61 67 61 69 6e 20 69 6e 20 61 20 64 69 66 66 65  again in a diffe
24f30 72 65 6e 74 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a  rent encoding..*
24f40 2a 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 73 20 72  *.** The names r
24f50 65 74 75 72 6e 65 64 20 61 72 65 20 74 68 65 20  eturned are the 
24f60 6f 72 69 67 69 6e 61 6c 20 75 6e 2d 61 6c 69 61  original un-alia
24f70 73 65 64 20 6e 61 6d 65 73 20 6f 66 20 74 68 65  sed names of the
24f80 0a 2a 2a 20 64 61 74 61 62 61 73 65 2c 20 74 61  .** database, ta
24f90 62 6c 65 2c 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e  ble, and column.
24fa0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  .**.** The first
24fb0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
24fc0 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 61 6c 6c 73   following calls
24fd0 20 69 73 20 61 20 5b 70 72 65 70 61 72 65 64 20   is a [prepared 
24fe0 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 54  statement]..** T
24ff0 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 72  hese functions r
25000 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f  eturn informatio
25010 6e 20 61 62 6f 75 74 20 74 68 65 20 4e 74 68 20  n about the Nth 
25020 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20  column returned 
25030 62 79 0a 2a 2a 20 74 68 65 20 73 74 61 74 65 6d  by.** the statem
25040 65 6e 74 2c 20 77 68 65 72 65 20 4e 20 69 73 20  ent, where N is 
25050 74 68 65 20 73 65 63 6f 6e 64 20 66 75 6e 63 74  the second funct
25060 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  ion argument..**
25070 0a 2a 2a 20 49 66 20 74 68 65 20 4e 74 68 20 63  .** If the Nth c
25080 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62  olumn returned b
25090 79 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  y the statement 
250a0 69 73 20 61 6e 20 65 78 70 72 65 73 73 69 6f 6e  is an expression
250b0 20 6f 72 0a 2a 2a 20 73 75 62 71 75 65 72 79 20   or.** subquery 
250c0 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 63 6f 6c  and is not a col
250d0 75 6d 6e 20 76 61 6c 75 65 2c 20 74 68 65 6e 20  umn value, then 
250e0 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 66 75 6e  all of these fun
250f0 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 0a 2a 2a  ctions return.**
25100 20 4e 55 4c 4c 2e 20 20 54 68 65 73 65 20 72 6f   NULL.  These ro
25110 75 74 69 6e 65 20 6d 69 67 68 74 20 61 6c 73 6f  utine might also
25120 20 72 65 74 75 72 6e 20 4e 55 4c 4c 20 69 66 20   return NULL if 
25130 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  a memory allocat
25140 69 6f 6e 20 65 72 72 6f 72 0a 2a 2a 20 6f 63 63  ion error.** occ
25150 75 72 73 2e 20 20 4f 74 68 65 72 77 69 73 65 2c  urs.  Otherwise,
25160 20 74 68 65 79 20 72 65 74 75 72 6e 20 74 68 65   they return the
25170 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 61 74 74   name of the att
25180 61 63 68 65 64 20 64 61 74 61 62 61 73 65 2c 20  ached database, 
25190 74 61 62 6c 65 0a 2a 2a 20 61 6e 64 20 63 6f 6c  table.** and col
251a0 75 6d 6e 20 74 68 61 74 20 71 75 65 72 79 20 72  umn that query r
251b0 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 77 61 73  esult column was
251c0 20 65 78 74 72 61 63 74 65 64 20 66 72 6f 6d 2e   extracted from.
251d0 0a 2a 2a 0a 2a 2a 20 41 73 20 77 69 74 68 20 61  .**.** As with a
251e0 6c 6c 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20  ll other SQLite 
251f0 41 50 49 73 2c 20 74 68 6f 73 65 20 70 6f 73 74  APIs, those post
25200 66 69 78 65 64 20 77 69 74 68 20 22 31 36 22 20  fixed with "16" 
25210 72 65 74 75 72 6e 0a 2a 2a 20 55 54 46 2d 31 36  return.** UTF-16
25220 20 65 6e 63 6f 64 65 64 20 73 74 72 69 6e 67 73   encoded strings
25230 2c 20 74 68 65 20 6f 74 68 65 72 20 66 75 6e 63  , the other func
25240 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 55 54 46  tions return UTF
25250 2d 38 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20  -8. {END}.**.** 
25260 54 68 65 73 65 20 41 50 49 73 20 61 72 65 20 6f  These APIs are o
25270 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66  nly available if
25280 20 74 68 65 20 6c 69 62 72 61 72 79 20 77 61 73   the library was
25290 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74   compiled with t
252a0 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e  he.** [SQLITE_EN
252b0 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41  ABLE_COLUMN_META
252c0 44 41 54 41 5d 20 43 2d 70 72 65 70 72 6f 63 65  DATA] C-preproce
252d0 73 73 6f 72 20 73 79 6d 62 6f 6c 20 64 65 66 69  ssor symbol defi
252e0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 41 31 33 37  ned..**.** {A137
252f0 35 31 7d 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72  51}.** If two or
25300 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63 61   more threads ca
25310 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f  ll one or more o
25320 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
25330 20 61 67 61 69 6e 73 74 20 74 68 65 20 73 61 6d   against the sam
25340 65 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 73 74  e.** prepared st
25350 61 74 65 6d 65 6e 74 20 61 6e 64 20 63 6f 6c 75  atement and colu
25360 6d 6e 20 61 74 20 74 68 65 20 73 61 6d 65 20 74  mn at the same t
25370 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65 73  ime then the res
25380 75 6c 74 73 20 61 72 65 0a 2a 2a 20 75 6e 64 65  ults are.** unde
25390 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56  fined..**.** INV
253a0 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
253b0 48 31 33 37 34 31 7d 20 54 68 65 20 5b 73 71 6c  H13741} The [sql
253c0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61  ite3_column_data
253d0 62 61 73 65 5f 6e 61 6d 65 28 53 2c 4e 29 5d 20  base_name(S,N)] 
253e0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
253f0 73 20 65 69 74 68 65 72 0a 2a 2a 20 20 20 20 20  s either.**     
25400 20 20 20 20 20 74 68 65 20 55 54 46 2d 38 20 7a       the UTF-8 z
25410 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 6e  ero-terminated n
25420 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62  ame of the datab
25430 61 73 65 20 66 72 6f 6d 20 77 68 69 63 68 20 74  ase from which t
25440 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4e  he.**          N
25450 74 68 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  th result column
25460 20 6f 66 20 74 68 65 20 5b 70 72 65 70 61 72 65   of the [prepare
25470 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69  d statement] S i
25480 73 20 65 78 74 72 61 63 74 65 64 2c 0a 2a 2a 20  s extracted,.** 
25490 20 20 20 20 20 20 20 20 20 6f 72 20 4e 55 4c 4c           or NULL
254a0 20 69 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75   if the Nth colu
254b0 6d 6e 20 6f 66 20 53 20 69 73 20 61 20 67 65 6e  mn of S is a gen
254c0 65 72 61 6c 20 65 78 70 72 65 73 73 69 6f 6e 0a  eral expression.
254d0 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 69  **          or i
254e0 66 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f  f unable to allo
254f0 63 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20 73  cate memory to s
25500 74 6f 72 65 20 74 68 65 20 6e 61 6d 65 2e 0a 2a  tore the name..*
25510 2a 0a 2a 2a 20 7b 48 31 33 37 34 32 7d 20 54 68  *.** {H13742} Th
25520 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  e [sqlite3_colum
25530 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 31  n_database_name1
25540 36 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63  6(S,N)] interfac
25550 65 20 72 65 74 75 72 6e 73 20 65 69 74 68 65 72  e returns either
25560 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
25570 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62   UTF-16 native b
25580 79 74 65 20 6f 72 64 65 72 20 7a 65 72 6f 2d 74  yte order zero-t
25590 65 72 6d 69 6e 61 74 65 64 20 6e 61 6d 65 20 6f  erminated name o
255a0 66 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a  f the database.*
255b0 2a 20 20 20 20 20 20 20 20 20 20 66 72 6f 6d 20  *          from 
255c0 77 68 69 63 68 20 74 68 65 20 4e 74 68 20 72 65  which the Nth re
255d0 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74  sult column of t
255e0 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
255f0 74 65 6d 65 6e 74 5d 20 53 20 69 73 0a 2a 2a 20  tement] S is.** 
25600 20 20 20 20 20 20 20 20 20 65 78 74 72 61 63 74           extract
25610 65 64 2c 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74  ed, or NULL if t
25620 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66  he Nth column of
25630 20 53 20 69 73 20 61 20 67 65 6e 65 72 61 6c 20   S is a general 
25640 65 78 70 72 65 73 73 69 6f 6e 0a 2a 2a 20 20 20  expression.**   
25650 20 20 20 20 20 20 20 6f 72 20 69 66 20 75 6e 61         or if una
25660 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20  ble to allocate 
25670 6d 65 6d 6f 72 79 20 74 6f 20 73 74 6f 72 65 20  memory to store 
25680 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20  the name..**.** 
25690 7b 48 31 33 37 34 33 7d 20 54 68 65 20 5b 73 71  {H13743} The [sq
256a0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62  lite3_column_tab
256b0 6c 65 5f 6e 61 6d 65 28 53 2c 4e 29 5d 20 69 6e  le_name(S,N)] in
256c0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
256d0 65 69 74 68 65 72 0a 2a 2a 20 20 20 20 20 20 20  either.**       
256e0 20 20 20 74 68 65 20 55 54 46 2d 38 20 7a 65 72     the UTF-8 zer
256f0 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 6e 61 6d  o-terminated nam
25700 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20 66  e of the table f
25710 72 6f 6d 20 77 68 69 63 68 20 74 68 65 0a 2a 2a  rom which the.**
25720 20 20 20 20 20 20 20 20 20 20 4e 74 68 20 72 65            Nth re
25730 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74  sult column of t
25740 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
25750 74 65 6d 65 6e 74 5d 20 53 20 69 73 20 65 78 74  tement] S is ext
25760 72 61 63 74 65 64 2c 0a 2a 2a 20 20 20 20 20 20  racted,.**      
25770 20 20 20 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74      or NULL if t
25780 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66  he Nth column of
25790 20 53 20 69 73 20 61 20 67 65 6e 65 72 61 6c 20   S is a general 
257a0 65 78 70 72 65 73 73 69 6f 6e 0a 2a 2a 20 20 20  expression.**   
257b0 20 20 20 20 20 20 20 6f 72 20 69 66 20 75 6e 61         or if una
257c0 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20  ble to allocate 
257d0 6d 65 6d 6f 72 79 20 74 6f 20 73 74 6f 72 65 20  memory to store 
257e0 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20  the name..**.** 
257f0 7b 48 31 33 37 34 34 7d 20 54 68 65 20 5b 73 71  {H13744} The [sq
25800 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62  lite3_column_tab
25810 6c 65 5f 6e 61 6d 65 31 36 28 53 2c 4e 29 5d 20  le_name16(S,N)] 
25820 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
25830 73 20 65 69 74 68 65 72 0a 2a 2a 20 20 20 20 20  s either.**     
25840 20 20 20 20 20 74 68 65 20 55 54 46 2d 31 36 20       the UTF-16 
25850 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
25860 72 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  r zero-terminate
25870 64 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 74 61  d name of the ta
25880 62 6c 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ble.**          
25890 66 72 6f 6d 20 77 68 69 63 68 20 74 68 65 20 4e  from which the N
258a0 74 68 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  th result column
258b0 20 6f 66 20 74 68 65 20 5b 70 72 65 70 61 72 65   of the [prepare
258c0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69  d statement] S i
258d0 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 65 78  s.**          ex
258e0 74 72 61 63 74 65 64 2c 20 6f 72 20 4e 55 4c 4c  tracted, or NULL
258f0 20 69 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75   if the Nth colu
25900 6d 6e 20 6f 66 20 53 20 69 73 20 61 20 67 65 6e  mn of S is a gen
25910 65 72 61 6c 20 65 78 70 72 65 73 73 69 6f 6e 0a  eral expression.
25920 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 69  **          or i
25930 66 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f  f unable to allo
25940 63 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20 73  cate memory to s
25950 74 6f 72 65 20 74 68 65 20 6e 61 6d 65 2e 0a 2a  tore the name..*
25960 2a 0a 2a 2a 20 7b 48 31 33 37 34 35 7d 20 54 68  *.** {H13745} Th
25970 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  e [sqlite3_colum
25980 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 28 53 2c  n_origin_name(S,
25990 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  N)] interface re
259a0 74 75 72 6e 73 20 65 69 74 68 65 72 0a 2a 2a 20  turns either.** 
259b0 20 20 20 20 20 20 20 20 20 74 68 65 20 55 54 46           the UTF
259c0 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  -8 zero-terminat
259d0 65 64 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 74  ed name of the t
259e0 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 66 72 6f 6d  able column from
259f0 20 77 68 69 63 68 20 74 68 65 0a 2a 2a 20 20 20   which the.**   
25a00 20 20 20 20 20 20 20 4e 74 68 20 72 65 73 75 6c         Nth resul
25a10 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20  t column of the 
25a20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
25a30 65 6e 74 5d 20 53 20 69 73 20 65 78 74 72 61 63  ent] S is extrac
25a40 74 65 64 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  ted,.**         
25a50 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 65 20   or NULL if the 
25a60 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 53 20  Nth column of S 
25a70 69 73 20 61 20 67 65 6e 65 72 61 6c 20 65 78 70  is a general exp
25a80 72 65 73 73 69 6f 6e 0a 2a 2a 20 20 20 20 20 20  ression.**      
25a90 20 20 20 20 6f 72 20 69 66 20 75 6e 61 62 6c 65      or if unable
25aa0 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d   to allocate mem
25ab0 6f 72 79 20 74 6f 20 73 74 6f 72 65 20 74 68 65  ory to store the
25ac0 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31   name..**.** {H1
25ad0 33 37 34 36 7d 20 54 68 65 20 5b 73 71 6c 69 74  3746} The [sqlit
25ae0 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e  e3_column_origin
25af0 5f 6e 61 6d 65 31 36 28 53 2c 4e 29 5d 20 69 6e  _name16(S,N)] in
25b00 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
25b10 65 69 74 68 65 72 0a 2a 2a 20 20 20 20 20 20 20  either.**       
25b20 20 20 20 74 68 65 20 55 54 46 2d 31 36 20 6e 61     the UTF-16 na
25b30 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20  tive byte order 
25b40 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
25b50 6e 61 6d 65 20 6f 66 20 74 68 65 20 74 61 62 6c  name of the tabl
25b60 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f  e.**          co
25b70 6c 75 6d 6e 20 66 72 6f 6d 20 77 68 69 63 68 20  lumn from which 
25b80 74 68 65 20 4e 74 68 20 72 65 73 75 6c 74 20 63  the Nth result c
25b90 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 0a 2a 2a 20  olumn of the.** 
25ba0 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72           [prepar
25bb0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20  ed statement] S 
25bc0 69 73 20 65 78 74 72 61 63 74 65 64 2c 20 6f 72  is extracted, or
25bd0 20 4e 55 4c 4c 20 69 66 20 74 68 65 20 4e 74 68   NULL if the Nth
25be0 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 20 20 20 20 20   column.**      
25bf0 20 20 20 20 6f 66 20 53 20 69 73 20 61 20 67 65      of S is a ge
25c00 6e 65 72 61 6c 20 65 78 70 72 65 73 73 69 6f 6e  neral expression
25c10 20 6f 72 20 69 66 20 75 6e 61 62 6c 65 20 74 6f   or if unable to
25c20 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79   allocate memory
25c30 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20  .**          to 
25c40 73 74 6f 72 65 20 74 68 65 20 6e 61 6d 65 2e 0a  store the name..
25c50 2a 2a 0a 2a 2a 20 7b 48 31 33 37 34 38 7d 20 54  **.** {H13748} T
25c60 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 73  he return values
25c70 20 66 72 6f 6d 0a 2a 2a 20 20 20 20 20 20 20 20   from.**        
25c80 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d    [sqlite3_colum
25c90 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 20  n_database_name 
25ca0 7c 20 63 6f 6c 75 6d 6e 20 6d 65 74 61 64 61 74  | column metadat
25cb0 61 20 69 6e 74 65 72 66 61 63 65 73 5d 0a 2a 2a  a interfaces].**
25cc0 20 20 20 20 20 20 20 20 20 20 61 72 65 20 76 61            are va
25cd0 6c 69 64 20 66 6f 72 20 74 68 65 20 6c 69 66 65  lid for the life
25ce0 74 69 6d 65 20 6f 66 20 74 68 65 20 5b 70 72 65  time of the [pre
25cf0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
25d00 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20  .**          or 
25d10 75 6e 74 69 6c 20 74 68 65 20 65 6e 63 6f 64 69  until the encodi
25d20 6e 67 20 69 73 20 63 68 61 6e 67 65 64 20 62 79  ng is changed by
25d30 20 61 6e 6f 74 68 65 72 20 6d 65 74 61 64 61 74   another metadat
25d40 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e  a.**          in
25d50 74 65 72 66 61 63 65 20 63 61 6c 6c 20 66 6f 72  terface call for
25d60 20 74 68 65 20 73 61 6d 65 20 70 72 65 70 61 72   the same prepar
25d70 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64  ed statement and
25d80 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 41   column..**.** A
25d90 53 53 55 4d 50 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a  SSUMPTIONS:.**.*
25da0 2a 20 7b 41 31 33 37 35 31 7d 20 49 66 20 74 77  * {A13751} If tw
25db0 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64  o or more thread
25dc0 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f  s call one or mo
25dd0 72 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  re.**          [
25de0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
25df0 61 74 61 62 61 73 65 5f 6e 61 6d 65 20 7c 20 63  atabase_name | c
25e00 6f 6c 75 6d 6e 20 6d 65 74 61 64 61 74 61 20 69  olumn metadata i
25e10 6e 74 65 72 66 61 63 65 73 5d 0a 2a 2a 20 20 20  nterfaces].**   
25e20 20 20 20 20 20 20 20 66 6f 72 20 74 68 65 20 73         for the s
25e30 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  ame [prepared st
25e40 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20 72 65 73  atement] and res
25e50 75 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 20 20  ult column.**   
25e60 20 20 20 20 20 20 20 61 74 20 74 68 65 20 73 61         at the sa
25e70 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65  me time then the
25e80 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64   results are und
25e90 65 66 69 6e 65 64 2e 0a 2a 2f 0a 63 6f 6e 73 74  efined..*/.const
25ea0 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63   char *sqlite3_c
25eb0 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e  olumn_database_n
25ec0 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ame(sqlite3_stmt
25ed0 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f  *,int);.const vo
25ee0 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  id *sqlite3_colu
25ef0 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65  mn_database_name
25f00 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
25f10 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61  ,int);.const cha
25f20 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  r *sqlite3_colum
25f30 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 28 73 71 6c  n_table_name(sql
25f40 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
25f50 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
25f60 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c  ite3_column_tabl
25f70 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33  e_name16(sqlite3
25f80 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e  _stmt*,int);.con
25f90 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
25fa0 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e  _column_origin_n
25fb0 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ame(sqlite3_stmt
25fc0 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f  *,int);.const vo
25fd0 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  id *sqlite3_colu
25fe0 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 31 36  mn_origin_name16
25ff0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
26000 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  nt);../*.** CAPI
26010 33 52 45 46 3a 20 44 65 63 6c 61 72 65 64 20 44  3REF: Declared D
26020 61 74 61 74 79 70 65 20 4f 66 20 41 20 51 75 65  atatype Of A Que
26030 72 79 20 52 65 73 75 6c 74 20 7b 48 31 33 37 36  ry Result {H1376
26040 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 2a 0a 2a  0} <S10700>.**.*
26050 2a 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61  * The first para
26060 6d 65 74 65 72 20 69 73 20 61 20 5b 70 72 65 70  meter is a [prep
26070 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
26080 0a 2a 2a 20 49 66 20 74 68 69 73 20 73 74 61 74  .** If this stat
26090 65 6d 65 6e 74 20 69 73 20 61 20 5b 53 45 4c 45  ement is a [SELE
260a0 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 61 6e  CT] statement an
260b0 64 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e  d the Nth column
260c0 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65 74 75 72   of the.** retur
260d0 6e 65 64 20 72 65 73 75 6c 74 20 73 65 74 20 6f  ned result set o
260e0 66 20 74 68 61 74 20 5b 53 45 4c 45 43 54 5d 20  f that [SELECT] 
260f0 69 73 20 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d  is a table colum
26100 6e 20 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78 70  n (not an.** exp
26110 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75  ression or subqu
26120 65 72 79 29 20 74 68 65 6e 20 74 68 65 20 64 65  ery) then the de
26130 63 6c 61 72 65 64 20 74 79 70 65 20 6f 66 20 74  clared type of t
26140 68 65 20 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75  he table.** colu
26150 6d 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20  mn is returned. 
26160 20 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75   If the Nth colu
26170 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  mn of the result
26180 20 73 65 74 20 69 73 20 61 6e 0a 2a 2a 20 65 78   set is an.** ex
26190 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71  pression or subq
261a0 75 65 72 79 2c 20 74 68 65 6e 20 61 20 4e 55 4c  uery, then a NUL
261b0 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74  L pointer is ret
261c0 75 72 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 72 65  urned..** The re
261d0 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73  turned string is
261e0 20 61 6c 77 61 79 73 20 55 54 46 2d 38 20 65 6e   always UTF-8 en
261f0 63 6f 64 65 64 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a  coded. {END}.**.
26200 2a 2a 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20  ** For example, 
26210 67 69 76 65 6e 20 74 68 65 20 64 61 74 61 62 61  given the databa
26220 73 65 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a  se schema:.**.**
26230 20 43 52 45 41 54 45 20 54 41 42 4c 45 20 74 31   CREATE TABLE t1
26240 28 63 31 20 56 41 52 49 41 4e 54 29 3b 0a 2a 2a  (c1 VARIANT);.**
26250 0a 2a 2a 20 61 6e 64 20 74 68 65 20 66 6f 6c 6c  .** and the foll
26260 6f 77 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20  owing statement 
26270 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 3a 0a  to be compiled:.
26280 2a 2a 0a 2a 2a 20 53 45 4c 45 43 54 20 63 31 20  **.** SELECT c1 
26290 2b 20 31 2c 20 63 31 20 46 52 4f 4d 20 74 31 3b  + 1, c1 FROM t1;
262a0 0a 2a 2a 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74  .**.** this rout
262b0 69 6e 65 20 77 6f 75 6c 64 20 72 65 74 75 72 6e  ine would return
262c0 20 74 68 65 20 73 74 72 69 6e 67 20 22 56 41 52   the string "VAR
262d0 49 41 4e 54 22 20 66 6f 72 20 74 68 65 20 73 65  IANT" for the se
262e0 63 6f 6e 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63  cond result.** c
262f0 6f 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c 20 61 6e  olumn (i==1), an
26300 64 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  d a NULL pointer
26310 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 72   for the first r
26320 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 28 69 3d  esult column (i=
26330 3d 30 29 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  =0)..**.** SQLit
26340 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20 72  e uses dynamic r
26350 75 6e 2d 74 69 6d 65 20 74 79 70 69 6e 67 2e 20  un-time typing. 
26360 20 53 6f 20 6a 75 73 74 20 62 65 63 61 75 73 65   So just because
26370 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20   a column.** is 
26380 64 65 63 6c 61 72 65 64 20 74 6f 20 63 6f 6e 74  declared to cont
26390 61 69 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72  ain a particular
263a0 20 74 79 70 65 20 64 6f 65 73 20 6e 6f 74 20 6d   type does not m
263b0 65 61 6e 20 74 68 61 74 20 74 68 65 0a 2a 2a 20  ean that the.** 
263c0 64 61 74 61 20 73 74 6f 72 65 64 20 69 6e 20 74  data stored in t
263d0 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6f 66  hat column is of
263e0 20 74 68 65 20 64 65 63 6c 61 72 65 64 20 74 79   the declared ty
263f0 70 65 2e 20 20 53 51 4c 69 74 65 20 69 73 0a 2a  pe.  SQLite is.*
26400 2a 20 73 74 72 6f 6e 67 6c 79 20 74 79 70 65 64  * strongly typed
26410 2c 20 62 75 74 20 74 68 65 20 74 79 70 69 6e 67  , but the typing
26420 20 69 73 20 64 79 6e 61 6d 69 63 20 6e 6f 74 20   is dynamic not 
26430 73 74 61 74 69 63 2e 20 20 54 79 70 65 0a 2a 2a  static.  Type.**
26440 20 69 73 20 61 73 73 6f 63 69 61 74 65 64 20 77   is associated w
26450 69 74 68 20 69 6e 64 69 76 69 64 75 61 6c 20 76  ith individual v
26460 61 6c 75 65 73 2c 20 6e 6f 74 20 77 69 74 68 20  alues, not with 
26470 74 68 65 20 63 6f 6e 74 61 69 6e 65 72 73 0a 2a  the containers.*
26480 2a 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 74  * used to hold t
26490 68 6f 73 65 20 76 61 6c 75 65 73 2e 0a 2a 2a 0a  hose values..**.
264a0 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
264b0 2a 0a 2a 2a 20 7b 48 31 33 37 36 31 7d 20 20 41  *.** {H13761}  A
264c0 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c   successful call
264d0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c   to [sqlite3_col
264e0 75 6d 6e 5f 64 65 63 6c 74 79 70 65 28 53 2c 4e  umn_decltype(S,N
264f0 29 5d 20 72 65 74 75 72 6e 73 20 61 0a 2a 2a 20  )] returns a.** 
26500 20 20 20 20 20 20 20 20 20 20 7a 65 72 6f 2d 74            zero-t
26510 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20  erminated UTF-8 
26520 73 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e 69 6e  string containin
26530 67 20 74 68 65 20 64 65 63 6c 61 72 65 64 20 64  g the declared d
26540 61 74 61 74 79 70 65 0a 2a 2a 20 20 20 20 20 20  atatype.**      
26550 20 20 20 20 20 6f 66 20 74 68 65 20 74 61 62 6c       of the tabl
26560 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 61 70  e column that ap
26570 70 65 61 72 73 20 61 73 20 74 68 65 20 4e 74 68  pears as the Nth
26580 20 63 6f 6c 75 6d 6e 20 28 6e 75 6d 62 65 72 65   column (numbere
26590 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 66  d.**           f
265a0 72 6f 6d 20 30 29 20 6f 66 20 74 68 65 20 72 65  rom 0) of the re
265b0 73 75 6c 74 20 73 65 74 20 74 6f 20 74 68 65 20  sult set to the 
265c0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
265d0 65 6e 74 5d 20 53 2e 0a 2a 2a 0a 2a 2a 20 7b 48  ent] S..**.** {H
265e0 31 33 37 36 32 7d 20 20 41 20 73 75 63 63 65 73  13762}  A succes
265f0 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71  sful call to [sq
26600 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63  lite3_column_dec
26610 6c 74 79 70 65 31 36 28 53 2c 4e 29 5d 0a 2a 2a  ltype16(S,N)].**
26620 20 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72             retur
26630 6e 73 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  ns a zero-termin
26640 61 74 65 64 20 55 54 46 2d 31 36 20 6e 61 74 69  ated UTF-16 nati
26650 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 73 74  ve byte order st
26660 72 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20  ring.**         
26670 20 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65    containing the
26680 20 64 65 63 6c 61 72 65 64 20 64 61 74 61 74 79   declared dataty
26690 70 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20  pe of the table 
266a0 63 6f 6c 75 6d 6e 20 74 68 61 74 20 61 70 70 65  column that appe
266b0 61 72 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ars.**          
266c0 20 61 73 20 74 68 65 20 4e 74 68 20 63 6f 6c 75   as the Nth colu
266d0 6d 6e 20 28 6e 75 6d 62 65 72 65 64 20 66 72 6f  mn (numbered fro
266e0 6d 20 30 29 20 6f 66 20 74 68 65 20 72 65 73 75  m 0) of the resu
266f0 6c 74 20 73 65 74 20 74 6f 20 74 68 65 0a 2a 2a  lt set to the.**
26700 20 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70             [prep
26710 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
26720 53 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 36 33  S..**.** {H13763
26730 7d 20 20 49 66 20 4e 20 69 73 20 6c 65 73 73 20  }  If N is less 
26740 74 68 61 6e 20 30 20 6f 72 20 4e 20 69 73 20 67  than 0 or N is g
26750 72 65 61 74 65 72 20 74 68 61 6e 20 6f 72 20 65  reater than or e
26760 71 75 61 6c 20 74 6f 0a 2a 2a 20 20 20 20 20 20  qual to.**      
26770 20 20 20 20 20 74 68 65 20 6e 75 6d 62 65 72 20       the number 
26780 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68  of columns in th
26790 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
267a0 65 6d 65 6e 74 5d 20 53 2c 0a 2a 2a 20 20 20 20  ement] S,.**    
267b0 20 20 20 20 20 20 20 6f 72 20 69 66 20 74 68 65         or if the
267c0 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 53   Nth column of S
267d0 20 69 73 20 61 6e 20 65 78 70 72 65 73 73 69 6f   is an expressio
267e0 6e 20 6f 72 20 73 75 62 71 75 65 72 79 20 72 61  n or subquery ra
267f0 74 68 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  ther.**         
26800 20 20 74 68 61 6e 20 61 20 74 61 62 6c 65 20 63    than a table c
26810 6f 6c 75 6d 6e 2c 20 6f 72 20 69 66 20 61 20 6d  olumn, or if a m
26820 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
26830 20 66 61 69 6c 75 72 65 0a 2a 2a 20 20 20 20 20   failure.**     
26840 20 20 20 20 20 20 6f 63 63 75 72 73 20 64 75 72        occurs dur
26850 69 6e 67 20 65 6e 63 6f 64 69 6e 67 20 63 6f 6e  ing encoding con
26860 76 65 72 73 69 6f 6e 73 2c 20 74 68 65 6e 0a 2a  versions, then.*
26870 2a 20 20 20 20 20 20 20 20 20 20 20 63 61 6c 6c  *           call
26880 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f  s to [sqlite3_co
26890 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 28 53 2c  lumn_decltype(S,
268a0 4e 29 5d 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20  N)] or.**       
268b0 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c      [sqlite3_col
268c0 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31 36 28 53  umn_decltype16(S
268d0 2c 4e 29 5d 20 72 65 74 75 72 6e 20 4e 55 4c 4c  ,N)] return NULL
268e0 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20  ..*/.const char 
268f0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
26900 64 65 63 6c 74 79 70 65 28 73 71 6c 69 74 65 33  decltype(sqlite3
26910 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e  _stmt*,int);.con
26920 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
26930 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65  _column_decltype
26940 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
26950 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ,int);../*.** CA
26960 50 49 33 52 45 46 3a 20 45 76 61 6c 75 61 74 65  PI3REF: Evaluate
26970 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e   An SQL Statemen
26980 74 20 7b 48 31 33 32 30 30 7d 20 3c 53 31 30 30  t {H13200} <S100
26990 30 30 3e 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20  00>.**.** After 
269a0 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
269b0 65 6d 65 6e 74 5d 20 68 61 73 20 62 65 65 6e 20  ement] has been 
269c0 70 72 65 70 61 72 65 64 20 75 73 69 6e 67 20 65  prepared using e
269d0 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  ither.** [sqlite
269e0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
269f0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  or [sqlite3_prep
26a00 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 6f  are16_v2()] or o
26a10 6e 65 20 6f 66 20 74 68 65 20 6c 65 67 61 63 79  ne of the legacy
26a20 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 5b  .** interfaces [
26a30 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
26a40 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70  )] or [sqlite3_p
26a50 72 65 70 61 72 65 31 36 28 29 5d 2c 20 74 68 69  repare16()], thi
26a60 73 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6d 75  s function.** mu
26a70 73 74 20 62 65 20 63 61 6c 6c 65 64 20 6f 6e 65  st be called one
26a80 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 20 74   or more times t
26a90 6f 20 65 76 61 6c 75 61 74 65 20 74 68 65 20 73  o evaluate the s
26aa0 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  tatement..**.** 
26ab0 54 68 65 20 64 65 74 61 69 6c 73 20 6f 66 20 74  The details of t
26ac0 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 74  he behavior of t
26ad0 68 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  he sqlite3_step(
26ae0 29 20 69 6e 74 65 72 66 61 63 65 20 64 65 70 65  ) interface depe
26af0 6e 64 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65 72  nd.** on whether
26b00 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77   the statement w
26b10 61 73 20 70 72 65 70 61 72 65 64 20 75 73 69 6e  as prepared usin
26b20 67 20 74 68 65 20 6e 65 77 65 72 20 22 76 32 22  g the newer "v2"
26b30 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 5b 73   interface.** [s
26b40 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
26b50 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  2()] and [sqlite
26b60 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
26b70 5d 20 6f 72 20 74 68 65 20 6f 6c 64 65 72 20 6c  ] or the older l
26b80 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61  egacy.** interfa
26b90 63 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ce [sqlite3_prep
26ba0 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  are()] and [sqli
26bb0 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d  te3_prepare16()]
26bc0 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20 74 68  .  The use of th
26bd0 65 0a 2a 2a 20 6e 65 77 20 22 76 32 22 20 69 6e  e.** new "v2" in
26be0 74 65 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d  terface is recom
26bf0 6d 65 6e 64 65 64 20 66 6f 72 20 6e 65 77 20 61  mended for new a
26c00 70 70 6c 69 63 61 74 69 6f 6e 73 20 62 75 74 20  pplications but 
26c10 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e  the legacy.** in
26c20 74 65 72 66 61 63 65 20 77 69 6c 6c 20 63 6f 6e  terface will con
26c30 74 69 6e 75 65 20 74 6f 20 62 65 20 73 75 70 70  tinue to be supp
26c40 6f 72 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20  orted..**.** In 
26c50 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72  the legacy inter
26c60 66 61 63 65 2c 20 74 68 65 20 72 65 74 75 72 6e  face, the return
26c70 20 76 61 6c 75 65 20 77 69 6c 6c 20 62 65 20 65   value will be e
26c80 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 42 55  ither [SQLITE_BU
26c90 53 59 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  SY],.** [SQLITE_
26ca0 44 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 52  DONE], [SQLITE_R
26cb0 4f 57 5d 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52  OW], [SQLITE_ERR
26cc0 4f 52 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  OR], or [SQLITE_
26cd0 4d 49 53 55 53 45 5d 2e 0a 2a 2a 20 57 69 74 68  MISUSE]..** With
26ce0 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66   the "v2" interf
26cf0 61 63 65 2c 20 61 6e 79 20 6f 66 20 74 68 65 20  ace, any of the 
26d00 6f 74 68 65 72 20 5b 72 65 73 75 6c 74 20 63 6f  other [result co
26d10 64 65 73 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65  des] or.** [exte
26d20 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
26d30 73 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74 75  s] might be retu
26d40 72 6e 65 64 20 61 73 20 77 65 6c 6c 2e 0a 2a 2a  rned as well..**
26d50 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  .** [SQLITE_BUSY
26d60 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  ] means that the
26d70 20 64 61 74 61 62 61 73 65 20 65 6e 67 69 6e 65   database engine
26d80 20 77 61 73 20 75 6e 61 62 6c 65 20 74 6f 20 61   was unable to a
26d90 63 71 75 69 72 65 20 74 68 65 0a 2a 2a 20 64 61  cquire the.** da
26da0 74 61 62 61 73 65 20 6c 6f 63 6b 73 20 69 74 20  tabase locks it 
26db0 6e 65 65 64 73 20 74 6f 20 64 6f 20 69 74 73 20  needs to do its 
26dc0 6a 6f 62 2e 20 20 49 66 20 74 68 65 20 73 74 61  job.  If the sta
26dd0 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 43 4f 4d  tement is a [COM
26de0 4d 49 54 5d 0a 2a 2a 20 6f 72 20 6f 63 63 75 72  MIT].** or occur
26df0 73 20 6f 75 74 73 69 64 65 20 6f 66 20 61 6e 20  s outside of an 
26e00 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63  explicit transac
26e10 74 69 6f 6e 2c 20 74 68 65 6e 20 79 6f 75 20 63  tion, then you c
26e20 61 6e 20 72 65 74 72 79 20 74 68 65 0a 2a 2a 20  an retry the.** 
26e30 73 74 61 74 65 6d 65 6e 74 2e 20 20 49 66 20 74  statement.  If t
26e40 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  he statement is 
26e50 6e 6f 74 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 61  not a [COMMIT] a
26e60 6e 64 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e  nd occurs within
26e70 20 61 0a 2a 2a 20 65 78 70 6c 69 63 69 74 20 74   a.** explicit t
26e80 72 61 6e 73 61 63 74 69 6f 6e 20 74 68 65 6e 20  ransaction then 
26e90 79 6f 75 20 73 68 6f 75 6c 64 20 72 6f 6c 6c 62  you should rollb
26ea0 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61 63 74  ack the transact
26eb0 69 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a 20 63 6f  ion before.** co
26ec0 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  ntinuing..**.** 
26ed0 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 20 6d 65  [SQLITE_DONE] me
26ee0 61 6e 73 20 74 68 61 74 20 74 68 65 20 73 74 61  ans that the sta
26ef0 74 65 6d 65 6e 74 20 68 61 73 20 66 69 6e 69 73  tement has finis
26f00 68 65 64 20 65 78 65 63 75 74 69 6e 67 0a 2a 2a  hed executing.**
26f10 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2e 20 20   successfully.  
26f20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73  sqlite3_step() s
26f30 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c  hould not be cal
26f40 6c 65 64 20 61 67 61 69 6e 20 6f 6e 20 74 68 69  led again on thi
26f50 73 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63  s virtual.** mac
26f60 68 69 6e 65 20 77 69 74 68 6f 75 74 20 66 69 72  hine without fir
26f70 73 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  st calling [sqli
26f80 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74 6f 20  te3_reset()] to 
26f90 72 65 73 65 74 20 74 68 65 20 76 69 72 74 75 61  reset the virtua
26fa0 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 62 61 63  l.** machine bac
26fb0 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61 6c  k to its initial
26fc0 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 49 66   state..**.** If
26fd0 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
26fe0 6e 74 20 62 65 69 6e 67 20 65 78 65 63 75 74 65  nt being execute
26ff0 64 20 72 65 74 75 72 6e 73 20 61 6e 79 20 64 61  d returns any da
27000 74 61 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45  ta, then [SQLITE
27010 5f 52 4f 57 5d 0a 2a 2a 20 69 73 20 72 65 74 75  _ROW].** is retu
27020 72 6e 65 64 20 65 61 63 68 20 74 69 6d 65 20 61  rned each time a
27030 20 6e 65 77 20 72 6f 77 20 6f 66 20 64 61 74 61   new row of data
27040 20 69 73 20 72 65 61 64 79 20 66 6f 72 20 70 72   is ready for pr
27050 6f 63 65 73 73 69 6e 67 20 62 79 20 74 68 65 0a  ocessing by the.
27060 2a 2a 20 63 61 6c 6c 65 72 2e 20 54 68 65 20 76  ** caller. The v
27070 61 6c 75 65 73 20 6d 61 79 20 62 65 20 61 63 63  alues may be acc
27080 65 73 73 65 64 20 75 73 69 6e 67 20 74 68 65 20  essed using the 
27090 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66  [column access f
270a0 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 73 71  unctions]..** sq
270b0 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 73 20  lite3_step() is 
270c0 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 74 6f 20  called again to 
270d0 72 65 74 72 69 65 76 65 20 74 68 65 20 6e 65 78  retrieve the nex
270e0 74 20 72 6f 77 20 6f 66 20 64 61 74 61 2e 0a 2a  t row of data..*
270f0 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52  *.** [SQLITE_ERR
27100 4f 52 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 61  OR] means that a
27110 20 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72 20   run-time error 
27120 28 73 75 63 68 20 61 73 20 61 20 63 6f 6e 73 74  (such as a const
27130 72 61 69 6e 74 0a 2a 2a 20 76 69 6f 6c 61 74 69  raint.** violati
27140 6f 6e 29 20 68 61 73 20 6f 63 63 75 72 72 65 64  on) has occurred
27150 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  .  sqlite3_step(
27160 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20  ) should not be 
27170 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 0a  called again on.
27180 2a 2a 20 74 68 65 20 56 4d 2e 20 4d 6f 72 65 20  ** the VM. More 
27190 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6d 61 79 20  information may 
271a0 62 65 20 66 6f 75 6e 64 20 62 79 20 63 61 6c 6c  be found by call
271b0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 72 72  ing [sqlite3_err
271c0 6d 73 67 28 29 5d 2e 0a 2a 2a 20 57 69 74 68 20  msg()]..** With 
271d0 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72  the legacy inter
271e0 66 61 63 65 2c 20 61 20 6d 6f 72 65 20 73 70 65  face, a more spe
271f0 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64 65  cific error code
27200 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a   (for example,.*
27210 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52  * [SQLITE_INTERR
27220 55 50 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 53 43  UPT], [SQLITE_SC
27230 48 45 4d 41 5d 2c 20 5b 53 51 4c 49 54 45 5f 43  HEMA], [SQLITE_C
27240 4f 52 52 55 50 54 5d 2c 20 61 6e 64 20 73 6f 20  ORRUPT], and so 
27250 66 6f 72 74 68 29 0a 2a 2a 20 63 61 6e 20 62 65  forth).** can be
27260 20 6f 62 74 61 69 6e 65 64 20 62 79 20 63 61 6c   obtained by cal
27270 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65  ling [sqlite3_re
27280 73 65 74 28 29 5d 20 6f 6e 20 74 68 65 0a 2a 2a  set()] on the.**
27290 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
272a0 6d 65 6e 74 5d 2e 20 20 49 6e 20 74 68 65 20 22  ment].  In the "
272b0 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c 0a 2a  v2" interface,.*
272c0 2a 20 74 68 65 20 6d 6f 72 65 20 73 70 65 63 69  * the more speci
272d0 66 69 63 20 65 72 72 6f 72 20 63 6f 64 65 20 69  fic error code i
272e0 73 20 72 65 74 75 72 6e 65 64 20 64 69 72 65 63  s returned direc
272f0 74 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f 73  tly by sqlite3_s
27300 74 65 70 28 29 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51  tep()..**.** [SQ
27310 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 6d 65 61  LITE_MISUSE] mea
27320 6e 73 20 74 68 61 74 20 74 68 65 20 74 68 69 73  ns that the this
27330 20 72 6f 75 74 69 6e 65 20 77 61 73 20 63 61 6c   routine was cal
27340 6c 65 64 20 69 6e 61 70 70 72 6f 70 72 69 61 74  led inappropriat
27350 65 6c 79 2e 0a 2a 2a 20 50 65 72 68 61 70 73 20  ely..** Perhaps 
27360 69 74 20 77 61 73 20 63 61 6c 6c 65 64 20 6f 6e  it was called on
27370 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
27380 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 68 61 73  tement] that has
27390 0a 2a 2a 20 61 6c 72 65 61 64 79 20 62 65 65 6e  .** already been
273a0 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
273b0 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65 64 5d 20  ze | finalized] 
273c0 6f 72 20 6f 6e 20 6f 6e 65 20 74 68 61 74 20 68  or on one that h
273d0 61 64 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79  ad.** previously
273e0 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54   returned [SQLIT
273f0 45 5f 45 52 52 4f 52 5d 20 6f 72 20 5b 53 51 4c  E_ERROR] or [SQL
27400 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 4f 72 20 69  ITE_DONE].  Or i
27410 74 20 63 6f 75 6c 64 0a 2a 2a 20 62 65 20 74 68  t could.** be th
27420 65 20 63 61 73 65 20 74 68 61 74 20 74 68 65 20  e case that the 
27430 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f  same database co
27440 6e 6e 65 63 74 69 6f 6e 20 69 73 20 62 65 69 6e  nnection is bein
27450 67 20 75 73 65 64 20 62 79 20 74 77 6f 20 6f 72  g used by two or
27460 0a 2a 2a 20 6d 6f 72 65 20 74 68 72 65 61 64 73  .** more threads
27470 20 61 74 20 74 68 65 20 73 61 6d 65 20 6d 6f 6d   at the same mom
27480 65 6e 74 20 69 6e 20 74 69 6d 65 2e 0a 2a 2a 0a  ent in time..**.
27490 2a 2a 20 3c 62 3e 47 6f 6f 66 79 20 49 6e 74 65  ** <b>Goofy Inte
274a0 72 66 61 63 65 20 41 6c 65 72 74 3a 3c 2f 62 3e  rface Alert:</b>
274b0 20 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20 69   In the legacy i
274c0 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20 73 71  nterface, the sq
274d0 6c 69 74 65 33 5f 73 74 65 70 28 29 0a 2a 2a 20  lite3_step().** 
274e0 41 50 49 20 61 6c 77 61 79 73 20 72 65 74 75 72  API always retur
274f0 6e 73 20 61 20 67 65 6e 65 72 69 63 20 65 72 72  ns a generic err
27500 6f 72 20 63 6f 64 65 2c 20 5b 53 51 4c 49 54 45  or code, [SQLITE
27510 5f 45 52 52 4f 52 5d 2c 20 66 6f 6c 6c 6f 77 69  _ERROR], followi
27520 6e 67 20 61 6e 79 0a 2a 2a 20 65 72 72 6f 72 20  ng any.** error 
27530 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49  other than [SQLI
27540 54 45 5f 42 55 53 59 5d 20 61 6e 64 20 5b 53 51  TE_BUSY] and [SQ
27550 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 59  LITE_MISUSE].  Y
27560 6f 75 20 6d 75 73 74 20 63 61 6c 6c 0a 2a 2a 20  ou must call.** 
27570 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
27580 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69  ] or [sqlite3_fi
27590 6e 61 6c 69 7a 65 28 29 5d 20 69 6e 20 6f 72 64  nalize()] in ord
275a0 65 72 20 74 6f 20 66 69 6e 64 20 6f 6e 65 20 6f  er to find one o
275b0 66 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 69  f the.** specifi
275c0 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20  c [error codes] 
275d0 74 68 61 74 20 62 65 74 74 65 72 20 64 65 73 63  that better desc
275e0 72 69 62 65 73 20 74 68 65 20 65 72 72 6f 72 2e  ribes the error.
275f0 0a 2a 2a 20 57 65 20 61 64 6d 69 74 20 74 68 61  .** We admit tha
27600 74 20 74 68 69 73 20 69 73 20 61 20 67 6f 6f 66  t this is a goof
27610 79 20 64 65 73 69 67 6e 2e 20 20 54 68 65 20 70  y design.  The p
27620 72 6f 62 6c 65 6d 20 68 61 73 20 62 65 65 6e 20  roblem has been 
27630 66 69 78 65 64 0a 2a 2a 20 77 69 74 68 20 74 68  fixed.** with th
27640 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65  e "v2" interface
27650 2e 20 20 49 66 20 79 6f 75 20 70 72 65 70 61 72  .  If you prepar
27660 65 20 61 6c 6c 20 6f 66 20 79 6f 75 72 20 53 51  e all of your SQ
27670 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20  L statements.** 
27680 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73 71  using either [sq
27690 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
276a0 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
276b0 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20  prepare16_v2()] 
276c0 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 74 68  instead.** of th
276d0 65 20 6c 65 67 61 63 79 20 5b 73 71 6c 69 74 65  e legacy [sqlite
276e0 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e 64  3_prepare()] and
276f0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
27700 65 31 36 28 29 5d 20 69 6e 74 65 72 66 61 63 65  e16()] interface
27710 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 6d  s,.** then the m
27720 6f 72 65 20 73 70 65 63 69 66 69 63 20 5b 65 72  ore specific [er
27730 72 6f 72 20 63 6f 64 65 73 5d 20 61 72 65 20 72  ror codes] are r
27740 65 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79  eturned directly
27750 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 73  .** by sqlite3_s
27760 74 65 70 28 29 2e 20 20 54 68 65 20 75 73 65 20  tep().  The use 
27770 6f 66 20 74 68 65 20 22 76 32 22 20 69 6e 74 65  of the "v2" inte
27780 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65  rface is recomme
27790 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  nded..**.** INVA
277a0 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48  RIANTS:.**.** {H
277b0 31 33 32 30 32 7d 20 20 49 66 20 74 68 65 20 5b  13202}  If the [
277c0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
277d0 6e 74 5d 20 53 20 69 73 20 72 65 61 64 79 20 74  nt] S is ready t
277e0 6f 20 62 65 20 72 75 6e 2c 20 74 68 65 6e 0a 2a  o be run, then.*
277f0 2a 20 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  *           [sql
27800 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 61 64  ite3_step(S)] ad
27810 76 61 6e 63 65 73 20 74 68 61 74 20 70 72 65 70  vances that prep
27820 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 75  ared statement u
27830 6e 74 69 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20  ntil.**         
27840 20 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 6f 72 20    completion or 
27850 75 6e 74 69 6c 20 69 74 20 69 73 20 72 65 61 64  until it is read
27860 79 20 74 6f 20 72 65 74 75 72 6e 20 61 6e 6f 74  y to return anot
27870 68 65 72 20 72 6f 77 20 6f 66 20 74 68 65 0a 2a  her row of the.*
27880 2a 20 20 20 20 20 20 20 20 20 20 20 72 65 73 75  *           resu
27890 6c 74 20 73 65 74 2c 20 6f 72 20 75 6e 74 69 6c  lt set, or until
278a0 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74   an [sqlite3_int
278b0 65 72 72 75 70 74 20 7c 20 69 6e 74 65 72 72 75  errupt | interru
278c0 70 74 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  pt].**          
278d0 20 6f 72 20 61 20 72 75 6e 2d 74 69 6d 65 20 65   or a run-time e
278e0 72 72 6f 72 20 6f 63 63 75 72 73 2e 0a 2a 2a 0a  rror occurs..**.
278f0 2a 2a 20 7b 48 31 35 33 30 34 7d 20 20 57 68 65  ** {H15304}  Whe
27900 6e 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  n a call to [sql
27910 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 63 61  ite3_step(S)] ca
27920 75 73 65 73 20 74 68 65 20 5b 70 72 65 70 61 72  uses the [prepar
27930 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a  ed statement].**
27940 20 20 20 20 20 20 20 20 20 20 20 53 20 74 6f 20             S to 
27950 72 75 6e 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f  run to completio
27960 6e 2c 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  n, the function 
27970 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
27980 44 4f 4e 45 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  DONE]..**.** {H1
27990 35 33 30 36 7d 20 20 57 68 65 6e 20 61 20 63 61  5306}  When a ca
279a0 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73  ll to [sqlite3_s
279b0 74 65 70 28 53 29 5d 20 73 74 6f 70 73 20 62 65  tep(S)] stops be
279c0 63 61 75 73 65 20 69 74 20 69 73 20 72 65 61 64  cause it is read
279d0 79 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20  y to.**         
279e0 20 20 72 65 74 75 72 6e 20 61 6e 6f 74 68 65 72    return another
279f0 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75   row of the resu
27a00 6c 74 20 73 65 74 2c 20 69 74 20 72 65 74 75 72  lt set, it retur
27a10 6e 73 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2e  ns [SQLITE_ROW].
27a20 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 33 30 38 7d 20  .**.** {H15308} 
27a30 20 49 66 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73   If a call to [s
27a40 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20  qlite3_step(S)] 
27a50 65 6e 63 6f 75 6e 74 65 72 73 20 61 6e 0a 2a 2a  encounters an.**
27a60 20 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69             [sqli
27a70 74 65 33 5f 69 6e 74 65 72 72 75 70 74 20 7c 20  te3_interrupt | 
27a80 69 6e 74 65 72 72 75 70 74 5d 20 6f 72 20 61 20  interrupt] or a 
27a90 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72 2c 0a  run-time error,.
27aa0 2a 2a 20 20 20 20 20 20 20 20 20 20 20 69 74 20  **           it 
27ab0 72 65 74 75 72 6e 73 20 61 6e 20 61 70 70 72 6f  returns an appro
27ac0 70 72 69 61 74 65 20 65 72 72 6f 72 20 63 6f 64  priate error cod
27ad0 65 20 74 68 61 74 20 69 73 20 6e 6f 74 20 6f 6e  e that is not on
27ae0 65 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20  e of.**         
27af0 20 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 5b    [SQLITE_OK], [
27b00 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 6f 72 20  SQLITE_ROW], or 
27b10 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 0a 2a  [SQLITE_DONE]..*
27b20 2a 0a 2a 2a 20 7b 48 31 35 33 31 30 7d 20 20 49  *.** {H15310}  I
27b30 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6e  f an [sqlite3_in
27b40 74 65 72 72 75 70 74 20 7c 20 69 6e 74 65 72 72  terrupt | interr
27b50 75 70 74 5d 20 6f 72 20 61 20 72 75 6e 2d 74 69  upt] or a run-ti
27b60 6d 65 20 65 72 72 6f 72 0a 2a 2a 20 20 20 20 20  me error.**     
27b70 20 20 20 20 20 20 6f 63 63 75 72 73 20 64 75 72        occurs dur
27b80 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73  ing a call to [s
27b90 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 0a  qlite3_step(S)].
27ba0 2a 2a 20 20 20 20 20 20 20 20 20 20 20 66 6f 72  **           for
27bb0 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
27bc0 74 65 6d 65 6e 74 5d 20 53 20 63 72 65 61 74 65  tement] S create
27bd0 64 20 75 73 69 6e 67 0a 2a 2a 20 20 20 20 20 20  d using.**      
27be0 20 20 20 20 20 6c 65 67 61 63 79 20 69 6e 74 65       legacy inte
27bf0 72 66 61 63 65 73 20 5b 73 71 6c 69 74 65 33 5f  rfaces [sqlite3_
27c00 70 72 65 70 61 72 65 28 29 5d 20 6f 72 0a 2a 2a  prepare()] or.**
27c10 20 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69             [sqli
27c20 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d  te3_prepare16()]
27c30 2c 20 74 68 65 6e 20 74 68 65 20 66 75 6e 63 74  , then the funct
27c40 69 6f 6e 20 72 65 74 75 72 6e 73 20 65 69 74 68  ion returns eith
27c50 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  er.**           
27c60 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20  [SQLITE_ERROR], 
27c70 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c 20 6f  [SQLITE_BUSY], o
27c80 72 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  r [SQLITE_MISUSE
27c90 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  ]..*/.int sqlite
27ca0 33 5f 73 74 65 70 28 73 71 6c 69 74 65 33 5f 73  3_step(sqlite3_s
27cb0 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  tmt*);../*.** CA
27cc0 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 6f  PI3REF: Number o
27cd0 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 72  f columns in a r
27ce0 65 73 75 6c 74 20 73 65 74 20 7b 48 31 33 37 37  esult set {H1377
27cf0 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 2a 0a 2a  0} <S10700>.**.*
27d00 2a 20 52 65 74 75 72 6e 73 20 74 68 65 20 6e 75  * Returns the nu
27d10 6d 62 65 72 20 6f 66 20 76 61 6c 75 65 73 20 69  mber of values i
27d20 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 72 6f  n the current ro
27d30 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  w of the result 
27d40 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  set..**.** INVAR
27d50 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31  IANTS:.**.** {H1
27d60 33 37 37 31 7d 20 20 41 66 74 65 72 20 61 20 63  3771}  After a c
27d70 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
27d80 73 74 65 70 28 53 29 5d 20 74 68 61 74 20 72 65  step(S)] that re
27d90 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 52 4f  turns [SQLITE_RO
27da0 57 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  W],.**          
27db0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 61   the [sqlite3_da
27dc0 74 61 5f 63 6f 75 6e 74 28 53 29 5d 20 72 6f 75  ta_count(S)] rou
27dd0 74 69 6e 65 20 77 69 6c 6c 20 72 65 74 75 72 6e  tine will return
27de0 20 74 68 65 20 73 61 6d 65 20 76 61 6c 75 65 0a   the same value.
27df0 2a 2a 20 20 20 20 20 20 20 20 20 20 20 61 73 20  **           as 
27e00 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  the [sqlite3_col
27e10 75 6d 6e 5f 63 6f 75 6e 74 28 53 29 5d 20 66 75  umn_count(S)] fu
27e20 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 48  nction..**.** {H
27e30 31 33 37 37 32 7d 20 20 41 66 74 65 72 20 5b 73  13772}  After [s
27e40 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20  qlite3_step(S)] 
27e50 68 61 73 20 72 65 74 75 72 6e 65 64 20 61 6e 79  has returned any
27e60 20 76 61 6c 75 65 20 6f 74 68 65 72 20 74 68 61   value other tha
27e70 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 5b  n.**           [
27e80 53 51 4c 49 54 45 5f 52 4f 57 5d 20 6f 72 20 62  SQLITE_ROW] or b
27e90 65 66 6f 72 65 20 5b 73 71 6c 69 74 65 33 5f 73  efore [sqlite3_s
27ea0 74 65 70 28 53 29 5d 20 68 61 73 20 62 65 65 6e  tep(S)] has been
27eb0 20 63 61 6c 6c 65 64 20 6f 6e 20 74 68 65 0a 2a   called on the.*
27ec0 2a 20 20 20 20 20 20 20 20 20 20 20 5b 70 72 65  *           [pre
27ed0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
27ee0 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 74   for the first t
27ef0 69 6d 65 20 73 69 6e 63 65 20 69 74 20 77 61 73  ime since it was
27f00 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 5b 73  .**           [s
27f10 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c  qlite3_prepare |
27f20 20 70 72 65 70 61 72 65 64 5d 20 6f 72 20 5b 73   prepared] or [s
27f30 71 6c 69 74 65 33 5f 72 65 73 65 74 20 7c 20 72  qlite3_reset | r
27f40 65 73 65 74 5d 2c 0a 2a 2a 20 20 20 20 20 20 20  eset],.**       
27f50 20 20 20 20 74 68 65 20 5b 73 71 6c 69 74 65 33      the [sqlite3
27f60 5f 64 61 74 61 5f 63 6f 75 6e 74 28 53 29 5d 20  _data_count(S)] 
27f70 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
27f80 7a 65 72 6f 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  zero..*/.int sql
27f90 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28  ite3_data_count(
27fa0 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
27fb0 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
27fc0 49 33 52 45 46 3a 20 46 75 6e 64 61 6d 65 6e 74  I3REF: Fundament
27fd0 61 6c 20 44 61 74 61 74 79 70 65 73 20 7b 48 31  al Datatypes {H1
27fe0 30 32 36 35 7d 20 3c 53 31 30 31 31 30 3e 3c 53  0265} <S10110><S
27ff0 31 30 31 32 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52  10120>.** KEYWOR
28000 44 53 3a 20 53 51 4c 49 54 45 5f 54 45 58 54 0a  DS: SQLITE_TEXT.
28010 2a 2a 0a 2a 2a 20 7b 48 31 30 32 36 36 7d 20 45  **.** {H10266} E
28020 76 65 72 79 20 76 61 6c 75 65 20 69 6e 20 53 51  very value in SQ
28030 4c 69 74 65 20 68 61 73 20 6f 6e 65 20 6f 66 20  Lite has one of 
28040 66 69 76 65 20 66 75 6e 64 61 6d 65 6e 74 61 6c  five fundamental
28050 20 64 61 74 61 74 79 70 65 73 3a 0a 2a 2a 0a 2a   datatypes:.**.*
28060 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 36  * <ul>.** <li> 6
28070 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74  4-bit signed int
28080 65 67 65 72 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d  eger.** <li> 64-
28090 62 69 74 20 49 45 45 45 20 66 6c 6f 61 74 69 6e  bit IEEE floatin
280a0 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 0a 2a  g point number.*
280b0 2a 20 3c 6c 69 3e 20 73 74 72 69 6e 67 0a 2a 2a  * <li> string.**
280c0 20 3c 6c 69 3e 20 42 4c 4f 42 0a 2a 2a 20 3c 6c   <li> BLOB.** <l
280d0 69 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e  i> NULL.** </ul>
280e0 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 65   {END}.**.** The
280f0 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65  se constants are
28100 20 63 6f 64 65 73 20 66 6f 72 20 65 61 63 68 20   codes for each 
28110 6f 66 20 74 68 6f 73 65 20 74 79 70 65 73 2e 0a  of those types..
28120 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  **.** Note that 
28130 74 68 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20  the SQLITE_TEXT 
28140 63 6f 6e 73 74 61 6e 74 20 77 61 73 20 61 6c 73  constant was als
28150 6f 20 75 73 65 64 20 69 6e 20 53 51 4c 69 74 65  o used in SQLite
28160 20 76 65 72 73 69 6f 6e 20 32 0a 2a 2a 20 66 6f   version 2.** fo
28170 72 20 61 20 63 6f 6d 70 6c 65 74 65 6c 79 20 64  r a completely d
28180 69 66 66 65 72 65 6e 74 20 6d 65 61 6e 69 6e 67  ifferent meaning
28190 2e 20 20 53 6f 66 74 77 61 72 65 20 74 68 61 74  .  Software that
281a0 20 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74 20 62   links against b
281b0 6f 74 68 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65  oth.** SQLite ve
281c0 72 73 69 6f 6e 20 32 20 61 6e 64 20 53 51 4c 69  rsion 2 and SQLi
281d0 74 65 20 76 65 72 73 69 6f 6e 20 33 20 73 68 6f  te version 3 sho
281e0 75 6c 64 20 75 73 65 20 53 51 4c 49 54 45 33 5f  uld use SQLITE3_
281f0 54 45 58 54 2c 20 6e 6f 74 0a 2a 2a 20 53 51 4c  TEXT, not.** SQL
28200 49 54 45 5f 54 45 58 54 2e 0a 2a 2f 0a 23 64 65  ITE_TEXT..*/.#de
28210 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45  fine SQLITE_INTE
28220 47 45 52 20 20 31 0a 23 64 65 66 69 6e 65 20 53  GER  1.#define S
28230 51 4c 49 54 45 5f 46 4c 4f 41 54 20 20 20 20 32  QLITE_FLOAT    2
28240 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
28250 42 4c 4f 42 20 20 20 20 20 34 0a 23 64 65 66 69  BLOB     4.#defi
28260 6e 65 20 53 51 4c 49 54 45 5f 4e 55 4c 4c 20 20  ne SQLITE_NULL  
28270 20 20 20 35 0a 23 69 66 64 65 66 20 53 51 4c 49     5.#ifdef SQLI
28280 54 45 5f 54 45 58 54 0a 23 20 75 6e 64 65 66 20  TE_TEXT.# undef 
28290 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 65 6c 73  SQLITE_TEXT.#els
282a0 65 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54  e.# define SQLIT
282b0 45 5f 54 45 58 54 20 20 20 20 20 33 0a 23 65 6e  E_TEXT     3.#en
282c0 64 69 66 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  dif.#define SQLI
282d0 54 45 33 5f 54 45 58 54 20 20 20 20 20 33 0a 0a  TE3_TEXT     3..
282e0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
282f0 52 65 73 75 6c 74 20 56 61 6c 75 65 73 20 46 72  Result Values Fr
28300 6f 6d 20 41 20 51 75 65 72 79 20 7b 48 31 33 38  om A Query {H138
28310 30 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 2a 20  00} <S10700>.** 
28320 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6c 75 6d  KEYWORDS: {colum
28330 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f  n access functio
28340 6e 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ns}.**.** These 
28350 72 6f 75 74 69 6e 65 73 20 66 6f 72 6d 20 74 68  routines form th
28360 65 20 22 72 65 73 75 6c 74 20 73 65 74 20 71 75  e "result set qu
28370 65 72 79 22 20 69 6e 74 65 72 66 61 63 65 2e 0a  ery" interface..
28380 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
28390 69 6e 65 73 20 72 65 74 75 72 6e 20 69 6e 66 6f  ines return info
283a0 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 61 20  rmation about a 
283b0 73 69 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20 6f 66  single column of
283c0 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20   the current.** 
283d0 72 65 73 75 6c 74 20 72 6f 77 20 6f 66 20 61 20  result row of a 
283e0 71 75 65 72 79 2e 20 20 49 6e 20 65 76 65 72 79  query.  In every
283f0 20 63 61 73 65 20 74 68 65 20 66 69 72 73 74 20   case the first 
28400 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f  argument is a po
28410 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20  inter.** to the 
28420 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
28430 65 6e 74 5d 20 74 68 61 74 20 69 73 20 62 65 69  ent] that is bei
28440 6e 67 20 65 76 61 6c 75 61 74 65 64 20 28 74 68  ng evaluated (th
28450 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  e [sqlite3_stmt*
28460 5d 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 72 65  ].** that was re
28470 74 75 72 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c  turned from [sql
28480 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
28490 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 69 74 73  )] or one of its
284a0 20 76 61 72 69 61 6e 74 73 29 0a 2a 2a 20 61 6e   variants).** an
284b0 64 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  d the second arg
284c0 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64  ument is the ind
284d0 65 78 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e  ex of the column
284e0 20 66 6f 72 20 77 68 69 63 68 20 69 6e 66 6f 72   for which infor
284f0 6d 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64  mation.** should
28500 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20 20 54   be returned.  T
28510 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75  he leftmost colu
28520 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  mn of the result
28530 20 73 65 74 20 68 61 73 20 74 68 65 20 69 6e 64   set has the ind
28540 65 78 20 30 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  ex 0..**.** If t
28550 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
28560 20 64 6f 65 73 20 6e 6f 74 20 63 75 72 72 65 6e   does not curren
28570 74 6c 79 20 70 6f 69 6e 74 20 74 6f 20 61 20 76  tly point to a v
28580 61 6c 69 64 20 72 6f 77 2c 20 6f 72 20 69 66 20  alid row, or if 
28590 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 6e  the.** column in
285a0 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61  dex is out of ra
285b0 6e 67 65 2c 20 74 68 65 20 72 65 73 75 6c 74 20  nge, the result 
285c0 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  is undefined..**
285d0 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
285e0 6d 61 79 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c  may only be call
285f0 65 64 20 77 68 65 6e 20 74 68 65 20 6d 6f 73 74  ed when the most
28600 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 0a   recent call to.
28610 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ** [sqlite3_step
28620 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64  ()] has returned
28630 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 61 6e   [SQLITE_ROW] an
28640 64 20 6e 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71  d neither.** [sq
28650 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6e  lite3_reset()] n
28660 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  or [sqlite3_fina
28670 6c 69 7a 65 28 29 5d 20 68 61 76 65 20 62 65 65  lize()] have bee
28680 6e 20 63 61 6c 6c 65 64 20 73 75 62 73 65 71 75  n called subsequ
28690 65 6e 74 6c 79 2e 0a 2a 2a 20 49 66 20 61 6e 79  ently..** If any
286a0 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
286b0 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 61 66  es are called af
286c0 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  ter [sqlite3_res
286d0 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c  et()] or.** [sql
286e0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
286f0 20 6f 72 20 61 66 74 65 72 20 5b 73 71 6c 69 74   or after [sqlit
28700 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72  e3_step()] has r
28710 65 74 75 72 6e 65 64 0a 2a 2a 20 73 6f 6d 65 74  eturned.** somet
28720 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61 6e 20  hing other than 
28730 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 74 68  [SQLITE_ROW], th
28740 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e  e results are un
28750 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 5b  defined..** If [
28760 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
28770 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  or [sqlite3_rese
28780 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  t()] or [sqlite3
28790 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20  _finalize()].** 
287a0 61 72 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20  are called from 
287b0 61 20 64 69 66 66 65 72 65 6e 74 20 74 68 72 65  a different thre
287c0 61 64 20 77 68 69 6c 65 20 61 6e 79 20 6f 66 20  ad while any of 
287d0 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a  these routines.*
287e0 2a 20 61 72 65 20 70 65 6e 64 69 6e 67 2c 20 74  * are pending, t
287f0 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20  hen the results 
28800 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a  are undefined..*
28810 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
28820 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 72  _column_type() r
28830 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74  outine returns t
28840 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e  he.** [SQLITE_IN
28850 54 45 47 45 52 20 7c 20 64 61 74 61 74 79 70 65  TEGER | datatype
28860 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 69   code] for the i
28870 6e 69 74 69 61 6c 20 64 61 74 61 20 74 79 70 65  nitial data type
28880 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65 73 75 6c  .** of the resul
28890 74 20 63 6f 6c 75 6d 6e 2e 20 20 54 68 65 20 72  t column.  The r
288a0 65 74 75 72 6e 65 64 20 76 61 6c 75 65 20 69 73  eturned value is
288b0 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f   one of [SQLITE_
288c0 49 4e 54 45 47 45 52 5d 2c 0a 2a 2a 20 5b 53 51  INTEGER],.** [SQ
288d0 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51  LITE_FLOAT], [SQ
288e0 4c 49 54 45 5f 54 45 58 54 5d 2c 20 5b 53 51 4c  LITE_TEXT], [SQL
288f0 49 54 45 5f 42 4c 4f 42 5d 2c 20 6f 72 20 5b 53  ITE_BLOB], or [S
28900 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2e 20 20 54 68  QLITE_NULL].  Th
28910 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72  e value.** retur
28920 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  ned by sqlite3_c
28930 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20  olumn_type() is 
28940 6f 6e 6c 79 20 6d 65 61 6e 69 6e 67 66 75 6c 20  only meaningful 
28950 69 66 20 6e 6f 20 74 79 70 65 0a 2a 2a 20 63 6f  if no type.** co
28960 6e 76 65 72 73 69 6f 6e 73 20 68 61 76 65 20 6f  nversions have o
28970 63 63 75 72 72 65 64 20 61 73 20 64 65 73 63 72  ccurred as descr
28980 69 62 65 64 20 62 65 6c 6f 77 2e 20 20 41 66 74  ibed below.  Aft
28990 65 72 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72  er a type conver
289a0 73 69 6f 6e 2c 0a 2a 2a 20 74 68 65 20 76 61 6c  sion,.** the val
289b0 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 73  ue returned by s
289c0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79  qlite3_column_ty
289d0 70 65 28 29 20 69 73 20 75 6e 64 65 66 69 6e 65  pe() is undefine
289e0 64 2e 20 20 46 75 74 75 72 65 0a 2a 2a 20 76 65  d.  Future.** ve
289f0 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
28a00 20 6d 61 79 20 63 68 61 6e 67 65 20 74 68 65 20   may change the 
28a10 62 65 68 61 76 69 6f 72 20 6f 66 20 73 71 6c 69  behavior of sqli
28a20 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28  te3_column_type(
28a30 29 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61  ).** following a
28a40 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e   type conversion
28a50 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 72  ..**.** If the r
28a60 65 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 20  esult is a BLOB 
28a70 6f 72 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20  or UTF-8 string 
28a80 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33  then the sqlite3
28a90 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a  _column_bytes().
28aa0 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  ** routine retur
28ab0 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
28ac0 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 42   bytes in that B
28ad0 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a  LOB or string..*
28ae0 2a 20 49 66 20 74 68 65 20 72 65 73 75 6c 74 20  * If the result 
28af0 69 73 20 61 20 55 54 46 2d 31 36 20 73 74 72 69  is a UTF-16 stri
28b00 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33  ng, then sqlite3
28b10 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20  _column_bytes() 
28b20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65 20  converts.** the 
28b30 73 74 72 69 6e 67 20 74 6f 20 55 54 46 2d 38 20  string to UTF-8 
28b40 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e 73  and then returns
28b50 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
28b60 79 74 65 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20  ytes..** If the 
28b70 72 65 73 75 6c 74 20 69 73 20 61 20 6e 75 6d 65  result is a nume
28b80 72 69 63 20 76 61 6c 75 65 20 74 68 65 6e 20 73  ric value then s
28b90 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
28ba0 74 65 73 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73  tes() uses.** [s
28bb0 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
28bc0 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68  )] to convert th
28bd0 61 74 20 76 61 6c 75 65 20 74 6f 20 61 20 55 54  at value to a UT
28be0 46 2d 38 20 73 74 72 69 6e 67 20 61 6e 64 20 72  F-8 string and r
28bf0 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75  eturns.** the nu
28c00 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e  mber of bytes in
28c10 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a   that string..**
28c20 20 54 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   The value retur
28c30 6e 65 64 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63  ned does not inc
28c40 6c 75 64 65 20 74 68 65 20 7a 65 72 6f 20 74 65  lude the zero te
28c50 72 6d 69 6e 61 74 6f 72 20 61 74 20 74 68 65 20  rminator at the 
28c60 65 6e 64 0a 2a 2a 20 6f 66 20 74 68 65 20 73 74  end.** of the st
28c70 72 69 6e 67 2e 20 20 46 6f 72 20 63 6c 61 72 69  ring.  For clari
28c80 74 79 3a 20 74 68 65 20 76 61 6c 75 65 20 72 65  ty: the value re
28c90 74 75 72 6e 65 64 20 69 73 20 74 68 65 20 6e 75  turned is the nu
28ca0 6d 62 65 72 20 6f 66 0a 2a 2a 20 62 79 74 65 73  mber of.** bytes
28cb0 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67 2c 20   in the string, 
28cc0 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  not the number o
28cd0 66 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a  f characters..**
28ce0 0a 2a 2a 20 53 74 72 69 6e 67 73 20 72 65 74 75  .** Strings retu
28cf0 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  rned by sqlite3_
28d00 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 61 6e  column_text() an
28d10 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  d sqlite3_column
28d20 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 65 76  _text16(),.** ev
28d30 65 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 73  en empty strings
28d40 2c 20 61 72 65 20 61 6c 77 61 79 73 20 7a 65 72  , are always zer
28d50 6f 20 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 54  o terminated.  T
28d60 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c  he return.** val
28d70 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ue from sqlite3_
28d80 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f  column_blob() fo
28d90 72 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20  r a zero-length 
28da0 42 4c 4f 42 20 69 73 20 61 6e 20 61 72 62 69 74  BLOB is an arbit
28db0 72 61 72 79 0a 2a 2a 20 70 6f 69 6e 74 65 72 2c  rary.** pointer,
28dc0 20 70 6f 73 73 69 62 6c 79 20 65 76 65 6e 20 61   possibly even a
28dd0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a   NULL pointer..*
28de0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
28df0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
28e00 29 20 72 6f 75 74 69 6e 65 20 69 73 20 73 69 6d  ) routine is sim
28e10 69 6c 61 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  ilar to sqlite3_
28e20 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a  column_bytes().*
28e30 2a 20 62 75 74 20 6c 65 61 76 65 73 20 74 68 65  * but leaves the
28e40 20 72 65 73 75 6c 74 20 69 6e 20 55 54 46 2d 31   result in UTF-1
28e50 36 20 69 6e 20 6e 61 74 69 76 65 20 62 79 74 65  6 in native byte
28e60 20 6f 72 64 65 72 20 69 6e 73 74 65 61 64 20 6f   order instead o
28e70 66 20 55 54 46 2d 38 2e 0a 2a 2a 20 54 68 65 20  f UTF-8..** The 
28e80 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20  zero terminator 
28e90 69 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 64 20  is not included 
28ea0 69 6e 20 74 68 69 73 20 63 6f 75 6e 74 2e 0a 2a  in this count..*
28eb0 2a 0a 2a 2a 20 54 68 65 20 6f 62 6a 65 63 74 20  *.** The object 
28ec0 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c  returned by [sql
28ed0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75  ite3_column_valu
28ee0 65 28 29 5d 20 69 73 20 61 6e 0a 2a 2a 20 5b 75  e()] is an.** [u
28ef0 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
28f00 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
28f10 2e 20 20 41 6e 20 75 6e 70 72 6f 74 65 63 74 65  .  An unprotecte
28f20 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  d sqlite3_value 
28f30 6f 62 6a 65 63 74 0a 2a 2a 20 6d 61 79 20 6f 6e  object.** may on
28f40 6c 79 20 62 65 20 75 73 65 64 20 77 69 74 68 20  ly be used with 
28f50 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61  [sqlite3_bind_va
28f60 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  lue()] and [sqli
28f70 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65  te3_result_value
28f80 28 29 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20 5b  ()]..** If the [
28f90 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
28fa0 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
28fb0 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a  t returned by.**
28fc0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
28fd0 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75 73 65  _value()] is use
28fe0 64 20 69 6e 20 61 6e 79 20 6f 74 68 65 72 20 77  d in any other w
28ff0 61 79 2c 20 69 6e 63 6c 75 64 69 6e 67 20 63 61  ay, including ca
29000 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f 75 74 69 6e  lls.** to routin
29010 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33  es like [sqlite3
29020 5f 76 61 6c 75 65 5f 69 6e 74 28 29 5d 2c 20 5b  _value_int()], [
29030 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
29040 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71  xt()],.** or [sq
29050 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65  lite3_value_byte
29060 73 28 29 5d 2c 20 74 68 65 6e 20 74 68 65 20 62  s()], then the b
29070 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66  ehavior is undef
29080 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ined..**.** Thes
29090 65 20 72 6f 75 74 69 6e 65 73 20 61 74 74 65 6d  e routines attem
290a0 70 74 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68  pt to convert th
290b0 65 20 76 61 6c 75 65 20 77 68 65 72 65 20 61 70  e value where ap
290c0 70 72 6f 70 72 69 61 74 65 2e 20 20 46 6f 72 0a  propriate.  For.
290d0 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 74  ** example, if t
290e0 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72  he internal repr
290f0 65 73 65 6e 74 61 74 69 6f 6e 20 69 73 20 46 4c  esentation is FL
29100 4f 41 54 20 61 6e 64 20 61 20 74 65 78 74 20 72  OAT and a text r
29110 65 73 75 6c 74 0a 2a 2a 20 69 73 20 72 65 71 75  esult.** is requ
29120 65 73 74 65 64 2c 20 5b 73 71 6c 69 74 65 33 5f  ested, [sqlite3_
29130 73 6e 70 72 69 6e 74 66 28 29 5d 20 69 73 20 75  snprintf()] is u
29140 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74  sed internally t
29150 6f 20 70 65 72 66 6f 72 6d 20 74 68 65 0a 2a 2a  o perform the.**
29160 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 75 74 6f   conversion auto
29170 6d 61 74 69 63 61 6c 6c 79 2e 20 20 54 68 65 20  matically.  The 
29180 66 6f 6c 6c 6f 77 69 6e 67 20 74 61 62 6c 65 20  following table 
29190 64 65 74 61 69 6c 73 20 74 68 65 20 63 6f 6e 76  details the conv
291a0 65 72 73 69 6f 6e 73 0a 2a 2a 20 74 68 61 74 20  ersions.** that 
291b0 61 72 65 20 61 70 70 6c 69 65 64 3a 0a 2a 2a 0a  are applied:.**.
291c0 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  ** <blockquote>.
291d0 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72  ** <table border
291e0 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68  ="1">.** <tr><th
291f0 3e 20 49 6e 74 65 72 6e 61 6c 3c 62 72 3e 54 79  > Internal<br>Ty
29200 70 65 20 3c 74 68 3e 20 52 65 71 75 65 73 74 65  pe <th> Requeste
29210 64 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 20  d<br>Type <th>  
29220 43 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a  Conversion.**.**
29230 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20   <tr><td>  NULL 
29240 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20     <td> INTEGER 
29250 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73    <td> Result is
29260 20 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20   0.** <tr><td>  
29270 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 46 4c  NULL    <td>  FL
29280 4f 41 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75  OAT    <td> Resu
29290 6c 74 20 69 73 20 30 2e 30 0a 2a 2a 20 3c 74 72  lt is 0.0.** <tr
292a0 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c  ><td>  NULL    <
292b0 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74  td>   TEXT    <t
292c0 64 3e 20 52 65 73 75 6c 74 20 69 73 20 4e 55 4c  d> Result is NUL
292d0 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72  L pointer.** <tr
292e0 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c  ><td>  NULL    <
292f0 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74  td>   BLOB    <t
29300 64 3e 20 52 65 73 75 6c 74 20 69 73 20 4e 55 4c  d> Result is NUL
29310 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72  L pointer.** <tr
29320 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c  ><td> INTEGER  <
29330 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74  td>  FLOAT    <t
29340 64 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20  d> Convert from 
29350 69 6e 74 65 67 65 72 20 74 6f 20 66 6c 6f 61 74  integer to float
29360 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54  .** <tr><td> INT
29370 45 47 45 52 20 20 3c 74 64 3e 20 20 20 54 45 58  EGER  <td>   TEX
29380 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20  T    <td> ASCII 
29390 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65  rendering of the
293a0 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e   integer.** <tr>
293b0 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74  <td> INTEGER  <t
293c0 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  d>   BLOB    <td
293d0 3e 20 53 61 6d 65 20 61 73 20 49 4e 54 45 47 45  > Same as INTEGE
293e0 52 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c  R->TEXT.** <tr><
293f0 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64  td>  FLOAT   <td
29400 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e  > INTEGER   <td>
29410 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 66 6c   Convert from fl
29420 6f 61 74 20 74 6f 20 69 6e 74 65 67 65 72 0a 2a  oat to integer.*
29430 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41  * <tr><td>  FLOA
29440 54 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20  T   <td>   TEXT 
29450 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65     <td> ASCII re
29460 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 66  ndering of the f
29470 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  loat.** <tr><td>
29480 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20    FLOAT   <td>  
29490 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53 61   BLOB    <td> Sa
294a0 6d 65 20 61 73 20 46 4c 4f 41 54 2d 3e 54 45 58  me as FLOAT->TEX
294b0 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54  T.** <tr><td>  T
294c0 45 58 54 20 20 20 20 3c 74 64 3e 20 49 4e 54 45  EXT    <td> INTE
294d0 47 45 52 20 20 20 3c 74 64 3e 20 55 73 65 20 61  GER   <td> Use a
294e0 74 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64  toi().** <tr><td
294f0 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20  >  TEXT    <td> 
29500 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 55   FLOAT    <td> U
29510 73 65 20 61 74 6f 66 28 29 0a 2a 2a 20 3c 74 72  se atof().** <tr
29520 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c  ><td>  TEXT    <
29530 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74  td>   BLOB    <t
29540 64 3e 20 4e 6f 20 63 68 61 6e 67 65 0a 2a 2a 20  d> No change.** 
29550 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20  <tr><td>  BLOB  
29560 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20    <td> INTEGER  
29570 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 74 6f   <td> Convert to
29580 20 54 45 58 54 20 74 68 65 6e 20 75 73 65 20 61   TEXT then use a
29590 74 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64  toi().** <tr><td
295a0 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20  >  BLOB    <td> 
295b0 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 43   FLOAT    <td> C
295c0 6f 6e 76 65 72 74 20 74 6f 20 54 45 58 54 20 74  onvert to TEXT t
295d0 68 65 6e 20 75 73 65 20 61 74 6f 66 28 29 0a 2a  hen use atof().*
295e0 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42  * <tr><td>  BLOB
295f0 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20      <td>   TEXT 
29600 20 20 20 3c 74 64 3e 20 41 64 64 20 61 20 7a 65     <td> Add a ze
29610 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 69 66  ro terminator if
29620 20 6e 65 65 64 65 64 0a 2a 2a 20 3c 2f 74 61 62   needed.** </tab
29630 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75  le>.** </blockqu
29640 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74  ote>.**.** The t
29650 61 62 6c 65 20 61 62 6f 76 65 20 6d 61 6b 65 73  able above makes
29660 20 72 65 66 65 72 65 6e 63 65 20 74 6f 20 73 74   reference to st
29670 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79  andard C library
29680 20 66 75 6e 63 74 69 6f 6e 73 20 61 74 6f 69 28   functions atoi(
29690 29 0a 2a 2a 20 61 6e 64 20 61 74 6f 66 28 29 2e  ).** and atof().
296a0 20 20 53 51 4c 69 74 65 20 64 6f 65 73 20 6e 6f    SQLite does no
296b0 74 20 72 65 61 6c 6c 79 20 75 73 65 20 74 68 65  t really use the
296c0 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 49  se functions.  I
296d0 74 20 68 61 73 20 69 74 73 0a 2a 2a 20 6f 77 6e  t has its.** own
296e0 20 65 71 75 69 76 61 6c 65 6e 74 20 69 6e 74 65   equivalent inte
296f0 72 6e 61 6c 20 72 6f 75 74 69 6e 65 73 2e 20 20  rnal routines.  
29700 54 68 65 20 61 74 6f 69 28 29 20 61 6e 64 20 61  The atoi() and a
29710 74 6f 66 28 29 20 6e 61 6d 65 73 20 61 72 65 0a  tof() names are.
29720 2a 2a 20 75 73 65 64 20 69 6e 20 74 68 65 20 74  ** used in the t
29730 61 62 6c 65 20 66 6f 72 20 62 72 65 76 69 74 79  able for brevity
29740 20 61 6e 64 20 62 65 63 61 75 73 65 20 74 68 65   and because the
29750 79 20 61 72 65 20 66 61 6d 69 6c 69 61 72 20 74  y are familiar t
29760 6f 20 6d 6f 73 74 0a 2a 2a 20 43 20 70 72 6f 67  o most.** C prog
29770 72 61 6d 6d 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 4e  rammers..**.** N
29780 6f 74 65 20 74 68 61 74 20 77 68 65 6e 20 74 79  ote that when ty
29790 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 6f  pe conversions o
297a0 63 63 75 72 2c 20 70 6f 69 6e 74 65 72 73 20 72  ccur, pointers r
297b0 65 74 75 72 6e 65 64 20 62 79 20 70 72 69 6f 72  eturned by prior
297c0 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c  .** calls to sql
297d0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
297e0 28 29 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  (), sqlite3_colu
297f0 6d 6e 5f 74 65 78 74 28 29 2c 20 61 6e 64 2f 6f  mn_text(), and/o
29800 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c  r.** sqlite3_col
29810 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 6d 61 79  umn_text16() may
29820 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e   be invalidated.
29830 0a 2a 2a 20 54 79 70 65 20 63 6f 6e 76 65 72 73  .** Type convers
29840 69 6f 6e 73 20 61 6e 64 20 70 6f 69 6e 74 65 72  ions and pointer
29850 20 69 6e 76 61 6c 69 64 61 74 69 6f 6e 73 20 6d   invalidations m
29860 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 69 6e  ight occur.** in
29870 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63   the following c
29880 61 73 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  ases:.**.** <ul>
29890 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69  .** <li> The ini
298a0 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20  tial content is 
298b0 61 20 42 4c 4f 42 20 61 6e 64 20 73 71 6c 69 74  a BLOB and sqlit
298c0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
298d0 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69   or.**      sqli
298e0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
298f0 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20  6() is called.  
29900 41 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f  A zero-terminato
29910 72 20 6d 69 67 68 74 0a 2a 2a 20 20 20 20 20 20  r might.**      
29920 6e 65 65 64 20 74 6f 20 62 65 20 61 64 64 65 64  need to be added
29930 20 74 6f 20 74 68 65 20 73 74 72 69 6e 67 2e 3c   to the string.<
29940 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  /li>.** <li> The
29950 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74   initial content
29960 20 69 73 20 55 54 46 2d 38 20 74 65 78 74 20 61   is UTF-8 text a
29970 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nd sqlite3_colum
29980 6e 5f 62 79 74 65 73 31 36 28 29 20 6f 72 0a 2a  n_bytes16() or.*
29990 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63  *      sqlite3_c
299a0 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69  olumn_text16() i
299b0 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63  s called.  The c
299c0 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63  ontent must be c
299d0 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20  onverted.**     
299e0 20 74 6f 20 55 54 46 2d 31 36 2e 3c 2f 6c 69 3e   to UTF-16.</li>
299f0 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69  .** <li> The ini
29a00 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20  tial content is 
29a10 55 54 46 2d 31 36 20 74 65 78 74 20 61 6e 64 20  UTF-16 text and 
29a20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
29a30 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 20 20 20  ytes() or.**    
29a40 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e    sqlite3_column
29a50 5f 74 65 78 74 28 29 20 69 73 20 63 61 6c 6c 65  _text() is calle
29a60 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20  d.  The content 
29a70 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65  must be converte
29a80 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55 54 46  d.**      to UTF
29a90 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c  -8.</li>.** </ul
29aa0 3e 0a 2a 2a 0a 2a 2a 20 43 6f 6e 76 65 72 73 69  >.**.** Conversi
29ab0 6f 6e 73 20 62 65 74 77 65 65 6e 20 55 54 46 2d  ons between UTF-
29ac0 31 36 62 65 20 61 6e 64 20 55 54 46 2d 31 36 6c  16be and UTF-16l
29ad0 65 20 61 72 65 20 61 6c 77 61 79 73 20 64 6f 6e  e are always don
29ae0 65 20 69 6e 20 70 6c 61 63 65 20 61 6e 64 20 64  e in place and d
29af0 6f 0a 2a 2a 20 6e 6f 74 20 69 6e 76 61 6c 69 64  o.** not invalid
29b00 61 74 65 20 61 20 70 72 69 6f 72 20 70 6f 69 6e  ate a prior poin
29b10 74 65 72 2c 20 74 68 6f 75 67 68 20 6f 66 20 63  ter, though of c
29b20 6f 75 72 73 65 20 74 68 65 20 63 6f 6e 74 65 6e  ourse the conten
29b30 74 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 0a  t of the buffer.
29b40 2a 2a 20 74 68 61 74 20 74 68 65 20 70 72 69 6f  ** that the prio
29b50 72 20 70 6f 69 6e 74 65 72 20 70 6f 69 6e 74 73  r pointer points
29b60 20 74 6f 20 77 69 6c 6c 20 68 61 76 65 20 62 65   to will have be
29b70 65 6e 20 6d 6f 64 69 66 69 65 64 2e 20 20 4f 74  en modified.  Ot
29b80 68 65 72 20 6b 69 6e 64 73 0a 2a 2a 20 6f 66 20  her kinds.** of 
29b90 63 6f 6e 76 65 72 73 69 6f 6e 20 61 72 65 20 64  conversion are d
29ba0 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 77 68 65  one in place whe
29bb0 6e 20 69 74 20 69 73 20 70 6f 73 73 69 62 6c 65  n it is possible
29bc0 2c 20 62 75 74 20 73 6f 6d 65 74 69 6d 65 73 20  , but sometimes 
29bd0 74 68 65 79 0a 2a 2a 20 61 72 65 20 6e 6f 74 20  they.** are not 
29be0 70 6f 73 73 69 62 6c 65 20 61 6e 64 20 69 6e 20  possible and in 
29bf0 74 68 6f 73 65 20 63 61 73 65 73 20 70 72 69 6f  those cases prio
29c00 72 20 70 6f 69 6e 74 65 72 73 20 61 72 65 20 69  r pointers are i
29c10 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 0a 2a  nvalidated..**.*
29c20 2a 20 54 68 65 20 73 61 66 65 73 74 20 61 6e 64  * The safest and
29c30 20 65 61 73 69 65 73 74 20 74 6f 20 72 65 6d 65   easiest to reme
29c40 6d 62 65 72 20 70 6f 6c 69 63 79 20 69 73 20 74  mber policy is t
29c50 6f 20 69 6e 76 6f 6b 65 20 74 68 65 73 65 20 72  o invoke these r
29c60 6f 75 74 69 6e 65 73 0a 2a 2a 20 69 6e 20 6f 6e  outines.** in on
29c70 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69  e of the followi
29c80 6e 67 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c  ng ways:.**.** <
29c90 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69  ul>.**  <li>sqli
29ca0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
29cb0 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71  ) followed by sq
29cc0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
29cd0 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c  es()</li>.**  <l
29ce0 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  i>sqlite3_column
29cf0 5f 62 6c 6f 62 28 29 20 66 6f 6c 6c 6f 77 65 64  _blob() followed
29d00 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   by sqlite3_colu
29d10 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a  mn_bytes()</li>.
29d20 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f  **  <li>sqlite3_
29d30 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20  column_text16() 
29d40 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69  followed by sqli
29d50 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
29d60 31 36 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75  16()</li>.** </u
29d70 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68 65  l>.**.** In othe
29d80 72 20 77 6f 72 64 73 2c 20 79 6f 75 20 73 68 6f  r words, you sho
29d90 75 6c 64 20 63 61 6c 6c 20 73 71 6c 69 74 65 33  uld call sqlite3
29da0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 0a  _column_text(),.
29db0 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ** sqlite3_colum
29dc0 6e 5f 62 6c 6f 62 28 29 2c 20 6f 72 20 73 71 6c  n_blob(), or sql
29dd0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
29de0 31 36 28 29 20 66 69 72 73 74 20 74 6f 20 66 6f  16() first to fo
29df0 72 63 65 20 74 68 65 20 72 65 73 75 6c 74 0a 2a  rce the result.*
29e00 2a 20 69 6e 74 6f 20 74 68 65 20 64 65 73 69 72  * into the desir
29e10 65 64 20 66 6f 72 6d 61 74 2c 20 74 68 65 6e 20  ed format, then 
29e20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63  invoke sqlite3_c
29e30 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72  olumn_bytes() or
29e40 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  .** sqlite3_colu
29e50 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 74 6f 20  mn_bytes16() to 
29e60 66 69 6e 64 20 74 68 65 20 73 69 7a 65 20 6f 66  find the size of
29e70 20 74 68 65 20 72 65 73 75 6c 74 2e 20 20 44 6f   the result.  Do
29e80 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 0a 2a   not mix calls.*
29e90 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c  * to sqlite3_col
29ea0 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 20 73 71  umn_text() or sq
29eb0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
29ec0 62 28 29 20 77 69 74 68 20 63 61 6c 6c 73 20 74  b() with calls t
29ed0 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c  o.** sqlite3_col
29ee0 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 2c 20 61  umn_bytes16(), a
29ef0 6e 64 20 64 6f 20 6e 6f 74 20 6d 69 78 20 63 61  nd do not mix ca
29f00 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  lls to sqlite3_c
29f10 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 0a 2a  olumn_text16().*
29f20 2a 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 20  * with calls to 
29f30 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
29f40 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68  ytes()..**.** Th
29f50 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72  e pointers retur
29f60 6e 65 64 20 61 72 65 20 76 61 6c 69 64 20 75 6e  ned are valid un
29f70 74 69 6c 20 61 20 74 79 70 65 20 63 6f 6e 76 65  til a type conve
29f80 72 73 69 6f 6e 20 6f 63 63 75 72 73 20 61 73 0a  rsion occurs as.
29f90 2a 2a 20 64 65 73 63 72 69 62 65 64 20 61 62 6f  ** described abo
29fa0 76 65 2c 20 6f 72 20 75 6e 74 69 6c 20 5b 73 71  ve, or until [sq
29fb0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72  lite3_step()] or
29fc0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
29fd0 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  )] or.** [sqlite
29fe0 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 73  3_finalize()] is
29ff0 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 6d 65   called.  The me
2a000 6d 6f 72 79 20 73 70 61 63 65 20 75 73 65 64 20  mory space used 
2a010 74 6f 20 68 6f 6c 64 20 73 74 72 69 6e 67 73 0a  to hold strings.
2a020 2a 2a 20 61 6e 64 20 42 4c 4f 42 73 20 69 73 20  ** and BLOBs is 
2a030 66 72 65 65 64 20 61 75 74 6f 6d 61 74 69 63 61  freed automatica
2a040 6c 6c 79 2e 20 20 44 6f 20 3c 62 3e 6e 6f 74 3c  lly.  Do <b>not<
2a050 2f 62 3e 20 70 61 73 73 20 74 68 65 20 70 6f 69  /b> pass the poi
2a060 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 0a 2a  nters returned.*
2a070 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  * [sqlite3_colum
2a080 6e 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69  n_blob()], [sqli
2a090 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
2a0a0 29 5d 2c 20 65 74 63 2e 20 69 6e 74 6f 0a 2a 2a  )], etc. into.**
2a0b0 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
2a0c0 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 6d 65  ]..**.** If a me
2a0d0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
2a0e0 65 72 72 6f 72 20 6f 63 63 75 72 73 20 64 75 72  error occurs dur
2a0f0 69 6e 67 20 74 68 65 20 65 76 61 6c 75 61 74 69  ing the evaluati
2a100 6f 6e 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20  on of any.** of 
2a110 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2c 20  these routines, 
2a120 61 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20  a default value 
2a130 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68  is returned.  Th
2a140 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 0a  e default value.
2a150 2a 2a 20 69 73 20 65 69 74 68 65 72 20 74 68 65  ** is either the
2a160 20 69 6e 74 65 67 65 72 20 30 2c 20 74 68 65 20   integer 0, the 
2a170 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e  floating point n
2a180 75 6d 62 65 72 20 30 2e 30 2c 20 6f 72 20 61 20  umber 0.0, or a 
2a190 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 2e  NULL.** pointer.
2a1a0 20 20 53 75 62 73 65 71 75 65 6e 74 20 63 61 6c    Subsequent cal
2a1b0 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65  ls to [sqlite3_e
2a1c0 72 72 63 6f 64 65 28 29 5d 20 77 69 6c 6c 20 72  rrcode()] will r
2a1d0 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45  eturn.** [SQLITE
2a1e0 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 49  _NOMEM]..**.** I
2a1f0 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
2a200 20 7b 48 31 33 38 30 33 7d 20 54 68 65 20 5b 73   {H13803} The [s
2a210 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
2a220 6f 62 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61  ob(S,N)] interfa
2a230 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65 0a  ce converts the.
2a240 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 74 68 20  **          Nth 
2a250 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 20 63 75  column in the cu
2a260 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65  rrent row of the
2a270 20 72 65 73 75 6c 74 20 73 65 74 20 66 6f 72 0a   result set for.
2a280 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
2a290 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2a2a0 65 6e 74 5d 20 53 20 69 6e 74 6f 20 61 20 42 4c  ent] S into a BL
2a2b0 4f 42 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75  OB and then retu
2a2c0 72 6e 73 20 61 0a 2a 2a 20 20 20 20 20 20 20 20  rns a.**        
2a2d0 20 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65    pointer to the
2a2e0 20 63 6f 6e 76 65 72 74 65 64 20 76 61 6c 75 65   converted value
2a2f0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 38 30 36 7d  ..**.** {H13806}
2a300 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   The [sqlite3_co
2a310 6c 75 6d 6e 5f 62 79 74 65 73 28 53 2c 4e 29 5d  lumn_bytes(S,N)]
2a320 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
2a330 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  ns the.**       
2a340 20 20 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74     number of byt
2a350 65 73 20 69 6e 20 74 68 65 20 42 4c 4f 42 20 6f  es in the BLOB o
2a360 72 20 73 74 72 69 6e 67 20 28 65 78 63 6c 75 73  r string (exclus
2a370 69 76 65 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20  ive of the.**   
2a380 20 20 20 20 20 20 20 7a 65 72 6f 20 74 65 72 6d         zero term
2a390 69 6e 61 74 6f 72 20 6f 6e 20 74 68 65 20 73 74  inator on the st
2a3a0 72 69 6e 67 29 20 74 68 61 74 20 77 61 73 20 72  ring) that was r
2a3b0 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 0a 2a  eturned by the.*
2a3c0 2a 20 20 20 20 20 20 20 20 20 20 6d 6f 73 74 20  *          most 
2a3d0 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b  recent call to [
2a3e0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2a3f0 6c 6f 62 28 53 2c 4e 29 5d 20 6f 72 0a 2a 2a 20  lob(S,N)] or.** 
2a400 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
2a410 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 53 2c  3_column_text(S,
2a420 4e 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 38  N)]..**.** {H138
2a430 30 39 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  09} The [sqlite3
2a440 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
2a450 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20  S,N)] interface 
2a460 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 20  returns the.**  
2a470 20 20 20 20 20 20 20 20 6e 75 6d 62 65 72 20 6f          number o
2a480 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 73  f bytes in the s
2a490 74 72 69 6e 67 20 28 65 78 63 6c 75 73 69 76 65  tring (exclusive
2a4a0 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20   of the.**      
2a4b0 20 20 20 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61      zero termina
2a4c0 74 6f 72 20 6f 6e 20 74 68 65 20 73 74 72 69 6e  tor on the strin
2a4d0 67 29 20 74 68 61 74 20 77 61 73 20 72 65 74 75  g) that was retu
2a4e0 72 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 20  rned by the.**  
2a4f0 20 20 20 20 20 20 20 20 6d 6f 73 74 20 72 65 63          most rec
2a500 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ent call to [sql
2a510 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
2a520 31 36 28 53 2c 4e 29 5d 2e 0a 2a 2a 0a 2a 2a 20  16(S,N)]..**.** 
2a530 7b 48 31 33 38 31 32 7d 20 54 68 65 20 5b 73 71  {H13812} The [sq
2a540 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75  lite3_column_dou
2a550 62 6c 65 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66  ble(S,N)] interf
2a560 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65  ace converts the
2a570 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 74 68  .**          Nth
2a580 20 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 20 63   column in the c
2a590 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68  urrent row of th
2a5a0 65 20 72 65 73 75 6c 74 20 73 65 74 20 66 6f 72  e result set for
2a5b0 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
2a5c0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2a5d0 6d 65 6e 74 5d 20 53 20 69 6e 74 6f 20 61 20 66  ment] S into a f
2a5e0 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61  loating point va
2a5f0 6c 75 65 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20  lue and.**      
2a600 20 20 20 20 72 65 74 75 72 6e 73 20 61 20 63 6f      returns a co
2a610 70 79 20 6f 66 20 74 68 61 74 20 76 61 6c 75 65  py of that value
2a620 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 38 31 35 7d  ..**.** {H13815}
2a630 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   The [sqlite3_co
2a640 6c 75 6d 6e 5f 69 6e 74 28 53 2c 4e 29 5d 20 69  lumn_int(S,N)] i
2a650 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74  nterface convert
2a660 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  s the.**        
2a670 20 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 69 6e 20    Nth column in 
2a680 74 68 65 20 63 75 72 72 65 6e 74 20 72 6f 77 20  the current row 
2a690 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  of the result se
2a6a0 74 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20  t for the.**    
2a6b0 20 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 20        [prepared 
2a6c0 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 74  statement] S int
2a6d0 6f 20 61 20 36 34 2d 62 69 74 20 73 69 67 6e 65  o a 64-bit signe
2a6e0 64 20 69 6e 74 65 67 65 72 20 61 6e 64 0a 2a 2a  d integer and.**
2a6f0 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e            return
2a700 73 20 74 68 65 20 6c 6f 77 65 72 20 33 32 20 62  s the lower 32 b
2a710 69 74 73 20 6f 66 20 74 68 61 74 20 69 6e 74 65  its of that inte
2a720 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 38  ger..**.** {H138
2a730 31 38 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  18} The [sqlite3
2a740 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34 28 53 2c  _column_int64(S,
2a750 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f  N)] interface co
2a760 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20  nverts the.**   
2a770 20 20 20 20 20 20 20 4e 74 68 20 63 6f 6c 75 6d         Nth colum
2a780 6e 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74  n in the current
2a790 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75   row of the resu
2a7a0 6c 74 20 73 65 74 20 66 6f 72 20 74 68 65 0a 2a  lt set for the.*
2a7b0 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70  *          [prep
2a7c0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2a7d0 53 20 69 6e 74 6f 20 61 20 36 34 2d 62 69 74 20  S into a 64-bit 
2a7e0 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20 61  signed integer a
2a7f0 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72  nd.**          r
2a800 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66  eturns a copy of
2a810 20 74 68 61 74 20 69 6e 74 65 67 65 72 2e 0a 2a   that integer..*
2a820 2a 0a 2a 2a 20 7b 48 31 33 38 32 31 7d 20 54 68  *.** {H13821} Th
2a830 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  e [sqlite3_colum
2a840 6e 5f 74 65 78 74 28 53 2c 4e 29 5d 20 69 6e 74  n_text(S,N)] int
2a850 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20  erface converts 
2a860 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
2a870 4e 74 68 20 63 6f 6c 75 6d 6e 20 69 6e 20 74 68  Nth column in th
2a880 65 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66  e current row of
2a890 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20   the result set 
2a8a0 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  for.**          
2a8b0 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
2a8c0 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 74 6f 20  atement] S into 
2a8d0 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  a zero-terminate
2a8e0 64 20 55 54 46 2d 38 0a 2a 2a 20 20 20 20 20 20  d UTF-8.**      
2a8f0 20 20 20 20 73 74 72 69 6e 67 20 61 6e 64 20 72      string and r
2a900 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
2a910 20 74 6f 20 74 68 61 74 20 73 74 72 69 6e 67 2e   to that string.
2a920 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 38 32 34 7d 20  .**.** {H13824} 
2a930 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  The [sqlite3_col
2a940 75 6d 6e 5f 74 65 78 74 31 36 28 53 2c 4e 29 5d  umn_text16(S,N)]
2a950 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65   interface conve
2a960 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  rts the.**      
2a970 20 20 20 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 69      Nth column i
2a980 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 72 6f  n the current ro
2a990 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  w of the result 
2a9a0 73 65 74 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20  set for the.**  
2a9b0 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65          [prepare
2a9c0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69  d statement] S i
2a9d0 6e 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69  nto a zero-termi
2a9e0 6e 61 74 65 64 20 32 2d 62 79 74 65 0a 2a 2a 20  nated 2-byte.** 
2a9f0 20 20 20 20 20 20 20 20 20 61 6c 69 67 6e 65 64           aligned
2aa00 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62   UTF-16 native b
2aa10 79 74 65 20 6f 72 64 65 72 20 73 74 72 69 6e 67  yte order string
2aa20 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20   and returns.** 
2aa30 20 20 20 20 20 20 20 20 20 61 20 70 6f 69 6e 74           a point
2aa40 65 72 20 74 6f 20 74 68 61 74 20 73 74 72 69 6e  er to that strin
2aa50 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 38 32 37  g..**.** {H13827
2aa60 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  } The [sqlite3_c
2aa70 6f 6c 75 6d 6e 5f 74 79 70 65 28 53 2c 4e 29 5d  olumn_type(S,N)]
2aa80 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
2aa90 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  ns.**          o
2aaa0 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 4e 55  ne of [SQLITE_NU
2aab0 4c 4c 5d 2c 20 5b 53 51 4c 49 54 45 5f 49 4e 54  LL], [SQLITE_INT
2aac0 45 47 45 52 5d 2c 20 5b 53 51 4c 49 54 45 5f 46  EGER], [SQLITE_F
2aad0 4c 4f 41 54 5d 2c 0a 2a 2a 20 20 20 20 20 20 20  LOAT],.**       
2aae0 20 20 20 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d     [SQLITE_TEXT]
2aaf0 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 42 4c 4f  , or [SQLITE_BLO
2ab00 42 5d 20 61 73 20 61 70 70 72 6f 70 72 69 61 74  B] as appropriat
2ab10 65 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20  e for.**        
2ab20 20 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e    the Nth column
2ab30 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20   in the current 
2ab40 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c  row of the resul
2ab50 74 20 73 65 74 20 66 6f 72 0a 2a 2a 20 20 20 20  t set for.**    
2ab60 20 20 20 20 20 20 74 68 65 20 5b 70 72 65 70 61        the [prepa
2ab70 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
2ab80 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 38 33 30 7d  ..**.** {H13830}
2ab90 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   The [sqlite3_co
2aba0 6c 75 6d 6e 5f 76 61 6c 75 65 28 53 2c 4e 29 5d  lumn_value(S,N)]
2abb0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
2abc0 6e 73 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 20  ns a.**         
2abd0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 5b   pointer to an [
2abe0 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
2abf0 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
2ac00 74 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20  t for the.**    
2ac10 20 20 20 20 20 20 4e 74 68 20 63 6f 6c 75 6d 6e        Nth column
2ac20 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20   in the current 
2ac30 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c  row of the resul
2ac40 74 20 73 65 74 20 66 6f 72 0a 2a 2a 20 20 20 20  t set for.**    
2ac50 20 20 20 20 20 20 74 68 65 20 5b 70 72 65 70 61        the [prepa
2ac60 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
2ac70 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69 64 20  ..*/.const void 
2ac80 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
2ac90 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d  blob(sqlite3_stm
2aca0 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69  t*, int iCol);.i
2acb0 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nt sqlite3_colum
2acc0 6e 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f  n_bytes(sqlite3_
2acd0 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
2ace0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  ;.int sqlite3_co
2acf0 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 73 71 6c  lumn_bytes16(sql
2ad00 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
2ad10 69 43 6f 6c 29 3b 0a 64 6f 75 62 6c 65 20 73 71  iCol);.double sq
2ad20 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75  lite3_column_dou
2ad30 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ble(sqlite3_stmt
2ad40 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e  *, int iCol);.in
2ad50 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  t sqlite3_column
2ad60 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  _int(sqlite3_stm
2ad70 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73  t*, int iCol);.s
2ad80 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c  qlite3_int64 sql
2ad90 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36  ite3_column_int6
2ada0 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  4(sqlite3_stmt*,
2adb0 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73   int iCol);.cons
2adc0 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20  t unsigned char 
2add0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
2ade0 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  text(sqlite3_stm
2adf0 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63  t*, int iCol);.c
2ae00 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
2ae10 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
2ae20 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2ae30 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73  int iCol);.int s
2ae40 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79  qlite3_column_ty
2ae50 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  pe(sqlite3_stmt*
2ae60 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 71 6c  , int iCol);.sql
2ae70 69 74 65 33 5f 76 61 6c 75 65 20 2a 73 71 6c 69  ite3_value *sqli
2ae80 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65  te3_column_value
2ae90 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2aea0 69 6e 74 20 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a  int iCol);../*.*
2aeb0 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 73 74  * CAPI3REF: Dest
2aec0 72 6f 79 20 41 20 50 72 65 70 61 72 65 64 20 53  roy A Prepared S
2aed0 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 20  tatement Object 
2aee0 7b 48 31 33 33 30 30 7d 20 3c 53 37 30 33 30 30  {H13300} <S70300
2aef0 3e 3c 53 33 30 31 30 30 3e 0a 2a 2a 0a 2a 2a 20  ><S30100>.**.** 
2af00 54 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6e 61  The sqlite3_fina
2af10 6c 69 7a 65 28 29 20 66 75 6e 63 74 69 6f 6e 20  lize() function 
2af20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 64 65 6c  is called to del
2af30 65 74 65 20 61 20 5b 70 72 65 70 61 72 65 64 20  ete a [prepared 
2af40 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 49  statement]..** I
2af50 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  f the statement 
2af60 77 61 73 20 65 78 65 63 75 74 65 64 20 73 75 63  was executed suc
2af70 63 65 73 73 66 75 6c 6c 79 20 6f 72 20 6e 6f 74  cessfully or not
2af80 20 65 78 65 63 75 74 65 64 20 61 74 20 61 6c 6c   executed at all
2af90 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 49 54 45  , then.** SQLITE
2afa0 5f 4f 4b 20 69 73 20 72 65 74 75 72 6e 65 64 2e  _OK is returned.
2afb0 20 49 66 20 65 78 65 63 75 74 69 6f 6e 20 6f 66   If execution of
2afc0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 66   the statement f
2afd0 61 69 6c 65 64 20 74 68 65 6e 20 61 6e 0a 2a 2a  ailed then an.**
2afe0 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72   [error code] or
2aff0 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72   [extended error
2b000 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e   code] is return
2b010 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72  ed..**.** This r
2b020 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20 63 61  outine can be ca
2b030 6c 6c 65 64 20 61 74 20 61 6e 79 20 70 6f 69 6e  lled at any poin
2b040 74 20 64 75 72 69 6e 67 20 74 68 65 20 65 78 65  t during the exe
2b050 63 75 74 69 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a  cution of the.**
2b060 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2b070 6d 65 6e 74 5d 2e 20 20 49 66 20 74 68 65 20 76  ment].  If the v
2b080 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 68  irtual machine h
2b090 61 73 20 6e 6f 74 0a 2a 2a 20 63 6f 6d 70 6c 65  as not.** comple
2b0a0 74 65 64 20 65 78 65 63 75 74 69 6f 6e 20 77 68  ted execution wh
2b0b0 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  en this routine 
2b0c0 69 73 20 63 61 6c 6c 65 64 2c 20 74 68 61 74 20  is called, that 
2b0d0 69 73 20 6c 69 6b 65 0a 2a 2a 20 65 6e 63 6f 75  is like.** encou
2b0e0 6e 74 65 72 69 6e 67 20 61 6e 20 65 72 72 6f 72  ntering an error
2b0f0 20 6f 72 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f   or an [sqlite3_
2b100 69 6e 74 65 72 72 75 70 74 20 7c 20 69 6e 74 65  interrupt | inte
2b110 72 72 75 70 74 5d 2e 0a 2a 2a 20 49 6e 63 6f 6d  rrupt]..** Incom
2b120 70 6c 65 74 65 20 75 70 64 61 74 65 73 20 6d 61  plete updates ma
2b130 79 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b  y be rolled back
2b140 20 61 6e 64 20 74 72 61 6e 73 61 63 74 69 6f 6e   and transaction
2b150 73 20 63 61 6e 63 65 6c 65 64 2c 0a 2a 2a 20 64  s canceled,.** d
2b160 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20  epending on the 
2b170 63 69 72 63 75 6d 73 74 61 6e 63 65 73 2c 20 61  circumstances, a
2b180 6e 64 20 74 68 65 0a 2a 2a 20 5b 65 72 72 6f 72  nd the.** [error
2b190 20 63 6f 64 65 5d 20 72 65 74 75 72 6e 65 64 20   code] returned 
2b1a0 77 69 6c 6c 20 62 65 20 5b 53 51 4c 49 54 45 5f  will be [SQLITE_
2b1b0 41 42 4f 52 54 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e  ABORT]..**.** IN
2b1c0 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
2b1d0 7b 48 31 31 33 30 32 7d 20 54 68 65 20 5b 73 71  {H11302} The [sq
2b1e0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53  lite3_finalize(S
2b1f0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 64 65 73  )] interface des
2b200 74 72 6f 79 73 20 74 68 65 0a 2a 2a 20 20 20 20  troys the.**    
2b210 20 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 20        [prepared 
2b220 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 61 6e 64  statement] S and
2b230 20 72 65 6c 65 61 73 65 73 20 61 6c 6c 0a 2a 2a   releases all.**
2b240 20 20 20 20 20 20 20 20 20 20 6d 65 6d 6f 72 79            memory
2b250 20 61 6e 64 20 66 69 6c 65 20 72 65 73 6f 75 72   and file resour
2b260 63 65 73 20 68 65 6c 64 20 62 79 20 74 68 61 74  ces held by that
2b270 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 7b   object..**.** {
2b280 48 31 31 33 30 34 7d 20 49 66 20 74 68 65 20 6d  H11304} If the m
2b290 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20  ost recent call 
2b2a0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  to [sqlite3_step
2b2b0 28 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20  (S)] for the.** 
2b2c0 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72           [prepar
2b2d0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20  ed statement] S 
2b2e0 72 65 74 75 72 6e 65 64 20 61 6e 20 65 72 72 6f  returned an erro
2b2f0 72 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  r,.**          t
2b300 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  hen [sqlite3_fin
2b310 61 6c 69 7a 65 28 53 29 5d 20 72 65 74 75 72 6e  alize(S)] return
2b320 73 20 74 68 61 74 20 73 61 6d 65 20 65 72 72 6f  s that same erro
2b330 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  r..*/.int sqlite
2b340 33 5f 66 69 6e 61 6c 69 7a 65 28 73 71 6c 69 74  3_finalize(sqlit
2b350 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
2b360 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2b370 3a 20 52 65 73 65 74 20 41 20 50 72 65 70 61 72  : Reset A Prepar
2b380 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a  ed Statement Obj
2b390 65 63 74 20 7b 48 31 33 33 33 30 7d 20 3c 53 37  ect {H13330} <S7
2b3a0 30 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  0300>.**.** The 
2b3b0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 20  sqlite3_reset() 
2b3c0 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c  function is call
2b3d0 65 64 20 74 6f 20 72 65 73 65 74 20 61 20 5b 70  ed to reset a [p
2b3e0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2b3f0 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 62 61 63  t].** object bac
2b400 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61 6c  k to its initial
2b410 20 73 74 61 74 65 2c 20 72 65 61 64 79 20 74 6f   state, ready to
2b420 20 62 65 20 72 65 2d 65 78 65 63 75 74 65 64 2e   be re-executed.
2b430 0a 2a 2a 20 41 6e 79 20 53 51 4c 20 73 74 61 74  .** Any SQL stat
2b440 65 6d 65 6e 74 20 76 61 72 69 61 62 6c 65 73 20  ement variables 
2b450 74 68 61 74 20 68 61 64 20 76 61 6c 75 65 73 20  that had values 
2b460 62 6f 75 6e 64 20 74 6f 20 74 68 65 6d 20 75 73  bound to them us
2b470 69 6e 67 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69  ing.** the [sqli
2b480 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20  te3_bind_blob | 
2b490 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29  sqlite3_bind_*()
2b4a0 20 41 50 49 5d 20 72 65 74 61 69 6e 20 74 68 65   API] retain the
2b4b0 69 72 20 76 61 6c 75 65 73 2e 0a 2a 2a 20 55 73  ir values..** Us
2b4c0 65 20 5b 73 71 6c 69 74 65 33 5f 63 6c 65 61 72  e [sqlite3_clear
2b4d0 5f 62 69 6e 64 69 6e 67 73 28 29 5d 20 74 6f 20  _bindings()] to 
2b4e0 72 65 73 65 74 20 74 68 65 20 62 69 6e 64 69 6e  reset the bindin
2b4f0 67 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 33 33  gs..**.** {H1133
2b500 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  2} The [sqlite3_
2b510 72 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66  reset(S)] interf
2b520 61 63 65 20 72 65 73 65 74 73 20 74 68 65 20 5b  ace resets the [
2b530 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2b540 6e 74 5d 20 53 0a 2a 2a 20 20 20 20 20 20 20 20  nt] S.**        
2b550 20 20 62 61 63 6b 20 74 6f 20 74 68 65 20 62 65    back to the be
2b560 67 69 6e 6e 69 6e 67 20 6f 66 20 69 74 73 20 70  ginning of its p
2b570 72 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20 7b 48  rogram..**.** {H
2b580 31 31 33 33 34 7d 20 49 66 20 74 68 65 20 6d 6f  11334} If the mo
2b590 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74  st recent call t
2b5a0 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  o [sqlite3_step(
2b5b0 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20  S)] for the.**  
2b5c0 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65          [prepare
2b5d0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 72  d statement] S r
2b5e0 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f  eturned [SQLITE_
2b5f0 52 4f 57 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  ROW] or [SQLITE_
2b600 44 4f 4e 45 5d 2c 0a 2a 2a 20 20 20 20 20 20 20  DONE],.**       
2b610 20 20 20 6f 72 20 69 66 20 5b 73 71 6c 69 74 65     or if [sqlite
2b620 33 5f 73 74 65 70 28 53 29 5d 20 68 61 73 20 6e  3_step(S)] has n
2b630 65 76 65 72 20 62 65 66 6f 72 65 20 62 65 65 6e  ever before been
2b640 20 63 61 6c 6c 65 64 20 6f 6e 20 53 2c 0a 2a 2a   called on S,.**
2b650 20 20 20 20 20 20 20 20 20 20 74 68 65 6e 20 5b            then [
2b660 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29  sqlite3_reset(S)
2b670 5d 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  ] returns [SQLIT
2b680 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  E_OK]..**.** {H1
2b690 31 33 33 36 7d 20 49 66 20 74 68 65 20 6d 6f 73  1336} If the mos
2b6a0 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f  t recent call to
2b6b0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53   [sqlite3_step(S
2b6c0 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20 20  )] for the.**   
2b6d0 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65 64         [prepared
2b6e0 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e   statement] S in
2b6f0 64 69 63 61 74 65 64 20 61 6e 20 65 72 72 6f 72  dicated an error
2b700 2c 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20  , then.**       
2b710 20 20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65     [sqlite3_rese
2b720 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20 61 6e  t(S)] returns an
2b730 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72   appropriate [er
2b740 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a  ror code]..**.**
2b750 20 7b 48 31 31 33 33 38 7d 20 54 68 65 20 5b 73   {H11338} The [s
2b760 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d  qlite3_reset(S)]
2b770 20 69 6e 74 65 72 66 61 63 65 20 64 6f 65 73 20   interface does 
2b780 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 76  not change the v
2b790 61 6c 75 65 73 0a 2a 2a 20 20 20 20 20 20 20 20  alues.**        
2b7a0 20 20 6f 66 20 61 6e 79 20 5b 73 71 6c 69 74 65    of any [sqlite
2b7b0 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 62 69 6e 64  3_bind_blob|bind
2b7c0 69 6e 67 73 5d 20 6f 6e 20 74 68 65 20 5b 70 72  ings] on the [pr
2b7d0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2b7e0 5d 20 53 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ] S..*/.int sqli
2b7f0 74 65 33 5f 72 65 73 65 74 28 73 71 6c 69 74 65  te3_reset(sqlite
2b800 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a  3_stmt *pStmt);.
2b810 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2b820 20 43 72 65 61 74 65 20 4f 72 20 52 65 64 65 66   Create Or Redef
2b830 69 6e 65 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e  ine SQL Function
2b840 73 20 7b 48 31 36 31 30 30 7d 20 3c 53 32 30 32  s {H16100} <S202
2b850 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  00>.** KEYWORDS:
2b860 20 7b 66 75 6e 63 74 69 6f 6e 20 63 72 65 61 74   {function creat
2b870 69 6f 6e 20 72 6f 75 74 69 6e 65 73 7d 0a 2a 2a  ion routines}.**
2b880 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c   KEYWORDS: {appl
2b890 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
2b8a0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 7d 0a 2a 2a  SQL function}.**
2b8b0 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c   KEYWORDS: {appl
2b8c0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
2b8d0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a  SQL functions}.*
2b8e0 2a 0a 2a 2a 20 54 68 65 73 65 20 74 77 6f 20 66  *.** These two f
2b8f0 75 6e 63 74 69 6f 6e 73 20 28 63 6f 6c 6c 65 63  unctions (collec
2b900 74 69 76 65 6c 79 20 6b 6e 6f 77 6e 20 61 73 20  tively known as 
2b910 22 66 75 6e 63 74 69 6f 6e 20 63 72 65 61 74 69  "function creati
2b920 6f 6e 20 72 6f 75 74 69 6e 65 73 22 29 0a 2a 2a  on routines").**
2b930 20 61 72 65 20 75 73 65 64 20 74 6f 20 61 64 64   are used to add
2b940 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f   SQL functions o
2b950 72 20 61 67 67 72 65 67 61 74 65 73 20 6f 72 20  r aggregates or 
2b960 74 6f 20 72 65 64 65 66 69 6e 65 20 74 68 65 20  to redefine the 
2b970 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f 66 20 65  behavior.** of e
2b980 78 69 73 74 69 6e 67 20 53 51 4c 20 66 75 6e 63  xisting SQL func
2b990 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61  tions or aggrega
2b9a0 74 65 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20 64  tes.  The only d
2b9b0 69 66 66 65 72 65 6e 63 65 20 62 65 74 77 65 65  ifference betwee
2b9c0 6e 20 74 68 65 0a 2a 2a 20 74 77 6f 20 69 73 20  n the.** two is 
2b9d0 74 68 61 74 20 74 68 65 20 73 65 63 6f 6e 64 20  that the second 
2b9e0 70 61 72 61 6d 65 74 65 72 2c 20 74 68 65 20 6e  parameter, the n
2b9f0 61 6d 65 20 6f 66 20 74 68 65 20 28 73 63 61 6c  ame of the (scal
2ba00 61 72 29 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a  ar) function or.
2ba10 2a 2a 20 61 67 67 72 65 67 61 74 65 2c 20 69 73  ** aggregate, is
2ba20 20 65 6e 63 6f 64 65 64 20 69 6e 20 55 54 46 2d   encoded in UTF-
2ba30 38 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72  8 for sqlite3_cr
2ba40 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 20  eate_function() 
2ba50 61 6e 64 20 55 54 46 2d 31 36 0a 2a 2a 20 66 6f  and UTF-16.** fo
2ba60 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  r sqlite3_create
2ba70 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 2e 0a 2a  _function16()..*
2ba80 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70  *.** The first p
2ba90 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20  arameter is the 
2baa0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
2bab0 74 69 6f 6e 5d 20 74 6f 20 77 68 69 63 68 20 74  tion] to which t
2bac0 68 65 20 53 51 4c 0a 2a 2a 20 66 75 6e 63 74 69  he SQL.** functi
2bad0 6f 6e 20 69 73 20 74 6f 20 62 65 20 61 64 64 65  on is to be adde
2bae0 64 2e 20 20 49 66 20 61 20 73 69 6e 67 6c 65 20  d.  If a single 
2baf0 70 72 6f 67 72 61 6d 20 75 73 65 73 20 6d 6f 72  program uses mor
2bb00 65 20 74 68 61 6e 20 6f 6e 65 20 64 61 74 61 62  e than one datab
2bb10 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  ase.** connectio
2bb20 6e 20 69 6e 74 65 72 6e 61 6c 6c 79 2c 20 74 68  n internally, th
2bb30 65 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  en SQL functions
2bb40 20 6d 75 73 74 20 62 65 20 61 64 64 65 64 20 69   must be added i
2bb50 6e 64 69 76 69 64 75 61 6c 6c 79 20 74 6f 0a 2a  ndividually to.*
2bb60 2a 20 65 61 63 68 20 64 61 74 61 62 61 73 65 20  * each database 
2bb70 63 6f 6e 6e 65 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a  connection..**.*
2bb80 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72  * The second par
2bb90 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e 61  ameter is the na
2bba0 6d 65 20 6f 66 20 74 68 65 20 53 51 4c 20 66 75  me of the SQL fu
2bbb0 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 63 72 65  nction to be cre
2bbc0 61 74 65 64 20 6f 72 0a 2a 2a 20 72 65 64 65 66  ated or.** redef
2bbd0 69 6e 65 64 2e 20 20 54 68 65 20 6c 65 6e 67 74  ined.  The lengt
2bbe0 68 20 6f 66 20 74 68 65 20 6e 61 6d 65 20 69 73  h of the name is
2bbf0 20 6c 69 6d 69 74 65 64 20 74 6f 20 32 35 35 20   limited to 255 
2bc00 62 79 74 65 73 2c 20 65 78 63 6c 75 73 69 76 65  bytes, exclusive
2bc10 20 6f 66 0a 2a 2a 20 74 68 65 20 7a 65 72 6f 2d   of.** the zero-
2bc20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 4e 6f 74  terminator.  Not
2bc30 65 20 74 68 61 74 20 74 68 65 20 6e 61 6d 65 20  e that the name 
2bc40 6c 65 6e 67 74 68 20 6c 69 6d 69 74 20 69 73 20  length limit is 
2bc50 69 6e 20 62 79 74 65 73 2c 20 6e 6f 74 0a 2a 2a  in bytes, not.**
2bc60 20 63 68 61 72 61 63 74 65 72 73 2e 20 20 41 6e   characters.  An
2bc70 79 20 61 74 74 65 6d 70 74 20 74 6f 20 63 72 65  y attempt to cre
2bc80 61 74 65 20 61 20 66 75 6e 63 74 69 6f 6e 20 77  ate a function w
2bc90 69 74 68 20 61 20 6c 6f 6e 67 65 72 20 6e 61 6d  ith a longer nam
2bca0 65 0a 2a 2a 20 77 69 6c 6c 20 72 65 73 75 6c 74  e.** will result
2bcb0 20 69 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f   in [SQLITE_ERRO
2bcc0 52 5d 20 62 65 69 6e 67 20 72 65 74 75 72 6e 65  R] being returne
2bcd0 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 68 69  d..**.** The thi
2bce0 72 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  rd parameter is 
2bcf0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 61 72  the number of ar
2bd00 67 75 6d 65 6e 74 73 20 74 68 61 74 20 74 68 65  guments that the
2bd10 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72   SQL function or
2bd20 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20 74 61  .** aggregate ta
2bd30 6b 65 73 2e 20 49 66 20 74 68 69 73 20 70 61 72  kes. If this par
2bd40 61 6d 65 74 65 72 20 69 73 20 6e 65 67 61 74 69  ameter is negati
2bd50 76 65 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c  ve, then the SQL
2bd60 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20   function or.** 
2bd70 61 67 67 72 65 67 61 74 65 20 6d 61 79 20 74 61  aggregate may ta
2bd80 6b 65 20 61 6e 79 20 6e 75 6d 62 65 72 20 6f 66  ke any number of
2bd90 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a   arguments..**.*
2bda0 2a 20 54 68 65 20 66 6f 75 72 74 68 20 70 61 72  * The fourth par
2bdb0 61 6d 65 74 65 72 2c 20 65 54 65 78 74 52 65 70  ameter, eTextRep
2bdc0 2c 20 73 70 65 63 69 66 69 65 73 20 77 68 61 74  , specifies what
2bdd0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 38  .** [SQLITE_UTF8
2bde0 20 7c 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67   | text encoding
2bdf0 5d 20 74 68 69 73 20 53 51 4c 20 66 75 6e 63 74  ] this SQL funct
2be00 69 6f 6e 20 70 72 65 66 65 72 73 20 66 6f 72 0a  ion prefers for.
2be10 2a 2a 20 69 74 73 20 70 61 72 61 6d 65 74 65 72  ** its parameter
2be20 73 2e 20 20 41 6e 79 20 53 51 4c 20 66 75 6e 63  s.  Any SQL func
2be30 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74  tion implementat
2be40 69 6f 6e 20 73 68 6f 75 6c 64 20 62 65 20 61 62  ion should be ab
2be50 6c 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77 6f  le to work.** wo
2be60 72 6b 20 77 69 74 68 20 55 54 46 2d 38 2c 20 55  rk with UTF-8, U
2be70 54 46 2d 31 36 6c 65 2c 20 6f 72 20 55 54 46 2d  TF-16le, or UTF-
2be80 31 36 62 65 2e 20 20 42 75 74 20 73 6f 6d 65 20  16be.  But some 
2be90 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
2bea0 6d 61 79 20 62 65 0a 2a 2a 20 6d 6f 72 65 20 65  may be.** more e
2beb0 66 66 69 63 69 65 6e 74 20 77 69 74 68 20 6f 6e  fficient with on
2bec0 65 20 65 6e 63 6f 64 69 6e 67 20 74 68 61 6e 20  e encoding than 
2bed0 61 6e 6f 74 68 65 72 2e 20 20 49 74 20 69 73 20  another.  It is 
2bee0 61 6c 6c 6f 77 65 64 20 74 6f 0a 2a 2a 20 69 6e  allowed to.** in
2bef0 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63 72 65  voke sqlite3_cre
2bf00 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 20 6f  ate_function() o
2bf10 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  r sqlite3_create
2bf20 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 20 6d 75  _function16() mu
2bf30 6c 74 69 70 6c 65 0a 2a 2a 20 74 69 6d 65 73 20  ltiple.** times 
2bf40 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 66 75  with the same fu
2bf50 6e 63 74 69 6f 6e 20 62 75 74 20 77 69 74 68 20  nction but with 
2bf60 64 69 66 66 65 72 65 6e 74 20 76 61 6c 75 65 73  different values
2bf70 20 6f 66 20 65 54 65 78 74 52 65 70 2e 0a 2a 2a   of eTextRep..**
2bf80 20 57 68 65 6e 20 6d 75 6c 74 69 70 6c 65 20 69   When multiple i
2bf90 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f  mplementations o
2bfa0 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74  f the same funct
2bfb0 69 6f 6e 20 61 72 65 20 61 76 61 69 6c 61 62 6c  ion are availabl
2bfc0 65 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c  e, SQLite.** wil
2bfd0 6c 20 70 69 63 6b 20 74 68 65 20 6f 6e 65 20 74  l pick the one t
2bfe0 68 61 74 20 69 6e 76 6f 6c 76 65 73 20 74 68 65  hat involves the
2bff0 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66   least amount of
2c000 20 64 61 74 61 20 63 6f 6e 76 65 72 73 69 6f 6e   data conversion
2c010 2e 0a 2a 2a 20 49 66 20 74 68 65 72 65 20 69 73  ..** If there is
2c020 20 6f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 69   only a single i
2c030 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 68  mplementation wh
2c040 69 63 68 20 64 6f 65 73 20 6e 6f 74 20 63 61 72  ich does not car
2c050 65 20 77 68 61 74 20 74 65 78 74 0a 2a 2a 20 65  e what text.** e
2c060 6e 63 6f 64 69 6e 67 20 69 73 20 75 73 65 64 2c  ncoding is used,
2c070 20 74 68 65 6e 20 74 68 65 20 66 6f 75 72 74 68   then the fourth
2c080 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64   argument should
2c090 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 4e 59 5d   be [SQLITE_ANY]
2c0a0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 66 74  ..**.** The fift
2c0b0 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  h parameter is a
2c0c0 6e 20 61 72 62 69 74 72 61 72 79 20 70 6f 69 6e  n arbitrary poin
2c0d0 74 65 72 2e 20 20 54 68 65 20 69 6d 70 6c 65 6d  ter.  The implem
2c0e0 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 0a  entation of the.
2c0f0 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20  ** function can 
2c100 67 61 69 6e 20 61 63 63 65 73 73 20 74 6f 20 74  gain access to t
2c110 68 69 73 20 70 6f 69 6e 74 65 72 20 75 73 69 6e  his pointer usin
2c120 67 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f  g [sqlite3_user_
2c130 64 61 74 61 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54  data()]..**.** T
2c140 68 65 20 73 65 76 65 6e 74 68 2c 20 65 69 67 68  he seventh, eigh
2c150 74 68 20 61 6e 64 20 6e 69 6e 74 68 20 70 61 72  th and ninth par
2c160 61 6d 65 74 65 72 73 2c 20 78 46 75 6e 63 2c 20  ameters, xFunc, 
2c170 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61 6c  xStep and xFinal
2c180 2c 20 61 72 65 0a 2a 2a 20 70 6f 69 6e 74 65 72  , are.** pointer
2c190 73 20 74 6f 20 43 2d 6c 61 6e 67 75 61 67 65 20  s to C-language 
2c1a0 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 69  functions that i
2c1b0 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c  mplement the SQL
2c1c0 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20   function or.** 
2c1d0 61 67 67 72 65 67 61 74 65 2e 20 41 20 73 63 61  aggregate. A sca
2c1e0 6c 61 72 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  lar SQL function
2c1f0 20 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d 70   requires an imp
2c200 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74  lementation of t
2c210 68 65 20 78 46 75 6e 63 0a 2a 2a 20 63 61 6c 6c  he xFunc.** call
2c220 62 61 63 6b 20 6f 6e 6c 79 2c 20 4e 55 4c 4c 20  back only, NULL 
2c230 70 6f 69 6e 74 65 72 73 20 73 68 6f 75 6c 64 20  pointers should 
2c240 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65  be passed as the
2c250 20 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61   xStep and xFina
2c260 6c 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 2e  l.** parameters.
2c270 20 41 6e 20 61 67 67 72 65 67 61 74 65 20 53 51   An aggregate SQ
2c280 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69  L function requi
2c290 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74  res an implement
2c2a0 61 74 69 6f 6e 20 6f 66 20 78 53 74 65 70 0a 2a  ation of xStep.*
2c2b0 2a 20 61 6e 64 20 78 46 69 6e 61 6c 20 61 6e 64  * and xFinal and
2c2c0 20 4e 55 4c 4c 20 73 68 6f 75 6c 64 20 62 65 20   NULL should be 
2c2d0 70 61 73 73 65 64 20 66 6f 72 20 78 46 75 6e 63  passed for xFunc
2c2e0 2e 20 54 6f 20 64 65 6c 65 74 65 20 61 6e 20 65  . To delete an e
2c2f0 78 69 73 74 69 6e 67 0a 2a 2a 20 53 51 4c 20 66  xisting.** SQL f
2c300 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65  unction or aggre
2c310 67 61 74 65 2c 20 70 61 73 73 20 4e 55 4c 4c 20  gate, pass NULL 
2c320 66 6f 72 20 61 6c 6c 20 74 68 72 65 65 20 66 75  for all three fu
2c330 6e 63 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 73  nction callbacks
2c340 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73 20 70 65  ..**.** It is pe
2c350 72 6d 69 74 74 65 64 20 74 6f 20 72 65 67 69 73  rmitted to regis
2c360 74 65 72 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70  ter multiple imp
2c370 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20  lementations of 
2c380 74 68 65 20 73 61 6d 65 0a 2a 2a 20 66 75 6e 63  the same.** func
2c390 74 69 6f 6e 73 20 77 69 74 68 20 74 68 65 20 73  tions with the s
2c3a0 61 6d 65 20 6e 61 6d 65 20 62 75 74 20 77 69 74  ame name but wit
2c3b0 68 20 65 69 74 68 65 72 20 64 69 66 66 65 72 69  h either differi
2c3c0 6e 67 20 6e 75 6d 62 65 72 73 20 6f 66 0a 2a 2a  ng numbers of.**
2c3d0 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 64 69   arguments or di
2c3e0 66 66 65 72 69 6e 67 20 70 72 65 66 65 72 72 65  ffering preferre
2c3f0 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73  d text encodings
2c400 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75  .  SQLite will u
2c410 73 65 0a 2a 2a 20 74 68 65 20 69 6d 70 6c 65 6d  se.** the implem
2c420 65 6e 74 61 74 69 6f 6e 20 6d 6f 73 74 20 63 6c  entation most cl
2c430 6f 73 65 6c 79 20 6d 61 74 63 68 65 73 20 74 68  osely matches th
2c440 65 20 77 61 79 20 69 6e 20 77 68 69 63 68 20 74  e way in which t
2c450 68 65 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69  he.** SQL functi
2c460 6f 6e 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a  on is used..**.*
2c470 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
2c480 0a 2a 2a 20 7b 48 31 36 31 30 33 7d 20 54 68 65  .** {H16103} The
2c490 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
2c4a0 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20 69  _function16()] i
2c4b0 6e 74 65 72 66 61 63 65 20 62 65 68 61 76 65 73  nterface behaves
2c4c0 20 65 78 61 63 74 6c 79 0a 2a 2a 20 20 20 20 20   exactly.**     
2c4d0 20 20 20 20 20 6c 69 6b 65 20 5b 73 71 6c 69 74       like [sqlit
2c4e0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
2c4f0 6f 6e 28 29 5d 20 69 6e 20 65 76 65 72 79 20 77  on()] in every w
2c500 61 79 20 65 78 63 65 70 74 20 74 68 61 74 20 69  ay except that i
2c510 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e  t.**          in
2c520 74 65 72 70 72 65 74 73 20 74 68 65 20 7a 46 75  terprets the zFu
2c530 6e 63 74 69 6f 6e 4e 61 6d 65 20 61 72 67 75 6d  nctionName argum
2c540 65 6e 74 20 61 73 20 7a 65 72 6f 2d 74 65 72 6d  ent as zero-term
2c550 69 6e 61 74 65 64 20 55 54 46 2d 31 36 0a 2a 2a  inated UTF-16.**
2c560 20 20 20 20 20 20 20 20 20 20 6e 61 74 69 76 65            native
2c570 20 62 79 74 65 20 6f 72 64 65 72 20 69 6e 73 74   byte order inst
2c580 65 61 64 20 6f 66 20 61 73 20 7a 65 72 6f 2d 74  ead of as zero-t
2c590 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 2e  erminated UTF-8.
2c5a0 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 31 30 36 7d 20  .**.** {H16106} 
2c5b0 41 20 73 75 63 63 65 73 73 66 75 6c 20 69 6e 76  A successful inv
2c5c0 6f 63 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 20 20  ocation of.**   
2c5d0 20 20 20 20 20 20 20 74 68 65 20 5b 73 71 6c 69         the [sqli
2c5e0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
2c5f0 69 6f 6e 28 44 2c 58 2c 4e 2c 45 2c 2e 2e 2e 29  ion(D,X,N,E,...)
2c600 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69  ] interface regi
2c610 73 74 65 72 73 0a 2a 2a 20 20 20 20 20 20 20 20  sters.**        
2c620 20 20 6f 72 20 72 65 70 6c 61 63 65 73 20 63 61    or replaces ca
2c630 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 73  llback functions
2c640 20 69 6e 20 74 68 65 20 5b 64 61 74 61 62 61 73   in the [databas
2c650 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a  e connection] D.
2c660 2a 2a 20 20 20 20 20 20 20 20 20 20 75 73 65 64  **          used
2c670 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68   to implement th
2c680 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6e  e SQL function n
2c690 61 6d 65 64 20 58 20 77 69 74 68 20 4e 20 70 61  amed X with N pa
2c6a0 72 61 6d 65 74 65 72 73 0a 2a 2a 20 20 20 20 20  rameters.**     
2c6b0 20 20 20 20 20 61 6e 64 20 68 61 76 69 6e 67 20       and having 
2c6c0 61 20 70 72 65 66 65 72 72 65 64 20 74 65 78 74  a preferred text
2c6d0 20 65 6e 63 6f 64 69 6e 67 20 6f 66 20 45 2e 0a   encoding of E..
2c6e0 2a 2a 0a 2a 2a 20 7b 48 31 36 31 30 39 7d 20 41  **.** {H16109} A
2c6f0 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c   successful call
2c700 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65   to [sqlite3_cre
2c710 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58  ate_function(D,X
2c720 2c 4e 2c 45 2c 50 2c 46 2c 53 2c 4c 29 5d 0a 2a  ,N,E,P,F,S,L)].*
2c730 2a 20 20 20 20 20 20 20 20 20 20 72 65 70 6c 61  *          repla
2c740 63 65 73 20 74 68 65 20 50 2c 20 46 2c 20 53 2c  ces the P, F, S,
2c750 20 61 6e 64 20 4c 20 76 61 6c 75 65 73 20 66 72   and L values fr
2c760 6f 6d 20 61 6e 79 20 70 72 69 6f 72 20 63 61 6c  om any prior cal
2c770 6c 73 20 77 69 74 68 0a 2a 2a 20 20 20 20 20 20  ls with.**      
2c780 20 20 20 20 74 68 65 20 73 61 6d 65 20 44 2c 20      the same D, 
2c790 58 2c 20 4e 2c 20 61 6e 64 20 45 20 76 61 6c 75  X, N, and E valu
2c7a0 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 31 31  es..**.** {H1611
2c7b0 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  2} The [sqlite3_
2c7c0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
2c7d0 44 2c 58 2c 2e 2e 2e 29 5d 20 69 6e 74 65 72 66  D,X,...)] interf
2c7e0 61 63 65 20 66 61 69 6c 73 20 77 69 74 68 0a 2a  ace fails with.*
2c7f0 2a 20 20 20 20 20 20 20 20 20 20 61 20 72 65 74  *          a ret
2c800 75 72 6e 20 63 6f 64 65 20 6f 66 20 5b 53 51 4c  urn code of [SQL
2c810 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 74 68  ITE_ERROR] if th
2c820 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6e  e SQL function n
2c830 61 6d 65 20 58 20 69 73 0a 2a 2a 20 20 20 20 20  ame X is.**     
2c840 20 20 20 20 20 6c 6f 6e 67 65 72 20 74 68 61 6e       longer than
2c850 20 32 35 35 20 62 79 74 65 73 20 65 78 63 6c 75   255 bytes exclu
2c860 73 69 76 65 20 6f 66 20 74 68 65 20 7a 65 72 6f  sive of the zero
2c870 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 0a   terminator..**.
2c880 2a 2a 20 7b 48 31 36 31 31 38 7d 20 45 69 74 68  ** {H16118} Eith
2c890 65 72 20 46 20 6d 75 73 74 20 62 65 20 4e 55 4c  er F must be NUL
2c8a0 4c 20 61 6e 64 20 53 20 61 6e 64 20 4c 20 61 72  L and S and L ar
2c8b0 65 20 6e 6f 6e 2d 4e 55 4c 4c 20 6f 72 20 65 6c  e non-NULL or el
2c8c0 73 65 20 46 0a 2a 2a 20 20 20 20 20 20 20 20 20  se F.**         
2c8d0 20 69 73 20 6e 6f 6e 2d 4e 55 4c 4c 20 61 6e 64   is non-NULL and
2c8e0 20 53 20 61 6e 64 20 4c 20 61 72 65 20 4e 55 4c   S and L are NUL
2c8f0 4c 2c 20 6f 74 68 65 72 77 69 73 65 0a 2a 2a 20  L, otherwise.** 
2c900 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
2c910 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
2c920 6e 28 44 2c 58 2c 4e 2c 45 2c 50 2c 46 2c 53 2c  n(D,X,N,E,P,F,S,
2c930 4c 29 5d 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  L)] returns [SQL
2c940 49 54 45 5f 45 52 52 4f 52 5d 2e 0a 2a 2a 0a 2a  ITE_ERROR]..**.*
2c950 2a 20 7b 48 31 36 31 32 31 7d 20 54 68 65 20 5b  * {H16121} The [
2c960 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
2c970 75 6e 63 74 69 6f 6e 28 44 2c 2e 2e 2e 29 5d 20  unction(D,...)] 
2c980 69 6e 74 65 72 66 61 63 65 20 66 61 69 6c 73 20  interface fails 
2c990 77 69 74 68 20 61 6e 0a 2a 2a 20 20 20 20 20 20  with an.**      
2c9a0 20 20 20 20 65 72 72 6f 72 20 63 6f 64 65 20 6f      error code o
2c9b0 66 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20  f [SQLITE_BUSY] 
2c9c0 69 66 20 74 68 65 72 65 20 65 78 69 73 74 20 5b  if there exist [
2c9d0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2c9e0 6e 74 73 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  nts].**         
2c9f0 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
2ca00 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
2ca10 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2e 0a 2a 2a  onnection] D..**
2ca20 0a 2a 2a 20 7b 48 31 36 31 32 34 7d 20 54 68 65  .** {H16124} The
2ca30 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
2ca40 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c  _function(D,X,N,
2ca50 2e 2e 2e 29 5d 20 69 6e 74 65 72 66 61 63 65 20  ...)] interface 
2ca60 66 61 69 6c 73 20 77 69 74 68 20 61 6e 0a 2a 2a  fails with an.**
2ca70 20 20 20 20 20 20 20 20 20 20 65 72 72 6f 72 20            error 
2ca80 63 6f 64 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f  code of [SQLITE_
2ca90 45 52 52 4f 52 5d 20 69 66 20 70 61 72 61 6d 65  ERROR] if parame
2caa0 74 65 72 20 4e 20 28 73 70 65 63 69 66 79 69 6e  ter N (specifyin
2cab0 67 20 74 68 65 20 6e 75 6d 62 65 72 0a 2a 2a 20  g the number.** 
2cac0 20 20 20 20 20 20 20 20 20 6f 66 20 61 72 67 75           of argu
2cad0 6d 65 6e 74 73 20 74 6f 20 74 68 65 20 53 51 4c  ments to the SQL
2cae0 20 66 75 6e 63 74 69 6f 6e 20 62 65 69 6e 67 20   function being 
2caf0 72 65 67 69 73 74 65 72 65 64 29 20 69 73 20 6c  registered) is l
2cb00 65 73 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ess.**          
2cb10 74 68 61 6e 20 2d 31 20 6f 72 20 67 72 65 61 74  than -1 or great
2cb20 65 72 20 74 68 61 6e 20 31 32 37 2e 0a 2a 2a 0a  er than 127..**.
2cb30 2a 2a 20 7b 48 31 36 31 32 37 7d 20 57 68 65 6e  ** {H16127} When
2cb40 20 4e 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69   N is non-negati
2cb50 76 65 2c 20 74 68 65 20 5b 73 71 6c 69 74 65 33  ve, the [sqlite3
2cb60 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
2cb70 28 44 2c 58 2c 4e 2c 2e 2e 2e 29 5d 0a 2a 2a 20  (D,X,N,...)].** 
2cb80 20 20 20 20 20 20 20 20 20 69 6e 74 65 72 66 61           interfa
2cb90 63 65 20 63 61 75 73 65 73 20 63 61 6c 6c 62 61  ce causes callba
2cba0 63 6b 73 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65  cks to be invoke
2cbb0 64 20 66 6f 72 20 74 68 65 20 53 51 4c 20 66 75  d for the SQL fu
2cbc0 6e 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20  nction.**       
2cbd0 20 20 20 6e 61 6d 65 64 20 58 20 77 68 65 6e 20     named X when 
2cbe0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 61 72  the number of ar
2cbf0 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 65 20 53  guments to the S
2cc00 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 0a 2a  QL function is.*
2cc10 2a 20 20 20 20 20 20 20 20 20 20 65 78 61 63 74  *          exact
2cc20 6c 79 20 4e 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36  ly N..**.** {H16
2cc30 31 33 30 7d 20 57 68 65 6e 20 4e 20 69 73 20 2d  130} When N is -
2cc40 31 2c 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  1, the [sqlite3_
2cc50 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
2cc60 44 2c 58 2c 4e 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20  D,X,N,...)].**  
2cc70 20 20 20 20 20 20 20 20 69 6e 74 65 72 66 61 63          interfac
2cc80 65 20 63 61 75 73 65 73 20 63 61 6c 6c 62 61 63  e causes callbac
2cc90 6b 73 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64  ks to be invoked
2cca0 20 66 6f 72 20 74 68 65 20 53 51 4c 20 66 75 6e   for the SQL fun
2ccb0 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20  ction.**        
2ccc0 20 20 6e 61 6d 65 64 20 58 20 77 69 74 68 20 61    named X with a
2ccd0 6e 79 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67  ny number of arg
2cce0 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48  uments..**.** {H
2ccf0 31 36 31 33 33 7d 20 57 68 65 6e 20 63 61 6c 6c  16133} When call
2cd00 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72  s to [sqlite3_cr
2cd10 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c  eate_function(D,
2cd20 58 2c 4e 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20  X,N,...)].**    
2cd30 20 20 20 20 20 20 73 70 65 63 69 66 79 20 6d 75        specify mu
2cd40 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74  ltiple implement
2cd50 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61  ations of the sa
2cd60 6d 65 20 66 75 6e 63 74 69 6f 6e 20 58 0a 2a 2a  me function X.**
2cd70 20 20 20 20 20 20 20 20 20 20 61 6e 64 20 77 68            and wh
2cd80 65 6e 20 6f 6e 65 20 69 6d 70 6c 65 6d 65 6e 74  en one implement
2cd90 61 74 69 6f 6e 20 68 61 73 20 4e 3e 3d 30 20 61  ation has N>=0 a
2cda0 6e 64 20 74 68 65 20 6f 74 68 65 72 20 68 61 73  nd the other has
2cdb0 20 4e 3d 28 2d 31 29 0a 2a 2a 20 20 20 20 20 20   N=(-1).**      
2cdc0 20 20 20 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e      the implemen
2cdd0 74 61 74 69 6f 6e 20 77 69 74 68 20 61 20 6e 6f  tation with a no
2cde0 6e 2d 7a 65 72 6f 20 4e 20 69 73 20 70 72 65 66  n-zero N is pref
2cdf0 65 72 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  erred..**.** {H1
2ce00 36 31 33 36 7d 20 57 68 65 6e 20 63 61 6c 6c 73  6136} When calls
2ce10 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65   to [sqlite3_cre
2ce20 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58  ate_function(D,X
2ce30 2c 4e 2c 45 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20  ,N,E,...)].**   
2ce40 20 20 20 20 20 20 20 73 70 65 63 69 66 79 20 6d         specify m
2ce50 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e  ultiple implemen
2ce60 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73  tations of the s
2ce70 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 58 20 77  ame function X w
2ce80 69 74 68 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ith.**          
2ce90 74 68 65 20 73 61 6d 65 20 6e 75 6d 62 65 72 20  the same number 
2cea0 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 4e 20 62  of arguments N b
2ceb0 75 74 20 77 69 74 68 20 64 69 66 66 65 72 65 6e  ut with differen
2cec0 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 65 6e  t.**          en
2ced0 63 6f 64 69 6e 67 73 20 45 2c 20 74 68 65 6e 20  codings E, then 
2cee0 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  the implementati
2cef0 6f 6e 20 77 68 65 72 65 20 45 20 6d 61 74 63 68  on where E match
2cf00 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  es the.**       
2cf10 20 20 20 64 61 74 61 62 61 73 65 20 65 6e 63 6f     database enco
2cf20 64 69 6e 67 20 69 73 20 70 72 65 66 65 72 72 65  ding is preferre
2cf30 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 31 33 39  d..**.** {H16139
2cf40 7d 20 46 6f 72 20 61 6e 20 61 67 67 72 65 67 61  } For an aggrega
2cf50 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  te SQL function 
2cf60 63 72 65 61 74 65 64 20 75 73 69 6e 67 0a 2a 2a  created using.**
2cf70 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
2cf80 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
2cf90 6f 6e 28 44 2c 58 2c 4e 2c 45 2c 50 2c 30 2c 53  on(D,X,N,E,P,0,S
2cfa0 2c 4c 29 5d 20 74 68 65 20 66 69 6e 61 6c 69 7a  ,L)] the finaliz
2cfb0 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66  er.**          f
2cfc0 75 6e 63 74 69 6f 6e 20 4c 20 77 69 6c 6c 20 61  unction L will a
2cfd0 6c 77 61 79 73 20 62 65 20 69 6e 76 6f 6b 65 64  lways be invoked
2cfe0 20 65 78 61 63 74 6c 79 20 6f 6e 63 65 20 69 66   exactly once if
2cff0 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
2d000 20 73 74 65 70 20 66 75 6e 63 74 69 6f 6e 20 53   step function S
2d010 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 65 20 6f   is called one o
2d020 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a  r more times..**
2d030 0a 2a 2a 20 7b 48 31 36 31 34 32 7d 20 57 68 65  .** {H16142} Whe
2d040 6e 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73  n SQLite invokes
2d050 20 65 69 74 68 65 72 20 74 68 65 20 78 46 75 6e   either the xFun
2d060 63 20 6f 72 20 78 53 74 65 70 20 66 75 6e 63 74  c or xStep funct
2d070 69 6f 6e 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20  ion of.**       
2d080 20 20 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f     an applicatio
2d090 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75  n-defined SQL fu
2d0a0 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67  nction or aggreg
2d0b0 61 74 65 20 63 72 65 61 74 65 64 0a 2a 2a 20 20  ate created.**  
2d0c0 20 20 20 20 20 20 20 20 62 79 20 5b 73 71 6c 69          by [sqli
2d0d0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
2d0e0 69 6f 6e 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  ion()] or [sqlit
2d0f0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
2d100 6f 6e 31 36 28 29 5d 2c 0a 2a 2a 20 20 20 20 20  on16()],.**     
2d110 20 20 20 20 20 74 68 65 6e 20 74 68 65 20 61 72       then the ar
2d120 72 61 79 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f  ray of [sqlite3_
2d130 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 20 70  value] objects p
2d140 61 73 73 65 64 20 61 73 20 74 68 65 0a 2a 2a 20  assed as the.** 
2d150 20 20 20 20 20 20 20 20 20 74 68 69 72 64 20 70           third p
2d160 61 72 61 6d 65 74 65 72 20 61 72 65 20 61 6c 77  arameter are alw
2d170 61 79 73 20 5b 70 72 6f 74 65 63 74 65 64 20 73  ays [protected s
2d180 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
2d190 6a 65 63 74 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71  jects..*/.int sq
2d1a0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
2d1b0 63 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33  ction(.  sqlite3
2d1c0 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68   *db,.  const ch
2d1d0 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d  ar *zFunctionNam
2d1e0 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20  e,.  int nArg,. 
2d1f0 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20   int eTextRep,. 
2d200 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76   void *pApp,.  v
2d210 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c  oid (*xFunc)(sql
2d220 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e  ite3_context*,in
2d230 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t,sqlite3_value*
2d240 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74  *),.  void (*xSt
2d250 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ep)(sqlite3_cont
2d260 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33  ext*,int,sqlite3
2d270 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69  _value**),.  voi
2d280 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69  d (*xFinal)(sqli
2d290 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b  te3_context*).);
2d2a0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65  .int sqlite3_cre
2d2b0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 0a  ate_function16(.
2d2c0 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20    sqlite3 *db,. 
2d2d0 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 46 75   const void *zFu
2d2e0 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e  nctionName,.  in
2d2f0 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54  t nArg,.  int eT
2d300 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a  extRep,.  void *
2d310 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78  pApp,.  void (*x
2d320 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f  Func)(sqlite3_co
2d330 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74  ntext*,int,sqlit
2d340 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76  e3_value**),.  v
2d350 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c  oid (*xStep)(sql
2d360 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e  ite3_context*,in
2d370 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t,sqlite3_value*
2d380 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69  *),.  void (*xFi
2d390 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  nal)(sqlite3_con
2d3a0 74 65 78 74 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  text*).);../*.**
2d3b0 20 43 41 50 49 33 52 45 46 3a 20 54 65 78 74 20   CAPI3REF: Text 
2d3c0 45 6e 63 6f 64 69 6e 67 73 20 7b 48 31 30 32 36  Encodings {H1026
2d3d0 37 7d 20 3c 53 35 30 32 30 30 3e 20 3c 48 31 36  7} <S50200> <H16
2d3e0 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  100>.**.** These
2d3f0 20 63 6f 6e 73 74 61 6e 74 20 64 65 66 69 6e 65   constant define
2d400 20 69 6e 74 65 67 65 72 20 63 6f 64 65 73 20 74   integer codes t
2d410 68 61 74 20 72 65 70 72 65 73 65 6e 74 20 74 68  hat represent th
2d420 65 20 76 61 72 69 6f 75 73 0a 2a 2a 20 74 65 78  e various.** tex
2d430 74 20 65 6e 63 6f 64 69 6e 67 73 20 73 75 70 70  t encodings supp
2d440 6f 72 74 65 64 20 62 79 20 53 51 4c 69 74 65 2e  orted by SQLite.
2d450 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
2d460 54 45 5f 55 54 46 38 20 20 20 20 20 20 20 20 20  TE_UTF8         
2d470 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    1.#define SQLI
2d480 54 45 5f 55 54 46 31 36 4c 45 20 20 20 20 20 20  TE_UTF16LE      
2d490 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    2.#define SQLI
2d4a0 54 45 5f 55 54 46 31 36 42 45 20 20 20 20 20 20  TE_UTF16BE      
2d4b0 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    3.#define SQLI
2d4c0 54 45 5f 55 54 46 31 36 20 20 20 20 20 20 20 20  TE_UTF16        
2d4d0 20 20 34 20 20 20 20 2f 2a 20 55 73 65 20 6e 61    4    /* Use na
2d4e0 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20  tive byte order 
2d4f0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
2d500 45 5f 41 4e 59 20 20 20 20 20 20 20 20 20 20 20  E_ANY           
2d510 20 35 20 20 20 20 2f 2a 20 73 71 6c 69 74 65 33   5    /* sqlite3
2d520 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
2d530 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
2d540 20 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c   SQLITE_UTF16_AL
2d550 49 47 4e 45 44 20 20 38 20 20 20 20 2f 2a 20 73  IGNED  8    /* s
2d560 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
2d570 6c 6c 61 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a  llation only */.
2d580 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2d590 20 44 65 70 72 65 63 61 74 65 64 20 46 75 6e 63   Deprecated Func
2d5a0 74 69 6f 6e 73 0a 2a 2a 20 44 45 50 52 45 43 41  tions.** DEPRECA
2d5b0 54 45 44 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  TED.**.** These 
2d5c0 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 5b 64  functions are [d
2d5d0 65 70 72 65 63 61 74 65 64 5d 2e 20 20 49 6e 20  eprecated].  In 
2d5e0 6f 72 64 65 72 20 74 6f 20 6d 61 69 6e 74 61 69  order to maintai
2d5f0 6e 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 63  n.** backwards c
2d600 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 77 69 74  ompatibility wit
2d610 68 20 6f 6c 64 65 72 20 63 6f 64 65 2c 20 74 68  h older code, th
2d620 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 63 6f  ese functions co
2d630 6e 74 69 6e 75 65 20 0a 2a 2a 20 74 6f 20 62 65  ntinue .** to be
2d640 20 73 75 70 70 6f 72 74 65 64 2e 20 20 48 6f 77   supported.  How
2d650 65 76 65 72 2c 20 6e 65 77 20 61 70 70 6c 69 63  ever, new applic
2d660 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 61 76  ations should av
2d670 6f 69 64 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f  oid.** the use o
2d680 66 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  f these function
2d690 73 2e 20 20 54 6f 20 68 65 6c 70 20 65 6e 63 6f  s.  To help enco
2d6a0 75 72 61 67 65 20 70 65 6f 70 6c 65 20 74 6f 20  urage people to 
2d6b0 61 76 6f 69 64 0a 2a 2a 20 75 73 69 6e 67 20 74  avoid.** using t
2d6c0 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2c 20  hese functions, 
2d6d0 77 65 20 61 72 65 20 6e 6f 74 20 67 6f 69 6e 67  we are not going
2d6e0 20 74 6f 20 74 65 6c 6c 20 79 6f 75 20 77 61 6e   to tell you wan
2d6f0 74 20 74 68 65 79 20 64 6f 2e 0a 2a 2f 0a 53 51  t they do..*/.SQ
2d700 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20  LITE_DEPRECATED 
2d710 69 6e 74 20 73 71 6c 69 74 65 33 5f 61 67 67 72  int sqlite3_aggr
2d720 65 67 61 74 65 5f 63 6f 75 6e 74 28 73 71 6c 69  egate_count(sqli
2d730 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 53  te3_context*);.S
2d740 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44  QLITE_DEPRECATED
2d750 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 70   int sqlite3_exp
2d760 69 72 65 64 28 73 71 6c 69 74 65 33 5f 73 74 6d  ired(sqlite3_stm
2d770 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52  t*);.SQLITE_DEPR
2d780 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74  ECATED int sqlit
2d790 65 33 5f 74 72 61 6e 73 66 65 72 5f 62 69 6e 64  e3_transfer_bind
2d7a0 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d  ings(sqlite3_stm
2d7b0 74 2a 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  t*, sqlite3_stmt
2d7c0 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45  *);.SQLITE_DEPRE
2d7d0 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65  CATED int sqlite
2d7e0 33 5f 67 6c 6f 62 61 6c 5f 72 65 63 6f 76 65 72  3_global_recover
2d7f0 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 44  (void);.SQLITE_D
2d800 45 50 52 45 43 41 54 45 44 20 76 6f 69 64 20 73  EPRECATED void s
2d810 71 6c 69 74 65 33 5f 74 68 72 65 61 64 5f 63 6c  qlite3_thread_cl
2d820 65 61 6e 75 70 28 76 6f 69 64 29 3b 0a 53 51 4c  eanup(void);.SQL
2d830 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69  ITE_DEPRECATED i
2d840 6e 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  nt sqlite3_memor
2d850 79 5f 61 6c 61 72 6d 28 76 6f 69 64 28 2a 29 28  y_alarm(void(*)(
2d860 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e  void*,sqlite3_in
2d870 74 36 34 2c 69 6e 74 29 2c 76 6f 69 64 2a 2c 73  t64,int),void*,s
2d880 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 0a  qlite3_int64);..
2d890 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2d8a0 4f 62 74 61 69 6e 69 6e 67 20 53 51 4c 20 46 75  Obtaining SQL Fu
2d8b0 6e 63 74 69 6f 6e 20 50 61 72 61 6d 65 74 65 72  nction Parameter
2d8c0 20 56 61 6c 75 65 73 20 7b 48 31 35 31 30 30 7d   Values {H15100}
2d8d0 20 3c 53 32 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20   <S20200>.**.** 
2d8e0 54 68 65 20 43 2d 6c 61 6e 67 75 61 67 65 20 69  The C-language i
2d8f0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
2d900 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61   SQL functions a
2d910 6e 64 20 61 67 67 72 65 67 61 74 65 73 20 75 73  nd aggregates us
2d920 65 73 0a 2a 2a 20 74 68 69 73 20 73 65 74 20 6f  es.** this set o
2d930 66 20 69 6e 74 65 72 66 61 63 65 20 72 6f 75 74  f interface rout
2d940 69 6e 65 73 20 74 6f 20 61 63 63 65 73 73 20 74  ines to access t
2d950 68 65 20 70 61 72 61 6d 65 74 65 72 20 76 61 6c  he parameter val
2d960 75 65 73 20 6f 6e 0a 2a 2a 20 74 68 65 20 66 75  ues on.** the fu
2d970 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67  nction or aggreg
2d980 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  ate..**.** The x
2d990 46 75 6e 63 20 28 66 6f 72 20 73 63 61 6c 61 72  Func (for scalar
2d9a0 20 66 75 6e 63 74 69 6f 6e 73 29 20 6f 72 20 78   functions) or x
2d9b0 53 74 65 70 20 28 66 6f 72 20 61 67 67 72 65 67  Step (for aggreg
2d9c0 61 74 65 73 29 20 70 61 72 61 6d 65 74 65 72 73  ates) parameters
2d9d0 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  .** to [sqlite3_
2d9e0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
2d9f0 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
2da00 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31  create_function1
2da10 36 28 29 5d 0a 2a 2a 20 64 65 66 69 6e 65 20 63  6()].** define c
2da20 61 6c 6c 62 61 63 6b 73 20 74 68 61 74 20 69 6d  allbacks that im
2da30 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 20  plement the SQL 
2da40 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67  functions and ag
2da50 67 72 65 67 61 74 65 73 2e 0a 2a 2a 20 54 68 65  gregates..** The
2da60 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   4th parameter t
2da70 6f 20 74 68 65 73 65 20 63 61 6c 6c 62 61 63 6b  o these callback
2da80 73 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66  s is an array of
2da90 20 70 6f 69 6e 74 65 72 73 20 74 6f 0a 2a 2a 20   pointers to.** 
2daa0 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  [protected sqlit
2dab0 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
2dac0 73 2e 20 20 54 68 65 72 65 20 69 73 20 6f 6e 65  s.  There is one
2dad0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d   [sqlite3_value]
2dae0 20 6f 62 6a 65 63 74 20 66 6f 72 0a 2a 2a 20 65   object for.** e
2daf0 61 63 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ach parameter to
2db00 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
2db10 6e 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e  n.  These routin
2db20 65 73 20 61 72 65 20 75 73 65 64 20 74 6f 0a 2a  es are used to.*
2db30 2a 20 65 78 74 72 61 63 74 20 76 61 6c 75 65 73  * extract values
2db40 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74   from the [sqlit
2db50 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
2db60 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  s..**.** These r
2db70 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20 6f 6e 6c  outines work onl
2db80 79 20 77 69 74 68 20 5b 70 72 6f 74 65 63 74 65  y with [protecte
2db90 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
2dba0 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 41 6e 79   objects..** Any
2dbb0 20 61 74 74 65 6d 70 74 20 74 6f 20 75 73 65 20   attempt to use 
2dbc0 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f  these routines o
2dbd0 6e 20 61 6e 20 5b 75 6e 70 72 6f 74 65 63 74 65  n an [unprotecte
2dbe0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
2dbf0 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 73 75 6c  .** object resul
2dc00 74 73 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20  ts in undefined 
2dc10 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20  behavior..**.** 
2dc20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77  These routines w
2dc30 6f 72 6b 20 6a 75 73 74 20 6c 69 6b 65 20 74 68  ork just like th
2dc40 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20  e corresponding 
2dc50 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66  [column access f
2dc60 75 6e 63 74 69 6f 6e 73 5d 0a 2a 2a 20 65 78 63  unctions].** exc
2dc70 65 70 74 20 74 68 61 74 20 20 74 68 65 73 65 20  ept that  these 
2dc80 72 6f 75 74 69 6e 65 73 20 74 61 6b 65 20 61 20  routines take a 
2dc90 73 69 6e 67 6c 65 20 5b 70 72 6f 74 65 63 74 65  single [protecte
2dca0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
2dcb0 20 6f 62 6a 65 63 74 0a 2a 2a 20 70 6f 69 6e 74   object.** point
2dcc0 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20  er instead of a 
2dcd0 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 20  [sqlite3_stmt*] 
2dce0 70 6f 69 6e 74 65 72 20 61 6e 64 20 61 6e 20 69  pointer and an i
2dcf0 6e 74 65 67 65 72 20 63 6f 6c 75 6d 6e 20 6e 75  nteger column nu
2dd00 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  mber..**.** The 
2dd10 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
2dd20 78 74 31 36 28 29 20 69 6e 74 65 72 66 61 63 65  xt16() interface
2dd30 20 65 78 74 72 61 63 74 73 20 61 20 55 54 46 2d   extracts a UTF-
2dd40 31 36 20 73 74 72 69 6e 67 0a 2a 2a 20 69 6e 20  16 string.** in 
2dd50 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 2d  the native byte-
2dd60 6f 72 64 65 72 20 6f 66 20 74 68 65 20 68 6f 73  order of the hos
2dd70 74 20 6d 61 63 68 69 6e 65 2e 20 20 54 68 65 0a  t machine.  The.
2dd80 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ** sqlite3_value
2dd90 5f 74 65 78 74 31 36 62 65 28 29 20 61 6e 64 20  _text16be() and 
2dda0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
2ddb0 78 74 31 36 6c 65 28 29 20 69 6e 74 65 72 66 61  xt16le() interfa
2ddc0 63 65 73 0a 2a 2a 20 65 78 74 72 61 63 74 20 55  ces.** extract U
2ddd0 54 46 2d 31 36 20 73 74 72 69 6e 67 73 20 61 73  TF-16 strings as
2dde0 20 62 69 67 2d 65 6e 64 69 61 6e 20 61 6e 64 20   big-endian and 
2ddf0 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e 20 72 65  little-endian re
2de00 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a  spectively..**.*
2de10 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61  * The sqlite3_va
2de20 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65  lue_numeric_type
2de30 28 29 20 69 6e 74 65 72 66 61 63 65 20 61 74 74  () interface att
2de40 65 6d 70 74 73 20 74 6f 20 61 70 70 6c 79 0a 2a  empts to apply.*
2de50 2a 20 6e 75 6d 65 72 69 63 20 61 66 66 69 6e 69  * numeric affini
2de60 74 79 20 74 6f 20 74 68 65 20 76 61 6c 75 65 2e  ty to the value.
2de70 20 20 54 68 69 73 20 6d 65 61 6e 73 20 74 68 61    This means tha
2de80 74 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73 0a  t an attempt is.
2de90 2a 2a 20 6d 61 64 65 20 74 6f 20 63 6f 6e 76 65  ** made to conve
2dea0 72 74 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20  rt the value to 
2deb0 61 6e 20 69 6e 74 65 67 65 72 20 6f 72 20 66 6c  an integer or fl
2dec0 6f 61 74 69 6e 67 20 70 6f 69 6e 74 2e 20 20 49  oating point.  I
2ded0 66 0a 2a 2a 20 73 75 63 68 20 61 20 63 6f 6e 76  f.** such a conv
2dee0 65 72 73 69 6f 6e 20 69 73 20 70 6f 73 73 69 62  ersion is possib
2def0 6c 65 20 77 69 74 68 6f 75 74 20 6c 6f 73 73 20  le without loss 
2df00 6f 66 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 28  of information (
2df10 69 6e 20 6f 74 68 65 72 0a 2a 2a 20 77 6f 72 64  in other.** word
2df20 73 2c 20 69 66 20 74 68 65 20 76 61 6c 75 65 20  s, if the value 
2df30 69 73 20 61 20 73 74 72 69 6e 67 20 74 68 61 74  is a string that
2df40 20 6c 6f 6f 6b 73 20 6c 69 6b 65 20 61 20 6e 75   looks like a nu
2df50 6d 62 65 72 29 0a 2a 2a 20 74 68 65 6e 20 74 68  mber).** then th
2df60 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20  e conversion is 
2df70 70 65 72 66 6f 72 6d 65 64 2e 20 20 4f 74 68 65  performed.  Othe
2df80 72 77 69 73 65 20 6e 6f 20 63 6f 6e 76 65 72 73  rwise no convers
2df90 69 6f 6e 20 6f 63 63 75 72 73 2e 0a 2a 2a 20 54  ion occurs..** T
2dfa0 68 65 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47  he [SQLITE_INTEG
2dfb0 45 52 20 7c 20 64 61 74 61 74 79 70 65 5d 20 61  ER | datatype] a
2dfc0 66 74 65 72 20 63 6f 6e 76 65 72 73 69 6f 6e 20  fter conversion 
2dfd0 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  is returned..**.
2dfe0 2a 2a 20 50 6c 65 61 73 65 20 70 61 79 20 70 61  ** Please pay pa
2dff0 72 74 69 63 75 6c 61 72 20 61 74 74 65 6e 74 69  rticular attenti
2e000 6f 6e 20 74 6f 20 74 68 65 20 66 61 63 74 20 74  on to the fact t
2e010 68 61 74 20 74 68 65 20 70 6f 69 6e 74 65 72 20  hat the pointer 
2e020 72 65 74 75 72 6e 65 64 0a 2a 2a 20 66 72 6f 6d  returned.** from
2e030 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
2e040 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65  blob()], [sqlite
2e050 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c  3_value_text()],
2e060 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
2e070 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 20  value_text16()] 
2e080 63 61 6e 20 62 65 20 69 6e 76 61 6c 69 64 61 74  can be invalidat
2e090 65 64 20 62 79 20 61 20 73 75 62 73 65 71 75 65  ed by a subseque
2e0a0 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73  nt call to.** [s
2e0b0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74  qlite3_value_byt
2e0c0 65 73 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  es()], [sqlite3_
2e0d0 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28 29 5d  value_bytes16()]
2e0e0 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  , [sqlite3_value
2e0f0 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20  _text()],.** or 
2e100 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
2e110 65 78 74 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  ext16()]..**.** 
2e120 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d  These routines m
2e130 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72  ust be called fr
2e140 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65  om the same thre
2e150 61 64 20 61 73 0a 2a 2a 20 74 68 65 20 53 51 4c  ad as.** the SQL
2e160 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 73   function that s
2e170 75 70 70 6c 69 65 64 20 74 68 65 20 5b 73 71 6c  upplied the [sql
2e180 69 74 65 33 5f 76 61 6c 75 65 2a 5d 20 70 61 72  ite3_value*] par
2e190 61 6d 65 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 49  ameters..**.** I
2e1a0 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
2e1b0 20 7b 48 31 35 31 30 33 7d 20 54 68 65 20 5b 73   {H15103} The [s
2e1c0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f  qlite3_value_blo
2e1d0 62 28 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20  b(V)] interface 
2e1e0 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20  converts the.** 
2e1f0 20 20 20 20 20 20 20 20 20 5b 70 72 6f 74 65 63           [protec
2e200 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
2e210 65 5d 20 6f 62 6a 65 63 74 20 56 20 69 6e 74 6f  e] object V into
2e220 20 61 20 42 4c 4f 42 20 61 6e 64 20 74 68 65 6e   a BLOB and then
2e230 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74  .**          ret
2e240 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
2e250 6f 20 74 68 65 20 63 6f 6e 76 65 72 74 65 64 20  o the converted 
2e260 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  value..**.** {H1
2e270 35 31 30 36 7d 20 54 68 65 20 5b 73 71 6c 69 74  5106} The [sqlit
2e280 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 56  e3_value_bytes(V
2e290 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  )] interface ret
2e2a0 75 72 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20 20  urns the.**     
2e2b0 20 20 20 20 20 6e 75 6d 62 65 72 20 6f 66 20 62       number of b
2e2c0 79 74 65 73 20 69 6e 20 74 68 65 20 42 4c 4f 42  ytes in the BLOB
2e2d0 20 6f 72 20 73 74 72 69 6e 67 20 28 65 78 63 6c   or string (excl
2e2e0 75 73 69 76 65 20 6f 66 20 74 68 65 0a 2a 2a 20  usive of the.** 
2e2f0 20 20 20 20 20 20 20 20 20 7a 65 72 6f 20 74 65           zero te
2e300 72 6d 69 6e 61 74 6f 72 20 6f 6e 20 74 68 65 20  rminator on the 
2e310 73 74 72 69 6e 67 29 20 74 68 61 74 20 77 61 73  string) that was
2e320 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65   returned by the
2e330 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 6f 73  .**          mos
2e340 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f  t recent call to
2e350 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
2e360 62 6c 6f 62 28 56 29 5d 20 6f 72 0a 2a 2a 20 20  blob(V)] or.**  
2e370 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
2e380 5f 76 61 6c 75 65 5f 74 65 78 74 28 56 29 5d 2e  _value_text(V)].
2e390 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 31 30 39 7d 20  .**.** {H15109} 
2e3a0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  The [sqlite3_val
2e3b0 75 65 5f 62 79 74 65 73 31 36 28 56 29 5d 20 69  ue_bytes16(V)] i
2e3c0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
2e3d0 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
2e3e0 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
2e3f0 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67 20 28   in the string (
2e400 65 78 63 6c 75 73 69 76 65 20 6f 66 20 74 68 65  exclusive of the
2e410 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 7a 65 72  .**          zer
2e420 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 6f 6e 20  o terminator on 
2e430 74 68 65 20 73 74 72 69 6e 67 29 20 74 68 61 74  the string) that
2e440 20 77 61 73 20 72 65 74 75 72 6e 65 64 20 62 79   was returned by
2e450 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
2e460 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c   most recent cal
2e470 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 76 61  l to [sqlite3_va
2e480 6c 75 65 5f 74 65 78 74 31 36 28 56 29 5d 2c 0a  lue_text16(V)],.
2e490 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
2e4a0 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
2e4b0 36 62 65 28 56 29 5d 2c 20 6f 72 20 5b 73 71 6c  6be(V)], or [sql
2e4c0 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
2e4d0 36 6c 65 28 56 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b  6le(V)]..**.** {
2e4e0 48 31 35 31 31 32 7d 20 54 68 65 20 5b 73 71 6c  H15112} The [sql
2e4f0 69 74 65 33 5f 76 61 6c 75 65 5f 64 6f 75 62 6c  ite3_value_doubl
2e500 65 28 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20  e(V)] interface 
2e510 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20  converts the.** 
2e520 20 20 20 20 20 20 20 20 20 5b 70 72 6f 74 65 63           [protec
2e530 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
2e540 65 5d 20 6f 62 6a 65 63 74 20 56 20 69 6e 74 6f  e] object V into
2e550 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e   a floating poin
2e560 74 20 76 61 6c 75 65 20 61 6e 64 0a 2a 2a 20 20  t value and.**  
2e570 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 73 20          returns 
2e580 61 20 63 6f 70 79 20 6f 66 20 74 68 61 74 20 76  a copy of that v
2e590 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35  alue..**.** {H15
2e5a0 31 31 35 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  115} The [sqlite
2e5b0 33 5f 76 61 6c 75 65 5f 69 6e 74 28 56 29 5d 20  3_value_int(V)] 
2e5c0 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72  interface conver
2e5d0 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  ts the.**       
2e5e0 20 20 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71     [protected sq
2e5f0 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
2e600 65 63 74 20 56 20 69 6e 74 6f 20 61 20 36 34 2d  ect V into a 64-
2e610 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67  bit signed integ
2e620 65 72 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20  er and.**       
2e630 20 20 20 72 65 74 75 72 6e 73 20 74 68 65 20 6c     returns the l
2e640 6f 77 65 72 20 33 32 20 62 69 74 73 20 6f 66 20  ower 32 bits of 
2e650 74 68 61 74 20 69 6e 74 65 67 65 72 2e 0a 2a 2a  that integer..**
2e660 0a 2a 2a 20 7b 48 31 35 31 31 38 7d 20 54 68 65  .** {H15118} The
2e670 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
2e680 69 6e 74 36 34 28 56 29 5d 20 69 6e 74 65 72 66  int64(V)] interf
2e690 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65  ace converts the
2e6a0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72  .**          [pr
2e6b0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
2e6c0 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56 20  value] object V 
2e6d0 69 6e 74 6f 20 61 20 36 34 2d 62 69 74 20 73 69  into a 64-bit si
2e6e0 67 6e 65 64 20 69 6e 74 65 67 65 72 20 61 6e 64  gned integer and
2e6f0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74  .**          ret
2e700 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 20 74  urns a copy of t
2e710 68 61 74 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a  hat integer..**.
2e720 2a 2a 20 7b 48 31 35 31 32 31 7d 20 54 68 65 20  ** {H15121} The 
2e730 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
2e740 65 78 74 28 56 29 5d 20 69 6e 74 65 72 66 61 63  ext(V)] interfac
2e750 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a  e converts the.*
2e760 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 6f 74  *          [prot
2e770 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
2e780 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56 20 69 6e  lue] object V in
2e790 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  to a zero-termin
2e7a0 61 74 65 64 20 55 54 46 2d 38 0a 2a 2a 20 20 20  ated UTF-8.**   
2e7b0 20 20 20 20 20 20 20 73 74 72 69 6e 67 20 61 6e         string an
2e7c0 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  d returns a poin
2e7d0 74 65 72 20 74 6f 20 74 68 61 74 20 73 74 72 69  ter to that stri
2e7e0 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 31 32  ng..**.** {H1512
2e7f0 34 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  4} The [sqlite3_
2e800 76 61 6c 75 65 5f 74 65 78 74 31 36 28 56 29 5d  value_text16(V)]
2e810 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65   interface conve
2e820 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  rts the.**      
2e830 20 20 20 20 5b 70 72 6f 74 65 63 74 65 64 20 73      [protected s
2e840 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
2e850 6a 65 63 74 20 56 20 69 6e 74 6f 20 61 20 7a 65  ject V into a ze
2e860 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 32 2d  ro-terminated 2-
2e870 62 79 74 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  byte.**         
2e880 20 61 6c 69 67 6e 65 64 20 55 54 46 2d 31 36 20   aligned UTF-16 
2e890 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
2e8a0 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 74  r.**          st
2e8b0 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73  ring and returns
2e8c0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
2e8d0 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a  at string..**.**
2e8e0 20 7b 48 31 35 31 32 37 7d 20 54 68 65 20 5b 73   {H15127} The [s
2e8f0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
2e900 74 31 36 62 65 28 56 29 5d 20 69 6e 74 65 72 66  t16be(V)] interf
2e910 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65  ace converts the
2e920 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72  .**          [pr
2e930 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
2e940 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56 20  value] object V 
2e950 69 6e 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d  into a zero-term
2e960 69 6e 61 74 65 64 20 32 2d 62 79 74 65 0a 2a 2a  inated 2-byte.**
2e970 20 20 20 20 20 20 20 20 20 20 61 6c 69 67 6e 65            aligne
2e980 64 20 55 54 46 2d 31 36 20 62 69 67 2d 65 6e 64  d UTF-16 big-end
2e990 69 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ian.**          
2e9a0 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72  string and retur
2e9b0 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
2e9c0 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a  that string..**.
2e9d0 2a 2a 20 7b 48 31 35 31 33 30 7d 20 54 68 65 20  ** {H15130} The 
2e9e0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
2e9f0 65 78 74 31 36 6c 65 28 56 29 5d 20 69 6e 74 65  ext16le(V)] inte
2ea00 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74  rface converts t
2ea10 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  he.**          [
2ea20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
2ea30 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
2ea40 56 20 69 6e 74 6f 20 61 20 7a 65 72 6f 2d 74 65  V into a zero-te
2ea50 72 6d 69 6e 61 74 65 64 20 32 2d 62 79 74 65 0a  rminated 2-byte.
2ea60 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6c 69 67  **          alig
2ea70 6e 65 64 20 55 54 46 2d 31 36 20 6c 69 74 74 6c  ned UTF-16 littl
2ea80 65 2d 65 6e 64 69 61 6e 0a 2a 2a 20 20 20 20 20  e-endian.**     
2ea90 20 20 20 20 20 73 74 72 69 6e 67 20 61 6e 64 20       string and 
2eaa0 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
2eab0 72 20 74 6f 20 74 68 61 74 20 73 74 72 69 6e 67  r to that string
2eac0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 31 33 33 7d  ..**.** {H15133}
2ead0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   The [sqlite3_va
2eae0 6c 75 65 5f 74 79 70 65 28 56 29 5d 20 69 6e 74  lue_type(V)] int
2eaf0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 0a 2a  erface returns.*
2eb00 2a 20 20 20 20 20 20 20 20 20 20 6f 6e 65 20 6f  *          one o
2eb10 66 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2c  f [SQLITE_NULL],
2eb20 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52   [SQLITE_INTEGER
2eb30 5d 2c 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54  ], [SQLITE_FLOAT
2eb40 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  ],.**          [
2eb50 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20 6f 72  SQLITE_TEXT], or
2eb60 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 20 61   [SQLITE_BLOB] a
2eb70 73 20 61 70 70 72 6f 70 72 69 61 74 65 20 66 6f  s appropriate fo
2eb80 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  r.**          th
2eb90 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
2eba0 5d 20 6f 62 6a 65 63 74 20 56 2e 0a 2a 2a 0a 2a  ] object V..**.*
2ebb0 2a 20 7b 48 31 35 31 33 36 7d 20 54 68 65 20 5b  * {H15136} The [
2ebc0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75  sqlite3_value_nu
2ebd0 6d 65 72 69 63 5f 74 79 70 65 28 56 29 5d 20 69  meric_type(V)] i
2ebe0 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74  nterface convert
2ebf0 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  s.**          th
2ec00 65 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c  e [protected sql
2ec10 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
2ec20 63 74 20 56 20 69 6e 74 6f 20 65 69 74 68 65 72  ct V into either
2ec30 20 61 6e 20 69 6e 74 65 67 65 72 20 6f 72 0a 2a   an integer or.*
2ec40 2a 20 20 20 20 20 20 20 20 20 20 61 20 66 6c 6f  *          a flo
2ec50 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75  ating point valu
2ec60 65 20 69 66 20 69 74 20 63 61 6e 20 64 6f 20 73  e if it can do s
2ec70 6f 20 77 69 74 68 6f 75 74 20 6c 6f 73 73 20 6f  o without loss o
2ec80 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e  f.**          in
2ec90 66 6f 72 6d 61 74 69 6f 6e 2c 20 61 6e 64 20 72  formation, and r
2eca0 65 74 75 72 6e 73 20 6f 6e 65 20 6f 66 20 5b 53  eturns one of [S
2ecb0 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2c 0a 2a 2a 20  QLITE_NULL],.** 
2ecc0 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45           [SQLITE
2ecd0 5f 49 4e 54 45 47 45 52 5d 2c 20 5b 53 51 4c 49  _INTEGER], [SQLI
2ece0 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49  TE_FLOAT], [SQLI
2ecf0 54 45 5f 54 45 58 54 5d 2c 20 6f 72 0a 2a 2a 20  TE_TEXT], or.** 
2ed00 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45           [SQLITE
2ed10 5f 42 4c 4f 42 5d 20 61 73 20 61 70 70 72 6f 70  _BLOB] as approp
2ed20 72 69 61 74 65 20 66 6f 72 20 74 68 65 0a 2a 2a  riate for the.**
2ed30 20 20 20 20 20 20 20 20 20 20 5b 70 72 6f 74 65            [prote
2ed40 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
2ed50 75 65 5d 20 6f 62 6a 65 63 74 20 56 20 61 66 74  ue] object V aft
2ed60 65 72 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f  er the conversio
2ed70 6e 20 61 74 74 65 6d 70 74 2e 0a 2a 2f 0a 63 6f  n attempt..*/.co
2ed80 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
2ed90 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 73 71 6c  3_value_blob(sql
2eda0 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e  ite3_value*);.in
2edb0 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  t sqlite3_value_
2edc0 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f 76 61  bytes(sqlite3_va
2edd0 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  lue*);.int sqlit
2ede0 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36  e3_value_bytes16
2edf0 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
2ee00 3b 0a 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33  ;.double sqlite3
2ee10 5f 76 61 6c 75 65 5f 64 6f 75 62 6c 65 28 73 71  _value_double(sq
2ee20 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69  lite3_value*);.i
2ee30 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt sqlite3_value
2ee40 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 76 61 6c  _int(sqlite3_val
2ee50 75 65 2a 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e  ue*);.sqlite3_in
2ee60 74 36 34 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  t64 sqlite3_valu
2ee70 65 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f  e_int64(sqlite3_
2ee80 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 75  value*);.const u
2ee90 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a 73 71  nsigned char *sq
2eea0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
2eeb0 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
2eec0 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
2eed0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
2eee0 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  16(sqlite3_value
2eef0 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  *);.const void *
2ef00 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
2ef10 78 74 31 36 6c 65 28 73 71 6c 69 74 65 33 5f 76  xt16le(sqlite3_v
2ef20 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f  alue*);.const vo
2ef30 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75  id *sqlite3_valu
2ef40 65 5f 74 65 78 74 31 36 62 65 28 73 71 6c 69 74  e_text16be(sqlit
2ef50 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20  e3_value*);.int 
2ef60 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79  sqlite3_value_ty
2ef70 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  pe(sqlite3_value
2ef80 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  *);.int sqlite3_
2ef90 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79  value_numeric_ty
2efa0 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  pe(sqlite3_value
2efb0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
2efc0 52 45 46 3a 20 4f 62 74 61 69 6e 20 41 67 67 72  REF: Obtain Aggr
2efd0 65 67 61 74 65 20 46 75 6e 63 74 69 6f 6e 20 43  egate Function C
2efe0 6f 6e 74 65 78 74 20 7b 48 31 36 32 31 30 7d 20  ontext {H16210} 
2eff0 3c 53 32 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54  <S20200>.**.** T
2f000 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
2f010 6e 20 6f 66 20 61 67 67 72 65 67 61 74 65 20 53  n of aggregate S
2f020 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 75 73 65  QL functions use
2f030 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 74 6f   this routine to
2f040 20 61 6c 6c 6f 63 61 74 65 0a 2a 2a 20 61 20 73   allocate.** a s
2f050 74 72 75 63 74 75 72 65 20 66 6f 72 20 73 74 6f  tructure for sto
2f060 72 69 6e 67 20 74 68 65 69 72 20 73 74 61 74 65  ring their state
2f070 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73  ..**.** The firs
2f080 74 20 74 69 6d 65 20 74 68 65 20 73 71 6c 69 74  t time the sqlit
2f090 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
2f0a0 74 65 78 74 28 29 20 72 6f 75 74 69 6e 65 20 69  text() routine i
2f0b0 73 20 63 61 6c 6c 65 64 20 66 6f 72 20 61 0a 2a  s called for a.*
2f0c0 2a 20 70 61 72 74 69 63 75 6c 61 72 20 61 67 67  * particular agg
2f0d0 72 65 67 61 74 65 2c 20 53 51 4c 69 74 65 20 61  regate, SQLite a
2f0e0 6c 6c 6f 63 61 74 65 73 20 6e 42 79 74 65 73 20  llocates nBytes 
2f0f0 6f 66 20 6d 65 6d 6f 72 79 2c 20 7a 65 72 6f 65  of memory, zeroe
2f100 73 20 6f 75 74 20 74 68 61 74 0a 2a 2a 20 6d 65  s out that.** me
2f110 6d 6f 72 79 2c 20 61 6e 64 20 72 65 74 75 72 6e  mory, and return
2f120 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 69  s a pointer to i
2f130 74 2e 20 4f 6e 20 73 65 63 6f 6e 64 20 61 6e 64  t. On second and
2f140 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c   subsequent call
2f150 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  s to.** sqlite3_
2f160 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
2f170 74 28 29 20 66 6f 72 20 74 68 65 20 73 61 6d 65  t() for the same
2f180 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74   aggregate funct
2f190 69 6f 6e 20 69 6e 64 65 78 2c 0a 2a 2a 20 74 68  ion index,.** th
2f1a0 65 20 73 61 6d 65 20 62 75 66 66 65 72 20 69 73  e same buffer is
2f1b0 20 72 65 74 75 72 6e 65 64 2e 20 54 68 65 20 69   returned. The i
2f1c0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
2f1d0 20 74 68 65 20 61 67 67 72 65 67 61 74 65 20 63   the aggregate c
2f1e0 61 6e 20 75 73 65 0a 2a 2a 20 74 68 65 20 72 65  an use.** the re
2f1f0 74 75 72 6e 65 64 20 62 75 66 66 65 72 20 74 6f  turned buffer to
2f200 20 61 63 63 75 6d 75 6c 61 74 65 20 64 61 74 61   accumulate data
2f210 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 61  ..**.** SQLite a
2f220 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 66 72 65  utomatically fre
2f230 65 73 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64  es the allocated
2f240 20 62 75 66 66 65 72 20 77 68 65 6e 20 74 68 65   buffer when the
2f250 20 61 67 67 72 65 67 61 74 65 0a 2a 2a 20 71 75   aggregate.** qu
2f260 65 72 79 20 63 6f 6e 63 6c 75 64 65 73 2e 0a 2a  ery concludes..*
2f270 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70  *.** The first p
2f280 61 72 61 6d 65 74 65 72 20 73 68 6f 75 6c 64 20  arameter should 
2f290 62 65 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  be a copy of the
2f2a0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
2f2b0 74 65 78 74 20 7c 20 53 51 4c 20 66 75 6e 63 74  text | SQL funct
2f2c0 69 6f 6e 20 63 6f 6e 74 65 78 74 5d 20 74 68 61  ion context] tha
2f2d0 74 20 69 73 20 74 68 65 20 66 69 72 73 74 20 70  t is the first p
2f2e0 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74  arameter.** to t
2f2f0 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 6f 75 74  he callback rout
2f300 69 6e 65 20 74 68 61 74 20 69 6d 70 6c 65 6d 65  ine that impleme
2f310 6e 74 73 20 74 68 65 20 61 67 67 72 65 67 61 74  nts the aggregat
2f320 65 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a  e function..**.*
2f330 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6d  * This routine m
2f340 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72  ust be called fr
2f350 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65  om the same thre
2f360 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74  ad in which.** t
2f370 68 65 20 61 67 67 72 65 67 61 74 65 20 53 51 4c  he aggregate SQL
2f380 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e   function is run
2f390 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  ning..**.** INVA
2f3a0 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48  RIANTS:.**.** {H
2f3b0 31 36 32 31 31 7d 20 54 68 65 20 66 69 72 73 74  16211} The first
2f3c0 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b   invocation of [
2f3d0 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
2f3e0 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 5d 20  e_context(C,N)] 
2f3f0 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  for.**          
2f400 61 20 70 61 72 74 69 63 75 6c 61 72 20 69 6e 73  a particular ins
2f410 74 61 6e 63 65 20 6f 66 20 61 6e 20 61 67 67 72  tance of an aggr
2f420 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 28  egate function (
2f430 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72  for a particular
2f440 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6e  .**          con
2f450 74 65 78 74 20 43 29 20 63 61 75 73 65 73 20 53  text C) causes S
2f460 51 4c 69 74 65 20 74 6f 20 61 6c 6c 6f 63 61 74  QLite to allocat
2f470 65 20 4e 20 62 79 74 65 73 20 6f 66 20 6d 65 6d  e N bytes of mem
2f480 6f 72 79 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  ory,.**         
2f490 20 7a 65 72 6f 20 74 68 61 74 20 6d 65 6d 6f 72   zero that memor
2f4a0 79 2c 20 61 6e 64 20 72 65 74 75 72 6e 20 61 20  y, and return a 
2f4b0 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 61  pointer to the a
2f4c0 6c 6c 6f 63 61 74 65 64 20 6d 65 6d 6f 72 79 2e  llocated memory.
2f4d0 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 32 31 33 7d 20  .**.** {H16213} 
2f4e0 49 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  If a memory allo
2f4f0 63 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63  cation error occ
2f500 75 72 73 20 64 75 72 69 6e 67 0a 2a 2a 20 20 20  urs during.**   
2f510 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
2f520 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
2f530 74 28 43 2c 4e 29 5d 20 74 68 65 6e 20 74 68 65  t(C,N)] then the
2f540 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
2f550 73 20 30 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 32  s 0..**.** {H162
2f560 31 35 7d 20 53 65 63 6f 6e 64 20 61 6e 64 20 73  15} Second and s
2f570 75 62 73 65 71 75 65 6e 74 20 69 6e 76 6f 63 61  ubsequent invoca
2f580 74 69 6f 6e 73 20 6f 66 0a 2a 2a 20 20 20 20 20  tions of.**     
2f590 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 61 67       [sqlite3_ag
2f5a0 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
2f5b0 43 2c 4e 29 5d 20 66 6f 72 20 74 68 65 20 73 61  C,N)] for the sa
2f5c0 6d 65 20 63 6f 6e 74 65 78 74 20 70 6f 69 6e 74  me context point
2f5d0 65 72 20 43 0a 2a 2a 20 20 20 20 20 20 20 20 20  er C.**         
2f5e0 20 69 67 6e 6f 72 65 20 74 68 65 20 4e 20 70 61   ignore the N pa
2f5f0 72 61 6d 65 74 65 72 20 61 6e 64 20 72 65 74 75  rameter and retu
2f600 72 6e 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  rn a pointer to 
2f610 74 68 65 20 73 61 6d 65 0a 2a 2a 20 20 20 20 20  the same.**     
2f620 20 20 20 20 20 62 6c 6f 63 6b 20 6f 66 20 6d 65       block of me
2f630 6d 6f 72 79 20 72 65 74 75 72 6e 65 64 20 62 79  mory returned by
2f640 20 74 68 65 20 66 69 72 73 74 20 69 6e 76 6f 63   the first invoc
2f650 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  ation..**.** {H1
2f660 36 32 31 37 7d 20 54 68 65 20 6d 65 6d 6f 72 79  6217} The memory
2f670 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 5b 73   allocated by [s
2f680 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
2f690 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 5d 20 69  _context(C,N)] i
2f6a0 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 75  s.**          au
2f6b0 74 6f 6d 61 74 69 63 61 6c 6c 79 20 66 72 65 65  tomatically free
2f6c0 64 20 6f 6e 20 74 68 65 20 6e 65 78 74 20 63 61  d on the next ca
2f6d0 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72  ll to [sqlite3_r
2f6e0 65 73 65 74 28 29 5d 0a 2a 2a 20 20 20 20 20 20  eset()].**      
2f6f0 20 20 20 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f      or [sqlite3_
2f700 66 69 6e 61 6c 69 7a 65 28 29 5d 20 66 6f 72 20  finalize()] for 
2f710 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
2f720 61 74 65 6d 65 6e 74 5d 20 63 6f 6e 74 61 69 6e  atement] contain
2f730 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ing.**          
2f740 74 68 65 20 61 67 67 72 65 67 61 74 65 20 66 75  the aggregate fu
2f750 6e 63 74 69 6f 6e 20 61 73 73 6f 63 69 61 74 65  nction associate
2f760 64 20 77 69 74 68 20 63 6f 6e 74 65 78 74 20 43  d with context C
2f770 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74  ..*/.void *sqlit
2f780 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
2f790 74 65 78 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e  text(sqlite3_con
2f7a0 74 65 78 74 2a 2c 20 69 6e 74 20 6e 42 79 74 65  text*, int nByte
2f7b0 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  s);../*.** CAPI3
2f7c0 52 45 46 3a 20 55 73 65 72 20 44 61 74 61 20 46  REF: User Data F
2f7d0 6f 72 20 46 75 6e 63 74 69 6f 6e 73 20 7b 48 31  or Functions {H1
2f7e0 36 32 34 30 7d 20 3c 53 32 30 32 30 30 3e 0a 2a  6240} <S20200>.*
2f7f0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
2f800 5f 75 73 65 72 5f 64 61 74 61 28 29 20 69 6e 74  _user_data() int
2f810 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61  erface returns a
2f820 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20   copy of.** the 
2f830 70 6f 69 6e 74 65 72 20 74 68 61 74 20 77 61 73  pointer that was
2f840 20 74 68 65 20 70 55 73 65 72 44 61 74 61 20 70   the pUserData p
2f850 61 72 61 6d 65 74 65 72 20 28 74 68 65 20 35 74  arameter (the 5t
2f860 68 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20  h parameter).** 
2f870 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
2f880 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
2f890 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74  )].** and [sqlit
2f8a0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
2f8b0 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73  on16()] routines
2f8c0 20 74 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79   that originally
2f8d0 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64 20 74  .** registered t
2f8e0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  he application d
2f8f0 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e  efined function.
2f900 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 69   {END}.**.** Thi
2f910 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62  s routine must b
2f920 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68  e called from th
2f930 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e  e same thread in
2f940 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 70   which.** the ap
2f950 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
2f960 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75  d function is ru
2f970 6e 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56  nning..**.** INV
2f980 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
2f990 48 31 36 32 34 33 7d 20 54 68 65 20 5b 73 71 6c  H16243} The [sql
2f9a0 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 43  ite3_user_data(C
2f9b0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  )] interface ret
2f9c0 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 20 74  urns a copy of t
2f9d0 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 50  he.**          P
2f9e0 20 70 6f 69 6e 74 65 72 20 66 72 6f 6d 20 74 68   pointer from th
2f9f0 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  e [sqlite3_creat
2fa00 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e  e_function(D,X,N
2fa10 2c 45 2c 50 2c 46 2c 53 2c 4c 29 5d 0a 2a 2a 20  ,E,P,F,S,L)].** 
2fa20 20 20 20 20 20 20 20 20 20 6f 72 20 5b 73 71 6c           or [sql
2fa30 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
2fa40 74 69 6f 6e 31 36 28 44 2c 58 2c 4e 2c 45 2c 50  tion16(D,X,N,E,P
2fa50 2c 46 2c 53 2c 4c 29 5d 20 63 61 6c 6c 20 74 68  ,F,S,L)] call th
2fa60 61 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72  at.**          r
2fa70 65 67 69 73 74 65 72 65 64 20 74 68 65 20 53 51  egistered the SQ
2fa80 4c 20 66 75 6e 63 74 69 6f 6e 20 61 73 73 6f 63  L function assoc
2fa90 69 61 74 65 64 20 77 69 74 68 20 5b 73 71 6c 69  iated with [sqli
2faa0 74 65 33 5f 63 6f 6e 74 65 78 74 5d 20 43 2e 0a  te3_context] C..
2fab0 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  */.void *sqlite3
2fac0 5f 75 73 65 72 5f 64 61 74 61 28 73 71 6c 69 74  _user_data(sqlit
2fad0 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f  e3_context*);../
2fae0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
2faf0 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69  atabase Connecti
2fb00 6f 6e 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73  on For Functions
2fb10 20 7b 48 31 36 32 35 30 7d 20 3c 53 36 30 36 30   {H16250} <S6060
2fb20 30 3e 3c 53 32 30 32 30 30 3e 0a 2a 2a 0a 2a 2a  0><S20200>.**.**
2fb30 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e   The sqlite3_con
2fb40 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29  text_db_handle()
2fb50 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
2fb60 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20  ns a copy of.** 
2fb70 74 68 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  the pointer to t
2fb80 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
2fb90 6e 65 63 74 69 6f 6e 5d 20 28 74 68 65 20 31 73  nection] (the 1s
2fba0 74 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20  t parameter).** 
2fbb0 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
2fbc0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
2fbd0 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74  )].** and [sqlit
2fbe0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
2fbf0 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73  on16()] routines
2fc00 20 74 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79   that originally
2fc10 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64 20 74  .** registered t
2fc20 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  he application d
2fc30 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e  efined function.
2fc40 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
2fc50 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 32 35 33  S:.**.** {H16253
2fc60 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  } The [sqlite3_c
2fc70 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65  ontext_db_handle
2fc80 28 43 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  (C)] interface r
2fc90 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66  eturns a copy of
2fca0 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
2fcb0 20 44 20 70 6f 69 6e 74 65 72 20 66 72 6f 6d 20   D pointer from 
2fcc0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  the [sqlite3_cre
2fcd0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58  ate_function(D,X
2fce0 2c 4e 2c 45 2c 50 2c 46 2c 53 2c 4c 29 5d 0a 2a  ,N,E,P,F,S,L)].*
2fcf0 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 5b 73  *          or [s
2fd00 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
2fd10 6e 63 74 69 6f 6e 31 36 28 44 2c 58 2c 4e 2c 45  nction16(D,X,N,E
2fd20 2c 50 2c 46 2c 53 2c 4c 29 5d 20 63 61 6c 6c 20  ,P,F,S,L)] call 
2fd30 74 68 61 74 0a 2a 2a 20 20 20 20 20 20 20 20 20  that.**         
2fd40 20 72 65 67 69 73 74 65 72 65 64 20 74 68 65 20   registered the 
2fd50 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 61 73 73  SQL function ass
2fd60 6f 63 69 61 74 65 64 20 77 69 74 68 20 5b 73 71  ociated with [sq
2fd70 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5d 20 43  lite3_context] C
2fd80 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 20 2a 73 71  ..*/.sqlite3 *sq
2fd90 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62  lite3_context_db
2fda0 5f 68 61 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f  _handle(sqlite3_
2fdb0 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a  context*);../*.*
2fdc0 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e 63  * CAPI3REF: Func
2fdd0 74 69 6f 6e 20 41 75 78 69 6c 69 61 72 79 20 44  tion Auxiliary D
2fde0 61 74 61 20 7b 48 31 36 32 37 30 7d 20 3c 53 32  ata {H16270} <S2
2fdf0 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  0200>.**.** The 
2fe00 66 6f 6c 6c 6f 77 69 6e 67 20 74 77 6f 20 66 75  following two fu
2fe10 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 75  nctions may be u
2fe20 73 65 64 20 62 79 20 73 63 61 6c 61 72 20 53 51  sed by scalar SQ
2fe30 4c 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f 0a 2a  L functions to.*
2fe40 2a 20 61 73 73 6f 63 69 61 74 65 20 6d 65 74 61  * associate meta
2fe50 64 61 74 61 20 77 69 74 68 20 61 72 67 75 6d 65  data with argume
2fe60 6e 74 20 76 61 6c 75 65 73 2e 20 49 66 20 74 68  nt values. If th
2fe70 65 20 73 61 6d 65 20 76 61 6c 75 65 20 69 73 20  e same value is 
2fe80 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20 6d 75 6c  passed to.** mul
2fe90 74 69 70 6c 65 20 69 6e 76 6f 63 61 74 69 6f 6e  tiple invocation
2fea0 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 53 51  s of the same SQ
2feb0 4c 20 66 75 6e 63 74 69 6f 6e 20 64 75 72 69 6e  L function durin
2fec0 67 20 71 75 65 72 79 20 65 78 65 63 75 74 69 6f  g query executio
2fed0 6e 2c 20 75 6e 64 65 72 0a 2a 2a 20 73 6f 6d 65  n, under.** some
2fee0 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73 20 74   circumstances t
2fef0 68 65 20 61 73 73 6f 63 69 61 74 65 64 20 6d 65  he associated me
2ff00 74 61 64 61 74 61 20 6d 61 79 20 62 65 20 70 72  tadata may be pr
2ff10 65 73 65 72 76 65 64 2e 20 54 68 69 73 20 6d 61  eserved. This ma
2ff20 79 0a 2a 2a 20 62 65 20 75 73 65 64 2c 20 66 6f  y.** be used, fo
2ff30 72 20 65 78 61 6d 70 6c 65 2c 20 74 6f 20 61 64  r example, to ad
2ff40 64 20 61 20 72 65 67 75 6c 61 72 2d 65 78 70 72  d a regular-expr
2ff50 65 73 73 69 6f 6e 20 6d 61 74 63 68 69 6e 67 20  ession matching 
2ff60 73 63 61 6c 61 72 0a 2a 2a 20 66 75 6e 63 74 69  scalar.** functi
2ff70 6f 6e 2e 20 54 68 65 20 63 6f 6d 70 69 6c 65 64  on. The compiled
2ff80 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20   version of the 
2ff90 72 65 67 75 6c 61 72 20 65 78 70 72 65 73 73 69  regular expressi
2ffa0 6f 6e 20 69 73 20 73 74 6f 72 65 64 20 61 73 0a  on is stored as.
2ffb0 2a 2a 20 6d 65 74 61 64 61 74 61 20 61 73 73 6f  ** metadata asso
2ffc0 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20  ciated with the 
2ffd0 53 51 4c 20 76 61 6c 75 65 20 70 61 73 73 65 64  SQL value passed
2ffe0 20 61 73 20 74 68 65 20 72 65 67 75 6c 61 72 20   as the regular 
2fff0 65 78 70 72 65 73 73 69 6f 6e 0a 2a 2a 20 70 61  expression.** pa
30000 74 74 65 72 6e 2e 20 20 54 68 65 20 63 6f 6d 70  ttern.  The comp
30010 69 6c 65 64 20 72 65 67 75 6c 61 72 20 65 78 70  iled regular exp
30020 72 65 73 73 69 6f 6e 20 63 61 6e 20 62 65 20 72  ression can be r
30030 65 75 73 65 64 20 6f 6e 20 6d 75 6c 74 69 70 6c  eused on multipl
30040 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73  e.** invocations
30050 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e   of the same fun
30060 63 74 69 6f 6e 20 73 6f 20 74 68 61 74 20 74 68  ction so that th
30070 65 20 6f 72 69 67 69 6e 61 6c 20 70 61 74 74 65  e original patte
30080 72 6e 20 73 74 72 69 6e 67 0a 2a 2a 20 64 6f 65  rn string.** doe
30090 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65  s not need to be
300a0 20 72 65 63 6f 6d 70 69 6c 65 64 20 6f 6e 20 65   recompiled on e
300b0 61 63 68 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 0a  ach invocation..
300c0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
300d0 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 20  3_get_auxdata() 
300e0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
300f0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  s a pointer to t
30100 68 65 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20 61  he metadata.** a
30110 73 73 6f 63 69 61 74 65 64 20 62 79 20 74 68 65  ssociated by the
30120 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78   sqlite3_set_aux
30130 64 61 74 61 28 29 20 66 75 6e 63 74 69 6f 6e 20  data() function 
30140 77 69 74 68 20 74 68 65 20 4e 74 68 20 61 72 67  with the Nth arg
30150 75 6d 65 6e 74 0a 2a 2a 20 76 61 6c 75 65 20 74  ument.** value t
30160 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  o the applicatio
30170 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
30180 6f 6e 2e 20 49 66 20 6e 6f 20 6d 65 74 61 64 61  on. If no metada
30190 74 61 20 68 61 73 20 62 65 65 6e 20 65 76 65 72  ta has been ever
301a0 0a 2a 2a 20 62 65 65 6e 20 73 65 74 20 66 6f 72  .** been set for
301b0 20 74 68 65 20 4e 74 68 20 61 72 67 75 6d 65 6e   the Nth argumen
301c0 74 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f  t of the functio
301d0 6e 2c 20 6f 72 20 69 66 20 74 68 65 20 63 6f 72  n, or if the cor
301e0 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 66 75  responding.** fu
301f0 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65 74 65 72  nction parameter
30200 20 68 61 73 20 63 68 61 6e 67 65 64 20 73 69 6e   has changed sin
30210 63 65 20 74 68 65 20 6d 65 74 61 2d 64 61 74 61  ce the meta-data
30220 20 77 61 73 20 73 65 74 2c 0a 2a 2a 20 74 68 65   was set,.** the
30230 6e 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75  n sqlite3_get_au
30240 78 64 61 74 61 28 29 20 72 65 74 75 72 6e 73 20  xdata() returns 
30250 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a  a NULL pointer..
30260 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
30270 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20  3_set_auxdata() 
30280 69 6e 74 65 72 66 61 63 65 20 73 61 76 65 73 20  interface saves 
30290 74 68 65 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20  the metadata.** 
302a0 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 69 74  pointed to by it
302b0 73 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20  s 3rd parameter 
302c0 61 73 20 74 68 65 20 6d 65 74 61 64 61 74 61 20  as the metadata 
302d0 66 6f 72 20 74 68 65 20 4e 2d 74 68 0a 2a 2a 20  for the N-th.** 
302e0 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 68 65 20  argument of the 
302f0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
30300 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20 20 53  ned function.  S
30310 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 63 61 6c  ubsequent.** cal
30320 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 67 65  ls to sqlite3_ge
30330 74 5f 61 75 78 64 61 74 61 28 29 20 6d 69 67 68  t_auxdata() migh
30340 74 20 72 65 74 75 72 6e 20 74 68 69 73 20 64 61  t return this da
30350 74 61 2c 20 69 66 20 69 74 20 68 61 73 0a 2a 2a  ta, if it has.**
30360 20 6e 6f 74 20 62 65 65 6e 20 64 65 73 74 72 6f   not been destro
30370 79 65 64 2e 0a 2a 2a 20 49 66 20 69 74 20 69 73  yed..** If it is
30380 20 6e 6f 74 20 4e 55 4c 4c 2c 20 53 51 4c 69 74   not NULL, SQLit
30390 65 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 68  e will invoke th
303a0 65 20 64 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20  e destructor.** 
303b0 66 75 6e 63 74 69 6f 6e 20 67 69 76 65 6e 20 62  function given b
303c0 79 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65  y the 4th parame
303d0 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  ter to sqlite3_s
303e0 65 74 5f 61 75 78 64 61 74 61 28 29 20 6f 6e 0a  et_auxdata() on.
303f0 2a 2a 20 74 68 65 20 6d 65 74 61 64 61 74 61 20  ** the metadata 
30400 77 68 65 6e 20 74 68 65 20 63 6f 72 72 65 73 70  when the corresp
30410 6f 6e 64 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20  onding function 
30420 70 61 72 61 6d 65 74 65 72 20 63 68 61 6e 67 65  parameter change
30430 73 0a 2a 2a 20 6f 72 20 77 68 65 6e 20 74 68 65  s.** or when the
30440 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 63   SQL statement c
30450 6f 6d 70 6c 65 74 65 73 2c 20 77 68 69 63 68 65  ompletes, whiche
30460 76 65 72 20 63 6f 6d 65 73 20 66 69 72 73 74 2e  ver comes first.
30470 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 69 73  .**.** SQLite is
30480 20 66 72 65 65 20 74 6f 20 63 61 6c 6c 20 74 68   free to call th
30490 65 20 64 65 73 74 72 75 63 74 6f 72 20 61 6e 64  e destructor and
304a0 20 64 72 6f 70 20 6d 65 74 61 64 61 74 61 20 6f   drop metadata o
304b0 6e 20 61 6e 79 0a 2a 2a 20 70 61 72 61 6d 65 74  n any.** paramet
304c0 65 72 20 6f 66 20 61 6e 79 20 66 75 6e 63 74 69  er of any functi
304d0 6f 6e 20 61 74 20 61 6e 79 20 74 69 6d 65 2e 20  on at any time. 
304e0 20 54 68 65 20 6f 6e 6c 79 20 67 75 61 72 61 6e   The only guaran
304f0 74 65 65 20 69 73 20 74 68 61 74 0a 2a 2a 20 74  tee is that.** t
30500 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 77 69  he destructor wi
30510 6c 6c 20 62 65 20 63 61 6c 6c 65 64 20 62 65 66  ll be called bef
30520 6f 72 65 20 74 68 65 20 6d 65 74 61 64 61 74 61  ore the metadata
30530 20 69 73 20 64 72 6f 70 70 65 64 2e 0a 2a 2a 0a   is dropped..**.
30540 2a 2a 20 49 6e 20 70 72 61 63 74 69 63 65 2c 20  ** In practice, 
30550 6d 65 74 61 64 61 74 61 20 69 73 20 70 72 65 73  metadata is pres
30560 65 72 76 65 64 20 62 65 74 77 65 65 6e 20 66 75  erved between fu
30570 6e 63 74 69 6f 6e 20 63 61 6c 6c 73 20 66 6f 72  nction calls for
30580 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 73 20  .** expressions 
30590 74 68 61 74 20 61 72 65 20 63 6f 6e 73 74 61 6e  that are constan
305a0 74 20 61 74 20 63 6f 6d 70 69 6c 65 20 74 69 6d  t at compile tim
305b0 65 2e 20 54 68 69 73 20 69 6e 63 6c 75 64 65 73  e. This includes
305c0 20 6c 69 74 65 72 61 6c 0a 2a 2a 20 76 61 6c 75   literal.** valu
305d0 65 73 20 61 6e 64 20 53 51 4c 20 76 61 72 69 61  es and SQL varia
305e0 62 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  bles..**.** Thes
305f0 65 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20  e routines must 
30600 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74  be called from t
30610 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69  he same thread i
30620 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 53  n which.** the S
30630 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72  QL function is r
30640 75 6e 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 49 4e  unning..**.** IN
30650 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
30660 7b 48 31 36 32 37 32 7d 20 54 68 65 20 5b 73 71  {H16272} The [sq
30670 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74  lite3_get_auxdat
30680 61 28 43 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63  a(C,N)] interfac
30690 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  e returns a poin
306a0 74 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ter.**          
306b0 74 6f 20 6d 65 74 61 64 61 74 61 20 61 73 73 6f  to metadata asso
306c0 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20  ciated with the 
306d0 4e 74 68 20 70 61 72 61 6d 65 74 65 72 20 6f 66  Nth parameter of
306e0 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
306f0 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 68  n.**          wh
30700 6f 73 65 20 63 6f 6e 74 65 78 74 20 69 73 20 43  ose context is C
30710 2c 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 65  , or NULL if the
30720 72 65 20 69 73 20 6e 6f 20 6d 65 74 61 64 61 74  re is no metadat
30730 61 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20  a associated.** 
30740 20 20 20 20 20 20 20 20 20 77 69 74 68 20 74 68           with th
30750 61 74 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  at parameter..**
30760 0a 2a 2a 20 7b 48 31 36 32 37 34 7d 20 54 68 65  .** {H16274} The
30770 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75   [sqlite3_set_au
30780 78 64 61 74 61 28 43 2c 4e 2c 50 2c 44 29 5d 20  xdata(C,N,P,D)] 
30790 69 6e 74 65 72 66 61 63 65 20 61 73 73 69 67 6e  interface assign
307a0 73 20 61 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20  s a metadata.** 
307b0 20 20 20 20 20 20 20 20 20 70 6f 69 6e 74 65 72           pointer
307c0 20 50 20 74 6f 20 74 68 65 20 4e 74 68 20 70 61   P to the Nth pa
307d0 72 61 6d 65 74 65 72 20 6f 66 20 74 68 65 20 53  rameter of the S
307e0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68  QL function with
307f0 20 63 6f 6e 74 65 78 74 20 43 2e 0a 2a 2a 0a 2a   context C..**.*
30800 2a 20 7b 48 31 36 32 37 36 7d 20 53 51 4c 69 74  * {H16276} SQLit
30810 65 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 68  e will invoke th
30820 65 20 64 65 73 74 72 75 63 74 6f 72 20 44 20 77  e destructor D w
30830 69 74 68 20 61 20 73 69 6e 67 6c 65 20 61 72 67  ith a single arg
30840 75 6d 65 6e 74 0a 2a 2a 20 20 20 20 20 20 20 20  ument.**        
30850 20 20 77 68 69 63 68 20 69 73 20 74 68 65 20 6d    which is the m
30860 65 74 61 64 61 74 61 20 70 6f 69 6e 74 65 72 20  etadata pointer 
30870 50 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 61  P following a ca
30880 6c 6c 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20  ll to.**        
30890 20 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61    [sqlite3_set_a
308a0 75 78 64 61 74 61 28 43 2c 4e 2c 50 2c 44 29 5d  uxdata(C,N,P,D)]
308b0 20 77 68 65 6e 20 53 51 4c 69 74 65 20 63 65 61   when SQLite cea
308c0 73 65 73 20 74 6f 20 68 6f 6c 64 0a 2a 2a 20 20  ses to hold.**  
308d0 20 20 20 20 20 20 20 20 74 68 65 20 6d 65 74 61          the meta
308e0 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36  data..**.** {H16
308f0 32 37 37 7d 20 53 51 4c 69 74 65 20 63 65 61 73  277} SQLite ceas
30900 65 73 20 74 6f 20 68 6f 6c 64 20 6d 65 74 61 64  es to hold metad
30910 61 74 61 20 66 6f 72 20 61 6e 20 53 51 4c 20 66  ata for an SQL f
30920 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65 74 65  unction paramete
30930 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 68  r.**          wh
30940 65 6e 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  en the value of 
30950 74 68 61 74 20 70 61 72 61 6d 65 74 65 72 20 63  that parameter c
30960 68 61 6e 67 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48  hanges..**.** {H
30970 31 36 32 37 38 7d 20 57 68 65 6e 20 5b 73 71 6c  16278} When [sql
30980 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
30990 28 43 2c 4e 2c 50 2c 44 29 5d 20 69 73 20 69 6e  (C,N,P,D)] is in
309a0 76 6f 6b 65 64 2c 20 74 68 65 20 64 65 73 74 72  voked, the destr
309b0 75 63 74 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20  uctor.**        
309c0 20 20 69 73 20 63 61 6c 6c 65 64 20 66 6f 72 20    is called for 
309d0 61 6e 79 20 70 72 69 6f 72 20 6d 65 74 61 64 61  any prior metada
309e0 74 61 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ta associated wi
309f0 74 68 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63  th the same func
30a00 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  tion.**         
30a10 20 63 6f 6e 74 65 78 74 20 43 20 61 6e 64 20 70   context C and p
30a20 61 72 61 6d 65 74 65 72 20 4e 2e 0a 2a 2a 0a 2a  arameter N..**.*
30a30 2a 20 7b 48 31 36 32 37 39 7d 20 53 51 4c 69 74  * {H16279} SQLit
30a40 65 20 77 69 6c 6c 20 63 61 6c 6c 20 64 65 73 74  e will call dest
30a50 72 75 63 74 6f 72 73 20 66 6f 72 20 61 6e 79 20  ructors for any 
30a60 6d 65 74 61 64 61 74 61 20 69 74 20 69 73 20 68  metadata it is h
30a70 6f 6c 64 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20  olding.**       
30a80 20 20 20 69 6e 20 61 20 70 61 72 74 69 63 75 6c     in a particul
30a90 61 72 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ar [prepared sta
30aa0 74 65 6d 65 6e 74 5d 20 53 20 77 68 65 6e 20 65  tement] S when e
30ab0 69 74 68 65 72 0a 2a 2a 20 20 20 20 20 20 20 20  ither.**        
30ac0 20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74    [sqlite3_reset
30ad0 28 53 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  (S)] or [sqlite3
30ae0 5f 66 69 6e 61 6c 69 7a 65 28 53 29 5d 20 69 73  _finalize(S)] is
30af0 20 63 61 6c 6c 65 64 2e 0a 2a 2f 0a 76 6f 69 64   called..*/.void
30b00 20 2a 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75   *sqlite3_get_au
30b10 78 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f  xdata(sqlite3_co
30b20 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a  ntext*, int N);.
30b30 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 73 65 74  void sqlite3_set
30b40 5f 61 75 78 64 61 74 61 28 73 71 6c 69 74 65 33  _auxdata(sqlite3
30b50 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e  _context*, int N
30b60 2c 20 76 6f 69 64 2a 2c 20 76 6f 69 64 20 28 2a  , void*, void (*
30b70 29 28 76 6f 69 64 2a 29 29 3b 0a 0a 0a 2f 2a 0a  )(void*));.../*.
30b80 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e  ** CAPI3REF: Con
30b90 73 74 61 6e 74 73 20 44 65 66 69 6e 69 6e 67 20  stants Defining 
30ba0 53 70 65 63 69 61 6c 20 44 65 73 74 72 75 63 74  Special Destruct
30bb0 6f 72 20 42 65 68 61 76 69 6f 72 20 7b 48 31 30  or Behavior {H10
30bc0 32 38 30 7d 20 3c 53 33 30 31 30 30 3e 0a 2a 2a  280} <S30100>.**
30bd0 0a 2a 2a 20 54 68 65 73 65 20 61 72 65 20 73 70  .** These are sp
30be0 65 63 69 61 6c 20 76 61 6c 75 65 73 20 66 6f 72  ecial values for
30bf0 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20   the destructor 
30c00 74 68 61 74 20 69 73 20 70 61 73 73 65 64 20 69  that is passed i
30c10 6e 20 61 73 20 74 68 65 0a 2a 2a 20 66 69 6e 61  n as the.** fina
30c20 6c 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 72 6f  l argument to ro
30c30 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c  utines like [sql
30c40 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62  ite3_result_blob
30c50 28 29 5d 2e 20 20 49 66 20 74 68 65 20 64 65 73  ()].  If the des
30c60 74 72 75 63 74 6f 72 0a 2a 2a 20 61 72 67 75 6d  tructor.** argum
30c70 65 6e 74 20 69 73 20 53 51 4c 49 54 45 5f 53 54  ent is SQLITE_ST
30c80 41 54 49 43 2c 20 69 74 20 6d 65 61 6e 73 20 74  ATIC, it means t
30c90 68 61 74 20 74 68 65 20 63 6f 6e 74 65 6e 74 20  hat the content 
30ca0 70 6f 69 6e 74 65 72 20 69 73 20 63 6f 6e 73 74  pointer is const
30cb0 61 6e 74 0a 2a 2a 20 61 6e 64 20 77 69 6c 6c 20  ant.** and will 
30cc0 6e 65 76 65 72 20 63 68 61 6e 67 65 2e 20 20 49  never change.  I
30cd0 74 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20  t does not need 
30ce0 74 6f 20 62 65 20 64 65 73 74 72 6f 79 65 64 2e  to be destroyed.
30cf0 20 20 54 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f    The.** SQLITE_
30d00 54 52 41 4e 53 49 45 4e 54 20 76 61 6c 75 65 20  TRANSIENT value 
30d10 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 63  means that the c
30d20 6f 6e 74 65 6e 74 20 77 69 6c 6c 20 6c 69 6b 65  ontent will like
30d30 6c 79 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a 20  ly change in.** 
30d40 74 68 65 20 6e 65 61 72 20 66 75 74 75 72 65 20  the near future 
30d50 61 6e 64 20 74 68 61 74 20 53 51 4c 69 74 65 20  and that SQLite 
30d60 73 68 6f 75 6c 64 20 6d 61 6b 65 20 69 74 73 20  should make its 
30d70 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79  own private copy
30d80 20 6f 66 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65   of.** the conte
30d90 6e 74 20 62 65 66 6f 72 65 20 72 65 74 75 72 6e  nt before return
30da0 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74  ing..**.** The t
30db0 79 70 65 64 65 66 20 69 73 20 6e 65 63 65 73 73  ypedef is necess
30dc0 61 72 79 20 74 6f 20 77 6f 72 6b 20 61 72 6f 75  ary to work arou
30dd0 6e 64 20 70 72 6f 62 6c 65 6d 73 20 69 6e 20 63  nd problems in c
30de0 65 72 74 61 69 6e 0a 2a 2a 20 43 2b 2b 20 63 6f  ertain.** C++ co
30df0 6d 70 69 6c 65 72 73 2e 20 20 53 65 65 20 74 69  mpilers.  See ti
30e00 63 6b 65 74 20 23 32 31 39 31 2e 0a 2a 2f 0a 74  cket #2191..*/.t
30e10 79 70 65 64 65 66 20 76 6f 69 64 20 28 2a 73 71  ypedef void (*sq
30e20 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72  lite3_destructor
30e30 5f 74 79 70 65 29 28 76 6f 69 64 2a 29 3b 0a 23  _type)(void*);.#
30e40 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 54  define SQLITE_ST
30e50 41 54 49 43 20 20 20 20 20 20 28 28 73 71 6c 69  ATIC      ((sqli
30e60 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74  te3_destructor_t
30e70 79 70 65 29 30 29 0a 23 64 65 66 69 6e 65 20 53  ype)0).#define S
30e80 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 20  QLITE_TRANSIENT 
30e90 20 20 28 28 73 71 6c 69 74 65 33 5f 64 65 73 74    ((sqlite3_dest
30ea0 72 75 63 74 6f 72 5f 74 79 70 65 29 2d 31 29 0a  ructor_type)-1).
30eb0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
30ec0 20 53 65 74 74 69 6e 67 20 54 68 65 20 52 65 73   Setting The Res
30ed0 75 6c 74 20 4f 66 20 41 6e 20 53 51 4c 20 46 75  ult Of An SQL Fu
30ee0 6e 63 74 69 6f 6e 20 7b 48 31 36 34 30 30 7d 20  nction {H16400} 
30ef0 3c 53 32 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54  <S20200>.**.** T
30f00 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
30f10 65 20 75 73 65 64 20 62 79 20 74 68 65 20 78 46  e used by the xF
30f20 75 6e 63 20 6f 72 20 78 46 69 6e 61 6c 20 63 61  unc or xFinal ca
30f30 6c 6c 62 61 63 6b 73 20 74 68 61 74 0a 2a 2a 20  llbacks that.** 
30f40 69 6d 70 6c 65 6d 65 6e 74 20 53 51 4c 20 66 75  implement SQL fu
30f50 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72  nctions and aggr
30f60 65 67 61 74 65 73 2e 20 20 53 65 65 0a 2a 2a 20  egates.  See.** 
30f70 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
30f80 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20  function()] and 
30f90 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
30fa0 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a  function16()].**
30fb0 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20   for additional 
30fc0 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a  information..**.
30fd0 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f  ** These functio
30fe0 6e 73 20 77 6f 72 6b 20 76 65 72 79 20 6d 75 63  ns work very muc
30ff0 68 20 6c 69 6b 65 20 74 68 65 20 5b 70 61 72 61  h like the [para
31000 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 5d 20 66  meter binding] f
31010 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 66 75 6e 63  amily of.** func
31020 74 69 6f 6e 73 20 75 73 65 64 20 74 6f 20 62 69  tions used to bi
31030 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 68 6f 73  nd values to hos
31040 74 20 70 61 72 61 6d 65 74 65 72 73 20 69 6e 20  t parameters in 
31050 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
31060 6e 74 73 2e 0a 2a 2a 20 52 65 66 65 72 20 74 6f  nts..** Refer to
31070 20 74 68 65 20 5b 53 51 4c 20 70 61 72 61 6d 65   the [SQL parame
31080 74 65 72 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69  ter] documentati
31090 6f 6e 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61  on for additiona
310a0 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  l information..*
310b0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
310c0 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29 20 69  _result_blob() i
310d0 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68  nterface sets th
310e0 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a  e result from.**
310f0 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d   an application-
31100 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
31110 20 74 6f 20 62 65 20 74 68 65 20 42 4c 4f 42 20   to be the BLOB 
31120 77 68 6f 73 65 20 63 6f 6e 74 65 6e 74 20 69 73  whose content is
31130 20 70 6f 69 6e 74 65 64 0a 2a 2a 20 74 6f 20 62   pointed.** to b
31140 79 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72  y the second par
31150 61 6d 65 74 65 72 20 61 6e 64 20 77 68 69 63 68  ameter and which
31160 20 69 73 20 4e 20 62 79 74 65 73 20 6c 6f 6e 67   is N bytes long
31170 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 0a   where N is the.
31180 2a 2a 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  ** third paramet
31190 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  er..**.** The sq
311a0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72  lite3_result_zer
311b0 6f 62 6c 6f 62 28 29 20 69 6e 74 65 72 66 61 63  oblob() interfac
311c0 65 73 20 73 65 74 20 74 68 65 20 72 65 73 75 6c  es set the resul
311d0 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c  t of.** the appl
311e0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
311f0 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61  function to be a
31200 20 42 4c 4f 42 20 63 6f 6e 74 61 69 6e 69 6e 67   BLOB containing
31210 20 61 6c 6c 20 7a 65 72 6f 0a 2a 2a 20 62 79 74   all zero.** byt
31220 65 73 20 61 6e 64 20 4e 20 62 79 74 65 73 20 69  es and N bytes i
31230 6e 20 73 69 7a 65 2c 20 77 68 65 72 65 20 4e 20  n size, where N 
31240 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  is the value of 
31250 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65  the 2nd paramete
31260 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  r..**.** The sql
31270 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62  ite3_result_doub
31280 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 73  le() interface s
31290 65 74 73 20 74 68 65 20 72 65 73 75 6c 74 20 66  ets the result f
312a0 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63  rom.** an applic
312b0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
312c0 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 66  nction to be a f
312d0 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61  loating point va
312e0 6c 75 65 20 73 70 65 63 69 66 69 65 64 0a 2a 2a  lue specified.**
312f0 20 62 79 20 69 74 73 20 32 6e 64 20 61 72 67 75   by its 2nd argu
31300 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ment..**.** The 
31310 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
31320 72 72 6f 72 28 29 20 61 6e 64 20 73 71 6c 69 74  rror() and sqlit
31330 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31  e3_result_error1
31340 36 28 29 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a  6() functions.**
31350 20 63 61 75 73 65 20 74 68 65 20 69 6d 70 6c 65   cause the imple
31360 6d 65 6e 74 65 64 20 53 51 4c 20 66 75 6e 63 74  mented SQL funct
31370 69 6f 6e 20 74 6f 20 74 68 72 6f 77 20 61 6e 20  ion to throw an 
31380 65 78 63 65 70 74 69 6f 6e 2e 0a 2a 2a 20 53 51  exception..** SQ
31390 4c 69 74 65 20 75 73 65 73 20 74 68 65 20 73 74  Lite uses the st
313a0 72 69 6e 67 20 70 6f 69 6e 74 65 64 20 74 6f 20  ring pointed to 
313b0 62 79 20 74 68 65 0a 2a 2a 20 32 6e 64 20 70 61  by the.** 2nd pa
313c0 72 61 6d 65 74 65 72 20 6f 66 20 73 71 6c 69 74  rameter of sqlit
313d0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28  e3_result_error(
313e0 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73  ) or sqlite3_res
313f0 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a  ult_error16().**
31400 20 61 73 20 74 68 65 20 74 65 78 74 20 6f 66 20   as the text of 
31410 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  an error message
31420 2e 20 20 53 51 4c 69 74 65 20 69 6e 74 65 72 70  .  SQLite interp
31430 72 65 74 73 20 74 68 65 20 65 72 72 6f 72 0a 2a  rets the error.*
31440 2a 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67  * message string
31450 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65   from sqlite3_re
31460 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 73 20  sult_error() as 
31470 55 54 46 2d 38 2e 20 53 51 4c 69 74 65 0a 2a 2a  UTF-8. SQLite.**
31480 20 69 6e 74 65 72 70 72 65 74 73 20 74 68 65 20   interprets the 
31490 73 74 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69  string from sqli
314a0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
314b0 31 36 28 29 20 61 73 20 55 54 46 2d 31 36 20 69  16() as UTF-16 i
314c0 6e 20 6e 61 74 69 76 65 0a 2a 2a 20 62 79 74 65  n native.** byte
314d0 20 6f 72 64 65 72 2e 20 20 49 66 20 74 68 65 20   order.  If the 
314e0 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
314f0 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  to sqlite3_resul
31500 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20  t_error().** or 
31510 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
31520 72 72 6f 72 31 36 28 29 20 69 73 20 6e 65 67 61  rror16() is nega
31530 74 69 76 65 20 74 68 65 6e 20 53 51 4c 69 74 65  tive then SQLite
31540 20 74 61 6b 65 73 20 61 73 20 74 68 65 20 65 72   takes as the er
31550 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 61  ror.** message a
31560 6c 6c 20 74 65 78 74 20 75 70 20 74 68 72 6f 75  ll text up throu
31570 67 68 20 74 68 65 20 66 69 72 73 74 20 7a 65 72  gh the first zer
31580 6f 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20  o character..** 
31590 49 66 20 74 68 65 20 74 68 69 72 64 20 70 61 72  If the third par
315a0 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
315b0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29  3_result_error()
315c0 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72   or.** sqlite3_r
315d0 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20  esult_error16() 
315e0 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20  is non-negative 
315f0 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65  then SQLite take
31600 73 20 74 68 61 74 20 6d 61 6e 79 0a 2a 2a 20 62  s that many.** b
31610 79 74 65 73 20 28 6e 6f 74 20 63 68 61 72 61 63  ytes (not charac
31620 74 65 72 73 29 20 66 72 6f 6d 20 74 68 65 20 32  ters) from the 2
31630 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 73 20  nd parameter as 
31640 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67  the error messag
31650 65 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  e..** The sqlite
31660 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29  3_result_error()
31670 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73   and sqlite3_res
31680 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a  ult_error16().**
31690 20 72 6f 75 74 69 6e 65 73 20 6d 61 6b 65 20 61   routines make a
316a0 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66   private copy of
316b0 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61   the error messa
316c0 67 65 20 74 65 78 74 20 62 65 66 6f 72 65 0a 2a  ge text before.*
316d0 2a 20 74 68 65 79 20 72 65 74 75 72 6e 2e 20 20  * they return.  
316e0 48 65 6e 63 65 2c 20 74 68 65 20 63 61 6c 6c 69  Hence, the calli
316f0 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20  ng function can 
31700 64 65 61 6c 6c 6f 63 61 74 65 20 6f 72 0a 2a 2a  deallocate or.**
31710 20 6d 6f 64 69 66 79 20 74 68 65 20 74 65 78 74   modify the text
31720 20 61 66 74 65 72 20 74 68 65 79 20 72 65 74 75   after they retu
31730 72 6e 20 77 69 74 68 6f 75 74 20 68 61 72 6d 2e  rn without harm.
31740 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
31750 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64  result_error_cod
31760 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 63 68 61  e() function cha
31770 6e 67 65 73 20 74 68 65 20 65 72 72 6f 72 20 63  nges the error c
31780 6f 64 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20  ode.** returned 
31790 62 79 20 53 51 4c 69 74 65 20 61 73 20 61 20 72  by SQLite as a r
317a0 65 73 75 6c 74 20 6f 66 20 61 6e 20 65 72 72 6f  esult of an erro
317b0 72 20 69 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e  r in a function.
317c0 20 20 42 79 20 64 65 66 61 75 6c 74 2c 0a 2a 2a    By default,.**
317d0 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 20   the error code 
317e0 69 73 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e  is SQLITE_ERROR.
317f0 20 20 41 20 73 75 62 73 65 71 75 65 6e 74 20 63    A subsequent c
31800 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 72  all to sqlite3_r
31810 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a  esult_error().**
31820 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75   or sqlite3_resu
31830 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 72 65 73  lt_error16() res
31840 65 74 73 20 74 68 65 20 65 72 72 6f 72 20 63 6f  ets the error co
31850 64 65 20 74 6f 20 53 51 4c 49 54 45 5f 45 52 52  de to SQLITE_ERR
31860 4f 52 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  OR..**.** The sq
31870 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 6f 6f  lite3_result_too
31880 62 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20  big() interface 
31890 63 61 75 73 65 73 20 53 51 4c 69 74 65 20 74 6f  causes SQLite to
318a0 20 74 68 72 6f 77 20 61 6e 20 65 72 72 6f 72 0a   throw an error.
318b0 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68  ** indicating th
318c0 61 74 20 61 20 73 74 72 69 6e 67 20 6f 72 20 42  at a string or B
318d0 4c 4f 42 20 69 73 20 74 6f 20 6c 6f 6e 67 20 74  LOB is to long t
318e0 6f 20 72 65 70 72 65 73 65 6e 74 2e 0a 2a 2a 0a  o represent..**.
318f0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72  ** The sqlite3_r
31900 65 73 75 6c 74 5f 6e 6f 6d 65 6d 28 29 20 69 6e  esult_nomem() in
31910 74 65 72 66 61 63 65 20 63 61 75 73 65 73 20 53  terface causes S
31920 51 4c 69 74 65 20 74 6f 20 74 68 72 6f 77 20 61  QLite to throw a
31930 6e 20 65 72 72 6f 72 0a 2a 2a 20 69 6e 64 69 63  n error.** indic
31940 61 74 69 6e 67 20 74 68 61 74 20 61 20 6d 65 6d  ating that a mem
31950 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66  ory allocation f
31960 61 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ailed..**.** The
31970 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
31980 69 6e 74 28 29 20 69 6e 74 65 72 66 61 63 65 20  int() interface 
31990 73 65 74 73 20 74 68 65 20 72 65 74 75 72 6e 20  sets the return 
319a0 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20  value.** of the 
319b0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
319c0 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  ned function to 
319d0 62 65 20 74 68 65 20 33 32 2d 62 69 74 20 73 69  be the 32-bit si
319e0 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20  gned integer.** 
319f0 76 61 6c 75 65 20 67 69 76 65 6e 20 69 6e 20 74  value given in t
31a00 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e  he 2nd argument.
31a10 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
31a20 72 65 73 75 6c 74 5f 69 6e 74 36 34 28 29 20 69  result_int64() i
31a30 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68  nterface sets th
31a40 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a  e return value.*
31a50 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61  * of the applica
31a60 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
31a70 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20  ction to be the 
31a80 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e  64-bit signed in
31a90 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67  teger.** value g
31aa0 69 76 65 6e 20 69 6e 20 74 68 65 20 32 6e 64 20  iven in the 2nd 
31ab0 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  argument..**.** 
31ac0 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
31ad0 6c 74 5f 6e 75 6c 6c 28 29 20 69 6e 74 65 72 66  lt_null() interf
31ae0 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65 74  ace sets the ret
31af0 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20  urn value.** of 
31b00 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
31b10 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
31b20 20 74 6f 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a   to be NULL..**.
31b30 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72  ** The sqlite3_r
31b40 65 73 75 6c 74 5f 74 65 78 74 28 29 2c 20 73 71  esult_text(), sq
31b50 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
31b60 74 31 36 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65  t16(),.** sqlite
31b70 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c  3_result_text16l
31b80 65 28 29 2c 20 61 6e 64 20 73 71 6c 69 74 65 33  e(), and sqlite3
31b90 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65  _result_text16be
31ba0 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  () interfaces.**
31bb0 20 73 65 74 20 74 68 65 20 72 65 74 75 72 6e 20   set the return 
31bc0 76 61 6c 75 65 20 6f 66 20 74 68 65 20 61 70 70  value of the app
31bd0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
31be0 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 0a   function to be.
31bf0 2a 2a 20 61 20 74 65 78 74 20 73 74 72 69 6e 67  ** a text string
31c00 20 77 68 69 63 68 20 69 73 20 72 65 70 72 65 73   which is repres
31c10 65 6e 74 65 64 20 61 73 20 55 54 46 2d 38 2c 20  ented as UTF-8, 
31c20 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79  UTF-16 native by
31c30 74 65 20 6f 72 64 65 72 2c 0a 2a 2a 20 55 54 46  te order,.** UTF
31c40 2d 31 36 20 6c 69 74 74 6c 65 20 65 6e 64 69 61  -16 little endia
31c50 6e 2c 20 6f 72 20 55 54 46 2d 31 36 20 62 69 67  n, or UTF-16 big
31c60 20 65 6e 64 69 61 6e 2c 20 72 65 73 70 65 63 74   endian, respect
31c70 69 76 65 6c 79 2e 0a 2a 2a 20 53 51 4c 69 74 65  ively..** SQLite
31c80 20 74 61 6b 65 73 20 74 68 65 20 74 65 78 74 20   takes the text 
31c90 72 65 73 75 6c 74 20 66 72 6f 6d 20 74 68 65 20  result from the 
31ca0 61 70 70 6c 69 63 61 74 69 6f 6e 20 66 72 6f 6d  application from
31cb0 0a 2a 2a 20 74 68 65 20 32 6e 64 20 70 61 72 61  .** the 2nd para
31cc0 6d 65 74 65 72 20 6f 66 20 74 68 65 20 73 71 6c  meter of the sql
31cd0 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
31ce0 2a 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a  * interfaces..**
31cf0 20 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61   If the 3rd para
31d00 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c  meter to the sql
31d10 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
31d20 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  * interfaces.** 
31d30 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65  is negative, the
31d40 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20 72  n SQLite takes r
31d50 65 73 75 6c 74 20 74 65 78 74 20 66 72 6f 6d 20  esult text from 
31d60 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65  the 2nd paramete
31d70 72 0a 2a 2a 20 74 68 72 6f 75 67 68 20 74 68 65  r.** through the
31d80 20 66 69 72 73 74 20 7a 65 72 6f 20 63 68 61 72   first zero char
31d90 61 63 74 65 72 2e 0a 2a 2a 20 49 66 20 74 68 65  acter..** If the
31da0 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74   3rd parameter t
31db0 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65  o the sqlite3_re
31dc0 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72  sult_text* inter
31dd0 66 61 63 65 73 0a 2a 2a 20 69 73 20 6e 6f 6e 2d  faces.** is non-
31de0 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 61  negative, then a
31df0 73 20 6d 61 6e 79 20 62 79 74 65 73 20 28 6e 6f  s many bytes (no
31e00 74 20 63 68 61 72 61 63 74 65 72 73 29 20 6f 66  t characters) of
31e10 20 74 68 65 20 74 65 78 74 0a 2a 2a 20 70 6f 69   the text.** poi
31e20 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65 20 32  nted to by the 2
31e30 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 72 65  nd parameter are
31e40 20 74 61 6b 65 6e 20 61 73 20 74 68 65 20 61 70   taken as the ap
31e50 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
31e60 64 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 72 65  d.** function re
31e70 73 75 6c 74 2e 0a 2a 2a 20 49 66 20 74 68 65 20  sult..** If the 
31e80 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  4th parameter to
31e90 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   the sqlite3_res
31ea0 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66  ult_text* interf
31eb0 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74  aces.** or sqlit
31ec0 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69  e3_result_blob i
31ed0 73 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69  s a non-NULL poi
31ee0 6e 74 65 72 2c 20 74 68 65 6e 20 53 51 4c 69 74  nter, then SQLit
31ef0 65 20 63 61 6c 6c 73 20 74 68 61 74 0a 2a 2a 20  e calls that.** 
31f00 66 75 6e 63 74 69 6f 6e 20 61 73 20 74 68 65 20  function as the 
31f10 64 65 73 74 72 75 63 74 6f 72 20 6f 6e 20 74 68  destructor on th
31f20 65 20 74 65 78 74 20 6f 72 20 42 4c 4f 42 20 72  e text or BLOB r
31f30 65 73 75 6c 74 20 77 68 65 6e 20 69 74 20 68 61  esult when it ha
31f40 73 0a 2a 2a 20 66 69 6e 69 73 68 65 64 20 75 73  s.** finished us
31f50 69 6e 67 20 74 68 61 74 20 72 65 73 75 6c 74 2e  ing that result.
31f60 0a 2a 2a 20 49 66 20 74 68 65 20 34 74 68 20 70  .** If the 4th p
31f70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
31f80 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
31f90 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 20  ext* interfaces 
31fa0 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65  or.** sqlite3_re
31fb0 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68 65  sult_blob is the
31fc0 20 73 70 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e   special constan
31fd0 74 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 2c  t SQLITE_STATIC,
31fe0 20 74 68 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20   then SQLite.** 
31ff0 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65  assumes that the
32000 20 74 65 78 74 20 6f 72 20 42 4c 4f 42 20 72 65   text or BLOB re
32010 73 75 6c 74 20 69 73 20 69 6e 20 63 6f 6e 73 74  sult is in const
32020 61 6e 74 20 73 70 61 63 65 20 61 6e 64 20 64 6f  ant space and do
32030 65 73 20 6e 6f 74 0a 2a 2a 20 63 6f 70 79 20 74  es not.** copy t
32040 68 65 20 69 74 20 6f 72 20 63 61 6c 6c 20 61 20  he it or call a 
32050 64 65 73 74 72 75 63 74 6f 72 20 77 68 65 6e 20  destructor when 
32060 69 74 20 68 61 73 20 66 69 6e 69 73 68 65 64 20  it has finished 
32070 75 73 69 6e 67 20 74 68 61 74 20 72 65 73 75 6c  using that resul
32080 74 2e 0a 2a 2a 20 49 66 20 74 68 65 20 34 74 68  t..** If the 4th
32090 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
320a0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
320b0 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65  _text* interface
320c0 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f  s.** or sqlite3_
320d0 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74  result_blob is t
320e0 68 65 20 73 70 65 63 69 61 6c 20 63 6f 6e 73 74  he special const
320f0 61 6e 74 20 53 51 4c 49 54 45 5f 54 52 41 4e 53  ant SQLITE_TRANS
32100 49 45 4e 54 0a 2a 2a 20 74 68 65 6e 20 53 51 4c  IENT.** then SQL
32110 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79  ite makes a copy
32120 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 69   of the result i
32130 6e 74 6f 20 73 70 61 63 65 20 6f 62 74 61 69 6e  nto space obtain
32140 65 64 20 66 72 6f 6d 0a 2a 2a 20 66 72 6f 6d 20  ed from.** from 
32150 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
32160 29 5d 20 62 65 66 6f 72 65 20 69 74 20 72 65 74  )] before it ret
32170 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  urns..**.** The 
32180 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76  sqlite3_result_v
32190 61 6c 75 65 28 29 20 69 6e 74 65 72 66 61 63 65  alue() interface
321a0 20 73 65 74 73 20 74 68 65 20 72 65 73 75 6c 74   sets the result
321b0 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69   of.** the appli
321c0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
321d0 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20  unction to be a 
321e0 63 6f 70 79 20 74 68 65 0a 2a 2a 20 5b 75 6e 70  copy the.** [unp
321f0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
32200 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 73  _value] object s
32210 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20  pecified by the 
32220 32 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20  2nd parameter.  
32230 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72  The.** sqlite3_r
32240 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 69 6e  esult_value() in
32250 74 65 72 66 61 63 65 20 6d 61 6b 65 73 20 61 20  terface makes a 
32260 63 6f 70 79 20 6f 66 20 74 68 65 20 5b 73 71 6c  copy of the [sql
32270 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 73  ite3_value].** s
32280 6f 20 74 68 61 74 20 74 68 65 20 5b 73 71 6c 69  o that the [sqli
32290 74 65 33 5f 76 61 6c 75 65 5d 20 73 70 65 63 69  te3_value] speci
322a0 66 69 65 64 20 69 6e 20 74 68 65 20 70 61 72 61  fied in the para
322b0 6d 65 74 65 72 20 6d 61 79 20 63 68 61 6e 67 65  meter may change
322c0 20 6f 72 0a 2a 2a 20 62 65 20 64 65 61 6c 6c 6f   or.** be deallo
322d0 63 61 74 65 64 20 61 66 74 65 72 20 73 71 6c 69  cated after sqli
322e0 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65  te3_result_value
322f0 28 29 20 72 65 74 75 72 6e 73 20 77 69 74 68 6f  () returns witho
32300 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 41 20 5b 70  ut harm..** A [p
32310 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
32320 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 6d  _value] object m
32330 61 79 20 61 6c 77 61 79 73 20 62 65 20 75 73 65  ay always be use
32340 64 20 77 68 65 72 65 20 61 6e 0a 2a 2a 20 5b 75  d where an.** [u
32350 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
32360 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
32370 20 69 73 20 72 65 71 75 69 72 65 64 2c 20 73 6f   is required, so
32380 20 65 69 74 68 65 72 0a 2a 2a 20 6b 69 6e 64 20   either.** kind 
32390 6f 66 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  of [sqlite3_valu
323a0 65 5d 20 6f 62 6a 65 63 74 20 63 61 6e 20 62 65  e] object can be
323b0 20 75 73 65 64 20 77 69 74 68 20 74 68 69 73 20   used with this 
323c0 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a  interface..**.**
323d0 20 49 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   If these routin
323e0 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 66 72  es are called fr
323f0 6f 6d 20 77 69 74 68 69 6e 20 74 68 65 20 64 69  om within the di
32400 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 0a 2a  fferent thread.*
32410 2a 20 74 68 61 6e 20 74 68 65 20 6f 6e 65 20 63  * than the one c
32420 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 61 70  ontaining the ap
32430 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
32440 64 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20  d function that 
32450 72 65 63 65 69 76 65 64 0a 2a 2a 20 74 68 65 20  received.** the 
32460 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  [sqlite3_context
32470 5d 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 20 72  ] pointer, the r
32480 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66  esults are undef
32490 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  ined..**.** INVA
324a0 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48  RIANTS:.**.** {H
324b0 31 36 34 30 33 7d 20 54 68 65 20 64 65 66 61 75  16403} The defau
324c0 6c 74 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  lt return value 
324d0 66 72 6f 6d 20 61 6e 79 20 53 51 4c 20 66 75 6e  from any SQL fun
324e0 63 74 69 6f 6e 20 69 73 20 4e 55 4c 4c 2e 0a 2a  ction is NULL..*
324f0 2a 0a 2a 2a 20 7b 48 31 36 34 30 36 7d 20 54 68  *.** {H16406} Th
32500 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  e [sqlite3_resul
32510 74 5f 62 6c 6f 62 28 43 2c 56 2c 4e 2c 44 29 5d  t_blob(C,V,N,D)]
32520 20 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67   interface chang
32530 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  es the.**       
32540 20 20 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20     return value 
32550 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f  of function C to
32560 20 62 65 20 61 20 42 4c 4f 42 20 74 68 61 74 20   be a BLOB that 
32570 69 73 20 4e 20 62 79 74 65 73 0a 2a 2a 20 20 20  is N bytes.**   
32580 20 20 20 20 20 20 20 69 6e 20 6c 65 6e 67 74 68         in length
32590 20 61 6e 64 20 77 69 74 68 20 63 6f 6e 74 65 6e   and with conten
325a0 74 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20  t pointed to by 
325b0 56 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 30 39  V..**.** {H16409
325c0 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72  } The [sqlite3_r
325d0 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28 43 2c 56  esult_double(C,V
325e0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68 61  )] interface cha
325f0 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 20  nges the.**     
32600 20 20 20 20 20 72 65 74 75 72 6e 20 76 61 6c 75       return valu
32610 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 20  e of function C 
32620 74 6f 20 62 65 20 74 68 65 20 66 6c 6f 61 74 69  to be the floati
32630 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 20 56  ng point value V
32640 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 31 32 7d  ..**.** {H16412}
32650 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65   The [sqlite3_re
32660 73 75 6c 74 5f 65 72 72 6f 72 28 43 2c 56 2c 4e  sult_error(C,V,N
32670 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68 61  )] interface cha
32680 6e 67 65 73 20 74 68 65 20 72 65 74 75 72 6e 0a  nges the return.
32690 2a 2a 20 20 20 20 20 20 20 20 20 20 76 61 6c 75  **          valu
326a0 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 20  e of function C 
326b0 74 6f 20 62 65 20 61 6e 20 65 78 63 65 70 74 69  to be an excepti
326c0 6f 6e 20 77 69 74 68 20 65 72 72 6f 72 20 63 6f  on with error co
326d0 64 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  de.**          [
326e0 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 61 6e  SQLITE_ERROR] an
326f0 64 20 61 20 55 54 46 2d 38 20 65 72 72 6f 72 20  d a UTF-8 error 
32700 6d 65 73 73 61 67 65 20 63 6f 70 69 65 64 20 66  message copied f
32710 72 6f 6d 20 56 20 75 70 20 74 6f 20 74 68 65 0a  rom V up to the.
32720 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69 72 73  **          firs
32730 74 20 7a 65 72 6f 20 62 79 74 65 20 6f 72 20 75  t zero byte or u
32740 6e 74 69 6c 20 4e 20 62 79 74 65 73 20 61 72 65  ntil N bytes are
32750 20 72 65 61 64 20 69 66 20 4e 20 69 73 20 70 6f   read if N is po
32760 73 69 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48  sitive..**.** {H
32770 31 36 34 31 35 7d 20 54 68 65 20 5b 73 71 6c 69  16415} The [sqli
32780 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
32790 31 36 28 43 2c 56 2c 4e 29 5d 20 69 6e 74 65 72  16(C,V,N)] inter
327a0 66 61 63 65 20 63 68 61 6e 67 65 73 20 74 68 65  face changes the
327b0 20 72 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20 20   return.**      
327c0 20 20 20 20 76 61 6c 75 65 20 6f 66 20 66 75 6e      value of fun
327d0 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 61 6e  ction C to be an
327e0 20 65 78 63 65 70 74 69 6f 6e 20 77 69 74 68 20   exception with 
327f0 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 20 20  error code.**   
32800 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 45         [SQLITE_E
32810 52 52 4f 52 5d 20 61 6e 64 20 61 20 55 54 46 2d  RROR] and a UTF-
32820 31 36 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  16 native byte o
32830 72 64 65 72 20 65 72 72 6f 72 20 6d 65 73 73 61  rder error messa
32840 67 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63  ge.**          c
32850 6f 70 69 65 64 20 66 72 6f 6d 20 56 20 75 70 20  opied from V up 
32860 74 6f 20 74 68 65 20 66 69 72 73 74 20 7a 65 72  to the first zer
32870 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 6f 72 20  o terminator or 
32880 75 6e 74 69 6c 20 4e 20 62 79 74 65 73 0a 2a 2a  until N bytes.**
32890 20 20 20 20 20 20 20 20 20 20 61 72 65 20 72 65            are re
328a0 61 64 20 69 66 20 4e 20 69 73 20 70 6f 73 69 74  ad if N is posit
328b0 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34  ive..**.** {H164
328c0 31 38 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  18} The [sqlite3
328d0 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 74 6f  _result_error_to
328e0 6f 62 69 67 28 43 29 5d 20 69 6e 74 65 72 66 61  obig(C)] interfa
328f0 63 65 20 63 68 61 6e 67 65 73 20 74 68 65 20 72  ce changes the r
32900 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20  eturn.**        
32910 20 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 66    value of the f
32920 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20  unction C to be 
32930 61 6e 20 65 78 63 65 70 74 69 6f 6e 20 77 69 74  an exception wit
32940 68 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20  h error code.** 
32950 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45           [SQLITE
32960 5f 54 4f 4f 42 49 47 5d 20 61 6e 64 20 61 6e 20  _TOOBIG] and an 
32970 61 70 70 72 6f 70 72 69 61 74 65 20 65 72 72 6f  appropriate erro
32980 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a  r message..**.**
32990 20 7b 48 31 36 34 32 31 7d 20 54 68 65 20 5b 73   {H16421} The [s
329a0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
329b0 72 6f 72 5f 6e 6f 6d 65 6d 28 43 29 5d 20 69 6e  ror_nomem(C)] in
329c0 74 65 72 66 61 63 65 20 63 68 61 6e 67 65 73 20  terface changes 
329d0 74 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20 20 20  the return.**   
329e0 20 20 20 20 20 20 20 76 61 6c 75 65 20 6f 66 20         value of 
329f0 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 43 20 74  the function C t
32a00 6f 20 62 65 20 61 6e 20 65 78 63 65 70 74 69 6f  o be an exceptio
32a10 6e 20 77 69 74 68 20 65 72 72 6f 72 20 63 6f 64  n with error cod
32a20 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53  e.**          [S
32a30 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20 61 6e 64  QLITE_NOMEM] and
32a40 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20   an appropriate 
32a50 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a  error message..*
32a60 2a 0a 2a 2a 20 7b 48 31 36 34 32 34 7d 20 54 68  *.** {H16424} Th
32a70 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  e [sqlite3_resul
32a80 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28 43 2c 45  t_error_code(C,E
32a90 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68 61  )] interface cha
32aa0 6e 67 65 73 20 74 68 65 20 72 65 74 75 72 6e 0a  nges the return.
32ab0 2a 2a 20 20 20 20 20 20 20 20 20 20 76 61 6c 75  **          valu
32ac0 65 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f  e of the functio
32ad0 6e 20 43 20 74 6f 20 62 65 20 61 6e 20 65 78 63  n C to be an exc
32ae0 65 70 74 69 6f 6e 20 77 69 74 68 20 65 72 72 6f  eption with erro
32af0 72 20 63 6f 64 65 20 45 2e 0a 2a 2a 20 20 20 20  r code E..**    
32b00 20 20 20 20 20 20 54 68 65 20 65 72 72 6f 72 20        The error 
32b10 6d 65 73 73 61 67 65 20 74 65 78 74 20 69 73 20  message text is 
32b20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a  unchanged..**.**
32b30 20 7b 48 31 36 34 32 37 7d 20 54 68 65 20 5b 73   {H16427} The [s
32b40 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e  qlite3_result_in
32b50 74 28 43 2c 56 29 5d 20 69 6e 74 65 72 66 61 63  t(C,V)] interfac
32b60 65 20 63 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a  e changes the.**
32b70 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e            return
32b80 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 69   value of functi
32b90 6f 6e 20 43 20 74 6f 20 62 65 20 74 68 65 20 33  on C to be the 3
32ba0 32 2d 62 69 74 20 69 6e 74 65 67 65 72 20 76 61  2-bit integer va
32bb0 6c 75 65 20 56 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  lue V..**.** {H1
32bc0 36 34 33 30 7d 20 54 68 65 20 5b 73 71 6c 69 74  6430} The [sqlit
32bd0 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 28  e3_result_int64(
32be0 43 2c 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20  C,V)] interface 
32bf0 63 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20  changes the.**  
32c00 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 20 76          return v
32c10 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e  alue of function
32c20 20 43 20 74 6f 20 62 65 20 74 68 65 20 36 34 2d   C to be the 64-
32c30 62 69 74 20 69 6e 74 65 67 65 72 20 76 61 6c 75  bit integer valu
32c40 65 20 56 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34  e V..**.** {H164
32c50 33 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  33} The [sqlite3
32c60 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 43 29 5d  _result_null(C)]
32c70 20 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67   interface chang
32c80 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  es the.**       
32c90 20 20 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20     return value 
32ca0 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f  of function C to
32cb0 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   be NULL..**.** 
32cc0 7b 48 31 36 34 33 36 7d 20 54 68 65 20 5b 73 71  {H16436} The [sq
32cd0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
32ce0 74 28 43 2c 56 2c 4e 2c 44 29 5d 20 69 6e 74 65  t(C,V,N,D)] inte
32cf0 72 66 61 63 65 20 63 68 61 6e 67 65 73 20 74 68  rface changes th
32d00 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65  e.**          re
32d10 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 66 75  turn value of fu
32d20 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 74  nction C to be t
32d30 68 65 20 55 54 46 2d 38 20 73 74 72 69 6e 67 0a  he UTF-8 string.
32d40 2a 2a 20 20 20 20 20 20 20 20 20 20 56 20 75 70  **          V up
32d50 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 7a 65   to the first ze
32d60 72 6f 20 69 66 20 4e 20 69 73 20 6e 65 67 61 74  ro if N is negat
32d70 69 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ive.**          
32d80 6f 72 20 74 68 65 20 66 69 72 73 74 20 4e 20 62  or the first N b
32d90 79 74 65 73 20 6f 66 20 56 20 69 66 20 4e 20 69  ytes of V if N i
32da0 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2e 0a  s non-negative..
32db0 2a 2a 0a 2a 2a 20 7b 48 31 36 34 33 39 7d 20 54  **.** {H16439} T
32dc0 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  he [sqlite3_resu
32dd0 6c 74 5f 74 65 78 74 31 36 28 43 2c 56 2c 4e 2c  lt_text16(C,V,N,
32de0 44 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68  D)] interface ch
32df0 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20 20 20  anges the.**    
32e00 20 20 20 20 20 20 72 65 74 75 72 6e 20 76 61 6c        return val
32e10 75 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43  ue of function C
32e20 20 74 6f 20 62 65 20 74 68 65 20 55 54 46 2d 31   to be the UTF-1
32e30 36 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  6 native byte or
32e40 64 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  der.**          
32e50 73 74 72 69 6e 67 20 56 20 75 70 20 74 6f 20 74  string V up to t
32e60 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 69 66  he first zero if
32e70 20 4e 20 69 73 20 6e 65 67 61 74 69 76 65 0a 2a   N is negative.*
32e80 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 74 68  *          or th
32e90 65 20 66 69 72 73 74 20 4e 20 62 79 74 65 73 20  e first N bytes 
32ea0 6f 66 20 56 20 69 66 20 4e 20 69 73 20 6e 6f 6e  of V if N is non
32eb0 2d 6e 65 67 61 74 69 76 65 2e 0a 2a 2a 0a 2a 2a  -negative..**.**
32ec0 20 7b 48 31 36 34 34 32 7d 20 54 68 65 20 5b 73   {H16442} The [s
32ed0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
32ee0 78 74 31 36 62 65 28 43 2c 56 2c 4e 2c 44 29 5d  xt16be(C,V,N,D)]
32ef0 20 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67   interface chang
32f00 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  es the.**       
32f10 20 20 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20     return value 
32f20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f  of function C to
32f30 20 62 65 20 74 68 65 20 55 54 46 2d 31 36 20 62   be the UTF-16 b
32f40 69 67 2d 65 6e 64 69 61 6e 0a 2a 2a 20 20 20 20  ig-endian.**    
32f50 20 20 20 20 20 20 73 74 72 69 6e 67 20 56 20 75        string V u
32f60 70 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 7a  p to the first z
32f70 65 72 6f 20 69 66 20 4e 20 69 73 20 6e 65 67 61  ero if N is nega
32f80 74 69 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  tive.**         
32f90 20 6f 72 20 74 68 65 20 66 69 72 73 74 20 4e 20   or the first N 
32fa0 62 79 74 65 73 20 6f 72 20 56 20 69 66 20 4e 20  bytes or V if N 
32fb0 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2e  is non-negative.
32fc0 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 34 35 7d 20  .**.** {H16445} 
32fd0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  The [sqlite3_res
32fe0 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 43 2c 56  ult_text16le(C,V
32ff0 2c 4e 2c 44 29 5d 20 69 6e 74 65 72 66 61 63 65  ,N,D)] interface
33000 20 63 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20   changes the.** 
33010 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 20           return 
33020 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 6f  value of functio
33030 6e 20 43 20 74 6f 20 62 65 20 74 68 65 20 55 54  n C to be the UT
33040 46 2d 31 36 20 6c 69 74 74 6c 65 2d 65 6e 64 69  F-16 little-endi
33050 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73  an.**          s
33060 74 72 69 6e 67 20 56 20 75 70 20 74 6f 20 74 68  tring V up to th
33070 65 20 66 69 72 73 74 20 7a 65 72 6f 20 69 66 20  e first zero if 
33080 4e 20 69 73 20 6e 65 67 61 74 69 76 65 0a 2a 2a  N is negative.**
33090 20 20 20 20 20 20 20 20 20 20 6f 72 20 74 68 65            or the
330a0 20 66 69 72 73 74 20 4e 20 62 79 74 65 73 20 6f   first N bytes o
330b0 66 20 56 20 69 66 20 4e 20 69 73 20 6e 6f 6e 2d  f V if N is non-
330c0 6e 65 67 61 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20  negative..**.** 
330d0 7b 48 31 36 34 34 38 7d 20 54 68 65 20 5b 73 71  {H16448} The [sq
330e0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c  lite3_result_val
330f0 75 65 28 43 2c 56 29 5d 20 69 6e 74 65 72 66 61  ue(C,V)] interfa
33100 63 65 20 63 68 61 6e 67 65 73 20 74 68 65 0a 2a  ce changes the.*
33110 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72  *          retur
33120 6e 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 74  n value of funct
33130 69 6f 6e 20 43 20 74 6f 20 62 65 20 74 68 65 20  ion C to be the 
33140 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c  [unprotected sql
33150 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 20  ite3_value].**  
33160 20 20 20 20 20 20 20 20 6f 62 6a 65 63 74 20 56          object V
33170 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 35 31 7d  ..**.** {H16451}
33180 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65   The [sqlite3_re
33190 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 43 2c  sult_zeroblob(C,
331a0 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68  N)] interface ch
331b0 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20 20 20  anges the.**    
331c0 20 20 20 20 20 20 72 65 74 75 72 6e 20 76 61 6c        return val
331d0 75 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43  ue of function C
331e0 20 74 6f 20 62 65 20 61 6e 20 4e 2d 62 79 74 65   to be an N-byte
331f0 20 42 4c 4f 42 20 6f 66 20 61 6c 6c 20 7a 65 72   BLOB of all zer
33200 6f 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 35  os..**.** {H1645
33210 34 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  4} The [sqlite3_
33220 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 5d 20  result_error()] 
33230 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  and [sqlite3_res
33240 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 5d 0a 2a  ult_error16()].*
33250 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74 65 72  *          inter
33260 66 61 63 65 73 20 6d 61 6b 65 20 61 20 63 6f 70  faces make a cop
33270 79 20 6f 66 20 74 68 65 69 72 20 65 72 72 6f 72  y of their error
33280 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 73   message strings
33290 20 62 65 66 6f 72 65 0a 2a 2a 20 20 20 20 20 20   before.**      
332a0 20 20 20 20 72 65 74 75 72 6e 69 6e 67 2e 0a 2a      returning..*
332b0 2a 0a 2a 2a 20 7b 48 31 36 34 35 37 7d 20 49 66  *.** {H16457} If
332c0 20 74 68 65 20 44 20 64 65 73 74 72 75 63 74 6f   the D destructo
332d0 72 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  r parameter to [
332e0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62  sqlite3_result_b
332f0 6c 6f 62 28 43 2c 56 2c 4e 2c 44 29 5d 2c 0a 2a  lob(C,V,N,D)],.*
33300 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
33310 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28  te3_result_text(
33320 43 2c 56 2c 4e 2c 44 29 5d 2c 20 5b 73 71 6c 69  C,V,N,D)], [sqli
33330 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31  te3_result_text1
33340 36 28 43 2c 56 2c 4e 2c 44 29 5d 2c 0a 2a 2a 20  6(C,V,N,D)],.** 
33350 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
33360 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62  3_result_text16b
33370 65 28 43 2c 56 2c 4e 2c 44 29 5d 2c 20 6f 72 0a  e(C,V,N,D)], or.
33380 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
33390 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
333a0 31 36 6c 65 28 43 2c 56 2c 4e 2c 44 29 5d 20 69  16le(C,V,N,D)] i
333b0 73 20 74 68 65 20 63 6f 6e 73 74 61 6e 74 20 5b  s the constant [
333c0 53 51 4c 49 54 45 5f 53 54 41 54 49 43 5d 0a 2a  SQLITE_STATIC].*
333d0 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 6e 20  *          then 
333e0 6e 6f 20 64 65 73 74 72 75 63 74 6f 72 20 69 73  no destructor is
333f0 20 65 76 65 72 20 63 61 6c 6c 65 64 20 6f 6e 20   ever called on 
33400 74 68 65 20 70 6f 69 6e 74 65 72 20 56 20 61 6e  the pointer V an
33410 64 20 53 51 4c 69 74 65 0a 2a 2a 20 20 20 20 20  d SQLite.**     
33420 20 20 20 20 20 61 73 73 75 6d 65 73 20 74 68 61       assumes tha
33430 74 20 56 20 69 73 20 69 6d 6d 75 74 61 62 6c 65  t V is immutable
33440 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 36 30 7d  ..**.** {H16460}
33450 20 49 66 20 74 68 65 20 44 20 64 65 73 74 72 75   If the D destru
33460 63 74 6f 72 20 70 61 72 61 6d 65 74 65 72 20 74  ctor parameter t
33470 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  o [sqlite3_resul
33480 74 5f 62 6c 6f 62 28 43 2c 56 2c 4e 2c 44 29 5d  t_blob(C,V,N,D)]
33490 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  ,.**          [s
334a0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
334b0 78 74 28 43 2c 56 2c 4e 2c 44 29 5d 2c 20 5b 73  xt(C,V,N,D)], [s
334c0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
334d0 78 74 31 36 28 43 2c 56 2c 4e 2c 44 29 5d 2c 0a  xt16(C,V,N,D)],.
334e0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
334f0 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
33500 31 36 62 65 28 43 2c 56 2c 4e 2c 44 29 5d 2c 20  16be(C,V,N,D)], 
33510 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  or.**          [
33520 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
33530 65 78 74 31 36 6c 65 28 43 2c 56 2c 4e 2c 44 29  ext16le(C,V,N,D)
33540 5d 20 69 73 20 74 68 65 20 63 6f 6e 73 74 61 6e  ] is the constan
33550 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53  t.**          [S
33560 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d  QLITE_TRANSIENT]
33570 20 74 68 65 6e 20 74 68 65 20 69 6e 74 65 72 66   then the interf
33580 61 63 65 73 20 6d 61 6b 65 73 20 61 20 63 6f 70  aces makes a cop
33590 79 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 20  y of the.**     
335a0 20 20 20 20 20 63 6f 6e 74 65 6e 74 20 6f 66 20       content of 
335b0 56 20 61 6e 64 20 72 65 74 61 69 6e 73 20 74 68  V and retains th
335c0 65 20 63 6f 70 79 2e 0a 2a 2a 0a 2a 2a 20 7b 48  e copy..**.** {H
335d0 31 36 34 36 33 7d 20 49 66 20 74 68 65 20 44 20  16463} If the D 
335e0 64 65 73 74 72 75 63 74 6f 72 20 70 61 72 61 6d  destructor param
335f0 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33  eter to [sqlite3
33600 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 43 2c 56  _result_blob(C,V
33610 2c 4e 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20  ,N,D)],.**      
33620 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73      [sqlite3_res
33630 75 6c 74 5f 74 65 78 74 28 43 2c 56 2c 4e 2c 44  ult_text(C,V,N,D
33640 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  )], [sqlite3_res
33650 75 6c 74 5f 74 65 78 74 31 36 28 43 2c 56 2c 4e  ult_text16(C,V,N
33660 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20  ,D)],.**        
33670 20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c    [sqlite3_resul
33680 74 5f 74 65 78 74 31 36 62 65 28 43 2c 56 2c 4e  t_text16be(C,V,N
33690 2c 44 29 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20 20  ,D)], or.**     
336a0 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 72 65       [sqlite3_re
336b0 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 43 2c  sult_text16le(C,
336c0 56 2c 4e 2c 44 29 5d 20 69 73 20 73 6f 6d 65 20  V,N,D)] is some 
336d0 76 61 6c 75 65 20 6f 74 68 65 72 20 74 68 61 6e  value other than
336e0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
336f0 20 63 6f 6e 73 74 61 6e 74 73 20 5b 53 51 4c 49   constants [SQLI
33700 54 45 5f 53 54 41 54 49 43 5d 20 61 6e 64 20 5b  TE_STATIC] and [
33710 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54  SQLITE_TRANSIENT
33720 5d 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20  ] then.**       
33730 20 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 69     SQLite will i
33740 6e 76 6f 6b 65 20 74 68 65 20 64 65 73 74 72 75  nvoke the destru
33750 63 74 6f 72 20 44 20 77 69 74 68 20 56 20 61 73  ctor D with V as
33760 20 69 74 73 20 6f 6e 6c 79 20 61 72 67 75 6d 65   its only argume
33770 6e 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77  nt.**          w
33780 68 65 6e 20 69 74 20 68 61 73 20 66 69 6e 69 73  hen it has finis
33790 68 65 64 20 77 69 74 68 20 74 68 65 20 56 20 76  hed with the V v
337a0 61 6c 75 65 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71  alue..*/.void sq
337b0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f  lite3_result_blo
337c0 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  b(sqlite3_contex
337d0 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  t*, const void*,
337e0 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f   int, void(*)(vo
337f0 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69  id*));.void sqli
33800 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c  te3_result_doubl
33810 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  e(sqlite3_contex
33820 74 2a 2c 20 64 6f 75 62 6c 65 29 3b 0a 76 6f 69  t*, double);.voi
33830 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
33840 5f 65 72 72 6f 72 28 73 71 6c 69 74 65 33 5f 63  _error(sqlite3_c
33850 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63  ontext*, const c
33860 68 61 72 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64  har*, int);.void
33870 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
33880 65 72 72 6f 72 31 36 28 73 71 6c 69 74 65 33 5f  error16(sqlite3_
33890 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20  context*, const 
338a0 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69  void*, int);.voi
338b0 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
338c0 5f 65 72 72 6f 72 5f 74 6f 6f 62 69 67 28 73 71  _error_toobig(sq
338d0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b  lite3_context*);
338e0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
338f0 73 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d  sult_error_nomem
33900 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
33910 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  *);.void sqlite3
33920 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63 6f  _result_error_co
33930 64 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  de(sqlite3_conte
33940 78 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20  xt*, int);.void 
33950 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69  sqlite3_result_i
33960 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  nt(sqlite3_conte
33970 78 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20  xt*, int);.void 
33980 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69  sqlite3_result_i
33990 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 63 6f 6e  nt64(sqlite3_con
339a0 74 65 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f 69  text*, sqlite3_i
339b0 6e 74 36 34 29 3b 0a 76 6f 69 64 20 73 71 6c 69  nt64);.void sqli
339c0 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28  te3_result_null(
339d0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
339e0 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
339f0 72 65 73 75 6c 74 5f 74 65 78 74 28 73 71 6c 69  result_text(sqli
33a00 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f  te3_context*, co
33a10 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 2c 20  nst char*, int, 
33a20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b  void(*)(void*));
33a30 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
33a40 73 75 6c 74 5f 74 65 78 74 31 36 28 73 71 6c 69  sult_text16(sqli
33a50 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f  te3_context*, co
33a60 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20  nst void*, int, 
33a70 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b  void(*)(void*));
33a80 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
33a90 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 73 71  sult_text16le(sq
33aa0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
33ab0 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
33ac0 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29  ,void(*)(void*))
33ad0 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
33ae0 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28 73  esult_text16be(s
33af0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
33b00 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e   const void*, in
33b10 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  t,void(*)(void*)
33b20 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
33b30 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 73 71 6c  result_value(sql
33b40 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73  ite3_context*, s
33b50 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
33b60 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
33b70 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c  ult_zeroblob(sql
33b80 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69  ite3_context*, i
33b90 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  nt n);../*.** CA
33ba0 50 49 33 52 45 46 3a 20 44 65 66 69 6e 65 20 4e  PI3REF: Define N
33bb0 65 77 20 43 6f 6c 6c 61 74 69 6e 67 20 53 65 71  ew Collating Seq
33bc0 75 65 6e 63 65 73 20 7b 48 31 36 36 30 30 7d 20  uences {H16600} 
33bd0 3c 53 32 30 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 54  <S20300>.**.** T
33be0 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 61  hese functions a
33bf0 72 65 20 75 73 65 64 20 74 6f 20 61 64 64 20 6e  re used to add n
33c00 65 77 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71  ew collation seq
33c10 75 65 6e 63 65 73 20 74 6f 20 74 68 65 0a 2a 2a  uences to the.**
33c20 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
33c30 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64  ction] specified
33c40 20 61 73 20 74 68 65 20 66 69 72 73 74 20 61 72   as the first ar
33c50 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68  gument..**.** Th
33c60 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6e 65  e name of the ne
33c70 77 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75  w collation sequ
33c80 65 6e 63 65 20 69 73 20 73 70 65 63 69 66 69 65  ence is specifie
33c90 64 20 61 73 20 61 20 55 54 46 2d 38 20 73 74 72  d as a UTF-8 str
33ca0 69 6e 67 0a 2a 2a 20 66 6f 72 20 73 71 6c 69 74  ing.** for sqlit
33cb0 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
33cc0 69 6f 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ion() and sqlite
33cd0 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
33ce0 6f 6e 5f 76 32 28 29 0a 2a 2a 20 61 6e 64 20 61  on_v2().** and a
33cf0 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 66   UTF-16 string f
33d00 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  or sqlite3_creat
33d10 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 2e  e_collation16().
33d20 20 49 6e 20 61 6c 6c 20 63 61 73 65 73 0a 2a 2a   In all cases.**
33d30 20 74 68 65 20 6e 61 6d 65 20 69 73 20 70 61 73   the name is pas
33d40 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e  sed as the secon
33d50 64 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d  d function argum
33d60 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74  ent..**.** The t
33d70 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 6d 61  hird argument ma
33d80 79 20 62 65 20 6f 6e 65 20 6f 66 20 74 68 65 20  y be one of the 
33d90 63 6f 6e 73 74 61 6e 74 73 20 5b 53 51 4c 49 54  constants [SQLIT
33da0 45 5f 55 54 46 38 5d 2c 0a 2a 2a 20 5b 53 51 4c  E_UTF8],.** [SQL
33db0 49 54 45 5f 55 54 46 31 36 4c 45 5d 20 6f 72 20  ITE_UTF16LE] or 
33dc0 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d  [SQLITE_UTF16BE]
33dd0 2c 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68 61  , indicating tha
33de0 74 20 74 68 65 20 75 73 65 72 2d 73 75 70 70 6c  t the user-suppl
33df0 69 65 64 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 65  ied.** routine e
33e00 78 70 65 63 74 73 20 74 6f 20 62 65 20 70 61 73  xpects to be pas
33e10 73 65 64 20 70 6f 69 6e 74 65 72 73 20 74 6f 20  sed pointers to 
33e20 73 74 72 69 6e 67 73 20 65 6e 63 6f 64 65 64 20  strings encoded 
33e30 75 73 69 6e 67 20 55 54 46 2d 38 2c 0a 2a 2a 20  using UTF-8,.** 
33e40 55 54 46 2d 31 36 20 6c 69 74 74 6c 65 2d 65 6e  UTF-16 little-en
33e50 64 69 61 6e 2c 20 6f 72 20 55 54 46 2d 31 36 20  dian, or UTF-16 
33e60 62 69 67 2d 65 6e 64 69 61 6e 2c 20 72 65 73 70  big-endian, resp
33e70 65 63 74 69 76 65 6c 79 2e 20 54 68 65 0a 2a 2a  ectively. The.**
33e80 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20   third argument 
33e90 6d 69 67 68 74 20 61 6c 73 6f 20 62 65 20 5b 53  might also be [S
33ea0 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47  QLITE_UTF16_ALIG
33eb0 4e 45 44 5d 20 74 6f 20 69 6e 64 69 63 61 74 65  NED] to indicate
33ec0 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 72 6f 75   that.** the rou
33ed0 74 69 6e 65 20 65 78 70 65 63 74 73 20 70 6f 69  tine expects poi
33ee0 6e 74 65 72 73 20 74 6f 20 31 36 2d 62 69 74 20  nters to 16-bit 
33ef0 77 6f 72 64 20 61 6c 69 67 6e 65 64 20 73 74 72  word aligned str
33f00 69 6e 67 73 0a 2a 2a 20 6f 66 20 55 54 46 2d 31  ings.** of UTF-1
33f10 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20  6 in the native 
33f20 62 79 74 65 20 6f 72 64 65 72 20 6f 66 20 74 68  byte order of th
33f30 65 20 68 6f 73 74 20 63 6f 6d 70 75 74 65 72 2e  e host computer.
33f40 0a 2a 2a 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72  .**.** A pointer
33f50 20 74 6f 20 74 68 65 20 75 73 65 72 20 73 75 70   to the user sup
33f60 70 6c 69 65 64 20 72 6f 75 74 69 6e 65 20 6d 75  plied routine mu
33f70 73 74 20 62 65 20 70 61 73 73 65 64 20 61 73 20  st be passed as 
33f80 74 68 65 20 66 69 66 74 68 0a 2a 2a 20 61 72 67  the fifth.** arg
33f90 75 6d 65 6e 74 2e 20 20 49 66 20 69 74 20 69 73  ument.  If it is
33fa0 20 4e 55 4c 4c 2c 20 74 68 69 73 20 69 73 20 74   NULL, this is t
33fb0 68 65 20 73 61 6d 65 20 61 73 20 64 65 6c 65 74  he same as delet
33fc0 69 6e 67 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f  ing the collatio
33fd0 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20 28 73  n.** sequence (s
33fe0 6f 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 61  o that SQLite ca
33ff0 6e 6e 6f 74 20 63 61 6c 6c 20 69 74 20 61 6e 79  nnot call it any
34000 6d 6f 72 65 29 2e 0a 2a 2a 20 45 61 63 68 20 74  more)..** Each t
34010 69 6d 65 20 74 68 65 20 61 70 70 6c 69 63 61 74  ime the applicat
34020 69 6f 6e 20 73 75 70 70 6c 69 65 64 20 66 75 6e  ion supplied fun
34030 63 74 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 64  ction is invoked
34040 2c 20 69 74 20 69 73 20 70 61 73 73 65 64 0a 2a  , it is passed.*
34050 2a 20 61 73 20 69 74 73 20 66 69 72 73 74 20 70  * as its first p
34060 61 72 61 6d 65 74 65 72 20 61 20 63 6f 70 79 20  arameter a copy 
34070 6f 66 20 74 68 65 20 76 6f 69 64 2a 20 70 61 73  of the void* pas
34080 73 65 64 20 61 73 20 74 68 65 20 66 6f 75 72 74  sed as the fourt
34090 68 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f  h argument.** to
340a0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
340b0 63 6f 6c 6c 61 74 69 6f 6e 28 29 20 6f 72 20 73  collation() or s
340c0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
340d0 6c 6c 61 74 69 6f 6e 31 36 28 29 2e 0a 2a 2a 0a  llation16()..**.
340e0 2a 2a 20 54 68 65 20 72 65 6d 61 69 6e 69 6e 67  ** The remaining
340f0 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68   arguments to th
34100 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73 75  e application-su
34110 70 70 6c 69 65 64 20 72 6f 75 74 69 6e 65 20 61  pplied routine a
34120 72 65 20 74 77 6f 20 73 74 72 69 6e 67 73 2c 0a  re two strings,.
34130 2a 2a 20 65 61 63 68 20 72 65 70 72 65 73 65 6e  ** each represen
34140 74 65 64 20 62 79 20 61 20 28 6c 65 6e 67 74 68  ted by a (length
34150 2c 20 64 61 74 61 29 20 70 61 69 72 20 61 6e 64  , data) pair and
34160 20 65 6e 63 6f 64 65 64 20 69 6e 20 74 68 65 20   encoded in the 
34170 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20 74 68 61 74  encoding.** that
34180 20 77 61 73 20 70 61 73 73 65 64 20 61 73 20 74   was passed as t
34190 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  he third argumen
341a0 74 20 77 68 65 6e 20 74 68 65 20 63 6f 6c 6c 61  t when the colla
341b0 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 20 77 61  tion sequence wa
341c0 73 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64 2e  s.** registered.
341d0 20 7b 45 4e 44 7d 20 20 54 68 65 20 61 70 70 6c   {END}  The appl
341e0 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20  ication defined 
341f0 63 6f 6c 6c 61 74 69 6f 6e 20 72 6f 75 74 69 6e  collation routin
34200 65 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75  e should.** retu
34210 72 6e 20 6e 65 67 61 74 69 76 65 2c 20 7a 65 72  rn negative, zer
34220 6f 20 6f 72 20 70 6f 73 69 74 69 76 65 20 69 66  o or positive if
34230 20 74 68 65 20 66 69 72 73 74 20 73 74 72 69 6e   the first strin
34240 67 20 69 73 20 6c 65 73 73 20 74 68 61 6e 2c 0a  g is less than,.
34250 2a 2a 20 65 71 75 61 6c 20 74 6f 2c 20 6f 72 20  ** equal to, or 
34260 67 72 65 61 74 65 72 20 74 68 61 6e 20 74 68 65  greater than the
34270 20 73 65 63 6f 6e 64 20 73 74 72 69 6e 67 2e 20   second string. 
34280 69 2e 65 2e 20 28 53 54 52 49 4e 47 31 20 2d 20  i.e. (STRING1 - 
34290 53 54 52 49 4e 47 32 29 2e 0a 2a 2a 0a 2a 2a 20  STRING2)..**.** 
342a0 54 68 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61  The sqlite3_crea
342b0 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28  te_collation_v2(
342c0 29 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c  ) works like sql
342d0 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
342e0 61 74 69 6f 6e 28 29 0a 2a 2a 20 65 78 63 65 70  ation().** excep
342f0 74 20 74 68 61 74 20 69 74 20 74 61 6b 65 73 20  t that it takes 
34300 61 6e 20 65 78 74 72 61 20 61 72 67 75 6d 65 6e  an extra argumen
34310 74 20 77 68 69 63 68 20 69 73 20 61 20 64 65 73  t which is a des
34320 74 72 75 63 74 6f 72 20 66 6f 72 0a 2a 2a 20 74  tructor for.** t
34330 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 2e 20 20 54  he collation.  T
34340 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 69 73  he destructor is
34350 20 63 61 6c 6c 65 64 20 77 68 65 6e 20 74 68 65   called when the
34360 20 63 6f 6c 6c 61 74 69 6f 6e 20 69 73 0a 2a 2a   collation is.**
34370 20 64 65 73 74 72 6f 79 65 64 20 61 6e 64 20 69   destroyed and i
34380 73 20 70 61 73 73 65 64 20 61 20 63 6f 70 79 20  s passed a copy 
34390 6f 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61  of the fourth pa
343a0 72 61 6d 65 74 65 72 20 76 6f 69 64 2a 20 70 6f  rameter void* po
343b0 69 6e 74 65 72 0a 2a 2a 20 6f 66 20 74 68 65 20  inter.** of the 
343c0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
343d0 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 2e 0a 2a  ollation_v2()..*
343e0 2a 20 43 6f 6c 6c 61 74 69 6f 6e 73 20 61 72 65  * Collations are
343f0 20 64 65 73 74 72 6f 79 65 64 20 77 68 65 6e 20   destroyed when 
34400 74 68 65 79 20 61 72 65 20 6f 76 65 72 72 69 64  they are overrid
34410 64 65 6e 20 62 79 20 6c 61 74 65 72 20 63 61 6c  den by later cal
34420 6c 73 20 74 6f 20 74 68 65 0a 2a 2a 20 63 6f 6c  ls to the.** col
34430 6c 61 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20  lation creation 
34440 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 77 68 65  functions or whe
34450 6e 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  n the [database 
34460 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 63  connection] is c
34470 6c 6f 73 65 64 0a 2a 2a 20 75 73 69 6e 67 20 5b  losed.** using [
34480 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d  sqlite3_close()]
34490 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  ..**.** INVARIAN
344a0 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 36 30  TS:.**.** {H1660
344b0 33 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c 20  3} A successful 
344c0 63 61 6c 6c 20 74 6f 20 74 68 65 0a 2a 2a 20 20  call to the.**  
344d0 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
344e0 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
344f0 6e 5f 76 32 28 42 2c 58 2c 45 2c 50 2c 46 2c 44  n_v2(B,X,E,P,F,D
34500 29 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  )] interface.** 
34510 20 20 20 20 20 20 20 20 20 72 65 67 69 73 74 65           registe
34520 72 73 20 66 75 6e 63 74 69 6f 6e 20 46 20 61 73  rs function F as
34530 20 74 68 65 20 63 6f 6d 70 61 72 69 73 6f 6e 20   the comparison 
34540 66 75 6e 63 74 69 6f 6e 20 75 73 65 64 20 74 6f  function used to
34550 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6d 70  .**          imp
34560 6c 65 6d 65 6e 74 20 63 6f 6c 6c 61 74 69 6f 6e  lement collation
34570 20 58 20 6f 6e 20 74 68 65 20 5b 64 61 74 61 62   X on the [datab
34580 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
34590 42 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20  B for.**        
345a0 20 20 64 61 74 61 62 61 73 65 73 20 68 61 76 69    databases havi
345b0 6e 67 20 65 6e 63 6f 64 69 6e 67 20 45 2e 0a 2a  ng encoding E..*
345c0 2a 0a 2a 2a 20 7b 48 31 36 36 30 34 7d 20 53 51  *.** {H16604} SQ
345d0 4c 69 74 65 20 75 6e 64 65 72 73 74 61 6e 64 73  Lite understands
345e0 20 74 68 65 20 58 20 70 61 72 61 6d 65 74 65 72   the X parameter
345f0 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   to.**          
34600 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
34610 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 42 2c 58  collation_v2(B,X
34620 2c 45 2c 50 2c 46 2c 44 29 5d 20 61 73 20 61 20  ,E,P,F,D)] as a 
34630 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a  zero-terminated.
34640 2a 2a 20 20 20 20 20 20 20 20 20 20 55 54 46 2d  **          UTF-
34650 38 20 73 74 72 69 6e 67 20 69 6e 20 77 68 69 63  8 string in whic
34660 68 20 63 61 73 65 20 69 73 20 69 67 6e 6f 72 65  h case is ignore
34670 64 20 66 6f 72 20 41 53 43 49 49 20 63 68 61 72  d for ASCII char
34680 61 63 74 65 72 73 20 61 6e 64 0a 2a 2a 20 20 20  acters and.**   
34690 20 20 20 20 20 20 20 69 73 20 73 69 67 6e 69 66         is signif
346a0 69 63 61 6e 74 20 66 6f 72 20 6e 6f 6e 2d 41 53  icant for non-AS
346b0 43 49 49 20 63 68 61 72 61 63 74 65 72 73 2e 0a  CII characters..
346c0 2a 2a 0a 2a 2a 20 7b 48 31 36 36 30 36 7d 20 53  **.** {H16606} S
346d0 75 63 63 65 73 73 69 76 65 20 63 61 6c 6c 73 20  uccessive calls 
346e0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  to [sqlite3_crea
346f0 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28  te_collation_v2(
34700 42 2c 58 2c 45 2c 50 2c 46 2c 44 29 5d 0a 2a 2a  B,X,E,P,F,D)].**
34710 20 20 20 20 20 20 20 20 20 20 77 69 74 68 20 74            with t
34720 68 65 20 73 61 6d 65 20 76 61 6c 75 65 73 20 66  he same values f
34730 6f 72 20 42 2c 20 58 2c 20 61 6e 64 20 45 2c 20  or B, X, and E, 
34740 6f 76 65 72 72 69 64 65 20 70 72 69 6f 72 20 76  override prior v
34750 61 6c 75 65 73 0a 2a 2a 20 20 20 20 20 20 20 20  alues.**        
34760 20 20 6f 66 20 50 2c 20 46 2c 20 61 6e 64 20 44    of P, F, and D
34770 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 36 30 39 7d  ..**.** {H16609}
34780 20 49 66 20 74 68 65 20 64 65 73 74 72 75 63 74   If the destruct
34790 6f 72 20 44 20 69 6e 20 5b 73 71 6c 69 74 65 33  or D in [sqlite3
347a0 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
347b0 6e 5f 76 32 28 42 2c 58 2c 45 2c 50 2c 46 2c 44  n_v2(B,X,E,P,F,D
347c0 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  )].**          i
347d0 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20  s not NULL then 
347e0 69 74 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74  it is called wit
347f0 68 20 61 72 67 75 6d 65 6e 74 20 50 20 77 68 65  h argument P whe
34800 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  n the.**        
34810 20 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63    collating func
34820 74 69 6f 6e 20 69 73 20 64 72 6f 70 70 65 64 20  tion is dropped 
34830 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a  by SQLite..**.**
34840 20 7b 48 31 36 36 31 32 7d 20 41 20 63 6f 6c 6c   {H16612} A coll
34850 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69  ating function i
34860 73 20 64 72 6f 70 70 65 64 20 77 68 65 6e 20 69  s dropped when i
34870 74 20 69 73 20 6f 76 65 72 6c 6f 61 64 65 64 2e  t is overloaded.
34880 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 36 31 35 7d 20  .**.** {H16615} 
34890 41 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63  A collating func
348a0 74 69 6f 6e 20 69 73 20 64 72 6f 70 70 65 64 20  tion is dropped 
348b0 77 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  when the databas
348c0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20  e connection.** 
348d0 20 20 20 20 20 20 20 20 20 69 73 20 63 6c 6f 73           is clos
348e0 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ed using [sqlite
348f0 33 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 0a 2a  3_close()]..**.*
34900 2a 20 7b 48 31 36 36 31 38 7d 20 54 68 65 20 70  * {H16618} The p
34910 6f 69 6e 74 65 72 20 50 20 69 6e 20 5b 73 71 6c  ointer P in [sql
34920 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
34930 61 74 69 6f 6e 5f 76 32 28 42 2c 58 2c 45 2c 50  ation_v2(B,X,E,P
34940 2c 46 2c 44 29 5d 0a 2a 2a 20 20 20 20 20 20 20  ,F,D)].**       
34950 20 20 20 69 73 20 70 61 73 73 65 64 20 74 68 72     is passed thr
34960 6f 75 67 68 20 61 73 20 74 68 65 20 66 69 72 73  ough as the firs
34970 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  t parameter to t
34980 68 65 20 63 6f 6d 70 61 72 69 73 6f 6e 0a 2a 2a  he comparison.**
34990 20 20 20 20 20 20 20 20 20 20 66 75 6e 63 74 69            functi
349a0 6f 6e 20 46 20 66 6f 72 20 61 6c 6c 20 73 75 62  on F for all sub
349b0 73 65 71 75 65 6e 74 20 69 6e 76 6f 63 61 74 69  sequent invocati
349c0 6f 6e 73 20 6f 66 20 46 2e 0a 2a 2a 0a 2a 2a 20  ons of F..**.** 
349d0 7b 48 31 36 36 32 31 7d 20 41 20 63 61 6c 6c 20  {H16621} A call 
349e0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  to [sqlite3_crea
349f0 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 42 2c 58  te_collation(B,X
34a00 2c 45 2c 50 2c 46 29 5d 20 69 73 20 65 78 61 63  ,E,P,F)] is exac
34a10 74 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  tly.**          
34a20 74 68 65 20 73 61 6d 65 20 61 73 20 61 20 63 61  the same as a ca
34a30 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ll to [sqlite3_c
34a40 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  reate_collation_
34a50 76 32 28 29 5d 20 77 69 74 68 0a 2a 2a 20 20 20  v2()] with.**   
34a60 20 20 20 20 20 20 20 74 68 65 20 73 61 6d 65 20         the same 
34a70 70 61 72 61 6d 65 74 65 72 73 20 61 6e 64 20 61  parameters and a
34a80 20 4e 55 4c 4c 20 64 65 73 74 72 75 63 74 6f 72   NULL destructor
34a90 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 36 32 34 7d  ..**.** {H16624}
34aa0 20 46 6f 6c 6c 6f 77 69 6e 67 20 61 20 5b 73 71   Following a [sq
34ab0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
34ac0 6c 61 74 69 6f 6e 5f 76 32 28 42 2c 58 2c 45 2c  lation_v2(B,X,E,
34ad0 50 2c 46 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20  P,F,D)],.**     
34ae0 20 20 20 20 20 53 51 4c 69 74 65 20 75 73 65 73       SQLite uses
34af0 20 74 68 65 20 63 6f 6d 70 61 72 69 73 6f 6e 20   the comparison 
34b00 66 75 6e 63 74 69 6f 6e 20 46 20 66 6f 72 20 61  function F for a
34b10 6c 6c 20 74 65 78 74 20 63 6f 6d 70 61 72 69 73  ll text comparis
34b20 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  on.**          o
34b30 70 65 72 61 74 69 6f 6e 73 20 6f 6e 20 74 68 65  perations on the
34b40 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
34b50 63 74 69 6f 6e 5d 20 42 20 6f 6e 20 74 65 78 74  ction] B on text
34b60 20 76 61 6c 75 65 73 20 74 68 61 74 0a 2a 2a 20   values that.** 
34b70 20 20 20 20 20 20 20 20 20 75 73 65 20 74 68 65           use the
34b80 20 63 6f 6c 6c 61 74 69 6e 67 20 73 65 71 75 65   collating seque
34b90 6e 63 65 20 6e 61 6d 65 64 20 58 2e 0a 2a 2a 0a  nce named X..**.
34ba0 2a 2a 20 7b 48 31 36 36 32 37 7d 20 54 68 65 20  ** {H16627} The 
34bb0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
34bc0 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 42 2c 58 2c  collation16(B,X,
34bd0 45 2c 50 2c 46 29 5d 20 77 6f 72 6b 73 20 74 68  E,P,F)] works th
34be0 65 20 73 61 6d 65 0a 2a 2a 20 20 20 20 20 20 20  e same.**       
34bf0 20 20 20 61 73 20 5b 73 71 6c 69 74 65 33 5f 63     as [sqlite3_c
34c00 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28  reate_collation(
34c10 42 2c 58 2c 45 2c 50 2c 46 29 5d 20 65 78 63 65  B,X,E,P,F)] exce
34c20 70 74 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 20  pt that the.**  
34c30 20 20 20 20 20 20 20 20 63 6f 6c 6c 61 74 69 6f          collatio
34c40 6e 20 6e 61 6d 65 20 58 20 69 73 20 75 6e 64 65  n name X is unde
34c50 72 73 74 6f 6f 64 20 61 73 20 55 54 46 2d 31 36  rstood as UTF-16
34c60 20 69 6e 20 6e 61 74 69 76 65 20 62 79 74 65 20   in native byte 
34c70 6f 72 64 65 72 0a 2a 2a 20 20 20 20 20 20 20 20  order.**        
34c80 20 20 69 6e 73 74 65 61 64 20 6f 66 20 55 54 46    instead of UTF
34c90 2d 38 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 36 33  -8..**.** {H1663
34ca0 30 7d 20 57 68 65 6e 20 6d 75 6c 74 69 70 6c 65  0} When multiple
34cb0 20 63 6f 6d 70 61 72 69 73 6f 6e 20 66 75 6e 63   comparison func
34cc0 74 69 6f 6e 73 20 61 72 65 20 61 76 61 69 6c 61  tions are availa
34cd0 62 6c 65 20 66 6f 72 20 74 68 65 20 73 61 6d 65  ble for the same
34ce0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6c  .**          col
34cf0 6c 61 74 69 6e 67 20 73 65 71 75 65 6e 63 65 2c  lating sequence,
34d00 20 53 51 4c 69 74 65 20 63 68 6f 6f 73 65 73 20   SQLite chooses 
34d10 74 68 65 20 6f 6e 65 20 77 68 6f 73 65 20 74 65  the one whose te
34d20 78 74 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20 20  xt encoding.**  
34d30 20 20 20 20 20 20 20 20 72 65 71 75 69 72 65 73          requires
34d40 20 74 68 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e   the least amoun
34d50 74 20 6f 66 20 63 6f 6e 76 65 72 73 69 6f 6e 20  t of conversion 
34d60 66 72 6f 6d 20 74 68 65 20 64 65 66 61 75 6c 74  from the default
34d70 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 65 78  .**          tex
34d80 74 20 65 6e 63 6f 64 69 6e 67 20 6f 66 20 74 68  t encoding of th
34d90 65 20 64 61 74 61 62 61 73 65 2e 0a 2a 2f 0a 69  e database..*/.i
34da0 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  nt sqlite3_creat
34db0 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 0a 20 20 73  e_collation(.  s
34dc0 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73  qlite3*, .  cons
34dd0 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a  t char *zName, .
34de0 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20    int eTextRep, 
34df0 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 69 6e 74 28  .  void*,.  int(
34e00 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a  *xCompare)(void*
34e10 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a  ,int,const void*
34e20 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a  ,int,const void*
34e30 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ).);.int sqlite3
34e40 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
34e50 6e 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 2a  n_v2(.  sqlite3*
34e60 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  , .  const char 
34e70 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65  *zName, .  int e
34e80 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64  TextRep, .  void
34e90 2a 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61  *,.  int(*xCompa
34ea0 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f  re)(void*,int,co
34eb0 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f  nst void*,int,co
34ec0 6e 73 74 20 76 6f 69 64 2a 29 2c 0a 20 20 76 6f  nst void*),.  vo
34ed0 69 64 28 2a 78 44 65 73 74 72 6f 79 29 28 76 6f  id(*xDestroy)(vo
34ee0 69 64 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69  id*).);.int sqli
34ef0 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
34f00 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74 65  tion16(.  sqlite
34f10 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 76 6f 69  3*, .  const voi
34f20 64 20 2a 7a 4e 61 6d 65 2c 0a 20 20 69 6e 74 20  d *zName,.  int 
34f30 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69  eTextRep, .  voi
34f40 64 2a 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70  d*,.  int(*xComp
34f50 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63  are)(void*,int,c
34f60 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63  onst void*,int,c
34f70 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a  onst void*).);..
34f80 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
34f90 43 6f 6c 6c 61 74 69 6f 6e 20 4e 65 65 64 65 64  Collation Needed
34fa0 20 43 61 6c 6c 62 61 63 6b 73 20 7b 48 31 36 37   Callbacks {H167
34fb0 30 30 7d 20 3c 53 32 30 33 30 30 3e 0a 2a 2a 0a  00} <S20300>.**.
34fc0 2a 2a 20 54 6f 20 61 76 6f 69 64 20 68 61 76 69  ** To avoid havi
34fd0 6e 67 20 74 6f 20 72 65 67 69 73 74 65 72 20 61  ng to register a
34fe0 6c 6c 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71  ll collation seq
34ff0 75 65 6e 63 65 73 20 62 65 66 6f 72 65 20 61 20  uences before a 
35000 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 61 6e 20  database.** can 
35010 62 65 20 75 73 65 64 2c 20 61 20 73 69 6e 67 6c  be used, a singl
35020 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  e callback funct
35030 69 6f 6e 20 6d 61 79 20 62 65 20 72 65 67 69 73  ion may be regis
35040 74 65 72 65 64 20 77 69 74 68 20 74 68 65 0a 2a  tered with the.*
35050 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
35060 65 63 74 69 6f 6e 5d 20 74 6f 20 62 65 20 63 61  ection] to be ca
35070 6c 6c 65 64 20 77 68 65 6e 65 76 65 72 20 61 6e  lled whenever an
35080 20 75 6e 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61   undefined colla
35090 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65  tion.** sequence
350a0 20 69 73 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a   is required..**
350b0 0a 2a 2a 20 49 66 20 74 68 65 20 66 75 6e 63 74  .** If the funct
350c0 69 6f 6e 20 69 73 20 72 65 67 69 73 74 65 72 65  ion is registere
350d0 64 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69  d using the sqli
350e0 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65  te3_collation_ne
350f0 65 64 65 64 28 29 20 41 50 49 2c 0a 2a 2a 20 74  eded() API,.** t
35100 68 65 6e 20 69 74 20 69 73 20 70 61 73 73 65 64  hen it is passed
35110 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 75 6e   the names of un
35120 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f  defined collatio
35130 6e 20 73 65 71 75 65 6e 63 65 73 20 61 73 20 73  n sequences as s
35140 74 72 69 6e 67 73 0a 2a 2a 20 65 6e 63 6f 64 65  trings.** encode
35150 64 20 69 6e 20 55 54 46 2d 38 2e 20 7b 48 31 36  d in UTF-8. {H16
35160 37 30 33 7d 20 49 66 20 73 71 6c 69 74 65 33 5f  703} If sqlite3_
35170 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64  collation_needed
35180 31 36 28 29 20 69 73 20 75 73 65 64 2c 0a 2a 2a  16() is used,.**
35190 20 74 68 65 20 6e 61 6d 65 73 20 61 72 65 20 70   the names are p
351a0 61 73 73 65 64 20 61 73 20 55 54 46 2d 31 36 20  assed as UTF-16 
351b0 69 6e 20 6d 61 63 68 69 6e 65 20 6e 61 74 69 76  in machine nativ
351c0 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a  e byte order..**
351d0 20 41 20 63 61 6c 6c 20 74 6f 20 65 69 74 68 65   A call to eithe
351e0 72 20 66 75 6e 63 74 69 6f 6e 20 72 65 70 6c 61  r function repla
351f0 63 65 73 20 61 6e 79 20 65 78 69 73 74 69 6e 67  ces any existing
35200 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a   callback..**.**
35210 20 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61   When the callba
35220 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 74  ck is invoked, t
35230 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
35240 74 20 70 61 73 73 65 64 20 69 73 20 61 20 63 6f  t passed is a co
35250 70 79 0a 2a 2a 20 6f 66 20 74 68 65 20 73 65 63  py.** of the sec
35260 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ond argument to 
35270 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f  sqlite3_collatio
35280 6e 5f 6e 65 65 64 65 64 28 29 20 6f 72 0a 2a 2a  n_needed() or.**
35290 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69   sqlite3_collati
352a0 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 2e 20 20  on_needed16().  
352b0 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  The second argum
352c0 65 6e 74 20 69 73 20 74 68 65 20 64 61 74 61 62  ent is the datab
352d0 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  ase.** connectio
352e0 6e 2e 20 20 54 68 65 20 74 68 69 72 64 20 61 72  n.  The third ar
352f0 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66  gument is one of
35300 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c 20   [SQLITE_UTF8], 
35310 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d  [SQLITE_UTF16BE]
35320 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f  ,.** or [SQLITE_
35330 55 54 46 31 36 4c 45 5d 2c 20 69 6e 64 69 63 61  UTF16LE], indica
35340 74 69 6e 67 20 74 68 65 20 6d 6f 73 74 20 64 65  ting the most de
35350 73 69 72 61 62 6c 65 20 66 6f 72 6d 20 6f 66 20  sirable form of 
35360 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a  the collation.**
35370 20 73 65 71 75 65 6e 63 65 20 66 75 6e 63 74 69   sequence functi
35380 6f 6e 20 72 65 71 75 69 72 65 64 2e 20 20 54 68  on required.  Th
35390 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
353a0 65 72 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f  er is the name o
353b0 66 20 74 68 65 0a 2a 2a 20 72 65 71 75 69 72 65  f the.** require
353c0 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75  d collation sequ
353d0 65 6e 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ence..**.** The 
353e0 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
353f0 6e 20 73 68 6f 75 6c 64 20 72 65 67 69 73 74 65  n should registe
35400 72 20 74 68 65 20 64 65 73 69 72 65 64 20 63 6f  r the desired co
35410 6c 6c 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a  llation using.**
35420 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
35430 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 5d 2c 20 5b  _collation()], [
35440 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
35450 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 5d 2c 20 6f  ollation16()], o
35460 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72  r.** [sqlite3_cr
35470 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76  eate_collation_v
35480 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  2()]..**.** INVA
35490 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48  RIANTS:.**.** {H
354a0 31 36 37 30 32 7d 20 41 20 73 75 63 63 65 73 73  16702} A success
354b0 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ful call to [sql
354c0 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e  ite3_collation_n
354d0 65 65 64 65 64 28 44 2c 50 2c 46 29 5d 0a 2a 2a  eeded(D,P,F)].**
354e0 20 20 20 20 20 20 20 20 20 20 6f 72 20 5b 73 71            or [sq
354f0 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  lite3_collation_
35500 6e 65 65 64 65 64 31 36 28 44 2c 50 2c 46 29 5d  needed16(D,P,F)]
35510 20 63 61 75 73 65 73 0a 2a 2a 20 20 20 20 20 20   causes.**      
35520 20 20 20 20 74 68 65 20 5b 64 61 74 61 62 61 73      the [databas
35530 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20  e connection] D 
35540 74 6f 20 69 6e 76 6f 6b 65 20 63 61 6c 6c 62 61  to invoke callba
35550 63 6b 20 46 20 77 69 74 68 20 66 69 72 73 74 0a  ck F with first.
35560 2a 2a 20 20 20 20 20 20 20 20 20 20 70 61 72 61  **          para
35570 6d 65 74 65 72 20 50 20 77 68 65 6e 65 76 65 72  meter P whenever
35580 20 69 74 20 6e 65 65 64 73 20 61 20 63 6f 6d 70   it needs a comp
35590 61 72 69 73 6f 6e 20 66 75 6e 63 74 69 6f 6e 20  arison function 
355a0 66 6f 72 20 61 0a 2a 2a 20 20 20 20 20 20 20 20  for a.**        
355b0 20 20 63 6f 6c 6c 61 74 69 6e 67 20 73 65 71 75    collating sequ
355c0 65 6e 63 65 20 74 68 61 74 20 69 74 20 64 6f 65  ence that it doe
355d0 73 20 6e 6f 74 20 6b 6e 6f 77 20 61 62 6f 75 74  s not know about
355e0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 37 30 34 7d  ..**.** {H16704}
355f0 20 45 61 63 68 20 73 75 63 63 65 73 73 66 75 6c   Each successful
35600 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
35610 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64  3_collation_need
35620 65 64 28 29 5d 20 6f 72 0a 2a 2a 20 20 20 20 20  ed()] or.**     
35630 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f       [sqlite3_co
35640 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36  llation_needed16
35650 28 29 5d 20 6f 76 65 72 72 69 64 65 73 20 74 68  ()] overrides th
35660 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 67 69 73  e callback regis
35670 74 65 72 65 64 0a 2a 2a 20 20 20 20 20 20 20 20  tered.**        
35680 20 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b 64    on the same [d
35690 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
356a0 6f 6e 5d 20 62 79 20 70 72 69 6f 72 20 63 61 6c  on] by prior cal
356b0 6c 73 20 74 6f 20 65 69 74 68 65 72 0a 2a 2a 20  ls to either.** 
356c0 20 20 20 20 20 20 20 20 20 69 6e 74 65 72 66 61           interfa
356d0 63 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 37 30  ce..**.** {H1670
356e0 36 7d 20 54 68 65 20 6e 61 6d 65 20 6f 66 20 74  6} The name of t
356f0 68 65 20 72 65 71 75 65 73 74 65 64 20 63 6f 6c  he requested col
35700 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20  lating function 
35710 70 61 73 73 65 64 20 69 6e 20 74 68 65 0a 2a 2a  passed in the.**
35720 20 20 20 20 20 20 20 20 20 20 34 74 68 20 70 61            4th pa
35730 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63  rameter to the c
35740 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 20 55 54  allback is in UT
35750 46 2d 38 20 69 66 20 74 68 65 20 63 61 6c 6c 62  F-8 if the callb
35760 61 63 6b 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ack.**          
35770 77 61 73 20 72 65 67 69 73 74 65 72 65 64 20 75  was registered u
35780 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6f  sing [sqlite3_co
35790 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29  llation_needed()
357a0 5d 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20  ] and.**        
357b0 20 20 69 73 20 69 6e 20 55 54 46 2d 31 36 20 6e    is in UTF-16 n
357c0 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
357d0 20 69 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   if the callback
357e0 20 77 61 73 0a 2a 2a 20 20 20 20 20 20 20 20 20   was.**         
357f0 20 72 65 67 69 73 74 65 72 65 64 20 75 73 69 6e   registered usin
35800 67 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61  g [sqlite3_colla
35810 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 5d  tion_needed16()]
35820 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
35830 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65  _collation_neede
35840 64 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a  d(.  sqlite3*, .
35850 20 20 76 6f 69 64 2a 2c 20 0a 20 20 76 6f 69 64    void*, .  void
35860 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65  (*)(void*,sqlite
35870 33 2a 2c 69 6e 74 20 65 54 65 78 74 52 65 70 2c  3*,int eTextRep,
35880 63 6f 6e 73 74 20 63 68 61 72 2a 29 0a 29 3b 0a  const char*).);.
35890 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c  int sqlite3_coll
358a0 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 0a  ation_needed16(.
358b0 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76    sqlite3*, .  v
358c0 6f 69 64 2a 2c 0a 20 20 76 6f 69 64 28 2a 29 28  oid*,.  void(*)(
358d0 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 69  void*,sqlite3*,i
358e0 6e 74 20 65 54 65 78 74 52 65 70 2c 63 6f 6e 73  nt eTextRep,cons
358f0 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a  t void*).);../*.
35900 2a 2a 20 53 70 65 63 69 66 79 20 74 68 65 20 6b  ** Specify the k
35910 65 79 20 66 6f 72 20 61 6e 20 65 6e 63 72 79 70  ey for an encryp
35920 74 65 64 20 64 61 74 61 62 61 73 65 2e 20 20 54  ted database.  T
35930 68 69 73 20 72 6f 75 74 69 6e 65 20 73 68 6f 75  his routine shou
35940 6c 64 20 62 65 0a 2a 2a 20 63 61 6c 6c 65 64 20  ld be.** called 
35950 72 69 67 68 74 20 61 66 74 65 72 20 73 71 6c 69  right after sqli
35960 74 65 33 5f 6f 70 65 6e 28 29 2e 0a 2a 2a 0a 2a  te3_open()..**.*
35970 2a 20 54 68 65 20 63 6f 64 65 20 74 6f 20 69 6d  * The code to im
35980 70 6c 65 6d 65 6e 74 20 74 68 69 73 20 41 50 49  plement this API
35990 20 69 73 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c   is not availabl
359a0 65 20 69 6e 20 74 68 65 20 70 75 62 6c 69 63 20  e in the public 
359b0 72 65 6c 65 61 73 65 0a 2a 2a 20 6f 66 20 53 51  release.** of SQ
359c0 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  Lite..*/.int sql
359d0 69 74 65 33 5f 6b 65 79 28 0a 20 20 73 71 6c 69  ite3_key(.  sqli
359e0 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
359f0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61             /* Da
35a00 74 61 62 61 73 65 20 74 6f 20 62 65 20 72 65 6b  tabase to be rek
35a10 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  eyed */.  const 
35a20 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20  void *pKey, int 
35a30 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54 68 65 20  nKey     /* The 
35a40 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  key */.);../*.**
35a50 20 43 68 61 6e 67 65 20 74 68 65 20 6b 65 79 20   Change the key 
35a60 6f 6e 20 61 6e 20 6f 70 65 6e 20 64 61 74 61 62  on an open datab
35a70 61 73 65 2e 20 20 49 66 20 74 68 65 20 63 75 72  ase.  If the cur
35a80 72 65 6e 74 20 64 61 74 61 62 61 73 65 20 69 73  rent database is
35a90 20 6e 6f 74 0a 2a 2a 20 65 6e 63 72 79 70 74 65   not.** encrypte
35aa0 64 2c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  d, this routine 
35ab0 77 69 6c 6c 20 65 6e 63 72 79 70 74 20 69 74 2e  will encrypt it.
35ac0 20 20 49 66 20 70 4e 65 77 3d 3d 30 20 6f 72 20    If pNew==0 or 
35ad0 6e 4e 65 77 3d 3d 30 2c 20 74 68 65 0a 2a 2a 20  nNew==0, the.** 
35ae0 64 61 74 61 62 61 73 65 20 69 73 20 64 65 63 72  database is decr
35af0 79 70 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ypted..**.** The
35b00 20 63 6f 64 65 20 74 6f 20 69 6d 70 6c 65 6d 65   code to impleme
35b10 6e 74 20 74 68 69 73 20 41 50 49 20 69 73 20 6e  nt this API is n
35b20 6f 74 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 20  ot available in 
35b30 74 68 65 20 70 75 62 6c 69 63 20 72 65 6c 65 61  the public relea
35b40 73 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 2e  se.** of SQLite.
35b50 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
35b60 72 65 6b 65 79 28 0a 20 20 73 71 6c 69 74 65 33  rekey(.  sqlite3
35b70 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
35b80 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62          /* Datab
35b90 61 73 65 20 74 6f 20 62 65 20 72 65 6b 65 79 65  ase to be rekeye
35ba0 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69  d */.  const voi
35bb0 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65  d *pKey, int nKe
35bc0 79 20 20 20 20 20 2f 2a 20 54 68 65 20 6e 65 77  y     /* The new
35bd0 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a   key */.);../*.*
35be0 2a 20 43 41 50 49 33 52 45 46 3a 20 53 75 73 70  * CAPI3REF: Susp
35bf0 65 6e 64 20 45 78 65 63 75 74 69 6f 6e 20 46 6f  end Execution Fo
35c00 72 20 41 20 53 68 6f 72 74 20 54 69 6d 65 20 7b  r A Short Time {
35c10 48 31 30 35 33 30 7d 20 3c 53 34 30 34 31 30 3e  H10530} <S40410>
35c20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
35c30 65 33 5f 73 6c 65 65 70 28 29 20 66 75 6e 63 74  e3_sleep() funct
35c40 69 6f 6e 20 63 61 75 73 65 73 20 74 68 65 20 63  ion causes the c
35c50 75 72 72 65 6e 74 20 74 68 72 65 61 64 20 74 6f  urrent thread to
35c60 20 73 75 73 70 65 6e 64 20 65 78 65 63 75 74 69   suspend executi
35c70 6f 6e 0a 2a 2a 20 66 6f 72 20 61 74 20 6c 65 61  on.** for at lea
35c80 73 74 20 61 20 6e 75 6d 62 65 72 20 6f 66 20 6d  st a number of m
35c90 69 6c 6c 69 73 65 63 6f 6e 64 73 20 73 70 65 63  illiseconds spec
35ca0 69 66 69 65 64 20 69 6e 20 69 74 73 20 70 61 72  ified in its par
35cb0 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66  ameter..**.** If
35cc0 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73   the operating s
35cd0 79 73 74 65 6d 20 64 6f 65 73 20 6e 6f 74 20 73  ystem does not s
35ce0 75 70 70 6f 72 74 20 73 6c 65 65 70 20 72 65 71  upport sleep req
35cf0 75 65 73 74 73 20 77 69 74 68 0a 2a 2a 20 6d 69  uests with.** mi
35d00 6c 6c 69 73 65 63 6f 6e 64 20 74 69 6d 65 20 72  llisecond time r
35d10 65 73 6f 6c 75 74 69 6f 6e 2c 20 74 68 65 6e 20  esolution, then 
35d20 74 68 65 20 74 69 6d 65 20 77 69 6c 6c 20 62 65  the time will be
35d30 20 72 6f 75 6e 64 65 64 20 75 70 20 74 6f 0a 2a   rounded up to.*
35d40 2a 20 74 68 65 20 6e 65 61 72 65 73 74 20 73 65  * the nearest se
35d50 63 6f 6e 64 2e 20 54 68 65 20 6e 75 6d 62 65 72  cond. The number
35d60 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73   of milliseconds
35d70 20 6f 66 20 73 6c 65 65 70 20 61 63 74 75 61 6c   of sleep actual
35d80 6c 79 0a 2a 2a 20 72 65 71 75 65 73 74 65 64 20  ly.** requested 
35d90 66 72 6f 6d 20 74 68 65 20 6f 70 65 72 61 74 69  from the operati
35da0 6e 67 20 73 79 73 74 65 6d 20 69 73 20 72 65 74  ng system is ret
35db0 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c  urned..**.** SQL
35dc0 69 74 65 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74  ite implements t
35dd0 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 62 79  his interface by
35de0 20 63 61 6c 6c 69 6e 67 20 74 68 65 20 78 53 6c   calling the xSl
35df0 65 65 70 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20  eep().** method 
35e00 6f 66 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b  of the default [
35e10 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a  sqlite3_vfs] obj
35e20 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  ect..**.** INVAR
35e30 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31  IANTS:.**.** {H1
35e40 30 35 33 33 7d 20 54 68 65 20 5b 73 71 6c 69 74  0533} The [sqlit
35e50 65 33 5f 73 6c 65 65 70 28 4d 29 5d 20 69 6e 74  e3_sleep(M)] int
35e60 65 72 66 61 63 65 20 69 6e 76 6f 6b 65 73 20 74  erface invokes t
35e70 68 65 20 78 53 6c 65 65 70 0a 2a 2a 20 20 20 20  he xSleep.**    
35e80 20 20 20 20 20 20 6d 65 74 68 6f 64 20 6f 66 20        method of 
35e90 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c  the default [sql
35ea0 69 74 65 33 5f 76 66 73 7c 56 46 53 5d 20 69 6e  ite3_vfs|VFS] in
35eb0 20 6f 72 64 65 72 20 74 6f 0a 2a 2a 20 20 20 20   order to.**    
35ec0 20 20 20 20 20 20 73 75 73 70 65 6e 64 20 65 78        suspend ex
35ed0 65 63 75 74 69 6f 6e 20 6f 66 20 74 68 65 20 63  ecution of the c
35ee0 75 72 72 65 6e 74 20 74 68 72 65 61 64 20 66 6f  urrent thread fo
35ef0 72 20 61 74 20 6c 65 61 73 74 0a 2a 2a 20 20 20  r at least.**   
35f00 20 20 20 20 20 20 20 4d 20 6d 69 6c 6c 69 73 65         M millise
35f10 63 6f 6e 64 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  conds..**.** {H1
35f20 30 35 33 36 7d 20 54 68 65 20 5b 73 71 6c 69 74  0536} The [sqlit
35f30 65 33 5f 73 6c 65 65 70 28 4d 29 5d 20 69 6e 74  e3_sleep(M)] int
35f40 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74  erface returns t
35f50 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20  he number of.** 
35f60 20 20 20 20 20 20 20 20 20 6d 69 6c 6c 69 73 65           millise
35f70 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 20 61  conds of sleep a
35f80 63 74 75 61 6c 6c 79 20 72 65 71 75 65 73 74 65  ctually requeste
35f90 64 20 6f 66 20 74 68 65 20 6f 70 65 72 61 74 69  d of the operati
35fa0 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73  ng.**          s
35fb0 79 73 74 65 6d 2c 20 77 68 69 63 68 20 6d 69 67  ystem, which mig
35fc0 68 74 20 62 65 20 6c 61 72 67 65 72 20 74 68 61  ht be larger tha
35fd0 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  n the parameter 
35fe0 4d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  M..*/.int sqlite
35ff0 33 5f 73 6c 65 65 70 28 69 6e 74 29 3b 0a 0a 2f  3_sleep(int);../
36000 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e  *.** CAPI3REF: N
36010 61 6d 65 20 4f 66 20 54 68 65 20 46 6f 6c 64 65  ame Of The Folde
36020 72 20 48 6f 6c 64 69 6e 67 20 54 65 6d 70 6f 72  r Holding Tempor
36030 61 72 79 20 46 69 6c 65 73 20 7b 48 31 30 33 31  ary Files {H1031
36040 30 7d 20 3c 53 32 30 30 30 30 3e 0a 2a 2a 0a 2a  0} <S20000>.**.*
36050 2a 20 49 66 20 74 68 69 73 20 67 6c 6f 62 61 6c  * If this global
36060 20 76 61 72 69 61 62 6c 65 20 69 73 20 6d 61 64   variable is mad
36070 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 61 20  e to point to a 
36080 73 74 72 69 6e 67 20 77 68 69 63 68 20 69 73 0a  string which is.
36090 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 61  ** the name of a
360a0 20 66 6f 6c 64 65 72 20 28 61 2e 6b 2e 61 2e 20   folder (a.k.a. 
360b0 64 69 72 65 63 74 6f 72 79 29 2c 20 74 68 65 6e  directory), then
360c0 20 61 6c 6c 20 74 65 6d 70 6f 72 61 72 79 20 66   all temporary f
360d0 69 6c 65 73 0a 2a 2a 20 63 72 65 61 74 65 64 20  iles.** created 
360e0 62 79 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 62  by SQLite will b
360f0 65 20 70 6c 61 63 65 64 20 69 6e 20 74 68 61 74  e placed in that
36100 20 64 69 72 65 63 74 6f 72 79 2e 20 20 49 66 20   directory.  If 
36110 74 68 69 73 20 76 61 72 69 61 62 6c 65 0a 2a 2a  this variable.**
36120 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
36130 65 72 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20  er, then SQLite 
36140 70 65 72 66 6f 72 6d 73 20 61 20 73 65 61 72 63  performs a searc
36150 68 20 66 6f 72 20 61 6e 20 61 70 70 72 6f 70 72  h for an appropr
36160 69 61 74 65 0a 2a 2a 20 74 65 6d 70 6f 72 61 72  iate.** temporar
36170 79 20 66 69 6c 65 20 64 69 72 65 63 74 6f 72 79  y file directory
36180 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73 20 6e 6f  ..**.** It is no
36190 74 20 73 61 66 65 20 74 6f 20 6d 6f 64 69 66 79  t safe to modify
361a0 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 6f   this variable o
361b0 6e 63 65 20 61 20 5b 64 61 74 61 62 61 73 65 20  nce a [database 
361c0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 68  connection].** h
361d0 61 73 20 62 65 65 6e 20 6f 70 65 6e 65 64 2e 20  as been opened. 
361e0 20 49 74 20 69 73 20 69 6e 74 65 6e 64 65 64 20   It is intended 
361f0 74 68 61 74 20 74 68 69 73 20 76 61 72 69 61 62  that this variab
36200 6c 65 20 62 65 20 73 65 74 20 6f 6e 63 65 0a 2a  le be set once.*
36210 2a 20 61 73 20 70 61 72 74 20 6f 66 20 70 72 6f  * as part of pro
36220 63 65 73 73 20 69 6e 69 74 69 61 6c 69 7a 61 74  cess initializat
36230 69 6f 6e 20 61 6e 64 20 62 65 66 6f 72 65 20 61  ion and before a
36240 6e 79 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  ny SQLite interf
36250 61 63 65 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20  ace.** routines 
36260 68 61 76 65 20 62 65 65 6e 20 63 61 6c 6c 20 61  have been call a
36270 6e 64 20 72 65 6d 61 69 6e 20 75 6e 63 68 61 6e  nd remain unchan
36280 67 65 64 20 74 68 65 72 65 61 66 74 65 72 2e 0a  ged thereafter..
36290 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 54 45 52 4e  */.SQLITE_EXTERN
362a0 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 74   char *sqlite3_t
362b0 65 6d 70 5f 64 69 72 65 63 74 6f 72 79 3b 0a 0a  emp_directory;..
362c0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
362d0 54 65 73 74 20 46 6f 72 20 41 75 74 6f 2d 43 6f  Test For Auto-Co
362e0 6d 6d 69 74 20 4d 6f 64 65 20 7b 48 31 32 39 33  mmit Mode {H1293
362f0 30 7d 20 3c 53 36 30 32 30 30 3e 0a 2a 2a 20 4b  0} <S60200>.** K
36300 45 59 57 4f 52 44 53 3a 20 7b 61 75 74 6f 63 6f  EYWORDS: {autoco
36310 6d 6d 69 74 20 6d 6f 64 65 7d 0a 2a 2a 0a 2a 2a  mmit mode}.**.**
36320 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74   The sqlite3_get
36330 5f 61 75 74 6f 63 6f 6d 6d 69 74 28 29 20 69 6e  _autocommit() in
36340 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
36350 6e 6f 6e 2d 7a 65 72 6f 20 6f 72 0a 2a 2a 20 7a  non-zero or.** z
36360 65 72 6f 20 69 66 20 74 68 65 20 67 69 76 65 6e  ero if the given
36370 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
36380 74 69 6f 6e 20 69 73 20 6f 72 20 69 73 20 6e 6f  tion is or is no
36390 74 20 69 6e 20 61 75 74 6f 63 6f 6d 6d 69 74 20  t in autocommit 
363a0 6d 6f 64 65 2c 0a 2a 2a 20 72 65 73 70 65 63 74  mode,.** respect
363b0 69 76 65 6c 79 2e 20 20 41 75 74 6f 63 6f 6d 6d  ively.  Autocomm
363c0 69 74 20 6d 6f 64 65 20 69 73 20 6f 6e 20 62 79  it mode is on by
363d0 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 20 41 75 74   default..** Aut
363e0 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20  ocommit mode is 
363f0 64 69 73 61 62 6c 65 64 20 62 79 20 61 20 5b 42  disabled by a [B
36400 45 47 49 4e 5d 20 73 74 61 74 65 6d 65 6e 74 2e  EGIN] statement.
36410 0a 2a 2a 20 41 75 74 6f 63 6f 6d 6d 69 74 20 6d  .** Autocommit m
36420 6f 64 65 20 69 73 20 72 65 2d 65 6e 61 62 6c 65  ode is re-enable
36430 64 20 62 79 20 61 20 5b 43 4f 4d 4d 49 54 5d 20  d by a [COMMIT] 
36440 6f 72 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2e 0a 2a  or [ROLLBACK]..*
36450 2a 0a 2a 2a 20 49 66 20 63 65 72 74 61 69 6e 20  *.** If certain 
36460 6b 69 6e 64 73 20 6f 66 20 65 72 72 6f 72 73 20  kinds of errors 
36470 6f 63 63 75 72 20 6f 6e 20 61 20 73 74 61 74 65  occur on a state
36480 6d 65 6e 74 20 77 69 74 68 69 6e 20 61 20 6d 75  ment within a mu
36490 6c 74 69 2d 73 74 61 74 65 6d 65 6e 74 0a 2a 2a  lti-statement.**
364a0 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 28 65 72   transaction (er
364b0 72 6f 72 73 20 69 6e 63 6c 75 64 69 6e 67 20 5b  rors including [
364c0 53 51 4c 49 54 45 5f 46 55 4c 4c 5d 2c 20 5b 53  SQLITE_FULL], [S
364d0 51 4c 49 54 45 5f 49 4f 45 52 52 5d 2c 0a 2a 2a  QLITE_IOERR],.**
364e0 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2c   [SQLITE_NOMEM],
364f0 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c 20   [SQLITE_BUSY], 
36500 61 6e 64 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45  and [SQLITE_INTE
36510 52 52 55 50 54 5d 29 20 74 68 65 6e 20 74 68 65  RRUPT]) then the
36520 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  .** transaction 
36530 6d 69 67 68 74 20 62 65 20 72 6f 6c 6c 65 64 20  might be rolled 
36540 62 61 63 6b 20 61 75 74 6f 6d 61 74 69 63 61 6c  back automatical
36550 6c 79 2e 20 20 54 68 65 20 6f 6e 6c 79 20 77 61  ly.  The only wa
36560 79 20 74 6f 0a 2a 2a 20 66 69 6e 64 20 6f 75 74  y to.** find out
36570 20 77 68 65 74 68 65 72 20 53 51 4c 69 74 65 20   whether SQLite 
36580 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f  automatically ro
36590 6c 6c 65 64 20 62 61 63 6b 20 74 68 65 20 74 72  lled back the tr
365a0 61 6e 73 61 63 74 69 6f 6e 20 61 66 74 65 72 0a  ansaction after.
365b0 2a 2a 20 61 6e 20 65 72 72 6f 72 20 69 73 20 74  ** an error is t
365c0 6f 20 75 73 65 20 74 68 69 73 20 66 75 6e 63 74  o use this funct
365d0 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  ion..**.** INVAR
365e0 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31  IANTS:.**.** {H1
365f0 32 39 33 31 7d 20 54 68 65 20 5b 73 71 6c 69 74  2931} The [sqlit
36600 65 33 5f 67 65 74 5f 61 75 74 6f 63 6f 6d 6d 69  e3_get_autocommi
36610 74 28 44 29 5d 20 69 6e 74 65 72 66 61 63 65 20  t(D)] interface 
36620 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f  returns non-zero
36630 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   or.**          
36640 7a 65 72 6f 20 69 66 20 74 68 65 20 5b 64 61 74  zero if the [dat
36650 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
36660 5d 20 44 20 69 73 20 6f 72 20 69 73 20 6e 6f 74  ] D is or is not
36670 20 69 6e 20 61 75 74 6f 63 6f 6d 6d 69 74 0a 2a   in autocommit.*
36680 2a 20 20 20 20 20 20 20 20 20 20 6d 6f 64 65 2c  *          mode,
36690 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a   respectively..*
366a0 2a 0a 2a 2a 20 7b 48 31 32 39 33 32 7d 20 41 75  *.** {H12932} Au
366b0 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73  tocommit mode is
366c0 20 6f 6e 20 62 79 20 64 65 66 61 75 6c 74 2e 0a   on by default..
366d0 2a 2a 0a 2a 2a 20 7b 48 31 32 39 33 33 7d 20 41  **.** {H12933} A
366e0 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69  utocommit mode i
366f0 73 20 64 69 73 61 62 6c 65 64 20 62 79 20 61 20  s disabled by a 
36700 73 75 63 63 65 73 73 66 75 6c 20 5b 42 45 47 49  successful [BEGI
36710 4e 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a  N] statement..**
36720 0a 2a 2a 20 7b 48 31 32 39 33 34 7d 20 41 75 74  .** {H12934} Aut
36730 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20  ocommit mode is 
36740 65 6e 61 62 6c 65 64 20 62 79 20 61 20 73 75 63  enabled by a suc
36750 63 65 73 73 66 75 6c 20 5b 43 4f 4d 4d 49 54 5d  cessful [COMMIT]
36760 20 6f 72 20 5b 52 4f 4c 4c 42 41 43 4b 5d 0a 2a   or [ROLLBACK].*
36770 2a 20 20 20 20 20 20 20 20 20 20 73 74 61 74 65  *          state
36780 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 41 53 53 55  ment..**.** ASSU
36790 4d 50 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b  MPTIONS:.**.** {
367a0 41 31 32 39 33 36 7d 20 49 66 20 61 6e 6f 74 68  A12936} If anoth
367b0 65 72 20 74 68 72 65 61 64 20 63 68 61 6e 67 65  er thread change
367c0 73 20 74 68 65 20 61 75 74 6f 63 6f 6d 6d 69 74  s the autocommit
367d0 20 73 74 61 74 75 73 20 6f 66 20 74 68 65 20 64   status of the d
367e0 61 74 61 62 61 73 65 0a 2a 2a 20 20 20 20 20 20  atabase.**      
367f0 20 20 20 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77      connection w
36800 68 69 6c 65 20 74 68 69 73 20 72 6f 75 74 69 6e  hile this routin
36810 65 20 69 73 20 72 75 6e 6e 69 6e 67 2c 20 74 68  e is running, th
36820 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  en the return va
36830 6c 75 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  lue.**          
36840 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f  is undefined..*/
36850 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 65 74  .int sqlite3_get
36860 5f 61 75 74 6f 63 6f 6d 6d 69 74 28 73 71 6c 69  _autocommit(sqli
36870 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  te3*);../*.** CA
36880 50 49 33 52 45 46 3a 20 46 69 6e 64 20 54 68 65  PI3REF: Find The
36890 20 44 61 74 61 62 61 73 65 20 48 61 6e 64 6c 65   Database Handle
368a0 20 4f 66 20 41 20 50 72 65 70 61 72 65 64 20 53   Of A Prepared S
368b0 74 61 74 65 6d 65 6e 74 20 7b 48 31 33 31 32 30  tatement {H13120
368c0 7d 20 3c 53 36 30 36 30 30 3e 0a 2a 2a 0a 2a 2a  } <S60600>.**.**
368d0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 64 62 5f   The sqlite3_db_
368e0 68 61 6e 64 6c 65 20 69 6e 74 65 72 66 61 63 65  handle interface
368f0 20 72 65 74 75 72 6e 73 20 74 68 65 20 5b 64 61   returns the [da
36900 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
36910 6e 5d 20 68 61 6e 64 6c 65 0a 2a 2a 20 74 6f 20  n] handle.** to 
36920 77 68 69 63 68 20 61 20 5b 70 72 65 70 61 72 65  which a [prepare
36930 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 62 65 6c  d statement] bel
36940 6f 6e 67 73 2e 20 20 54 68 65 20 64 61 74 61 62  ongs.  The datab
36950 61 73 65 20 68 61 6e 64 6c 65 20 72 65 74 75 72  ase handle retur
36960 6e 65 64 20 62 79 0a 2a 2a 20 73 71 6c 69 74 65  ned by.** sqlite
36970 33 5f 64 62 5f 68 61 6e 64 6c 65 20 69 73 20 74  3_db_handle is t
36980 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65  he same database
36990 20 68 61 6e 64 6c 65 20 74 68 61 74 20 77 61 73   handle that was
369a0 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
369b0 65 6e 74 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73  ent.** to the [s
369c0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
369d0 32 28 29 5d 20 63 61 6c 6c 20 28 6f 72 20 69 74  2()] call (or it
369e0 73 20 76 61 72 69 61 6e 74 73 29 20 74 68 61 74  s variants) that
369f0 20 77 61 73 20 75 73 65 64 20 74 6f 0a 2a 2a 20   was used to.** 
36a00 63 72 65 61 74 65 20 74 68 65 20 73 74 61 74 65  create the state
36a10 6d 65 6e 74 20 69 6e 20 74 68 65 20 66 69 72 73  ment in the firs
36a20 74 20 70 6c 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 49  t place..**.** I
36a30 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
36a40 20 7b 48 31 33 31 32 33 7d 20 54 68 65 20 5b 73   {H13123} The [s
36a50 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65  qlite3_db_handle
36a60 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  (S)] interface r
36a70 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
36a80 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20  .**          to 
36a90 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
36aa0 6e 6e 65 63 74 69 6f 6e 5d 20 61 73 73 6f 63 69  nnection] associ
36ab0 61 74 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a  ated with the.**
36ac0 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 61            [prepa
36ad0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
36ae0 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 20 2a 73 71  ..*/.sqlite3 *sq
36af0 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65 28  lite3_db_handle(
36b00 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a  sqlite3_stmt*);.
36b10 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
36b20 20 46 69 6e 64 20 74 68 65 20 6e 65 78 74 20 70   Find the next p
36b30 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
36b40 74 20 7b 48 31 33 31 34 30 7d 20 3c 53 36 30 36  t {H13140} <S606
36b50 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69  00>.**.** This i
36b60 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
36b70 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
36b80 65 20 6e 65 78 74 20 5b 70 72 65 70 61 72 65 64  e next [prepared
36b90 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 66 74 65   statement] afte
36ba0 72 0a 2a 2a 20 70 53 74 6d 74 20 61 73 73 6f 63  r.** pStmt assoc
36bb0 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20 5b  iated with the [
36bc0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
36bd0 69 6f 6e 5d 20 70 44 62 2e 20 20 49 66 20 70 53  ion] pDb.  If pS
36be0 74 6d 74 20 69 73 20 4e 55 4c 4c 0a 2a 2a 20 74  tmt is NULL.** t
36bf0 68 65 6e 20 74 68 69 73 20 69 6e 74 65 72 66 61  hen this interfa
36c00 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  ce returns a poi
36c10 6e 74 65 72 20 74 6f 20 74 68 65 20 66 69 72 73  nter to the firs
36c20 74 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  t prepared state
36c30 6d 65 6e 74 0a 2a 2a 20 61 73 73 6f 63 69 61 74  ment.** associat
36c40 65 64 20 77 69 74 68 20 74 68 65 20 64 61 74 61  ed with the data
36c50 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
36c60 70 44 62 2e 20 20 49 66 20 6e 6f 20 70 72 65 70  pDb.  If no prep
36c70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a  ared statement.*
36c80 2a 20 73 61 74 69 73 66 69 65 73 20 74 68 65 20  * satisfies the 
36c90 63 6f 6e 64 69 74 69 6f 6e 73 20 6f 66 20 74 68  conditions of th
36ca0 69 73 20 72 6f 75 74 69 6e 65 2c 20 69 74 20 72  is routine, it r
36cb0 65 74 75 72 6e 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a  eturns NULL..**.
36cc0 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
36cd0 2a 0a 2a 2a 20 7b 48 31 33 31 34 33 7d 20 49 66  *.** {H13143} If
36ce0 20 44 20 69 73 20 61 20 5b 64 61 74 61 62 61 73   D is a [databas
36cf0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68  e connection] th
36d00 61 74 20 68 6f 6c 64 73 20 6f 6e 65 20 6f 72 20  at holds one or 
36d10 6d 6f 72 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  more.**         
36d20 20 75 6e 66 69 6e 61 6c 69 7a 65 64 20 5b 70 72   unfinalized [pr
36d30 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
36d40 73 5d 20 61 6e 64 20 53 20 69 73 20 61 20 4e 55  s] and S is a NU
36d50 4c 4c 20 70 6f 69 6e 74 65 72 2c 0a 2a 2a 20 20  LL pointer,.**  
36d60 20 20 20 20 20 20 20 20 74 68 65 6e 20 5b 73 71          then [sq
36d70 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28  lite3_next_stmt(
36d80 44 2c 20 53 29 5d 20 72 6f 75 74 69 6e 65 20 73  D, S)] routine s
36d90 68 61 6c 6c 20 72 65 74 75 72 6e 20 61 20 70 6f  hall return a po
36da0 69 6e 74 65 72 0a 2a 2a 20 20 20 20 20 20 20 20  inter.**        
36db0 20 20 74 6f 20 6f 6e 65 20 6f 66 20 74 68 65 20    to one of the 
36dc0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
36dd0 6e 74 73 20 61 73 73 6f 63 69 61 74 65 64 20 77  nts associated w
36de0 69 74 68 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  ith D..**.** {H1
36df0 33 31 34 36 7d 20 49 66 20 44 20 69 73 20 61 20  3146} If D is a 
36e00 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
36e10 74 69 6f 6e 5d 20 74 68 61 74 20 68 6f 6c 64 73  tion] that holds
36e20 20 6e 6f 20 75 6e 66 69 6e 61 6c 69 7a 65 64 0a   no unfinalized.
36e30 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 65  **          [pre
36e40 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73  pared statements
36e50 5d 20 61 6e 64 20 53 20 69 73 20 61 20 4e 55 4c  ] and S is a NUL
36e60 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 0a  L pointer, then.
36e70 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
36e80 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 44  ite3_next_stmt(D
36e90 2c 20 53 29 5d 20 72 6f 75 74 69 6e 65 20 73 68  , S)] routine sh
36ea0 61 6c 6c 20 72 65 74 75 72 6e 20 61 20 4e 55 4c  all return a NUL
36eb0 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a  L pointer..**.**
36ec0 20 7b 48 31 33 31 34 39 7d 20 49 66 20 53 20 69   {H13149} If S i
36ed0 73 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  s a [prepared st
36ee0 61 74 65 6d 65 6e 74 5d 20 69 6e 20 74 68 65 20  atement] in the 
36ef0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
36f00 74 69 6f 6e 5d 20 44 0a 2a 2a 20 20 20 20 20 20  tion] D.**      
36f10 20 20 20 20 61 6e 64 20 53 20 69 73 20 6e 6f 74      and S is not
36f20 20 74 68 65 20 6c 61 73 74 20 70 72 65 70 61 72   the last prepar
36f30 65 64 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20  ed statement in 
36f40 44 2c 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20  D, then.**      
36f50 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78      [sqlite3_nex
36f60 74 5f 73 74 6d 74 28 44 2c 20 53 29 5d 20 72 6f  t_stmt(D, S)] ro
36f70 75 74 69 6e 65 20 73 68 61 6c 6c 20 72 65 74 75  utine shall retu
36f80 72 6e 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  rn a pointer.** 
36f90 20 20 20 20 20 20 20 20 20 74 6f 20 74 68 65 20           to the 
36fa0 6e 65 78 74 20 70 72 65 70 61 72 65 64 20 73 74  next prepared st
36fb0 61 74 65 6d 65 6e 74 20 69 6e 20 44 20 61 66 74  atement in D aft
36fc0 65 72 20 53 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33  er S..**.** {H13
36fd0 31 35 32 7d 20 49 66 20 53 20 69 73 20 74 68 65  152} If S is the
36fe0 20 6c 61 73 74 20 5b 70 72 65 70 61 72 65 64 20   last [prepared 
36ff0 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 74 68  statement] in th
37000 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 64  e.**          [d
37010 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
37020 6f 6e 5d 20 44 20 74 68 65 6e 20 74 68 65 20 5b  on] D then the [
37030 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d  sqlite3_next_stm
37040 74 28 44 2c 20 53 29 5d 0a 2a 2a 20 20 20 20 20  t(D, S)].**     
37050 20 20 20 20 20 72 6f 75 74 69 6e 65 20 73 68 61       routine sha
37060 6c 6c 20 72 65 74 75 72 6e 20 61 20 4e 55 4c 4c  ll return a NULL
37070 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20   pointer..**.** 
37080 41 53 53 55 4d 50 54 49 4f 4e 53 3a 0a 2a 2a 0a  ASSUMPTIONS:.**.
37090 2a 2a 20 7b 41 31 33 31 35 34 7d 20 54 68 65 20  ** {A13154} The 
370a0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
370b0 74 69 6f 6e 5d 20 70 6f 69 6e 74 65 72 20 44 20  tion] pointer D 
370c0 69 6e 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20  in a call to.** 
370d0 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
370e0 33 5f 6e 65 78 74 5f 73 74 6d 74 28 44 2c 53 29  3_next_stmt(D,S)
370f0 5d 20 6d 75 73 74 20 72 65 66 65 72 20 74 6f 20  ] must refer to 
37100 61 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65  an open database
37110 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6e  .**          con
37120 6e 65 63 74 69 6f 6e 20 61 6e 64 20 69 6e 20 70  nection and in p
37130 61 72 74 69 63 75 6c 61 72 20 6d 75 73 74 20 6e  articular must n
37140 6f 74 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69  ot be a NULL poi
37150 6e 74 65 72 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33  nter..*/.sqlite3
37160 5f 73 74 6d 74 20 2a 73 71 6c 69 74 65 33 5f 6e  _stmt *sqlite3_n
37170 65 78 74 5f 73 74 6d 74 28 73 71 6c 69 74 65 33  ext_stmt(sqlite3
37180 20 2a 70 44 62 2c 20 73 71 6c 69 74 65 33 5f 73   *pDb, sqlite3_s
37190 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a  tmt *pStmt);../*
371a0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
371b0 6d 6d 69 74 20 41 6e 64 20 52 6f 6c 6c 62 61 63  mmit And Rollbac
371c0 6b 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e 20 43  k Notification C
371d0 61 6c 6c 62 61 63 6b 73 20 7b 48 31 32 39 35 30  allbacks {H12950
371e0 7d 20 3c 53 36 30 34 30 30 3e 0a 2a 2a 0a 2a 2a  } <S60400>.**.**
371f0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d   The sqlite3_com
37200 6d 69 74 5f 68 6f 6f 6b 28 29 20 69 6e 74 65 72  mit_hook() inter
37210 66 61 63 65 20 72 65 67 69 73 74 65 72 73 20 61  face registers a
37220 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e   callback.** fun
37230 63 74 69 6f 6e 20 74 6f 20 62 65 20 69 6e 76 6f  ction to be invo
37240 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61 20 74  ked whenever a t
37250 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 63 6f  ransaction is co
37260 6d 6d 69 74 74 65 64 2e 0a 2a 2a 20 41 6e 79 20  mmitted..** Any 
37270 63 61 6c 6c 62 61 63 6b 20 73 65 74 20 62 79 20  callback set by 
37280 61 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20  a previous call 
37290 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69  to sqlite3_commi
372a0 74 5f 68 6f 6f 6b 28 29 0a 2a 2a 20 66 6f 72 20  t_hook().** for 
372b0 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73  the same databas
372c0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
372d0 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 20 54  overridden..** T
372e0 68 65 20 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62  he sqlite3_rollb
372f0 61 63 6b 5f 68 6f 6f 6b 28 29 20 69 6e 74 65 72  ack_hook() inter
37300 66 61 63 65 20 72 65 67 69 73 74 65 72 73 20 61  face registers a
37310 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e   callback.** fun
37320 63 74 69 6f 6e 20 74 6f 20 62 65 20 69 6e 76 6f  ction to be invo
37330 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61 20 74  ked whenever a t
37340 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 63 6f  ransaction is co
37350 6d 6d 69 74 74 65 64 2e 0a 2a 2a 20 41 6e 79 20  mmitted..** Any 
37360 63 61 6c 6c 62 61 63 6b 20 73 65 74 20 62 79 20  callback set by 
37370 61 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20  a previous call 
37380 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69  to sqlite3_commi
37390 74 5f 68 6f 6f 6b 28 29 0a 2a 2a 20 66 6f 72 20  t_hook().** for 
373a0 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73  the same databas
373b0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
373c0 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 20 54  overridden..** T
373d0 68 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e 74  he pArg argument
373e0 20 69 73 20 70 61 73 73 65 64 20 74 68 72 6f 75   is passed throu
373f0 67 68 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61  gh to the callba
37400 63 6b 2e 0a 2a 2a 20 49 66 20 74 68 65 20 63 61  ck..** If the ca
37410 6c 6c 62 61 63 6b 20 6f 6e 20 61 20 63 6f 6d 6d  llback on a comm
37420 69 74 20 68 6f 6f 6b 20 66 75 6e 63 74 69 6f 6e  it hook function
37430 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72   returns non-zer
37440 6f 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63  o,.** then the c
37450 6f 6d 6d 69 74 20 69 73 20 63 6f 6e 76 65 72 74  ommit is convert
37460 65 64 20 69 6e 74 6f 20 61 20 72 6f 6c 6c 62 61  ed into a rollba
37470 63 6b 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 6f  ck..**.** If ano
37480 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 20 77 61  ther function wa
37490 73 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 67  s previously reg
374a0 69 73 74 65 72 65 64 2c 20 69 74 73 0a 2a 2a 20  istered, its.** 
374b0 70 41 72 67 20 76 61 6c 75 65 20 69 73 20 72 65  pArg value is re
374c0 74 75 72 6e 65 64 2e 20 20 4f 74 68 65 72 77 69  turned.  Otherwi
374d0 73 65 20 4e 55 4c 4c 20 69 73 20 72 65 74 75 72  se NULL is retur
374e0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73  ned..**.** Regis
374f0 74 65 72 69 6e 67 20 61 20 4e 55 4c 4c 20 66 75  tering a NULL fu
37500 6e 63 74 69 6f 6e 20 64 69 73 61 62 6c 65 73 20  nction disables 
37510 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a  the callback..**
37520 0a 2a 2a 20 46 6f 72 20 74 68 65 20 70 75 72 70  .** For the purp
37530 6f 73 65 73 20 6f 66 20 74 68 69 73 20 41 50 49  oses of this API
37540 2c 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  , a transaction 
37550 69 73 20 73 61 69 64 20 74 6f 20 68 61 76 65 20  is said to have 
37560 62 65 65 6e 0a 2a 2a 20 72 6f 6c 6c 65 64 20 62  been.** rolled b
37570 61 63 6b 20 69 66 20 61 6e 20 65 78 70 6c 69 63  ack if an explic
37580 69 74 20 22 52 4f 4c 4c 42 41 43 4b 22 20 73 74  it "ROLLBACK" st
37590 61 74 65 6d 65 6e 74 20 69 73 20 65 78 65 63 75  atement is execu
375a0 74 65 64 2c 20 6f 72 0a 2a 2a 20 61 6e 20 65 72  ted, or.** an er
375b0 72 6f 72 20 6f 72 20 63 6f 6e 73 74 72 61 69 6e  ror or constrain
375c0 74 20 63 61 75 73 65 73 20 61 6e 20 69 6d 70 6c  t causes an impl
375d0 69 63 69 74 20 72 6f 6c 6c 62 61 63 6b 20 74 6f  icit rollback to
375e0 20 6f 63 63 75 72 2e 0a 2a 2a 20 54 68 65 20 72   occur..** The r
375f0 6f 6c 6c 62 61 63 6b 20 63 61 6c 6c 62 61 63 6b  ollback callback
37600 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20   is not invoked 
37610 69 66 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e  if a transaction
37620 20 69 73 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63   is.** automatic
37630 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b  ally rolled back
37640 20 62 65 63 61 75 73 65 20 74 68 65 20 64 61 74   because the dat
37650 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
37660 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 20 54   is closed..** T
37670 68 65 20 72 6f 6c 6c 62 61 63 6b 20 63 61 6c 6c  he rollback call
37680 62 61 63 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f  back is not invo
37690 6b 65 64 20 69 66 20 61 20 74 72 61 6e 73 61 63  ked if a transac
376a0 74 69 6f 6e 20 69 73 0a 2a 2a 20 72 6f 6c 6c 65  tion is.** rolle
376b0 64 20 62 61 63 6b 20 62 65 63 61 75 73 65 20 61  d back because a
376c0 20 63 6f 6d 6d 69 74 20 63 61 6c 6c 62 61 63 6b   commit callback
376d0 20 72 65 74 75 72 6e 65 64 20 6e 6f 6e 2d 7a 65   returned non-ze
376e0 72 6f 2e 0a 2a 2a 20 3c 74 6f 64 6f 3e 20 43 68  ro..** <todo> Ch
376f0 65 63 6b 20 6f 6e 20 74 68 69 73 20 3c 2f 74 6f  eck on this </to
37700 64 6f 3e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  do>.**.** INVARI
37710 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  ANTS:.**.** {H12
37720 39 35 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  951} The [sqlite
37730 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 44 2c  3_commit_hook(D,
37740 46 2c 50 29 5d 20 69 6e 74 65 72 66 61 63 65 20  F,P)] interface 
37750 72 65 67 69 73 74 65 72 73 20 74 68 65 0a 2a 2a  registers the.**
37760 20 20 20 20 20 20 20 20 20 20 63 61 6c 6c 62 61            callba
37770 63 6b 20 66 75 6e 63 74 69 6f 6e 20 46 20 74 6f  ck function F to
37780 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68   be invoked with
37790 20 61 72 67 75 6d 65 6e 74 20 50 20 77 68 65 6e   argument P when
377a0 65 76 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  ever.**         
377b0 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 63   a transaction c
377c0 6f 6d 6d 69 74 73 20 6f 6e 20 74 68 65 20 5b 64  ommits on the [d
377d0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
377e0 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  on] D..**.** {H1
377f0 32 39 35 32 7d 20 54 68 65 20 5b 73 71 6c 69 74  2952} The [sqlit
37800 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 44  e3_commit_hook(D
37810 2c 46 2c 50 29 5d 20 69 6e 74 65 72 66 61 63 65  ,F,P)] interface
37820 20 72 65 74 75 72 6e 73 20 74 68 65 20 50 20 61   returns the P a
37830 72 67 75 6d 65 6e 74 0a 2a 2a 20 20 20 20 20 20  rgument.**      
37840 20 20 20 20 66 72 6f 6d 20 74 68 65 20 70 72 65      from the pre
37850 76 69 6f 75 73 20 63 61 6c 6c 20 77 69 74 68 20  vious call with 
37860 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61  the same [databa
37870 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44  se connection] D
37880 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72  ,.**          or
37890 20 4e 55 4c 4c 20 6f 6e 20 74 68 65 20 66 69 72   NULL on the fir
378a0 73 74 20 63 61 6c 6c 20 66 6f 72 20 61 20 70 61  st call for a pa
378b0 72 74 69 63 75 6c 61 72 20 64 61 74 61 62 61 73  rticular databas
378c0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 0a  e connection D..
378d0 2a 2a 0a 2a 2a 20 7b 48 31 32 39 35 33 7d 20 45  **.** {H12953} E
378e0 61 63 68 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ach call to [sql
378f0 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b  ite3_commit_hook
37900 28 29 5d 20 6f 76 65 72 77 72 69 74 65 73 20 74  ()] overwrites t
37910 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 20  he callback.**  
37920 20 20 20 20 20 20 20 20 72 65 67 69 73 74 65 72          register
37930 65 64 20 62 79 20 70 72 69 6f 72 20 63 61 6c 6c  ed by prior call
37940 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 35 34  s..**.** {H12954
37950 7d 20 49 66 20 74 68 65 20 46 20 61 72 67 75 6d  } If the F argum
37960 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ent to [sqlite3_
37970 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 44 2c 46 2c  commit_hook(D,F,
37980 50 29 5d 20 69 73 20 4e 55 4c 4c 0a 2a 2a 20 20  P)] is NULL.**  
37990 20 20 20 20 20 20 20 20 74 68 65 6e 20 74 68 65          then the
379a0 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b 20 63 61 6c   commit hook cal
379b0 6c 62 61 63 6b 20 69 73 20 63 61 6e 63 65 6c 65  lback is cancele
379c0 64 20 61 6e 64 20 6e 6f 20 63 61 6c 6c 62 61 63  d and no callbac
379d0 6b 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73  k.**          is
379e0 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 61 20   invoked when a 
379f0 74 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6d 6d  transaction comm
37a00 69 74 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39  its..**.** {H129
37a10 35 35 7d 20 49 66 20 74 68 65 20 63 6f 6d 6d 69  55} If the commi
37a20 74 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  t callback retur
37a30 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 20 74 68 65 6e  ns non-zero then
37a40 20 74 68 65 20 63 6f 6d 6d 69 74 20 69 73 0a 2a   the commit is.*
37a50 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6e 76 65  *          conve
37a60 72 74 65 64 20 69 6e 74 6f 20 61 20 72 6f 6c 6c  rted into a roll
37a70 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  back..**.** {H12
37a80 39 36 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  961} The [sqlite
37a90 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28  3_rollback_hook(
37aa0 44 2c 46 2c 50 29 5d 20 69 6e 74 65 72 66 61 63  D,F,P)] interfac
37ab0 65 20 72 65 67 69 73 74 65 72 73 20 74 68 65 0a  e registers the.
37ac0 2a 2a 20 20 20 20 20 20 20 20 20 20 63 61 6c 6c  **          call
37ad0 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 46 20  back function F 
37ae0 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69  to be invoked wi
37af0 74 68 20 61 72 67 75 6d 65 6e 74 20 50 20 77 68  th argument P wh
37b00 65 6e 65 76 65 72 0a 2a 2a 20 20 20 20 20 20 20  enever.**       
37b10 20 20 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e     a transaction
37b20 20 72 6f 6c 6c 73 20 62 61 63 6b 20 6f 6e 20 74   rolls back on t
37b30 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
37b40 6e 65 63 74 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a  nection] D..**.*
37b50 2a 20 7b 48 31 32 39 36 32 7d 20 54 68 65 20 5b  * {H12962} The [
37b60 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b  sqlite3_rollback
37b70 5f 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d 20 69 6e  _hook(D,F,P)] in
37b80 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
37b90 74 68 65 20 50 0a 2a 2a 20 20 20 20 20 20 20 20  the P.**        
37ba0 20 20 61 72 67 75 6d 65 6e 74 20 66 72 6f 6d 20    argument from 
37bb0 74 68 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c  the previous cal
37bc0 6c 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 0a  l with the same.
37bd0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 64 61 74  **          [dat
37be0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
37bf0 5d 20 44 2c 20 6f 72 20 4e 55 4c 4c 20 6f 6e 20  ] D, or NULL on 
37c00 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c 0a 2a  the first call.*
37c10 2a 20 20 20 20 20 20 20 20 20 20 66 6f 72 20 61  *          for a
37c20 20 70 61 72 74 69 63 75 6c 61 72 20 64 61 74 61   particular data
37c30 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
37c40 44 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 36 33  D..**.** {H12963
37c50 7d 20 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 5b  } Each call to [
37c60 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b  sqlite3_rollback
37c70 5f 68 6f 6f 6b 28 29 5d 20 6f 76 65 72 77 72 69  _hook()] overwri
37c80 74 65 73 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  tes the callback
37c90 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 67  .**          reg
37ca0 69 73 74 65 72 65 64 20 62 79 20 70 72 69 6f 72  istered by prior
37cb0 20 63 61 6c 6c 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48   calls..**.** {H
37cc0 31 32 39 36 34 7d 20 49 66 20 74 68 65 20 46 20  12964} If the F 
37cd0 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c  argument to [sql
37ce0 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f  ite3_rollback_ho
37cf0 6f 6b 28 44 2c 46 2c 50 29 5d 20 69 73 20 4e 55  ok(D,F,P)] is NU
37d00 4c 4c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  LL.**          t
37d10 68 65 6e 20 74 68 65 20 72 6f 6c 6c 62 61 63 6b  hen the rollback
37d20 20 68 6f 6f 6b 20 63 61 6c 6c 62 61 63 6b 20 69   hook callback i
37d30 73 20 63 61 6e 63 65 6c 65 64 20 61 6e 64 20 6e  s canceled and n
37d40 6f 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 20 20  o callback.**   
37d50 20 20 20 20 20 20 20 69 73 20 69 6e 76 6f 6b 65         is invoke
37d60 64 20 77 68 65 6e 20 61 20 74 72 61 6e 73 61 63  d when a transac
37d70 74 69 6f 6e 20 72 6f 6c 6c 73 20 62 61 63 6b 2e  tion rolls back.
37d80 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65  .*/.void *sqlite
37d90 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 73 71  3_commit_hook(sq
37da0 6c 69 74 65 33 2a 2c 20 69 6e 74 28 2a 29 28 76  lite3*, int(*)(v
37db0 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 76  oid*), void*);.v
37dc0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 6f 6c  oid *sqlite3_rol
37dd0 6c 62 61 63 6b 5f 68 6f 6f 6b 28 73 71 6c 69 74  lback_hook(sqlit
37de0 65 33 2a 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69  e3*, void(*)(voi
37df0 64 20 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f  d *), void*);../
37e00 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
37e10 61 74 61 20 43 68 61 6e 67 65 20 4e 6f 74 69 66  ata Change Notif
37e20 69 63 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b  ication Callback
37e30 73 20 7b 48 31 32 39 37 30 7d 20 3c 53 36 30 34  s {H12970} <S604
37e40 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  00>.**.** The sq
37e50 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f  lite3_update_hoo
37e60 6b 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  k() interface re
37e70 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61  gisters a callba
37e80 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77  ck function.** w
37e90 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 73  ith the [databas
37ea0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 64  e connection] id
37eb0 65 6e 74 69 66 69 65 64 20 62 79 20 74 68 65 20  entified by the 
37ec0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 0a 2a  first argument.*
37ed0 2a 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20  * to be invoked 
37ee0 77 68 65 6e 65 76 65 72 20 61 20 72 6f 77 20 69  whenever a row i
37ef0 73 20 75 70 64 61 74 65 64 2c 20 69 6e 73 65 72  s updated, inser
37f00 74 65 64 20 6f 72 20 64 65 6c 65 74 65 64 2e 0a  ted or deleted..
37f10 2a 2a 20 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20  ** Any callback 
37f20 73 65 74 20 62 79 20 61 20 70 72 65 76 69 6f 75  set by a previou
37f30 73 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20 66  s call to this f
37f40 75 6e 63 74 69 6f 6e 0a 2a 2a 20 66 6f 72 20 74  unction.** for t
37f50 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65  he same database
37f60 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f   connection is o
37f70 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 0a 2a 2a  verridden..**.**
37f80 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   The second argu
37f90 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65  ment is a pointe
37fa0 72 20 74 6f 20 74 68 65 20 66 75 6e 63 74 69 6f  r to the functio
37fb0 6e 20 74 6f 20 69 6e 76 6f 6b 65 20 77 68 65 6e  n to invoke when
37fc0 20 61 0a 2a 2a 20 72 6f 77 20 69 73 20 75 70 64   a.** row is upd
37fd0 61 74 65 64 2c 20 69 6e 73 65 72 74 65 64 20 6f  ated, inserted o
37fe0 72 20 64 65 6c 65 74 65 64 2e 0a 2a 2a 20 54 68  r deleted..** Th
37ff0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
38000 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   to the callback
38010 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68   is a copy of th
38020 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  e third argument
38030 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 75  .** to sqlite3_u
38040 70 64 61 74 65 5f 68 6f 6f 6b 28 29 2e 0a 2a 2a  pdate_hook()..**
38050 20 54 68 65 20 73 65 63 6f 6e 64 20 63 61 6c 6c   The second call
38060 62 61 63 6b 20 61 72 67 75 6d 65 6e 74 20 69 73  back argument is
38070 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f   one of [SQLITE_
38080 49 4e 53 45 52 54 5d 2c 20 5b 53 51 4c 49 54 45  INSERT], [SQLITE
38090 5f 44 45 4c 45 54 45 5d 2c 0a 2a 2a 20 6f 72 20  _DELETE],.** or 
380a0 5b 53 51 4c 49 54 45 5f 55 50 44 41 54 45 5d 2c  [SQLITE_UPDATE],
380b0 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68   depending on th
380c0 65 20 6f 70 65 72 61 74 69 6f 6e 20 74 68 61 74  e operation that
380d0 20 63 61 75 73 65 64 20 74 68 65 20 63 61 6c 6c   caused the call
380e0 62 61 63 6b 0a 2a 2a 20 74 6f 20 62 65 20 69 6e  back.** to be in
380f0 76 6f 6b 65 64 2e 0a 2a 2a 20 54 68 65 20 74 68  voked..** The th
38100 69 72 64 20 61 6e 64 20 66 6f 75 72 74 68 20 61  ird and fourth a
38110 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 65 20  rguments to the 
38120 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e  callback contain
38130 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 74 68 65   pointers to the
38140 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 61 6e 64  .** database and
38150 20 74 61 62 6c 65 20 6e 61 6d 65 20 63 6f 6e 74   table name cont
38160 61 69 6e 69 6e 67 20 74 68 65 20 61 66 66 65 63  aining the affec
38170 74 65 64 20 72 6f 77 2e 0a 2a 2a 20 54 68 65 20  ted row..** The 
38180 66 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 70  final callback p
38190 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20  arameter is the 
381a0 72 6f 77 69 64 20 6f 66 20 74 68 65 20 72 6f 77  rowid of the row
381b0 2e 20 49 6e 20 74 68 65 20 63 61 73 65 20 6f 66  . In the case of
381c0 0a 2a 2a 20 61 6e 20 75 70 64 61 74 65 2c 20 74  .** an update, t
381d0 68 69 73 20 69 73 20 74 68 65 20 72 6f 77 69 64  his is the rowid
381e0 20 61 66 74 65 72 20 74 68 65 20 75 70 64 61 74   after the updat
381f0 65 20 74 61 6b 65 73 20 70 6c 61 63 65 2e 0a 2a  e takes place..*
38200 2a 0a 2a 2a 20 54 68 65 20 75 70 64 61 74 65 20  *.** The update 
38210 68 6f 6f 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f  hook is not invo
38220 6b 65 64 20 77 68 65 6e 20 69 6e 74 65 72 6e 61  ked when interna
38230 6c 20 73 79 73 74 65 6d 20 74 61 62 6c 65 73 20  l system tables 
38240 61 72 65 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 20  are.** modified 
38250 28 69 2e 65 2e 20 73 71 6c 69 74 65 5f 6d 61 73  (i.e. sqlite_mas
38260 74 65 72 20 61 6e 64 20 73 71 6c 69 74 65 5f 73  ter and sqlite_s
38270 65 71 75 65 6e 63 65 29 2e 0a 2a 2a 0a 2a 2a 20  equence)..**.** 
38280 49 66 20 61 6e 6f 74 68 65 72 20 66 75 6e 63 74  If another funct
38290 69 6f 6e 20 77 61 73 20 70 72 65 76 69 6f 75 73  ion was previous
382a0 6c 79 20 72 65 67 69 73 74 65 72 65 64 2c 20 69  ly registered, i
382b0 74 73 20 70 41 72 67 20 76 61 6c 75 65 0a 2a 2a  ts pArg value.**
382c0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 4f   is returned.  O
382d0 74 68 65 72 77 69 73 65 20 4e 55 4c 4c 20 69 73  therwise NULL is
382e0 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
382f0 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
38300 2a 2a 20 7b 48 31 32 39 37 31 7d 20 54 68 65 20  ** {H12971} The 
38310 5b 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f  [sqlite3_update_
38320 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d 20 69 6e 74  hook(D,F,P)] int
38330 65 72 66 61 63 65 20 63 61 75 73 65 73 20 74 68  erface causes th
38340 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 20 20  e callback.**   
38350 20 20 20 20 20 20 20 66 75 6e 63 74 69 6f 6e 20         function 
38360 46 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20  F to be invoked 
38370 77 69 74 68 20 66 69 72 73 74 20 70 61 72 61 6d  with first param
38380 65 74 65 72 20 50 20 77 68 65 6e 65 76 65 72 0a  eter P whenever.
38390 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20 74 61  **          a ta
383a0 62 6c 65 20 72 6f 77 20 69 73 20 6d 6f 64 69 66  ble row is modif
383b0 69 65 64 2c 20 69 6e 73 65 72 74 65 64 2c 20 6f  ied, inserted, o
383c0 72 20 64 65 6c 65 74 65 64 20 6f 6e 0a 2a 2a 20  r deleted on.** 
383d0 20 20 20 20 20 20 20 20 20 74 68 65 20 5b 64 61           the [da
383e0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
383f0 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  n] D..**.** {H12
38400 39 37 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  973} The [sqlite
38410 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 44 2c  3_update_hook(D,
38420 46 2c 50 29 5d 20 69 6e 74 65 72 66 61 63 65 20  F,P)] interface 
38430 72 65 74 75 72 6e 73 20 74 68 65 20 76 61 6c 75  returns the valu
38440 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66  e.**          of
38450 20 50 20 66 6f 72 20 74 68 65 20 70 72 65 76 69   P for the previ
38460 6f 75 73 20 63 61 6c 6c 20 6f 6e 20 74 68 65 20  ous call on the 
38470 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63  same [database c
38480 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2c 0a 2a 2a  onnection] D,.**
38490 20 20 20 20 20 20 20 20 20 20 6f 72 20 4e 55 4c            or NUL
384a0 4c 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20  L for the first 
384b0 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  call..**.** {H12
384c0 39 37 35 7d 20 49 66 20 74 68 65 20 75 70 64 61  975} If the upda
384d0 74 65 20 68 6f 6f 6b 20 63 61 6c 6c 62 61 63 6b  te hook callback
384e0 20 46 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 75   F in [sqlite3_u
384f0 70 64 61 74 65 5f 68 6f 6f 6b 28 44 2c 46 2c 50  pdate_hook(D,F,P
38500 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  )].**          i
38510 73 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65 20  s NULL then the 
38520 6e 6f 20 75 70 64 61 74 65 20 63 61 6c 6c 62 61  no update callba
38530 63 6b 73 20 61 72 65 20 6d 61 64 65 2e 0a 2a 2a  cks are made..**
38540 0a 2a 2a 20 7b 48 31 32 39 37 37 7d 20 45 61 63  .** {H12977} Eac
38550 68 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  h call to [sqlit
38560 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 44  e3_update_hook(D
38570 2c 46 2c 50 29 5d 20 6f 76 65 72 72 69 64 65 73  ,F,P)] overrides
38580 20 70 72 69 6f 72 20 63 61 6c 6c 73 0a 2a 2a 20   prior calls.** 
38590 20 20 20 20 20 20 20 20 20 74 6f 20 74 68 65 20           to the 
385a0 73 61 6d 65 20 69 6e 74 65 72 66 61 63 65 20 6f  same interface o
385b0 6e 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61  n the same [data
385c0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
385d0 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 37   D..**.** {H1297
385e0 39 7d 20 54 68 65 20 75 70 64 61 74 65 20 68 6f  9} The update ho
385f0 6f 6b 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 6e  ok callback is n
38600 6f 74 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20  ot invoked when 
38610 69 6e 74 65 72 6e 61 6c 20 73 79 73 74 65 6d 0a  internal system.
38620 2a 2a 20 20 20 20 20 20 20 20 20 20 74 61 62 6c  **          tabl
38630 65 73 20 73 75 63 68 20 61 73 20 73 71 6c 69 74  es such as sqlit
38640 65 5f 6d 61 73 74 65 72 20 61 6e 64 20 73 71 6c  e_master and sql
38650 69 74 65 5f 73 65 71 75 65 6e 63 65 20 61 72 65  ite_sequence are
38660 20 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a 0a 2a 2a   modified..**.**
38670 20 7b 48 31 32 39 38 31 7d 20 54 68 65 20 73 65   {H12981} The se
38680 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74  cond parameter t
38690 6f 20 74 68 65 20 75 70 64 61 74 65 20 63 61 6c  o the update cal
386a0 6c 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 20 20  lback.**        
386b0 20 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c    is one of [SQL
386c0 49 54 45 5f 49 4e 53 45 52 54 5d 2c 20 5b 53 51  ITE_INSERT], [SQ
386d0 4c 49 54 45 5f 44 45 4c 45 54 45 5d 20 6f 72 20  LITE_DELETE] or 
386e0 5b 53 51 4c 49 54 45 5f 55 50 44 41 54 45 5d 2c  [SQLITE_UPDATE],
386f0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64 65 70  .**          dep
38700 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f 70  ending on the op
38710 65 72 61 74 69 6f 6e 20 74 68 61 74 20 63 61 75  eration that cau
38720 73 65 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  sed the callback
38730 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 2e 0a   to be invoked..
38740 2a 2a 0a 2a 2a 20 7b 48 31 32 39 38 33 7d 20 54  **.** {H12983} T
38750 68 65 20 74 68 69 72 64 20 61 6e 64 20 66 6f 75  he third and fou
38760 72 74 68 20 61 72 67 75 6d 65 6e 74 73 20 74 6f  rth arguments to
38770 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f   the callback co
38780 6e 74 61 69 6e 20 70 6f 69 6e 74 65 72 73 0a 2a  ntain pointers.*
38790 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20 7a 65  *          to ze
387a0 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54  ro-terminated UT
387b0 46 2d 38 20 73 74 72 69 6e 67 73 20 77 68 69 63  F-8 strings whic
387c0 68 20 61 72 65 20 74 68 65 20 6e 61 6d 65 73 20  h are the names 
387d0 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  of the.**       
387e0 20 20 20 64 61 74 61 62 61 73 65 20 61 6e 64 20     database and 
387f0 74 61 62 6c 65 20 74 68 61 74 20 69 73 20 62 65  table that is be
38800 69 6e 67 20 75 70 64 61 74 65 64 2e 0a 0a 2a 2a  ing updated...**
38810 20 7b 48 31 32 39 38 35 7d 20 54 68 65 20 66 69   {H12985} The fi
38820 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 70 61 72  nal callback par
38830 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 72 6f  ameter is the ro
38840