System.Data.SQLite
Hex Artifact Content
Not logged in

Artifact 09649635ea5f98c281c5adeee3e7ef6b18be451a:


0000: 2f 2a 0a 2a 2a 20 32 30 30 31 20 53 65 70 74 65  /*.** 2001 Septe
0010: 6d 62 65 72 20 31 35 0a 2a 2a 0a 2a 2a 20 54 68  mber 15.**.** Th
0020: 65 20 61 75 74 68 6f 72 20 64 69 73 63 6c 61 69  e author disclai
0030: 6d 73 20 63 6f 70 79 72 69 67 68 74 20 74 6f 20  ms copyright to 
0040: 74 68 69 73 20 73 6f 75 72 63 65 20 63 6f 64 65  this source code
0050: 2e 20 20 49 6e 20 70 6c 61 63 65 20 6f 66 0a 2a  .  In place of.*
0060: 2a 20 61 20 6c 65 67 61 6c 20 6e 6f 74 69 63 65  * a legal notice
0070: 2c 20 68 65 72 65 20 69 73 20 61 20 62 6c 65 73  , here is a bles
0080: 73 69 6e 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d  sing:.**.**    M
0090: 61 79 20 79 6f 75 20 64 6f 20 67 6f 6f 64 20 61  ay you do good a
00a0: 6e 64 20 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20  nd not evil..** 
00b0: 20 20 20 4d 61 79 20 79 6f 75 20 66 69 6e 64 20     May you find 
00c0: 66 6f 72 67 69 76 65 6e 65 73 73 20 66 6f 72 20  forgiveness for 
00d0: 79 6f 75 72 73 65 6c 66 20 61 6e 64 20 66 6f 72  yourself and for
00e0: 67 69 76 65 20 6f 74 68 65 72 73 2e 0a 2a 2a 20  give others..** 
00f0: 20 20 20 4d 61 79 20 79 6f 75 20 73 68 61 72 65     May you share
0100: 20 66 72 65 65 6c 79 2c 20 6e 65 76 65 72 20 74   freely, never t
0110: 61 6b 69 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20  aking more than 
0120: 79 6f 75 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a  you give..**.***
0130: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0140: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0150: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0160: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0170: 2a 2a 2a 2a 2a 2a 0a 2a 2a 20 54 68 69 73 20 68  ******.** This h
0180: 65 61 64 65 72 20 66 69 6c 65 20 64 65 66 69 6e  eader file defin
0190: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
01a0: 20 74 68 61 74 20 74 68 65 20 53 51 4c 69 74 65   that the SQLite
01b0: 20 6c 69 62 72 61 72 79 0a 2a 2a 20 70 72 65 73   library.** pres
01c0: 65 6e 74 73 20 74 6f 20 63 6c 69 65 6e 74 20 70  ents to client p
01d0: 72 6f 67 72 61 6d 73 2e 20 20 49 66 20 61 20 43  rograms.  If a C
01e0: 2d 66 75 6e 63 74 69 6f 6e 2c 20 73 74 72 75 63  -function, struc
01f0: 74 75 72 65 2c 20 64 61 74 61 74 79 70 65 2c 0a  ture, datatype,.
0200: 2a 2a 20 6f 72 20 63 6f 6e 73 74 61 6e 74 20 64  ** or constant d
0210: 65 66 69 6e 69 74 69 6f 6e 20 64 6f 65 73 20 6e  efinition does n
0220: 6f 74 20 61 70 70 65 61 72 20 69 6e 20 74 68 69  ot appear in thi
0230: 73 20 66 69 6c 65 2c 20 74 68 65 6e 20 69 74 20  s file, then it 
0240: 69 73 0a 2a 2a 20 6e 6f 74 20 61 20 70 75 62 6c  is.** not a publ
0250: 69 73 68 65 64 20 41 50 49 20 6f 66 20 53 51 4c  ished API of SQL
0260: 69 74 65 2c 20 69 73 20 73 75 62 6a 65 63 74 20  ite, is subject 
0270: 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75  to change withou
0280: 74 0a 2a 2a 20 6e 6f 74 69 63 65 2c 20 61 6e 64  t.** notice, and
0290: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 72   should not be r
02a0: 65 66 65 72 65 6e 63 65 64 20 62 79 20 70 72 6f  eferenced by pro
02b0: 67 72 61 6d 73 20 74 68 61 74 20 75 73 65 20 53  grams that use S
02c0: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d  QLite..**.** Som
02d0: 65 20 6f 66 20 74 68 65 20 64 65 66 69 6e 69 74  e of the definit
02e0: 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 69 6e  ions that are in
02f0: 20 74 68 69 73 20 66 69 6c 65 20 61 72 65 20 6d   this file are m
0300: 61 72 6b 65 64 20 61 73 0a 2a 2a 20 22 65 78 70  arked as.** "exp
0310: 65 72 69 6d 65 6e 74 61 6c 22 2e 20 20 45 78 70  erimental".  Exp
0320: 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66  erimental interf
0330: 61 63 65 73 20 61 72 65 20 6e 6f 72 6d 61 6c 6c  aces are normall
0340: 79 20 6e 65 77 0a 2a 2a 20 66 65 61 74 75 72 65  y new.** feature
0350: 73 20 72 65 63 65 6e 74 6c 79 20 61 64 64 65 64  s recently added
0360: 20 74 6f 20 53 51 4c 69 74 65 2e 20 20 57 65 20   to SQLite.  We 
0370: 64 6f 20 6e 6f 74 20 61 6e 74 69 63 69 70 61 74  do not anticipat
0380: 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 74 6f 20  e changes.** to 
0390: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
03a0: 65 72 66 61 63 65 73 20 62 75 74 20 72 65 73 65  erfaces but rese
03b0: 72 76 65 20 74 6f 20 6d 61 6b 65 20 6d 69 6e 6f  rve to make mino
03c0: 72 20 63 68 61 6e 67 65 73 20 69 66 0a 2a 2a 20  r changes if.** 
03d0: 65 78 70 65 72 69 65 6e 63 65 20 66 72 6f 6d 20  experience from 
03e0: 75 73 65 20 22 69 6e 20 74 68 65 20 77 69 6c 64  use "in the wild
03f0: 22 20 73 75 67 67 65 73 74 20 73 75 63 68 20 63  " suggest such c
0400: 68 61 6e 67 65 73 20 61 72 65 20 70 72 75 64 65  hanges are prude
0410: 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6f 66  nt..**.** The of
0420: 66 69 63 69 61 6c 20 43 2d 6c 61 6e 67 75 61 67  ficial C-languag
0430: 65 20 41 50 49 20 64 6f 63 75 6d 65 6e 74 61 74  e API documentat
0440: 69 6f 6e 20 66 6f 72 20 53 51 4c 69 74 65 20 69  ion for SQLite i
0450: 73 20 64 65 72 69 76 65 64 0a 2a 2a 20 66 72 6f  s derived.** fro
0460: 6d 20 63 6f 6d 6d 65 6e 74 73 20 69 6e 20 74 68  m comments in th
0470: 69 73 20 66 69 6c 65 2e 20 20 54 68 69 73 20 66  is file.  This f
0480: 69 6c 65 20 69 73 20 74 68 65 20 61 75 74 68 6f  ile is the autho
0490: 72 69 74 61 74 69 76 65 20 73 6f 75 72 63 65 0a  ritative source.
04a0: 2a 2a 20 6f 6e 20 68 6f 77 20 53 51 4c 69 74 65  ** on how SQLite
04b0: 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20   interfaces are 
04c0: 73 75 70 70 6f 73 65 20 74 6f 20 6f 70 65 72 61  suppose to opera
04d0: 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6e 61  te..**.** The na
04e0: 6d 65 20 6f 66 20 74 68 69 73 20 66 69 6c 65 20  me of this file 
04f0: 75 6e 64 65 72 20 63 6f 6e 66 69 67 75 72 61 74  under configurat
0500: 69 6f 6e 20 6d 61 6e 61 67 65 6d 65 6e 74 20 69  ion management i
0510: 73 20 22 73 71 6c 69 74 65 2e 68 2e 69 6e 22 2e  s "sqlite.h.in".
0520: 0a 2a 2a 20 54 68 65 20 6d 61 6b 65 66 69 6c 65  .** The makefile
0530: 20 6d 61 6b 65 73 20 73 6f 6d 65 20 6d 69 6e 6f   makes some mino
0540: 72 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 69  r changes to thi
0550: 73 20 66 69 6c 65 20 28 73 75 63 68 20 61 73 20  s file (such as 
0560: 69 6e 73 65 72 74 69 6e 67 0a 2a 2a 20 74 68 65  inserting.** the
0570: 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 29   version number)
0580: 20 61 6e 64 20 63 68 61 6e 67 65 73 20 69 74 73   and changes its
0590: 20 6e 61 6d 65 20 74 6f 20 22 73 71 6c 69 74 65   name to "sqlite
05a0: 33 2e 68 22 20 61 73 0a 2a 2a 20 70 61 72 74 20  3.h" as.** part 
05b0: 6f 66 20 74 68 65 20 62 75 69 6c 64 20 70 72 6f  of the build pro
05c0: 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 40 28 23 29  cess..**.** @(#)
05d0: 20 24 49 64 3a 20 73 71 6c 69 74 65 33 2e 68 2c   $Id: sqlite3.h,
05e0: 76 20 31 2e 33 38 20 32 30 30 38 2f 30 39 2f 32  v 1.38 2008/09/2
05f0: 32 20 31 36 3a 33 30 3a 32 33 20 72 6d 73 69 6d  2 16:30:23 rmsim
0600: 70 73 6f 6e 20 45 78 70 20 24 0a 2a 2f 0a 23 69  pson Exp $.*/.#i
0610: 66 6e 64 65 66 20 5f 53 51 4c 49 54 45 33 5f 48  fndef _SQLITE3_H
0620: 5f 0a 23 64 65 66 69 6e 65 20 5f 53 51 4c 49 54  _.#define _SQLIT
0630: 45 33 5f 48 5f 0a 23 69 6e 63 6c 75 64 65 20 3c  E3_H_.#include <
0640: 73 74 64 61 72 67 2e 68 3e 20 20 20 20 20 2f 2a  stdarg.h>     /*
0650: 20 4e 65 65 64 65 64 20 66 6f 72 20 74 68 65 20   Needed for the 
0660: 64 65 66 69 6e 69 74 69 6f 6e 20 6f 66 20 76 61  definition of va
0670: 5f 6c 69 73 74 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20  _list */../*.** 
0680: 4d 61 6b 65 20 73 75 72 65 20 77 65 20 63 61 6e  Make sure we can
0690: 20 63 61 6c 6c 20 74 68 69 73 20 73 74 75 66 66   call this stuff
06a0: 20 66 72 6f 6d 20 43 2b 2b 2e 0a 2a 2f 0a 23 69   from C++..*/.#i
06b0: 66 64 65 66 20 5f 5f 63 70 6c 75 73 70 6c 75 73  fdef __cplusplus
06c0: 0a 65 78 74 65 72 6e 20 22 43 22 20 7b 0a 23 65  .extern "C" {.#e
06d0: 6e 64 69 66 0a 0a 0a 2f 2a 0a 2a 2a 20 41 64 64  ndif.../*.** Add
06e0: 20 74 68 65 20 61 62 69 6c 69 74 79 20 74 6f 20   the ability to 
06f0: 6f 76 65 72 72 69 64 65 20 27 65 78 74 65 72 6e  override 'extern
0700: 27 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c  '.*/.#ifndef SQL
0710: 49 54 45 5f 45 58 54 45 52 4e 0a 23 20 64 65 66  ITE_EXTERN.# def
0720: 69 6e 65 20 53 51 4c 49 54 45 5f 45 58 54 45 52  ine SQLITE_EXTER
0730: 4e 20 65 78 74 65 72 6e 0a 23 65 6e 64 69 66 0a  N extern.#endif.
0740: 0a 2f 2a 0a 2a 2a 20 41 64 64 20 74 68 65 20 61  ./*.** Add the a
0750: 62 69 6c 69 74 79 20 74 6f 20 6d 61 72 6b 20 69  bility to mark i
0760: 6e 74 65 72 66 61 63 65 73 20 61 73 20 64 65 70  nterfaces as dep
0770: 72 65 63 61 74 65 64 2e 0a 2a 2f 0a 23 69 66 20  recated..*/.#if 
0780: 28 5f 5f 47 4e 55 43 5f 5f 20 3e 20 33 20 7c 7c  (__GNUC__ > 3 ||
0790: 20 28 5f 5f 47 4e 55 43 5f 5f 20 3d 3d 20 33 20   (__GNUC__ == 3 
07a0: 26 26 20 5f 5f 47 4e 55 43 5f 4d 49 4e 4f 52 5f  && __GNUC_MINOR_
07b0: 5f 20 3e 3d 20 31 29 29 0a 20 20 2f 2a 20 47 43  _ >= 1)).  /* GC
07c0: 43 20 61 64 64 65 64 20 74 68 65 20 64 65 70 72  C added the depr
07d0: 65 63 61 74 65 64 20 61 74 74 72 69 62 75 74 65  ecated attribute
07e0: 20 69 6e 20 76 65 72 73 69 6f 6e 20 33 2e 31 20   in version 3.1 
07f0: 2a 2f 0a 20 20 23 64 65 66 69 6e 65 20 53 51 4c  */.  #define SQL
0800: 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 5f  ITE_DEPRECATED _
0810: 5f 61 74 74 72 69 62 75 74 65 5f 5f 20 28 28 64  _attribute__ ((d
0820: 65 70 72 65 63 61 74 65 64 29 29 0a 23 65 6c 69  eprecated)).#eli
0830: 66 20 64 65 66 69 6e 65 64 28 5f 4d 53 43 5f 56  f defined(_MSC_V
0840: 45 52 29 20 26 26 20 28 5f 4d 53 43 5f 56 45 52  ER) && (_MSC_VER
0850: 3e 31 32 30 30 29 20 0a 20 20 23 64 65 66 69 6e  >1200) .  #defin
0860: 65 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41  e SQLITE_DEPRECA
0870: 54 45 44 20 5f 5f 64 65 63 6c 73 70 65 63 28 64  TED __declspec(d
0880: 65 70 72 65 63 61 74 65 64 29 0a 23 65 6c 73 65  eprecated).#else
0890: 0a 20 20 23 64 65 66 69 6e 65 20 53 51 4c 49 54  .  #define SQLIT
08a0: 45 5f 44 45 50 52 45 43 41 54 45 44 0a 23 65 6e  E_DEPRECATED.#en
08b0: 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 41 64 64 20 74  dif../*.** Add t
08c0: 68 65 20 61 62 69 6c 69 74 79 20 74 6f 20 6d 61  he ability to ma
08d0: 72 6b 20 69 6e 74 65 72 66 61 63 65 73 20 61 73  rk interfaces as
08e0: 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 2e 0a 2a   experimental..*
08f0: 2f 0a 23 69 66 20 28 5f 5f 47 4e 55 43 5f 5f 20  /.#if (__GNUC__ 
0900: 3e 20 34 20 7c 7c 20 28 5f 5f 47 4e 55 43 5f 5f  > 4 || (__GNUC__
0910: 20 3d 3d 20 34 20 26 26 20 5f 5f 47 4e 55 43 5f   == 4 && __GNUC_
0920: 4d 49 4e 4f 52 5f 5f 20 3e 3d 20 33 29 29 0a 20  MINOR__ >= 3)). 
0930: 20 2f 2a 20 49 20 63 61 6e 20 63 6f 6e 66 69 72   /* I can confir
0940: 6d 20 74 68 61 74 20 69 74 20 64 6f 65 73 20 6e  m that it does n
0950: 6f 74 20 77 6f 72 6b 20 6f 6e 20 76 65 72 73 69  ot work on versi
0960: 6f 6e 20 34 2e 31 2e 30 2e 2e 2e 20 2a 2f 0a 20  on 4.1.0... */. 
0970: 20 2f 2a 20 46 69 72 73 74 20 61 70 70 65 61 72   /* First appear
0980: 73 20 69 6e 20 47 43 43 20 64 6f 63 73 20 66 6f  s in GCC docs fo
0990: 72 20 76 65 72 73 69 6f 6e 20 34 2e 33 2e 30 20  r version 4.3.0 
09a0: 2a 2f 0a 20 20 23 64 65 66 69 6e 65 20 53 51 4c  */.  #define SQL
09b0: 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c  ITE_EXPERIMENTAL
09c0: 20 5f 5f 61 74 74 72 69 62 75 74 65 5f 5f 20 28   __attribute__ (
09d0: 28 77 61 72 6e 69 6e 67 20 28 22 69 73 20 65 78  (warning ("is ex
09e0: 70 65 72 69 6d 65 6e 74 61 6c 22 29 29 29 0a 23  perimental"))).#
09f0: 65 6c 69 66 20 64 65 66 69 6e 65 64 28 5f 4d 53  elif defined(_MS
0a00: 43 5f 56 45 52 29 20 26 26 20 28 5f 4d 53 43 5f  C_VER) && (_MSC_
0a10: 56 45 52 3e 31 32 30 30 29 20 0a 20 20 23 64 65  VER>1200) .  #de
0a20: 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 58 50 45  fine SQLITE_EXPE
0a30: 52 49 4d 45 4e 54 41 4c 20 5f 5f 64 65 63 6c 73  RIMENTAL __decls
0a40: 70 65 63 28 64 65 70 72 65 63 61 74 65 64 28 22  pec(deprecated("
0a50: 77 61 73 20 64 65 63 6c 61 72 65 64 20 65 78 70  was declared exp
0a60: 65 72 69 6d 65 6e 74 61 6c 22 29 29 0a 23 65 6c  erimental")).#el
0a70: 73 65 0a 20 20 23 64 65 66 69 6e 65 20 53 51 4c  se.  #define SQL
0a80: 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c  ITE_EXPERIMENTAL
0a90: 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 45  .#endif../*.** E
0aa0: 6e 73 75 72 65 20 74 68 65 73 65 20 73 79 6d 62  nsure these symb
0ab0: 6f 6c 73 20 77 65 72 65 20 6e 6f 74 20 64 65 66  ols were not def
0ac0: 69 6e 65 64 20 62 79 20 73 6f 6d 65 20 70 72 65  ined by some pre
0ad0: 76 69 6f 75 73 20 68 65 61 64 65 72 20 66 69 6c  vious header fil
0ae0: 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c  e..*/.#ifdef SQL
0af0: 49 54 45 5f 56 45 52 53 49 4f 4e 0a 23 20 75 6e  ITE_VERSION.# un
0b00: 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49  def SQLITE_VERSI
0b10: 4f 4e 0a 23 65 6e 64 69 66 0a 23 69 66 64 65 66  ON.#endif.#ifdef
0b20: 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f   SQLITE_VERSION_
0b30: 4e 55 4d 42 45 52 0a 23 20 75 6e 64 65 66 20 53  NUMBER.# undef S
0b40: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55  QLITE_VERSION_NU
0b50: 4d 42 45 52 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a  MBER.#endif../*.
0b60: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d  ** CAPI3REF: Com
0b70: 70 69 6c 65 2d 54 69 6d 65 20 4c 69 62 72 61 72  pile-Time Librar
0b80: 79 20 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65 72  y Version Number
0b90: 73 20 7b 48 31 30 30 31 30 7d 20 3c 53 36 30 31  s {H10010} <S601
0ba0: 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51  00>.**.** The SQ
0bb0: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 20 61 6e 64  LITE_VERSION and
0bc0: 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f   SQLITE_VERSION_
0bd0: 4e 55 4d 42 45 52 20 23 64 65 66 69 6e 65 73 20  NUMBER #defines 
0be0: 69 6e 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74 65  in.** the sqlite
0bf0: 33 2e 68 20 66 69 6c 65 20 73 70 65 63 69 66 79  3.h file specify
0c00: 20 74 68 65 20 76 65 72 73 69 6f 6e 20 6f 66 20   the version of 
0c10: 53 51 4c 69 74 65 20 77 69 74 68 20 77 68 69 63  SQLite with whic
0c20: 68 0a 2a 2a 20 74 68 61 74 20 68 65 61 64 65 72  h.** that header
0c30: 20 66 69 6c 65 20 69 73 20 61 73 73 6f 63 69 61   file is associa
0c40: 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 22  ted..**.** The "
0c50: 76 65 72 73 69 6f 6e 22 20 6f 66 20 53 51 4c 69  version" of SQLi
0c60: 74 65 20 69 73 20 61 20 73 74 72 69 6e 67 20 6f  te is a string o
0c70: 66 20 74 68 65 20 66 6f 72 6d 20 22 58 2e 59 2e  f the form "X.Y.
0c80: 5a 22 2e 0a 2a 2a 20 54 68 65 20 70 68 72 61 73  Z"..** The phras
0c90: 65 20 22 61 6c 70 68 61 22 20 6f 72 20 22 62 65  e "alpha" or "be
0ca0: 74 61 22 20 6d 69 67 68 74 20 62 65 20 61 70 70  ta" might be app
0cb0: 65 6e 64 65 64 20 61 66 74 65 72 20 74 68 65 20  ended after the 
0cc0: 5a 2e 0a 2a 2a 20 54 68 65 20 58 20 76 61 6c 75  Z..** The X valu
0cd0: 65 20 69 73 20 6d 61 6a 6f 72 20 76 65 72 73 69  e is major versi
0ce0: 6f 6e 20 6e 75 6d 62 65 72 20 61 6c 77 61 79 73  on number always
0cf0: 20 33 20 69 6e 20 53 51 4c 69 74 65 33 2e 0a 2a   3 in SQLite3..*
0d00: 2a 20 54 68 65 20 58 20 76 61 6c 75 65 20 6f 6e  * The X value on
0d10: 6c 79 20 63 68 61 6e 67 65 73 20 77 68 65 6e 20  ly changes when 
0d20: 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74  backwards compat
0d30: 69 62 69 6c 69 74 79 20 69 73 0a 2a 2a 20 62 72  ibility is.** br
0d40: 6f 6b 65 6e 20 61 6e 64 20 77 65 20 69 6e 74 65  oken and we inte
0d50: 6e 64 20 74 6f 20 6e 65 76 65 72 20 62 72 65 61  nd to never brea
0d60: 6b 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70  k backwards comp
0d70: 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 20 54 68  atibility..** Th
0d80: 65 20 59 20 76 61 6c 75 65 20 69 73 20 74 68 65  e Y value is the
0d90: 20 6d 69 6e 6f 72 20 76 65 72 73 69 6f 6e 20 6e   minor version n
0da0: 75 6d 62 65 72 20 61 6e 64 20 6f 6e 6c 79 20 63  umber and only c
0db0: 68 61 6e 67 65 73 20 77 68 65 6e 0a 2a 2a 20 74  hanges when.** t
0dc0: 68 65 72 65 20 61 72 65 20 6d 61 6a 6f 72 20 66  here are major f
0dd0: 65 61 74 75 72 65 20 65 6e 68 61 6e 63 65 6d 65  eature enhanceme
0de0: 6e 74 73 20 74 68 61 74 20 61 72 65 20 66 6f 72  nts that are for
0df0: 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 6c 65  wards compatible
0e00: 0a 2a 2a 20 62 75 74 20 6e 6f 74 20 62 61 63 6b  .** but not back
0e10: 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 6c 65  wards compatible
0e20: 2e 0a 2a 2a 20 54 68 65 20 5a 20 76 61 6c 75 65  ..** The Z value
0e30: 20 69 73 20 74 68 65 20 72 65 6c 65 61 73 65 20   is the release 
0e40: 6e 75 6d 62 65 72 20 61 6e 64 20 69 73 20 69 6e  number and is in
0e50: 63 72 65 6d 65 6e 74 65 64 20 77 69 74 68 0a 2a  cremented with.*
0e60: 2a 20 65 61 63 68 20 72 65 6c 65 61 73 65 20 62  * each release b
0e70: 75 74 20 72 65 73 65 74 73 20 62 61 63 6b 20 74  ut resets back t
0e80: 6f 20 30 20 77 68 65 6e 65 76 65 72 20 59 20 69  o 0 whenever Y i
0e90: 73 20 69 6e 63 72 65 6d 65 6e 74 65 64 2e 0a 2a  s incremented..*
0ea0: 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
0eb0: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
0ec0: 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  on()] and [sqlit
0ed0: 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75  e3_libversion_nu
0ee0: 6d 62 65 72 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49  mber()]..**.** I
0ef0: 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
0f00: 20 7b 48 31 30 30 31 31 7d 20 54 68 65 20 53 51   {H10011} The SQ
0f10: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 20 23 64 65  LITE_VERSION #de
0f20: 66 69 6e 65 20 69 6e 20 74 68 65 20 73 71 6c 69  fine in the sqli
0f30: 74 65 33 2e 68 20 68 65 61 64 65 72 20 66 69 6c  te3.h header fil
0f40: 65 20 73 68 61 6c 6c 0a 2a 2a 20 20 20 20 20 20  e shall.**      
0f50: 20 20 20 20 65 76 61 6c 75 61 74 65 20 74 6f 20      evaluate to 
0f60: 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c  a string literal
0f70: 20 74 68 61 74 20 69 73 20 74 68 65 20 53 51 4c   that is the SQL
0f80: 69 74 65 20 76 65 72 73 69 6f 6e 0a 2a 2a 20 20  ite version.**  
0f90: 20 20 20 20 20 20 20 20 77 69 74 68 20 77 68 69          with whi
0fa0: 63 68 20 74 68 65 20 68 65 61 64 65 72 20 66 69  ch the header fi
0fb0: 6c 65 20 69 73 20 61 73 73 6f 63 69 61 74 65 64  le is associated
0fc0: 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 30 31 34 7d  ..**.** {H10014}
0fd0: 20 54 68 65 20 53 51 4c 49 54 45 5f 56 45 52 53   The SQLITE_VERS
0fe0: 49 4f 4e 5f 4e 55 4d 42 45 52 20 23 64 65 66 69  ION_NUMBER #defi
0ff0: 6e 65 20 73 68 61 6c 6c 20 72 65 73 6f 6c 76 65  ne shall resolve
1000: 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a   to an integer.*
1010: 2a 20 20 20 20 20 20 20 20 20 20 77 69 74 68 20  *          with 
1020: 74 68 65 20 76 61 6c 75 65 20 28 58 2a 31 30 30  the value (X*100
1030: 30 30 30 30 20 2b 20 59 2a 31 30 30 30 20 2b 20  0000 + Y*1000 + 
1040: 5a 29 20 77 68 65 72 65 20 58 2c 20 59 2c 20 61  Z) where X, Y, a
1050: 6e 64 20 5a 0a 2a 2a 20 20 20 20 20 20 20 20 20  nd Z.**         
1060: 20 61 72 65 20 74 68 65 20 6d 61 6a 6f 72 20 76   are the major v
1070: 65 72 73 69 6f 6e 2c 20 6d 69 6e 6f 72 20 76 65  ersion, minor ve
1080: 72 73 69 6f 6e 2c 20 61 6e 64 20 72 65 6c 65 61  rsion, and relea
1090: 73 65 20 6e 75 6d 62 65 72 2e 0a 2a 2f 0a 23 64  se number..*/.#d
10a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56 45 52  efine SQLITE_VER
10b0: 53 49 4f 4e 20 20 20 20 20 20 20 20 20 22 33 2e  SION         "3.
10c0: 36 2e 33 22 0a 23 64 65 66 69 6e 65 20 53 51 4c  6.3".#define SQL
10d0: 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42  ITE_VERSION_NUMB
10e0: 45 52 20 20 33 30 30 36 30 30 33 0a 0a 2f 2a 0a  ER  3006003../*.
10f0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e  ** CAPI3REF: Run
1100: 2d 54 69 6d 65 20 4c 69 62 72 61 72 79 20 56 65  -Time Library Ve
1110: 72 73 69 6f 6e 20 4e 75 6d 62 65 72 73 20 7b 48  rsion Numbers {H
1120: 31 30 30 32 30 7d 20 3c 53 36 30 31 30 30 3e 0a  10020} <S60100>.
1130: 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c  ** KEYWORDS: sql
1140: 69 74 65 33 5f 76 65 72 73 69 6f 6e 0a 2a 2a 0a  ite3_version.**.
1150: 2a 2a 20 54 68 65 73 65 20 66 65 61 74 75 72 65  ** These feature
1160: 73 20 70 72 6f 76 69 64 65 20 74 68 65 20 73 61  s provide the sa
1170: 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61  me information a
1180: 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 56 45  s the [SQLITE_VE
1190: 52 53 49 4f 4e 5d 0a 2a 2a 20 61 6e 64 20 5b 53  RSION].** and [S
11a0: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55  QLITE_VERSION_NU
11b0: 4d 42 45 52 5d 20 23 64 65 66 69 6e 65 73 20 69  MBER] #defines i
11c0: 6e 20 74 68 65 20 68 65 61 64 65 72 2c 20 62 75  n the header, bu
11d0: 74 20 61 72 65 20 61 73 73 6f 63 69 61 74 65 64  t are associated
11e0: 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 6c 69 62  .** with the lib
11f0: 72 61 72 79 20 69 6e 73 74 65 61 64 20 6f 66 20  rary instead of 
1200: 74 68 65 20 68 65 61 64 65 72 20 66 69 6c 65 2e  the header file.
1210: 20 20 43 61 75 74 69 6f 75 73 20 70 72 6f 67 72    Cautious progr
1220: 61 6d 6d 65 72 73 20 6d 69 67 68 74 0a 2a 2a 20  ammers might.** 
1230: 69 6e 63 6c 75 64 65 20 61 20 63 68 65 63 6b 20  include a check 
1240: 69 6e 20 74 68 65 69 72 20 61 70 70 6c 69 63 61  in their applica
1250: 74 69 6f 6e 20 74 6f 20 76 65 72 69 66 79 20 74  tion to verify t
1260: 68 61 74 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6c  hat.** sqlite3_l
1270: 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72  ibversion_number
1280: 28 29 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e  () always return
1290: 73 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 5b  s the value.** [
12a0: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e  SQLITE_VERSION_N
12b0: 55 4d 42 45 52 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68  UMBER]..**.** Th
12c0: 65 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72  e sqlite3_libver
12d0: 73 69 6f 6e 28 29 20 66 75 6e 63 74 69 6f 6e 20  sion() function 
12e0: 72 65 74 75 72 6e 73 20 74 68 65 20 73 61 6d 65  returns the same
12f0: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 73 20   information as 
1300: 69 73 0a 2a 2a 20 69 6e 20 74 68 65 20 73 71 6c  is.** in the sql
1310: 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 20 73  ite3_version[] s
1320: 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 2e 20  tring constant. 
1330: 20 54 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73   The function is
1340: 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 66 6f 72   provided.** for
1350: 20 75 73 65 20 69 6e 20 44 4c 4c 73 20 73 69 6e   use in DLLs sin
1360: 63 65 20 44 4c 4c 20 75 73 65 72 73 20 75 73 75  ce DLL users usu
1370: 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 68 61 76 65  ally do not have
1380: 20 64 69 72 65 63 74 20 61 63 63 65 73 73 20 74   direct access t
1390: 6f 20 73 74 72 69 6e 67 0a 2a 2a 20 63 6f 6e 73  o string.** cons
13a0: 74 61 6e 74 73 20 77 69 74 68 69 6e 20 74 68 65  tants within the
13b0: 20 44 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41   DLL..**.** INVA
13c0: 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48  RIANTS:.**.** {H
13d0: 31 30 30 32 31 7d 20 54 68 65 20 5b 73 71 6c 69  10021} The [sqli
13e0: 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e  te3_libversion_n
13f0: 75 6d 62 65 72 28 29 5d 20 69 6e 74 65 72 66 61  umber()] interfa
1400: 63 65 20 73 68 61 6c 6c 20 72 65 74 75 72 6e 0a  ce shall return.
1410: 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6e 20 69  **          an i
1420: 6e 74 65 67 65 72 20 65 71 75 61 6c 20 74 6f 20  nteger equal to 
1430: 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f  [SQLITE_VERSION_
1440: 4e 55 4d 42 45 52 5d 2e 0a 2a 2a 0a 2a 2a 20 7b  NUMBER]..**.** {
1450: 48 31 30 30 32 32 7d 20 54 68 65 20 5b 73 71 6c  H10022} The [sql
1460: 69 74 65 33 5f 76 65 72 73 69 6f 6e 5d 20 73 74  ite3_version] st
1470: 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 20 73 68  ring constant sh
1480: 61 6c 6c 20 63 6f 6e 74 61 69 6e 0a 2a 2a 20 20  all contain.**  
1490: 20 20 20 20 20 20 20 20 74 68 65 20 74 65 78 74          the text
14a0: 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   of the [SQLITE_
14b0: 56 45 52 53 49 4f 4e 5d 20 73 74 72 69 6e 67 2e  VERSION] string.
14c0: 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 30 32 33 7d 20  .**.** {H10023} 
14d0: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 69 62  The [sqlite3_lib
14e0: 76 65 72 73 69 6f 6e 28 29 5d 20 66 75 6e 63 74  version()] funct
14f0: 69 6f 6e 20 73 68 61 6c 6c 20 72 65 74 75 72 6e  ion shall return
1500: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20 70  .**          a p
1510: 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73  ointer to the [s
1520: 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5d 20  qlite3_version] 
1530: 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 2e  string constant.
1540: 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 54 45 52  .*/.SQLITE_EXTER
1550: 4e 20 63 6f 6e 73 74 20 63 68 61 72 20 73 71 6c  N const char sql
1560: 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 3b 0a  ite3_version[];.
1570: 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
1580: 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 76  te3_libversion(v
1590: 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  oid);.int sqlite
15a0: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d  3_libversion_num
15b0: 62 65 72 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a  ber(void);../*.*
15c0: 2a 20 43 41 50 49 33 52 45 46 3a 20 54 65 73 74  * CAPI3REF: Test
15d0: 20 54 6f 20 53 65 65 20 49 66 20 54 68 65 20 4c   To See If The L
15e0: 69 62 72 61 72 79 20 49 73 20 54 68 72 65 61 64  ibrary Is Thread
15f0: 73 61 66 65 20 7b 48 31 30 31 30 30 7d 20 3c 53  safe {H10100} <S
1600: 36 30 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 53 51 4c  60100>.**.** SQL
1610: 69 74 65 20 63 61 6e 20 62 65 20 63 6f 6d 70 69  ite can be compi
1620: 6c 65 64 20 77 69 74 68 20 6f 72 20 77 69 74 68  led with or with
1630: 6f 75 74 20 6d 75 74 65 78 65 73 2e 20 20 57 68  out mutexes.  Wh
1640: 65 6e 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54  en.** the [SQLIT
1650: 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 43 20  E_THREADSAFE] C 
1660: 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63  preprocessor mac
1670: 72 6f 20 31 20 6f 72 20 32 2c 20 6d 75 74 65 78  ro 1 or 2, mutex
1680: 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65  es.** are enable
1690: 64 20 61 6e 64 20 53 51 4c 69 74 65 20 69 73 20  d and SQLite is 
16a0: 74 68 72 65 61 64 73 61 66 65 2e 20 20 57 68 65  threadsafe.  Whe
16b0: 6e 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  n the.** [SQLITE
16c0: 5f 54 48 52 45 41 44 53 41 46 45 5d 20 6d 61 63  _THREADSAFE] mac
16d0: 72 6f 20 69 73 20 30 2c 20 0a 2a 2a 20 74 68 65  ro is 0, .** the
16e0: 20 6d 75 74 65 78 65 73 20 61 72 65 20 6f 6d 69   mutexes are omi
16f0: 74 74 65 64 2e 20 20 57 69 74 68 6f 75 74 20 74  tted.  Without t
1700: 68 65 20 6d 75 74 65 78 65 73 2c 20 69 74 20 69  he mutexes, it i
1710: 73 20 6e 6f 74 20 73 61 66 65 0a 2a 2a 20 74 6f  s not safe.** to
1720: 20 75 73 65 20 53 51 4c 69 74 65 20 63 6f 6e 63   use SQLite conc
1730: 75 72 72 65 6e 74 6c 79 20 66 72 6f 6d 20 6d 6f  urrently from mo
1740: 72 65 20 74 68 61 6e 20 6f 6e 65 20 74 68 72 65  re than one thre
1750: 61 64 2e 0a 2a 2a 0a 2a 2a 20 45 6e 61 62 6c 69  ad..**.** Enabli
1760: 6e 67 20 6d 75 74 65 78 65 73 20 69 6e 63 75 72  ng mutexes incur
1770: 73 20 61 20 6d 65 61 73 75 72 61 62 6c 65 20 70  s a measurable p
1780: 65 72 66 6f 72 6d 61 6e 63 65 20 70 65 6e 61 6c  erformance penal
1790: 74 79 2e 0a 2a 2a 20 53 6f 20 69 66 20 73 70 65  ty..** So if spe
17a0: 65 64 20 69 73 20 6f 66 20 75 74 6d 6f 73 74 20  ed is of utmost 
17b0: 69 6d 70 6f 72 74 61 6e 63 65 2c 20 69 74 20 6d  importance, it m
17c0: 61 6b 65 73 20 73 65 6e 73 65 20 74 6f 20 64 69  akes sense to di
17d0: 73 61 62 6c 65 0a 2a 2a 20 74 68 65 20 6d 75 74  sable.** the mut
17e0: 65 78 65 73 2e 20 20 42 75 74 20 66 6f 72 20 6d  exes.  But for m
17f0: 61 78 69 6d 75 6d 20 73 61 66 65 74 79 2c 20 6d  aximum safety, m
1800: 75 74 65 78 65 73 20 73 68 6f 75 6c 64 20 62 65  utexes should be
1810: 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 54 68 65   enabled..** The
1820: 20 64 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f   default behavio
1830: 72 20 69 73 20 66 6f 72 20 6d 75 74 65 78 65 73  r is for mutexes
1840: 20 74 6f 20 62 65 20 65 6e 61 62 6c 65 64 2e 0a   to be enabled..
1850: 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72  **.** This inter
1860: 66 61 63 65 20 63 61 6e 20 62 65 20 75 73 65 64  face can be used
1870: 20 62 79 20 61 20 70 72 6f 67 72 61 6d 20 74 6f   by a program to
1880: 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74 20   make sure that 
1890: 74 68 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 6f  the.** version o
18a0: 66 20 53 51 4c 69 74 65 20 74 68 61 74 20 69 74  f SQLite that it
18b0: 20 69 73 20 6c 69 6e 6b 69 6e 67 20 61 67 61 69   is linking agai
18c0: 6e 73 74 20 77 61 73 20 63 6f 6d 70 69 6c 65 64  nst was compiled
18d0: 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 64 65 73   with.** the des
18e0: 69 72 65 64 20 73 65 74 74 69 6e 67 20 6f 66 20  ired setting of 
18f0: 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  the [SQLITE_THRE
1900: 41 44 53 41 46 45 5d 20 6d 61 63 72 6f 2e 0a 2a  ADSAFE] macro..*
1910: 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66  *.** This interf
1920: 61 63 65 20 6f 6e 6c 79 20 72 65 70 6f 72 74 73  ace only reports
1930: 20 6f 6e 20 74 68 65 20 63 6f 6d 70 69 6c 65 2d   on the compile-
1940: 74 69 6d 65 20 6d 75 74 65 78 20 73 65 74 74 69  time mutex setti
1950: 6e 67 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 53 51  ng.** of the [SQ
1960: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d  LITE_THREADSAFE]
1970: 20 66 6c 61 67 2e 20 20 49 66 20 53 51 4c 69 74   flag.  If SQLit
1980: 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
1990: 74 68 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 48 52  th.** SQLITE_THR
19a0: 45 41 44 53 41 46 45 3d 31 20 74 68 65 6e 20 6d  EADSAFE=1 then m
19b0: 75 74 65 78 65 73 20 61 72 65 20 65 6e 61 62 6c  utexes are enabl
19c0: 65 64 20 62 79 20 64 65 66 61 75 6c 74 20 62 75  ed by default bu
19d0: 74 0a 2a 2a 20 63 61 6e 20 62 65 20 66 75 6c 6c  t.** can be full
19e0: 79 20 6f 72 20 70 61 72 74 69 61 6c 6c 79 20 64  y or partially d
19f0: 69 73 61 62 6c 65 64 20 75 73 69 6e 67 20 61 20  isabled using a 
1a00: 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
1a10: 5f 63 6f 6e 66 69 67 28 29 5d 0a 2a 2a 20 77 69  _config()].** wi
1a20: 74 68 20 74 68 65 20 76 65 72 62 73 20 5b 53 51  th the verbs [SQ
1a30: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47  LITE_CONFIG_SING
1a40: 4c 45 54 48 52 45 41 44 5d 2c 20 5b 53 51 4c 49  LETHREAD], [SQLI
1a50: 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54  TE_CONFIG_MULTIT
1a60: 48 52 45 41 44 5d 2c 0a 2a 2a 20 6f 72 20 5b 53  HREAD],.** or [S
1a70: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54  QLITE_CONFIG_MUT
1a80: 45 58 5d 2e 20 20 54 68 65 20 72 65 74 75 72 6e  EX].  The return
1a90: 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73 20 66   value of this f
1aa0: 75 6e 63 74 69 6f 6e 20 73 68 6f 77 73 0a 2a 2a  unction shows.**
1ab0: 20 6f 6e 6c 79 20 74 68 65 20 64 65 66 61 75 6c   only the defaul
1ac0: 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 73  t compile-time s
1ad0: 65 74 74 69 6e 67 2c 20 6e 6f 74 20 61 6e 79 20  etting, not any 
1ae0: 72 75 6e 2d 74 69 6d 65 20 63 68 61 6e 67 65 73  run-time changes
1af0: 0a 2a 2a 20 74 6f 20 74 68 61 74 20 73 65 74 74  .** to that sett
1b00: 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 74  ing..**.** See t
1b10: 68 65 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  he [threading mo
1b20: 64 65 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f  de] documentatio
1b30: 6e 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  n for additional
1b40: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a   information..**
1b50: 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
1b60: 2a 2a 0a 2a 2a 20 7b 48 31 30 31 30 31 7d 20 54  **.** {H10101} T
1b70: 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 68 72 65  he [sqlite3_thre
1b80: 61 64 73 61 66 65 28 29 5d 20 66 75 6e 63 74 69  adsafe()] functi
1b90: 6f 6e 20 73 68 61 6c 6c 20 72 65 74 75 72 6e 20  on shall return 
1ba0: 6e 6f 6e 7a 65 72 6f 20 69 66 0a 2a 2a 20 20 20  nonzero if.**   
1bb0: 20 20 20 20 20 20 20 61 6e 64 20 6f 6e 6c 79 20         and only 
1bc0: 69 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 53  if.**          S
1bd0: 51 4c 69 74 65 20 77 61 73 20 63 6f 6d 70 69 6c  QLite was compil
1be0: 65 64 20 77 69 74 68 20 74 68 65 20 69 74 73 20  ed with the its 
1bf0: 6d 75 74 65 78 65 73 20 65 6e 61 62 6c 65 64 20  mutexes enabled 
1c00: 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a  by default..**.*
1c10: 2a 20 7b 48 31 30 31 30 32 7d 20 54 68 65 20 76  * {H10102} The v
1c20: 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79  alue returned by
1c30: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 68   the [sqlite3_th
1c40: 72 65 61 64 73 61 66 65 28 29 5d 20 66 75 6e 63  readsafe()] func
1c50: 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  tion.**         
1c60: 20 73 68 61 6c 6c 20 6e 6f 74 20 63 68 61 6e 67   shall not chang
1c70: 65 20 77 68 65 6e 20 6d 75 74 65 78 20 73 65 74  e when mutex set
1c80: 74 69 6e 67 20 61 72 65 20 6d 6f 64 69 66 69 65  ting are modifie
1c90: 64 20 61 74 0a 2a 2a 20 20 20 20 20 20 20 20 20  d at.**         
1ca0: 20 72 75 6e 74 69 6d 65 20 75 73 69 6e 67 20 74   runtime using t
1cb0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  he [sqlite3_conf
1cc0: 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  ig()] interface 
1cd0: 61 6e 64 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  and .**         
1ce0: 20 65 73 70 65 63 69 61 6c 6c 79 20 74 68 65 20   especially the 
1cf0: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  [SQLITE_CONFIG_S
1d00: 49 4e 47 4c 45 54 48 52 45 41 44 5d 2c 0a 2a 2a  INGLETHREAD],.**
1d10: 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54            [SQLIT
1d20: 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48  E_CONFIG_MULTITH
1d30: 52 45 41 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 43  READ], [SQLITE_C
1d40: 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44  ONFIG_SERIALIZED
1d50: 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  ],.**          a
1d60: 6e 64 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  nd [SQLITE_CONFI
1d70: 47 5f 4d 55 54 45 58 5d 20 76 65 72 62 73 2e 0a  G_MUTEX] verbs..
1d80: 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 74  */.int sqlite3_t
1d90: 68 72 65 61 64 73 61 66 65 28 76 6f 69 64 29 3b  hreadsafe(void);
1da0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1db0: 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65  : Database Conne
1dc0: 63 74 69 6f 6e 20 48 61 6e 64 6c 65 20 7b 48 31  ction Handle {H1
1dd0: 32 30 30 30 7d 20 3c 53 34 30 32 30 30 3e 0a 2a  2000} <S40200>.*
1de0: 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 64 61 74  * KEYWORDS: {dat
1df0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1e00: 7d 20 7b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  } {database conn
1e10: 65 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 45  ections}.**.** E
1e20: 61 63 68 20 6f 70 65 6e 20 53 51 4c 69 74 65 20  ach open SQLite 
1e30: 64 61 74 61 62 61 73 65 20 69 73 20 72 65 70 72  database is repr
1e40: 65 73 65 6e 74 65 64 20 62 79 20 61 20 70 6f 69  esented by a poi
1e50: 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61  nter to an insta
1e60: 6e 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6f 70  nce of.** the op
1e70: 61 71 75 65 20 73 74 72 75 63 74 75 72 65 20 6e  aque structure n
1e80: 61 6d 65 64 20 22 73 71 6c 69 74 65 33 22 2e 20  amed "sqlite3". 
1e90: 20 49 74 20 69 73 20 75 73 65 66 75 6c 20 74 6f   It is useful to
1ea0: 20 74 68 69 6e 6b 20 6f 66 20 61 6e 20 73 71 6c   think of an sql
1eb0: 69 74 65 33 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  ite3.** pointer 
1ec0: 61 73 20 61 6e 20 6f 62 6a 65 63 74 2e 20 20 54  as an object.  T
1ed0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  he [sqlite3_open
1ee0: 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ()], [sqlite3_op
1ef0: 65 6e 31 36 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20  en16()], and.** 
1f00: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
1f10: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 61  ()] interfaces a
1f20: 72 65 20 69 74 73 20 63 6f 6e 73 74 72 75 63 74  re its construct
1f30: 6f 72 73 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65  ors, and [sqlite
1f40: 33 5f 63 6c 6f 73 65 28 29 5d 0a 2a 2a 20 69 73  3_close()].** is
1f50: 20 69 74 73 20 64 65 73 74 72 75 63 74 6f 72 2e   its destructor.
1f60: 20 20 54 68 65 72 65 20 61 72 65 20 6d 61 6e 79    There are many
1f70: 20 6f 74 68 65 72 20 69 6e 74 65 72 66 61 63 65   other interface
1f80: 73 20 28 73 75 63 68 20 61 73 0a 2a 2a 20 5b 73  s (such as.** [s
1f90: 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
1fa0: 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63  2()], [sqlite3_c
1fb0: 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29  reate_function()
1fc0: 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  ], and.** [sqlit
1fd0: 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28  e3_busy_timeout(
1fe0: 29 5d 20 74 6f 20 6e 61 6d 65 20 62 75 74 20 74  )] to name but t
1ff0: 68 72 65 65 29 20 74 68 61 74 20 61 72 65 20 6d  hree) that are m
2000: 65 74 68 6f 64 73 20 6f 6e 20 61 6e 0a 2a 2a 20  ethods on an.** 
2010: 73 71 6c 69 74 65 33 20 6f 62 6a 65 63 74 2e 0a  sqlite3 object..
2020: 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
2030: 74 20 73 71 6c 69 74 65 33 20 73 71 6c 69 74 65  t sqlite3 sqlite
2040: 33 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  3;../*.** CAPI3R
2050: 45 46 3a 20 36 34 2d 42 69 74 20 49 6e 74 65 67  EF: 64-Bit Integ
2060: 65 72 20 54 79 70 65 73 20 7b 48 31 30 32 30 30  er Types {H10200
2070: 7d 20 3c 53 31 30 31 31 30 3e 0a 2a 2a 20 4b 45  } <S10110>.** KE
2080: 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 5f 69  YWORDS: sqlite_i
2090: 6e 74 36 34 20 73 71 6c 69 74 65 5f 75 69 6e 74  nt64 sqlite_uint
20a0: 36 34 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65  64.**.** Because
20b0: 20 74 68 65 72 65 20 69 73 20 6e 6f 20 63 72 6f   there is no cro
20c0: 73 73 2d 70 6c 61 74 66 6f 72 6d 20 77 61 79 20  ss-platform way 
20d0: 74 6f 20 73 70 65 63 69 66 79 20 36 34 2d 62 69  to specify 64-bi
20e0: 74 20 69 6e 74 65 67 65 72 20 74 79 70 65 73 0a  t integer types.
20f0: 2a 2a 20 53 51 4c 69 74 65 20 69 6e 63 6c 75 64  ** SQLite includ
2100: 65 73 20 74 79 70 65 64 65 66 73 20 66 6f 72 20  es typedefs for 
2110: 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 61 6e  64-bit signed an
2120: 64 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67  d unsigned integ
2130: 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ers..**.** The s
2140: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 61 6e 64  qlite3_int64 and
2150: 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 20   sqlite3_uint64 
2160: 61 72 65 20 74 68 65 20 70 72 65 66 65 72 72 65  are the preferre
2170: 64 20 74 79 70 65 20 64 65 66 69 6e 69 74 69 6f  d type definitio
2180: 6e 73 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  ns..** The sqlit
2190: 65 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69  e_int64 and sqli
21a0: 74 65 5f 75 69 6e 74 36 34 20 74 79 70 65 73 20  te_uint64 types 
21b0: 61 72 65 20 73 75 70 70 6f 72 74 65 64 20 66 6f  are supported fo
21c0: 72 20 62 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63  r backwards.** c
21d0: 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c  ompatibility onl
21e0: 79 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  y..**.** INVARIA
21f0: 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 32  NTS:.**.** {H102
2200: 30 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 5f  01} The [sqlite_
2210: 69 6e 74 36 34 5d 20 61 6e 64 20 5b 73 71 6c 69  int64] and [sqli
2220: 74 65 33 5f 69 6e 74 36 34 5d 20 74 79 70 65 20  te3_int64] type 
2230: 73 68 61 6c 6c 20 73 70 65 63 69 66 79 0a 2a 2a  shall specify.**
2240: 20 20 20 20 20 20 20 20 20 20 61 20 36 34 2d 62            a 64-b
2250: 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65  it signed intege
2260: 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 32 30 32  r..**.** {H10202
2270: 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 5f 75 69  } The [sqlite_ui
2280: 6e 74 36 34 5d 20 61 6e 64 20 5b 73 71 6c 69 74  nt64] and [sqlit
2290: 65 33 5f 75 69 6e 74 36 34 5d 20 74 79 70 65 20  e3_uint64] type 
22a0: 73 68 61 6c 6c 20 73 70 65 63 69 66 79 0a 2a 2a  shall specify.**
22b0: 20 20 20 20 20 20 20 20 20 20 61 20 36 34 2d 62            a 64-b
22c0: 69 74 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65  it unsigned inte
22d0: 67 65 72 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53  ger..*/.#ifdef S
22e0: 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45  QLITE_INT64_TYPE
22f0: 0a 20 20 74 79 70 65 64 65 66 20 53 51 4c 49 54  .  typedef SQLIT
2300: 45 5f 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c  E_INT64_TYPE sql
2310: 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70  ite_int64;.  typ
2320: 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20 53 51  edef unsigned SQ
2330: 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 20  LITE_INT64_TYPE 
2340: 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23  sqlite_uint64;.#
2350: 65 6c 69 66 20 64 65 66 69 6e 65 64 28 5f 4d 53  elif defined(_MS
2360: 43 5f 56 45 52 29 20 7c 7c 20 64 65 66 69 6e 65  C_VER) || define
2370: 64 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f 5f 29 0a  d(__BORLANDC__).
2380: 20 20 74 79 70 65 64 65 66 20 5f 5f 69 6e 74 36    typedef __int6
2390: 34 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a  4 sqlite_int64;.
23a0: 20 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e    typedef unsign
23b0: 65 64 20 5f 5f 69 6e 74 36 34 20 73 71 6c 69 74  ed __int64 sqlit
23c0: 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c 73 65 0a  e_uint64;.#else.
23d0: 20 20 74 79 70 65 64 65 66 20 6c 6f 6e 67 20 6c    typedef long l
23e0: 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 69  ong int sqlite_i
23f0: 6e 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20  nt64;.  typedef 
2400: 75 6e 73 69 67 6e 65 64 20 6c 6f 6e 67 20 6c 6f  unsigned long lo
2410: 6e 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 75 69  ng int sqlite_ui
2420: 6e 74 36 34 3b 0a 23 65 6e 64 69 66 0a 74 79 70  nt64;.#endif.typ
2430: 65 64 65 66 20 73 71 6c 69 74 65 5f 69 6e 74 36  edef sqlite_int6
2440: 34 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 3b  4 sqlite3_int64;
2450: 0a 74 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f  .typedef sqlite_
2460: 75 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 75  uint64 sqlite3_u
2470: 69 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a 20 49 66  int64;../*.** If
2480: 20 63 6f 6d 70 69 6c 69 6e 67 20 66 6f 72 20 61   compiling for a
2490: 20 70 72 6f 63 65 73 73 6f 72 20 74 68 61 74 20   processor that 
24a0: 6c 61 63 6b 73 20 66 6c 6f 61 74 69 6e 67 20 70  lacks floating p
24b0: 6f 69 6e 74 20 73 75 70 70 6f 72 74 2c 0a 2a 2a  oint support,.**
24c0: 20 73 75 62 73 74 69 74 75 74 65 20 69 6e 74 65   substitute inte
24d0: 67 65 72 20 66 6f 72 20 66 6c 6f 61 74 69 6e 67  ger for floating
24e0: 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a 23 69 66 64 65  -point..*/.#ifde
24f0: 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 46 4c  f SQLITE_OMIT_FL
2500: 4f 41 54 49 4e 47 5f 50 4f 49 4e 54 0a 23 20 64  OATING_POINT.# d
2510: 65 66 69 6e 65 20 64 6f 75 62 6c 65 20 73 71 6c  efine double sql
2520: 69 74 65 33 5f 69 6e 74 36 34 0a 23 65 6e 64 69  ite3_int64.#endi
2530: 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  f../*.** CAPI3RE
2540: 46 3a 20 43 6c 6f 73 69 6e 67 20 41 20 44 61 74  F: Closing A Dat
2550: 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e  abase Connection
2560: 20 7b 48 31 32 30 31 30 7d 20 3c 53 33 30 31 30   {H12010} <S3010
2570: 30 3e 3c 53 34 30 32 30 30 3e 0a 2a 2a 0a 2a 2a  0><S40200>.**.**
2580: 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73   This routine is
2590: 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20   the destructor 
25a0: 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33  for the [sqlite3
25b0: 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20  ] object..**.** 
25c0: 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f  Applications sho
25d0: 75 6c 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  uld [sqlite3_fin
25e0: 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65  alize | finalize
25f0: 5d 20 61 6c 6c 20 5b 70 72 65 70 61 72 65 64 20  ] all [prepared 
2600: 73 74 61 74 65 6d 65 6e 74 73 5d 0a 2a 2a 20 61  statements].** a
2610: 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  nd [sqlite3_blob
2620: 5f 63 6c 6f 73 65 20 7c 20 63 6c 6f 73 65 5d 20  _close | close] 
2630: 61 6c 6c 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65  all [BLOB handle
2640: 73 5d 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  s] associated wi
2650: 74 68 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74  th.** the [sqlit
2660: 65 33 5d 20 6f 62 6a 65 63 74 20 70 72 69 6f 72  e3] object prior
2670: 20 74 6f 20 61 74 74 65 6d 70 74 69 6e 67 20 74   to attempting t
2680: 6f 20 63 6c 6f 73 65 20 74 68 65 20 6f 62 6a 65  o close the obje
2690: 63 74 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69  ct..** The [sqli
26a0: 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 29 5d  te3_next_stmt()]
26b0: 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62   interface can b
26c0: 65 20 75 73 65 64 20 74 6f 20 6c 6f 63 61 74 65  e used to locate
26d0: 20 61 6c 6c 0a 2a 2a 20 5b 70 72 65 70 61 72 65   all.** [prepare
26e0: 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 20 61 73  d statements] as
26f0: 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 61 20  sociated with a 
2700: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
2710: 74 69 6f 6e 5d 20 69 66 20 64 65 73 69 72 65 64  tion] if desired
2720: 2e 0a 2a 2a 20 54 79 70 69 63 61 6c 20 63 6f 64  ..** Typical cod
2730: 65 20 6d 69 67 68 74 20 6c 6f 6f 6b 20 6c 69 6b  e might look lik
2740: 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62  e this:.**.** <b
2750: 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
2760: 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  ** sqlite3_stmt 
2770: 2a 70 53 74 6d 74 3b 0a 2a 2a 20 77 68 69 6c 65  *pStmt;.** while
2780: 28 20 28 70 53 74 6d 74 20 3d 20 73 71 6c 69 74  ( (pStmt = sqlit
2790: 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 64 62 2c  e3_next_stmt(db,
27a0: 20 30 29 29 21 3d 30 20 29 7b 0a 2a 2a 20 26 6e   0))!=0 ){.** &n
27b0: 62 73 70 3b 20 20 20 73 71 6c 69 74 65 33 5f 66  bsp;   sqlite3_f
27c0: 69 6e 61 6c 69 7a 65 28 70 53 74 6d 74 29 3b 0a  inalize(pStmt);.
27d0: 2a 2a 20 7d 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  ** }.** </pre></
27e0: 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
27f0: 2a 20 49 66 20 5b 73 71 6c 69 74 65 33 5f 63 6c  * If [sqlite3_cl
2800: 6f 73 65 28 29 5d 20 69 73 20 69 6e 76 6f 6b 65  ose()] is invoke
2810: 64 20 77 68 69 6c 65 20 61 20 74 72 61 6e 73 61  d while a transa
2820: 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 2c 0a 2a  ction is open,.*
2830: 2a 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f  * the transactio
2840: 6e 20 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c  n is automatical
2850: 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a  ly rolled back..
2860: 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
2870: 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 30 31 31 7d  :.**.** {H12011}
2880: 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 63 61   A successful ca
2890: 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ll to [sqlite3_c
28a0: 6c 6f 73 65 28 43 29 5d 20 73 68 61 6c 6c 20 64  lose(C)] shall d
28b0: 65 73 74 72 6f 79 20 74 68 65 0a 2a 2a 20 20 20  estroy the.**   
28c0: 20 20 20 20 20 20 20 5b 64 61 74 61 62 61 73 65         [database
28d0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62 6a   connection] obj
28e0: 65 63 74 20 43 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  ect C..**.** {H1
28f0: 32 30 31 32 7d 20 41 20 73 75 63 63 65 73 73 66  2012} A successf
2900: 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  ul call to [sqli
2910: 74 65 33 5f 63 6c 6f 73 65 28 43 29 5d 20 73 68  te3_close(C)] sh
2920: 61 6c 6c 20 72 65 74 75 72 6e 20 53 51 4c 49 54  all return SQLIT
2930: 45 5f 4f 4b 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  E_OK..**.** {H12
2940: 30 31 33 7d 20 41 20 73 75 63 63 65 73 73 66 75  013} A successfu
2950: 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  l call to [sqlit
2960: 65 33 5f 63 6c 6f 73 65 28 43 29 5d 20 73 68 61  e3_close(C)] sha
2970: 6c 6c 20 72 65 6c 65 61 73 65 20 61 6c 6c 0a 2a  ll release all.*
2980: 2a 20 20 20 20 20 20 20 20 20 20 6d 65 6d 6f 72  *          memor
2990: 79 20 61 6e 64 20 73 79 73 74 65 6d 20 72 65 73  y and system res
29a0: 6f 75 72 63 65 73 20 61 73 73 6f 63 69 61 74 65  ources associate
29b0: 64 20 77 69 74 68 20 5b 64 61 74 61 62 61 73 65  d with [database
29c0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20   connection].** 
29d0: 20 20 20 20 20 20 20 20 20 43 2e 0a 2a 2a 0a 2a           C..**.*
29e0: 2a 20 7b 48 31 32 30 31 34 7d 20 41 20 63 61 6c  * {H12014} A cal
29f0: 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c  l to [sqlite3_cl
2a00: 6f 73 65 28 43 29 5d 20 6f 6e 20 61 20 5b 64 61  ose(C)] on a [da
2a10: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2a20: 6e 5d 20 43 20 74 68 61 74 0a 2a 2a 20 20 20 20  n] C that.**    
2a30: 20 20 20 20 20 20 68 61 73 20 6f 6e 65 20 6f 72        has one or
2a40: 20 6d 6f 72 65 20 6f 70 65 6e 20 5b 70 72 65 70   more open [prep
2a50: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d  ared statements]
2a60: 20 73 68 61 6c 6c 20 66 61 69 6c 20 77 69 74 68   shall fail with
2a70: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6e 20  .**          an 
2a80: 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 65 72  [SQLITE_BUSY] er
2a90: 72 6f 72 20 63 6f 64 65 2e 0a 2a 2a 0a 2a 2a 20  ror code..**.** 
2aa0: 7b 48 31 32 30 31 35 7d 20 41 20 63 61 6c 6c 20  {H12015} A call 
2ab0: 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73  to [sqlite3_clos
2ac0: 65 28 43 29 5d 20 77 68 65 72 65 20 43 20 69 73  e(C)] where C is
2ad0: 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
2ae0: 73 68 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20  shall.**        
2af0: 20 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f    return SQLITE_
2b00: 4f 4b 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 30 31  OK..**.** {H1201
2b10: 39 7d 20 57 68 65 6e 20 5b 73 71 6c 69 74 65 33  9} When [sqlite3
2b20: 5f 63 6c 6f 73 65 28 43 29 5d 20 69 73 20 69 6e  _close(C)] is in
2b30: 76 6f 6b 65 64 20 6f 6e 20 61 20 5b 64 61 74 61  voked on a [data
2b40: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
2b50: 20 43 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74   C.**          t
2b60: 68 61 74 20 68 61 73 20 61 20 70 65 6e 64 69 6e  hat has a pendin
2b70: 67 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74  g transaction, t
2b80: 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 73  he transaction s
2b90: 68 61 6c 6c 20 62 65 0a 2a 2a 20 20 20 20 20 20  hall be.**      
2ba0: 20 20 20 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e      rolled back.
2bb0: 0a 2a 2a 0a 2a 2a 20 41 53 53 55 4d 50 54 49 4f  .**.** ASSUMPTIO
2bc0: 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 41 31 32 30 31  NS:.**.** {A1201
2bd0: 36 7d 20 54 68 65 20 43 20 70 61 72 61 6d 65 74  6} The C paramet
2be0: 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  er to [sqlite3_c
2bf0: 6c 6f 73 65 28 43 29 5d 20 6d 75 73 74 20 62 65  lose(C)] must be
2c00: 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 0a 2a   either a NULL.*
2c10: 2a 20 20 20 20 20 20 20 20 20 20 70 6f 69 6e 74  *          point
2c20: 65 72 20 6f 72 20 61 6e 20 5b 73 71 6c 69 74 65  er or an [sqlite
2c30: 33 5d 20 6f 62 6a 65 63 74 20 70 6f 69 6e 74 65  3] object pointe
2c40: 72 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 20 20  r obtained.**   
2c50: 20 20 20 20 20 20 20 66 72 6f 6d 20 5b 73 71 6c         from [sql
2c60: 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73  ite3_open()], [s
2c70: 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d  qlite3_open16()]
2c80: 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  , or.**         
2c90: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
2ca0: 32 28 29 5d 2c 20 61 6e 64 20 6e 6f 74 20 70 72  2()], and not pr
2cb0: 65 76 69 6f 75 73 6c 79 20 63 6c 6f 73 65 64 2e  eviously closed.
2cc0: 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
2cd0: 63 6c 6f 73 65 28 73 71 6c 69 74 65 33 20 2a 29  close(sqlite3 *)
2ce0: 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 74 79 70  ;../*.** The typ
2cf0: 65 20 66 6f 72 20 61 20 63 61 6c 6c 62 61 63 6b  e for a callback
2d00: 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68   function..** Th
2d10: 69 73 20 69 73 20 6c 65 67 61 63 79 20 61 6e 64  is is legacy and
2d20: 20 64 65 70 72 65 63 61 74 65 64 2e 20 20 49 74   deprecated.  It
2d30: 20 69 73 20 69 6e 63 6c 75 64 65 64 20 66 6f 72   is included for
2d40: 20 68 69 73 74 6f 72 69 63 61 6c 0a 2a 2a 20 63   historical.** c
2d50: 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 61 6e 64  ompatibility and
2d60: 20 69 73 20 6e 6f 74 20 64 6f 63 75 6d 65 6e 74   is not document
2d70: 65 64 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 69  ed..*/.typedef i
2d80: 6e 74 20 28 2a 73 71 6c 69 74 65 33 5f 63 61 6c  nt (*sqlite3_cal
2d90: 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e 74  lback)(void*,int
2da0: 2c 63 68 61 72 2a 2a 2c 20 63 68 61 72 2a 2a 29  ,char**, char**)
2db0: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2dc0: 46 3a 20 4f 6e 65 2d 53 74 65 70 20 51 75 65 72  F: One-Step Quer
2dd0: 79 20 45 78 65 63 75 74 69 6f 6e 20 49 6e 74 65  y Execution Inte
2de0: 72 66 61 63 65 20 7b 48 31 32 31 30 30 7d 20 3c  rface {H12100} <
2df0: 53 31 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68  S10000>.**.** Th
2e00: 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  e sqlite3_exec()
2e10: 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 61 20   interface is a 
2e20: 63 6f 6e 76 65 6e 69 65 6e 74 20 77 61 79 20 6f  convenient way o
2e30: 66 20 72 75 6e 6e 69 6e 67 20 6f 6e 65 20 6f 72  f running one or
2e40: 20 6d 6f 72 65 0a 2a 2a 20 53 51 4c 20 73 74 61   more.** SQL sta
2e50: 74 65 6d 65 6e 74 73 20 77 69 74 68 6f 75 74 20  tements without 
2e60: 68 61 76 69 6e 67 20 74 6f 20 77 72 69 74 65 20  having to write 
2e70: 61 20 6c 6f 74 20 6f 66 20 43 20 63 6f 64 65 2e  a lot of C code.
2e80: 20 20 54 68 65 20 55 54 46 2d 38 20 65 6e 63 6f    The UTF-8 enco
2e90: 64 65 64 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65  ded.** SQL state
2ea0: 6d 65 6e 74 73 20 61 72 65 20 70 61 73 73 65 64  ments are passed
2eb0: 20 69 6e 20 61 73 20 74 68 65 20 73 65 63 6f 6e   in as the secon
2ec0: 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  d parameter to s
2ed0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 2e 0a 2a  qlite3_exec()..*
2ee0: 2a 20 54 68 65 20 73 74 61 74 65 6d 65 6e 74 73  * The statements
2ef0: 20 61 72 65 20 65 76 61 6c 75 61 74 65 64 20 6f   are evaluated o
2f00: 6e 65 20 62 79 20 6f 6e 65 20 75 6e 74 69 6c 20  ne by one until 
2f10: 65 69 74 68 65 72 20 61 6e 20 65 72 72 6f 72 20  either an error 
2f20: 6f 72 0a 2a 2a 20 61 6e 20 69 6e 74 65 72 72 75  or.** an interru
2f30: 70 74 20 69 73 20 65 6e 63 6f 75 6e 74 65 72 65  pt is encountere
2f40: 64 2c 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 79  d, or until they
2f50: 20 61 72 65 20 61 6c 6c 20 64 6f 6e 65 2e 20 20   are all done.  
2f60: 54 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65  The 3rd paramete
2f70: 72 0a 2a 2a 20 69 73 20 61 6e 20 6f 70 74 69 6f  r.** is an optio
2f80: 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 74 68 61  nal callback tha
2f90: 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 63  t is invoked onc
2fa0: 65 20 66 6f 72 20 65 61 63 68 20 72 6f 77 20 6f  e for each row o
2fb0: 66 20 61 6e 79 20 71 75 65 72 79 0a 2a 2a 20 72  f any query.** r
2fc0: 65 73 75 6c 74 73 20 70 72 6f 64 75 63 65 64 20  esults produced 
2fd0: 62 79 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  by the SQL state
2fe0: 6d 65 6e 74 73 2e 20 20 54 68 65 20 35 74 68 20  ments.  The 5th 
2ff0: 70 61 72 61 6d 65 74 65 72 20 74 65 6c 6c 73 20  parameter tells 
3000: 77 68 65 72 65 0a 2a 2a 20 74 6f 20 77 72 69 74  where.** to writ
3010: 65 20 61 6e 79 20 65 72 72 6f 72 20 6d 65 73 73  e any error mess
3020: 61 67 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ages..**.** The 
3030: 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 70 61  error message pa
3040: 73 73 65 64 20 62 61 63 6b 20 74 68 72 6f 75 67  ssed back throug
3050: 68 20 74 68 65 20 35 74 68 20 70 61 72 61 6d 65  h the 5th parame
3060: 74 65 72 20 69 73 20 68 65 6c 64 0a 2a 2a 20 69  ter is held.** i
3070: 6e 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65  n memory obtaine
3080: 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
3090: 6d 61 6c 6c 6f 63 28 29 5d 2e 20 20 54 6f 20 61  malloc()].  To a
30a0: 76 6f 69 64 20 61 20 6d 65 6d 6f 72 79 20 6c 65  void a memory le
30b0: 61 6b 2c 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 69  ak,.** the calli
30c0: 6e 67 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73  ng application s
30d0: 68 6f 75 6c 64 20 63 61 6c 6c 20 5b 73 71 6c 69  hould call [sqli
30e0: 74 65 33 5f 66 72 65 65 28 29 5d 20 6f 6e 20 61  te3_free()] on a
30f0: 6e 79 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73  ny error.** mess
3100: 61 67 65 20 72 65 74 75 72 6e 65 64 20 74 68 72  age returned thr
3110: 6f 75 67 68 20 74 68 65 20 35 74 68 20 70 61 72  ough the 5th par
3120: 61 6d 65 74 65 72 20 77 68 65 6e 20 69 74 20 68  ameter when it h
3130: 61 73 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e  as finished usin
3140: 67 0a 2a 2a 20 74 68 65 20 65 72 72 6f 72 20 6d  g.** the error m
3150: 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 49 66  essage..**.** If
3160: 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
3170: 6e 74 20 69 6e 20 74 68 65 20 32 6e 64 20 70 61  nt in the 2nd pa
3180: 72 61 6d 65 74 65 72 20 69 73 20 4e 55 4c 4c 20  rameter is NULL 
3190: 6f 72 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69  or an empty stri
31a0: 6e 67 0a 2a 2a 20 6f 72 20 61 20 73 74 72 69 6e  ng.** or a strin
31b0: 67 20 63 6f 6e 74 61 69 6e 69 6e 67 20 6f 6e 6c  g containing onl
31c0: 79 20 77 68 69 74 65 73 70 61 63 65 20 61 6e 64  y whitespace and
31d0: 20 63 6f 6d 6d 65 6e 74 73 2c 20 74 68 65 6e 20   comments, then 
31e0: 6e 6f 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d  no SQL.** statem
31f0: 65 6e 74 73 20 61 72 65 20 65 76 61 6c 75 61 74  ents are evaluat
3200: 65 64 20 61 6e 64 20 74 68 65 20 64 61 74 61 62  ed and the datab
3210: 61 73 65 20 69 73 20 6e 6f 74 20 63 68 61 6e 67  ase is not chang
3220: 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ed..**.** The sq
3230: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 6e 74  lite3_exec() int
3240: 65 72 66 61 63 65 20 69 73 20 69 6d 70 6c 65 6d  erface is implem
3250: 65 6e 74 65 64 20 69 6e 20 74 65 72 6d 73 20 6f  ented in terms o
3260: 66 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  f.** [sqlite3_pr
3270: 65 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71  epare_v2()], [sq
3280: 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 20 61  lite3_step()], a
3290: 6e 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  nd [sqlite3_fina
32a0: 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20 54 68 65 20  lize()]..** The 
32b0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 72  sqlite3_exec() r
32c0: 6f 75 74 69 6e 65 20 64 6f 65 73 20 6e 6f 74 68  outine does noth
32d0: 69 6e 67 20 74 6f 20 74 68 65 20 64 61 74 61 62  ing to the datab
32e0: 61 73 65 20 74 68 61 74 20 63 61 6e 6e 6f 74 20  ase that cannot 
32f0: 62 65 20 64 6f 6e 65 0a 2a 2a 20 62 79 20 5b 73  be done.** by [s
3300: 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
3310: 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73  2()], [sqlite3_s
3320: 74 65 70 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c  tep()], and [sql
3330: 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
3340: 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  ..**.** INVARIAN
3350: 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 31 30  TS:.**.** {H1210
3360: 31 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c 20  1} A successful 
3370: 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73  invocation of [s
3380: 71 6c 69 74 65 33 5f 65 78 65 63 28 44 2c 53 2c  qlite3_exec(D,S,
3390: 43 2c 41 2c 45 29 5d 0a 2a 2a 20 20 20 20 20 20  C,A,E)].**      
33a0: 20 20 20 20 73 68 61 6c 6c 20 73 65 71 75 65 6e      shall sequen
33b0: 74 69 61 6c 6c 79 20 65 76 61 6c 75 61 74 65 20  tially evaluate 
33c0: 61 6c 6c 20 6f 66 20 74 68 65 20 55 54 46 2d 38  all of the UTF-8
33d0: 20 65 6e 63 6f 64 65 64 2c 0a 2a 2a 20 20 20 20   encoded,.**    
33e0: 20 20 20 20 20 20 73 65 6d 69 63 6f 6c 6f 6e 2d        semicolon-
33f0: 73 65 70 61 72 61 74 65 64 20 53 51 4c 20 73 74  separated SQL st
3400: 61 74 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20  atements in the 
3410: 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a  zero-terminated.
3420: 2a 2a 20 20 20 20 20 20 20 20 20 20 73 74 72 69  **          stri
3430: 6e 67 20 53 20 77 69 74 68 69 6e 20 74 68 65 20  ng S within the 
3440: 63 6f 6e 74 65 78 74 20 6f 66 20 74 68 65 20 5b  context of the [
3450: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
3460: 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 48  ion] D..**.** {H
3470: 31 32 31 30 32 7d 20 49 66 20 74 68 65 20 53 20  12102} If the S 
3480: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71  parameter to [sq
3490: 6c 69 74 65 33 5f 65 78 65 63 28 44 2c 53 2c 43  lite3_exec(D,S,C
34a0: 2c 41 2c 45 29 5d 20 69 73 20 4e 55 4c 4c 20 74  ,A,E)] is NULL t
34b0: 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  hen.**          
34c0: 74 68 65 20 61 63 74 69 6f 6e 73 20 6f 66 20 74  the actions of t
34d0: 68 65 20 69 6e 74 65 72 66 61 63 65 20 73 68 61  he interface sha
34e0: 6c 6c 20 62 65 20 74 68 65 20 73 61 6d 65 20 61  ll be the same a
34f0: 73 20 69 66 20 74 68 65 0a 2a 2a 20 20 20 20 20  s if the.**     
3500: 20 20 20 20 20 53 20 70 61 72 61 6d 65 74 65 72       S parameter
3510: 20 77 65 72 65 20 61 6e 20 65 6d 70 74 79 20 73   were an empty s
3520: 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  tring..**.** {H1
3530: 32 31 30 34 7d 20 54 68 65 20 72 65 74 75 72 6e  2104} The return
3540: 20 76 61 6c 75 65 20 6f 66 20 5b 73 71 6c 69 74   value of [sqlit
3550: 65 33 5f 65 78 65 63 28 29 5d 20 73 68 61 6c 6c  e3_exec()] shall
3560: 20 62 65 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20   be [SQLITE_OK] 
3570: 69 66 20 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20  if all.**       
3580: 20 20 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74     SQL statement
3590: 73 20 72 75 6e 20 73 75 63 63 65 73 73 66 75 6c  s run successful
35a0: 6c 79 20 61 6e 64 20 74 6f 20 63 6f 6d 70 6c 65  ly and to comple
35b0: 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  tion..**.** {H12
35c0: 31 30 35 7d 20 54 68 65 20 72 65 74 75 72 6e 20  105} The return 
35d0: 76 61 6c 75 65 20 6f 66 20 5b 73 71 6c 69 74 65  value of [sqlite
35e0: 33 5f 65 78 65 63 28 29 5d 20 73 68 61 6c 6c 20  3_exec()] shall 
35f0: 62 65 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74  be an appropriat
3600: 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 6f  e.**          no
3610: 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f  n-zero [error co
3620: 64 65 5d 20 69 66 20 61 6e 79 20 53 51 4c 20 73  de] if any SQL s
3630: 74 61 74 65 6d 65 6e 74 20 66 61 69 6c 73 2e 0a  tatement fails..
3640: 2a 2a 0a 2a 2a 20 7b 48 31 32 31 30 37 7d 20 49  **.** {H12107} I
3650: 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66  f one or more of
3660: 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
3670: 6e 74 73 20 68 61 6e 64 65 64 20 74 6f 20 5b 73  nts handed to [s
3680: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 0a 2a  qlite3_exec()].*
3690: 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72  *          retur
36a0: 6e 20 72 65 73 75 6c 74 73 20 61 6e 64 20 74 68  n results and th
36b0: 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20  e 3rd parameter 
36c0: 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65  is not NULL, the
36d0: 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  n.**          th
36e0: 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  e callback funct
36f0: 69 6f 6e 20 73 70 65 63 69 66 69 65 64 20 62 79  ion specified by
3700: 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74   the 3rd paramet
3710: 65 72 20 73 68 61 6c 6c 20 62 65 0a 2a 2a 20 20  er shall be.**  
3720: 20 20 20 20 20 20 20 20 69 6e 76 6f 6b 65 64 20          invoked 
3730: 6f 6e 63 65 20 66 6f 72 20 65 61 63 68 20 72 6f  once for each ro
3740: 77 20 6f 66 20 72 65 73 75 6c 74 2e 0a 2a 2a 0a  w of result..**.
3750: 2a 2a 20 7b 48 31 32 31 31 30 7d 20 49 66 20 74  ** {H12110} If t
3760: 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  he callback retu
3770: 72 6e 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 76  rns a non-zero v
3780: 61 6c 75 65 20 74 68 65 6e 20 5b 73 71 6c 69 74  alue then [sqlit
3790: 65 33 5f 65 78 65 63 28 29 5d 0a 2a 2a 20 20 20  e3_exec()].**   
37a0: 20 20 20 20 20 20 20 73 68 61 6c 6c 20 61 62 6f         shall abo
37b0: 72 74 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  rt the SQL state
37c0: 6d 65 6e 74 20 69 74 20 69 73 20 63 75 72 72 65  ment it is curre
37d0: 6e 74 6c 79 20 65 76 61 6c 75 61 74 69 6e 67 2c  ntly evaluating,
37e0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 6b 69  .**          ski
37f0: 70 20 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74  p all subsequent
3800: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2c   SQL statements,
3810: 20 61 6e 64 20 72 65 74 75 72 6e 20 5b 53 51 4c   and return [SQL
3820: 49 54 45 5f 41 42 4f 52 54 5d 2e 0a 2a 2a 0a 2a  ITE_ABORT]..**.*
3830: 2a 20 7b 48 31 32 31 31 33 7d 20 54 68 65 20 5b  * {H12113} The [
3840: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20  sqlite3_exec()] 
3850: 72 6f 75 74 69 6e 65 20 73 68 61 6c 6c 20 70 61  routine shall pa
3860: 73 73 20 69 74 73 20 34 74 68 20 70 61 72 61 6d  ss its 4th param
3870: 65 74 65 72 20 74 68 72 6f 75 67 68 0a 2a 2a 20  eter through.** 
3880: 20 20 20 20 20 20 20 20 20 61 73 20 74 68 65 20           as the 
3890: 31 73 74 20 70 61 72 61 6d 65 74 65 72 20 6f 66  1st parameter of
38a0: 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a   the callback..*
38b0: 2a 0a 2a 2a 20 7b 48 31 32 31 31 36 7d 20 54 68  *.** {H12116} Th
38c0: 65 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28  e [sqlite3_exec(
38d0: 29 5d 20 72 6f 75 74 69 6e 65 20 73 68 61 6c 6c  )] routine shall
38e0: 20 73 65 74 20 74 68 65 20 32 6e 64 20 70 61 72   set the 2nd par
38f0: 61 6d 65 74 65 72 20 6f 66 20 69 74 73 0a 2a 2a  ameter of its.**
3900: 20 20 20 20 20 20 20 20 20 20 63 61 6c 6c 62 61            callba
3910: 63 6b 20 74 6f 20 62 65 20 74 68 65 20 6e 75 6d  ck to be the num
3920: 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
3930: 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 72 6f  n the current ro
3940: 77 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20  w of.**         
3950: 20 72 65 73 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 7b   result..**.** {
3960: 48 31 32 31 31 39 7d 20 54 68 65 20 5b 73 71 6c  H12119} The [sql
3970: 69 74 65 33 5f 65 78 65 63 28 29 5d 20 72 6f 75  ite3_exec()] rou
3980: 74 69 6e 65 20 73 68 61 6c 6c 20 73 65 74 20 74  tine shall set t
3990: 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72  he 3rd parameter
39a0: 20 6f 66 20 69 74 73 0a 2a 2a 20 20 20 20 20 20   of its.**      
39b0: 20 20 20 20 63 61 6c 6c 62 61 63 6b 20 74 6f 20      callback to 
39c0: 62 65 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70  be an array of p
39d0: 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e  ointers to strin
39e0: 67 73 20 68 6f 6c 64 69 6e 67 20 74 68 65 0a 2a  gs holding the.*
39f0: 2a 20 20 20 20 20 20 20 20 20 20 76 61 6c 75 65  *          value
3a00: 73 20 66 6f 72 20 65 61 63 68 20 63 6f 6c 75 6d  s for each colum
3a10: 6e 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74  n in the current
3a20: 20 72 65 73 75 6c 74 20 73 65 74 20 72 6f 77 20   result set row 
3a30: 61 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  as.**          o
3a40: 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71  btained from [sq
3a50: 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
3a60: 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  t()]..**.** {H12
3a70: 31 32 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  122} The [sqlite
3a80: 33 5f 65 78 65 63 28 29 5d 20 72 6f 75 74 69 6e  3_exec()] routin
3a90: 65 20 73 68 61 6c 6c 20 73 65 74 20 74 68 65 20  e shall set the 
3aa0: 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 6f 66  4th parameter of
3ab0: 20 69 74 73 0a 2a 2a 20 20 20 20 20 20 20 20 20   its.**         
3ac0: 20 63 61 6c 6c 62 61 63 6b 20 74 6f 20 62 65 20   callback to be 
3ad0: 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e  an array of poin
3ae0: 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20  ters to strings 
3af0: 68 6f 6c 64 69 6e 67 20 74 68 65 0a 2a 2a 20 20  holding the.**  
3b00: 20 20 20 20 20 20 20 20 6e 61 6d 65 73 20 6f 66          names of
3b10: 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 73 20   result columns 
3b20: 61 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  as obtained from
3b30: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
3b40: 5f 6e 61 6d 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  _name()]..**.** 
3b50: 7b 48 31 32 31 32 35 7d 20 49 66 20 74 68 65 20  {H12125} If the 
3b60: 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  3rd parameter to
3b70: 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29   [sqlite3_exec()
3b80: 5d 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e 0a 2a  ] is NULL then.*
3b90: 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
3ba0: 74 65 33 5f 65 78 65 63 28 29 5d 20 73 68 61 6c  te3_exec()] shal
3bb0: 6c 20 73 69 6c 65 6e 74 6c 79 20 64 69 73 63 61  l silently disca
3bc0: 72 64 20 71 75 65 72 79 20 72 65 73 75 6c 74 73  rd query results
3bd0: 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 31 33 31 7d  ..**.** {H12131}
3be0: 20 49 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63   If an error occ
3bf0: 75 72 73 20 77 68 69 6c 65 20 70 61 72 73 69 6e  urs while parsin
3c00: 67 20 6f 72 20 65 76 61 6c 75 61 74 69 6e 67 20  g or evaluating 
3c10: 61 6e 79 20 6f 66 20 74 68 65 20 53 51 4c 0a 2a  any of the SQL.*
3c20: 2a 20 20 20 20 20 20 20 20 20 20 73 74 61 74 65  *          state
3c30: 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 53 20 70  ments in the S p
3c40: 61 72 61 6d 65 74 65 72 20 6f 66 20 5b 73 71 6c  arameter of [sql
3c50: 69 74 65 33 5f 65 78 65 63 28 44 2c 53 2c 43 2c  ite3_exec(D,S,C,
3c60: 41 2c 45 29 5d 20 61 6e 64 20 69 66 0a 2a 2a 20  A,E)] and if.** 
3c70: 20 20 20 20 20 20 20 20 20 74 68 65 20 45 20 70           the E p
3c80: 61 72 61 6d 65 74 65 72 20 69 73 20 6e 6f 74 20  arameter is not 
3c90: 4e 55 4c 4c 2c 20 74 68 65 6e 20 5b 73 71 6c 69  NULL, then [sqli
3ca0: 74 65 33 5f 65 78 65 63 28 29 5d 20 73 68 61 6c  te3_exec()] shal
3cb0: 6c 20 73 74 6f 72 65 0a 2a 2a 20 20 20 20 20 20  l store.**      
3cc0: 20 20 20 20 69 6e 20 2a 45 20 61 6e 20 61 70 70      in *E an app
3cd0: 72 6f 70 72 69 61 74 65 20 65 72 72 6f 72 20 6d  ropriate error m
3ce0: 65 73 73 61 67 65 20 77 72 69 74 74 65 6e 20 69  essage written i
3cf0: 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69  nto memory obtai
3d00: 6e 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ned.**          
3d10: 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61  from [sqlite3_ma
3d20: 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b  lloc()]..**.** {
3d30: 48 31 32 31 33 34 7d 20 54 68 65 20 5b 73 71 6c  H12134} The [sql
3d40: 69 74 65 33 5f 65 78 65 63 28 44 2c 53 2c 43 2c  ite3_exec(D,S,C,
3d50: 41 2c 45 29 5d 20 72 6f 75 74 69 6e 65 20 73 68  A,E)] routine sh
3d60: 61 6c 6c 20 73 65 74 20 74 68 65 20 76 61 6c 75  all set the valu
3d70: 65 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20  e of.**         
3d80: 20 2a 45 20 74 6f 20 4e 55 4c 4c 20 69 66 20 45   *E to NULL if E
3d90: 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64   is not NULL and
3da0: 20 74 68 65 72 65 20 61 72 65 20 6e 6f 20 65 72   there are no er
3db0: 72 6f 72 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  rors..**.** {H12
3dc0: 31 33 37 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  137} The [sqlite
3dd0: 33 5f 65 78 65 63 28 44 2c 53 2c 43 2c 41 2c 45  3_exec(D,S,C,A,E
3de0: 29 5d 20 66 75 6e 63 74 69 6f 6e 20 73 68 61 6c  )] function shal
3df0: 6c 20 73 65 74 20 74 68 65 20 5b 65 72 72 6f 72  l set the [error
3e00: 20 63 6f 64 65 5d 0a 2a 2a 20 20 20 20 20 20 20   code].**       
3e10: 20 20 20 61 6e 64 20 6d 65 73 73 61 67 65 20 61     and message a
3e20: 63 63 65 73 73 69 62 6c 65 20 76 69 61 20 5b 73  ccessible via [s
3e30: 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29  qlite3_errcode()
3e40: 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  ],.**          [
3e50: 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29  sqlite3_errmsg()
3e60: 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ], and [sqlite3_
3e70: 65 72 72 6d 73 67 31 36 28 29 5d 2e 0a 2a 2a 0a  errmsg16()]..**.
3e80: 2a 2a 20 7b 48 31 32 31 33 38 7d 20 49 66 20 74  ** {H12138} If t
3e90: 68 65 20 53 20 70 61 72 61 6d 65 74 65 72 20 74  he S parameter t
3ea0: 6f 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28  o [sqlite3_exec(
3eb0: 44 2c 53 2c 43 2c 41 2c 45 29 5d 20 69 73 20 4e  D,S,C,A,E)] is N
3ec0: 55 4c 4c 20 6f 72 20 61 6e 0a 2a 2a 20 20 20 20  ULL or an.**    
3ed0: 20 20 20 20 20 20 65 6d 70 74 79 20 73 74 72 69        empty stri
3ee0: 6e 67 20 6f 72 20 63 6f 6e 74 61 69 6e 73 20 6e  ng or contains n
3ef0: 6f 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61  othing other tha
3f00: 6e 20 77 68 69 74 65 73 70 61 63 65 2c 20 63 6f  n whitespace, co
3f10: 6d 6d 65 6e 74 73 2c 0a 2a 2a 20 20 20 20 20 20  mments,.**      
3f20: 20 20 20 20 61 6e 64 2f 6f 72 20 73 65 6d 69 63      and/or semic
3f30: 6f 6c 6f 6e 73 2c 20 74 68 65 6e 20 72 65 73 75  olons, then resu
3f40: 6c 74 73 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f  lts of [sqlite3_
3f50: 65 72 72 63 6f 64 65 28 29 5d 2c 0a 2a 2a 20 20  errcode()],.**  
3f60: 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
3f70: 5f 65 72 72 6d 73 67 28 29 5d 2c 20 61 6e 64 20  _errmsg()], and 
3f80: 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31  [sqlite3_errmsg1
3f90: 36 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  6()].**         
3fa0: 20 73 68 61 6c 6c 20 72 65 73 65 74 20 74 6f 20   shall reset to 
3fb0: 69 6e 64 69 63 61 74 65 20 6e 6f 20 65 72 72 6f  indicate no erro
3fc0: 72 73 2e 0a 2a 2a 0a 2a 2a 20 41 53 53 55 4d 50  rs..**.** ASSUMP
3fd0: 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 41 31  TIONS:.**.** {A1
3fe0: 32 31 34 31 7d 20 54 68 65 20 66 69 72 73 74 20  2141} The first 
3ff0: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71  parameter to [sq
4000: 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 6d 75  lite3_exec()] mu
4010: 73 74 20 62 65 20 61 6e 20 76 61 6c 69 64 20 61  st be an valid a
4020: 6e 64 20 6f 70 65 6e 0a 2a 2a 20 20 20 20 20 20  nd open.**      
4030: 20 20 20 20 5b 64 61 74 61 62 61 73 65 20 63 6f      [database co
4040: 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a  nnection]..**.**
4050: 20 7b 41 31 32 31 34 32 7d 20 54 68 65 20 64 61   {A12142} The da
4060: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
4070: 6e 20 6d 75 73 74 20 6e 6f 74 20 62 65 20 63 6c  n must not be cl
4080: 6f 73 65 64 20 77 68 69 6c 65 0a 2a 2a 20 20 20  osed while.**   
4090: 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
40a0: 65 78 65 63 28 29 5d 20 69 73 20 72 75 6e 6e 69  exec()] is runni
40b0: 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 41 31 32 31 34  ng..**.** {A1214
40c0: 33 7d 20 54 68 65 20 63 61 6c 6c 69 6e 67 20 66  3} The calling f
40d0: 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75  unction should u
40e0: 73 65 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  se [sqlite3_free
40f0: 28 29 5d 20 74 6f 20 66 72 65 65 0a 2a 2a 20 20  ()] to free.**  
4100: 20 20 20 20 20 20 20 20 74 68 65 20 6d 65 6d 6f          the memo
4110: 72 79 20 74 68 61 74 20 2a 65 72 72 6d 73 67 20  ry that *errmsg 
4120: 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67  is left pointing
4130: 20 61 74 20 6f 6e 63 65 20 74 68 65 20 65 72 72   at once the err
4140: 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d  or.**          m
4150: 65 73 73 61 67 65 20 69 73 20 6e 6f 20 6c 6f 6e  essage is no lon
4160: 67 65 72 20 6e 65 65 64 65 64 2e 0a 2a 2a 0a 2a  ger needed..**.*
4170: 2a 20 7b 41 31 32 31 34 35 7d 20 54 68 65 20 53  * {A12145} The S
4180: 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78  QL statement tex
4190: 74 20 69 6e 20 74 68 65 20 32 6e 64 20 70 61 72  t in the 2nd par
41a0: 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74  ameter to [sqlit
41b0: 65 33 5f 65 78 65 63 28 29 5d 0a 2a 2a 20 20 20  e3_exec()].**   
41c0: 20 20 20 20 20 20 20 6d 75 73 74 20 72 65 6d 61         must rema
41d0: 69 6e 20 75 6e 63 68 61 6e 67 65 64 20 77 68 69  in unchanged whi
41e0: 6c 65 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63  le [sqlite3_exec
41f0: 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a  ()] is running..
4200: 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65  */.int sqlite3_e
4210: 78 65 63 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c  xec(.  sqlite3*,
4220: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4230: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4240: 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74    /* An open dat
4250: 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  abase */.  const
4260: 20 63 68 61 72 20 2a 73 71 6c 2c 20 20 20 20 20   char *sql,     
4270: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4280: 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20        /* SQL to 
4290: 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a  be evaluated */.
42a0: 20 20 69 6e 74 20 28 2a 63 61 6c 6c 62 61 63 6b    int (*callback
42b0: 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 72  )(void*,int,char
42c0: 2a 2a 2c 63 68 61 72 2a 2a 29 2c 20 20 2f 2a 20  **,char**),  /* 
42d0: 43 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  Callback functio
42e0: 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 2c 20 20  n */.  void *,  
42f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4300: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4310: 20 20 2f 2a 20 31 73 74 20 61 72 67 75 6d 65 6e    /* 1st argumen
4320: 74 20 74 6f 20 63 61 6c 6c 62 61 63 6b 20 2a 2f  t to callback */
4330: 0a 20 20 63 68 61 72 20 2a 2a 65 72 72 6d 73 67  .  char **errmsg
4340: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4350: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
4360: 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74 74   Error msg writt
4370: 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 0a 2f  en here */.);../
4380: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
4390: 65 73 75 6c 74 20 43 6f 64 65 73 20 7b 48 31 30  esult Codes {H10
43a0: 32 31 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 2a  210} <S10700>.**
43b0: 20 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c 49 54   KEYWORDS: SQLIT
43c0: 45 5f 4f 4b 20 7b 65 72 72 6f 72 20 63 6f 64 65  E_OK {error code
43d0: 7d 20 7b 65 72 72 6f 72 20 63 6f 64 65 73 7d 0a  } {error codes}.
43e0: 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 72 65  ** KEYWORDS: {re
43f0: 73 75 6c 74 20 63 6f 64 65 7d 20 7b 72 65 73 75  sult code} {resu
4400: 6c 74 20 63 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a 20  lt codes}.**.** 
4410: 4d 61 6e 79 20 53 51 4c 69 74 65 20 66 75 6e 63  Many SQLite func
4420: 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 61 6e 20  tions return an 
4430: 69 6e 74 65 67 65 72 20 72 65 73 75 6c 74 20 63  integer result c
4440: 6f 64 65 20 66 72 6f 6d 20 74 68 65 20 73 65 74  ode from the set
4450: 20 73 68 6f 77 6e 0a 2a 2a 20 68 65 72 65 20 69   shown.** here i
4460: 6e 20 6f 72 64 65 72 20 74 6f 20 69 6e 64 69 63  n order to indic
4470: 61 74 65 73 20 73 75 63 63 65 73 73 20 6f 72 20  ates success or 
4480: 66 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 4e  failure..**.** N
4490: 65 77 20 65 72 72 6f 72 20 63 6f 64 65 73 20 6d  ew error codes m
44a0: 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66  ay be added in f
44b0: 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f  uture versions o
44c0: 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20  f SQLite..**.** 
44d0: 53 65 65 20 61 6c 73 6f 3a 20 5b 53 51 4c 49 54  See also: [SQLIT
44e0: 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 7c 20 65  E_IOERR_READ | e
44f0: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
4500: 6f 64 65 73 5d 0a 2a 2f 0a 23 64 65 66 69 6e 65  odes].*/.#define
4510: 20 53 51 4c 49 54 45 5f 4f 4b 20 20 20 20 20 20   SQLITE_OK      
4520: 20 20 20 20 20 30 20 20 20 2f 2a 20 53 75 63 63       0   /* Succ
4530: 65 73 73 66 75 6c 20 72 65 73 75 6c 74 20 2a 2f  essful result */
4540: 0a 2f 2a 20 62 65 67 69 6e 6e 69 6e 67 2d 6f 66  ./* beginning-of
4550: 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a  -error-codes */.
4560: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45  #define SQLITE_E
4570: 52 52 4f 52 20 20 20 20 20 20 20 20 31 20 20 20  RROR        1   
4580: 2f 2a 20 53 51 4c 20 65 72 72 6f 72 20 6f 72 20  /* SQL error or 
4590: 6d 69 73 73 69 6e 67 20 64 61 74 61 62 61 73 65  missing database
45a0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
45b0: 54 45 5f 49 4e 54 45 52 4e 41 4c 20 20 20 20 20  TE_INTERNAL     
45c0: 32 20 20 20 2f 2a 20 49 6e 74 65 72 6e 61 6c 20  2   /* Internal 
45d0: 6c 6f 67 69 63 20 65 72 72 6f 72 20 69 6e 20 53  logic error in S
45e0: 51 4c 69 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65  QLite */.#define
45f0: 20 53 51 4c 49 54 45 5f 50 45 52 4d 20 20 20 20   SQLITE_PERM    
4600: 20 20 20 20 20 33 20 20 20 2f 2a 20 41 63 63 65       3   /* Acce
4610: 73 73 20 70 65 72 6d 69 73 73 69 6f 6e 20 64 65  ss permission de
4620: 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  nied */.#define 
4630: 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 20 20 20  SQLITE_ABORT    
4640: 20 20 20 20 34 20 20 20 2f 2a 20 43 61 6c 6c 62      4   /* Callb
4650: 61 63 6b 20 72 6f 75 74 69 6e 65 20 72 65 71 75  ack routine requ
4660: 65 73 74 65 64 20 61 6e 20 61 62 6f 72 74 20 2a  ested an abort *
4670: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4680: 5f 42 55 53 59 20 20 20 20 20 20 20 20 20 35 20  _BUSY         5 
4690: 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73    /* The databas
46a0: 65 20 66 69 6c 65 20 69 73 20 6c 6f 63 6b 65 64  e file is locked
46b0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
46c0: 54 45 5f 4c 4f 43 4b 45 44 20 20 20 20 20 20 20  TE_LOCKED       
46d0: 36 20 20 20 2f 2a 20 41 20 74 61 62 6c 65 20 69  6   /* A table i
46e0: 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69  n the database i
46f0: 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66  s locked */.#def
4700: 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d  ine SQLITE_NOMEM
4710: 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 41          7   /* A
4720: 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 65 64   malloc() failed
4730: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4740: 54 45 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20  TE_READONLY     
4750: 38 20 20 20 2f 2a 20 41 74 74 65 6d 70 74 20 74  8   /* Attempt t
4760: 6f 20 77 72 69 74 65 20 61 20 72 65 61 64 6f 6e  o write a readon
4770: 6c 79 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23  ly database */.#
4780: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e  define SQLITE_IN
4790: 54 45 52 52 55 50 54 20 20 20 20 39 20 20 20 2f  TERRUPT    9   /
47a0: 2a 20 4f 70 65 72 61 74 69 6f 6e 20 74 65 72 6d  * Operation term
47b0: 69 6e 61 74 65 64 20 62 79 20 73 71 6c 69 74 65  inated by sqlite
47c0: 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2a 2f 0a  3_interrupt()*/.
47d0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
47e0: 4f 45 52 52 20 20 20 20 20 20 20 31 30 20 20 20  OERR       10   
47f0: 2f 2a 20 53 6f 6d 65 20 6b 69 6e 64 20 6f 66 20  /* Some kind of 
4800: 64 69 73 6b 20 49 2f 4f 20 65 72 72 6f 72 20 6f  disk I/O error o
4810: 63 63 75 72 72 65 64 20 2a 2f 0a 23 64 65 66 69  ccurred */.#defi
4820: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 50  ne SQLITE_CORRUP
4830: 54 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54 68  T     11   /* Th
4840: 65 20 64 61 74 61 62 61 73 65 20 64 69 73 6b 20  e database disk 
4850: 69 6d 61 67 65 20 69 73 20 6d 61 6c 66 6f 72 6d  image is malform
4860: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
4870: 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 20 20  LITE_NOTFOUND   
4880: 20 31 32 20 20 20 2f 2a 20 4e 4f 54 20 55 53 45   12   /* NOT USE
4890: 44 2e 20 54 61 62 6c 65 20 6f 72 20 72 65 63 6f  D. Table or reco
48a0: 72 64 20 6e 6f 74 20 66 6f 75 6e 64 20 2a 2f 0a  rd not found */.
48b0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
48c0: 55 4c 4c 20 20 20 20 20 20 20 20 31 33 20 20 20  ULL        13   
48d0: 2f 2a 20 49 6e 73 65 72 74 69 6f 6e 20 66 61 69  /* Insertion fai
48e0: 6c 65 64 20 62 65 63 61 75 73 65 20 64 61 74 61  led because data
48f0: 62 61 73 65 20 69 73 20 66 75 6c 6c 20 2a 2f 0a  base is full */.
4900: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
4910: 41 4e 54 4f 50 45 4e 20 20 20 20 31 34 20 20 20  ANTOPEN    14   
4920: 2f 2a 20 55 6e 61 62 6c 65 20 74 6f 20 6f 70 65  /* Unable to ope
4930: 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  n the database f
4940: 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ile */.#define S
4950: 51 4c 49 54 45 5f 50 52 4f 54 4f 43 4f 4c 20 20  QLITE_PROTOCOL  
4960: 20 20 31 35 20 20 20 2f 2a 20 4e 4f 54 20 55 53    15   /* NOT US
4970: 45 44 2e 20 44 61 74 61 62 61 73 65 20 6c 6f 63  ED. Database loc
4980: 6b 20 70 72 6f 74 6f 63 6f 6c 20 65 72 72 6f 72  k protocol error
4990: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
49a0: 54 45 5f 45 4d 50 54 59 20 20 20 20 20 20 20 31  TE_EMPTY       1
49b0: 36 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20  6   /* Database 
49c0: 69 73 20 65 6d 70 74 79 20 2a 2f 0a 23 64 65 66  is empty */.#def
49d0: 69 6e 65 20 53 51 4c 49 54 45 5f 53 43 48 45 4d  ine SQLITE_SCHEM
49e0: 41 20 20 20 20 20 20 31 37 20 20 20 2f 2a 20 54  A      17   /* T
49f0: 68 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65  he database sche
4a00: 6d 61 20 63 68 61 6e 67 65 64 20 2a 2f 0a 23 64  ma changed */.#d
4a10: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 4f 4f  efine SQLITE_TOO
4a20: 42 49 47 20 20 20 20 20 20 31 38 20 20 20 2f 2a  BIG      18   /*
4a30: 20 53 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20   String or BLOB 
4a40: 65 78 63 65 65 64 73 20 73 69 7a 65 20 6c 69 6d  exceeds size lim
4a50: 69 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  it */.#define SQ
4a60: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20  LITE_CONSTRAINT 
4a70: 20 31 39 20 20 20 2f 2a 20 41 62 6f 72 74 20 64   19   /* Abort d
4a80: 75 65 20 74 6f 20 63 6f 6e 73 74 72 61 69 6e 74  ue to constraint
4a90: 20 76 69 6f 6c 61 74 69 6f 6e 20 2a 2f 0a 23 64   violation */.#d
4aa0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53  efine SQLITE_MIS
4ab0: 4d 41 54 43 48 20 20 20 20 32 30 20 20 20 2f 2a  MATCH    20   /*
4ac0: 20 44 61 74 61 20 74 79 70 65 20 6d 69 73 6d 61   Data type misma
4ad0: 74 63 68 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  tch */.#define S
4ae0: 51 4c 49 54 45 5f 4d 49 53 55 53 45 20 20 20 20  QLITE_MISUSE    
4af0: 20 20 32 31 20 20 20 2f 2a 20 4c 69 62 72 61 72    21   /* Librar
4b00: 79 20 75 73 65 64 20 69 6e 63 6f 72 72 65 63 74  y used incorrect
4b10: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ly */.#define SQ
4b20: 4c 49 54 45 5f 4e 4f 4c 46 53 20 20 20 20 20 20  LITE_NOLFS      
4b30: 20 32 32 20 20 20 2f 2a 20 55 73 65 73 20 4f 53   22   /* Uses OS
4b40: 20 66 65 61 74 75 72 65 73 20 6e 6f 74 20 73 75   features not su
4b50: 70 70 6f 72 74 65 64 20 6f 6e 20 68 6f 73 74 20  pported on host 
4b60: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4b70: 45 5f 41 55 54 48 20 20 20 20 20 20 20 20 32 33  E_AUTH        23
4b80: 20 20 20 2f 2a 20 41 75 74 68 6f 72 69 7a 61 74     /* Authorizat
4b90: 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f 0a 23 64  ion denied */.#d
4ba0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 4f 52  efine SQLITE_FOR
4bb0: 4d 41 54 20 20 20 20 20 20 32 34 20 20 20 2f 2a  MAT      24   /*
4bc0: 20 41 75 78 69 6c 69 61 72 79 20 64 61 74 61 62   Auxiliary datab
4bd0: 61 73 65 20 66 6f 72 6d 61 74 20 65 72 72 6f 72  ase format error
4be0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4bf0: 54 45 5f 52 41 4e 47 45 20 20 20 20 20 20 20 32  TE_RANGE       2
4c00: 35 20 20 20 2f 2a 20 32 6e 64 20 70 61 72 61 6d  5   /* 2nd param
4c10: 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
4c20: 62 69 6e 64 20 6f 75 74 20 6f 66 20 72 61 6e 67  bind out of rang
4c30: 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  e */.#define SQL
4c40: 49 54 45 5f 4e 4f 54 41 44 42 20 20 20 20 20 20  ITE_NOTADB      
4c50: 32 36 20 20 20 2f 2a 20 46 69 6c 65 20 6f 70 65  26   /* File ope
4c60: 6e 65 64 20 74 68 61 74 20 69 73 20 6e 6f 74 20  ned that is not 
4c70: 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  a database file 
4c80: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4c90: 45 5f 52 4f 57 20 20 20 20 20 20 20 20 20 31 30  E_ROW         10
4ca0: 30 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74  0  /* sqlite3_st
4cb0: 65 70 28 29 20 68 61 73 20 61 6e 6f 74 68 65 72  ep() has another
4cc0: 20 72 6f 77 20 72 65 61 64 79 20 2a 2f 0a 23 64   row ready */.#d
4cd0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 4f 4e  efine SQLITE_DON
4ce0: 45 20 20 20 20 20 20 20 20 31 30 31 20 20 2f 2a  E        101  /*
4cf0: 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
4d00: 68 61 73 20 66 69 6e 69 73 68 65 64 20 65 78 65  has finished exe
4d10: 63 75 74 69 6e 67 20 2a 2f 0a 2f 2a 20 65 6e 64  cuting */./* end
4d20: 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20  -of-error-codes 
4d30: 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  */../*.** CAPI3R
4d40: 45 46 3a 20 45 78 74 65 6e 64 65 64 20 52 65 73  EF: Extended Res
4d50: 75 6c 74 20 43 6f 64 65 73 20 7b 48 31 30 32 32  ult Codes {H1022
4d60: 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 2a 20 4b  0} <S10700>.** K
4d70: 45 59 57 4f 52 44 53 3a 20 7b 65 78 74 65 6e 64  EYWORDS: {extend
4d80: 65 64 20 65 72 72 6f 72 20 63 6f 64 65 7d 20 7b  ed error code} {
4d90: 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63  extended error c
4da0: 6f 64 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44  odes}.** KEYWORD
4db0: 53 3a 20 7b 65 78 74 65 6e 64 65 64 20 72 65 73  S: {extended res
4dc0: 75 6c 74 20 63 6f 64 65 7d 20 7b 65 78 74 65 6e  ult code} {exten
4dd0: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
4de0: 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20 69 74 73 20 64  }.**.** In its d
4df0: 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61  efault configura
4e00: 74 69 6f 6e 2c 20 53 51 4c 69 74 65 20 41 50 49  tion, SQLite API
4e10: 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
4e20: 20 6f 6e 65 20 6f 66 20 32 36 20 69 6e 74 65 67   one of 26 integ
4e30: 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b  er.** [SQLITE_OK
4e40: 20 7c 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d   | result codes]
4e50: 2e 20 20 48 6f 77 65 76 65 72 2c 20 65 78 70 65  .  However, expe
4e60: 72 69 65 6e 63 65 20 68 61 73 20 73 68 6f 77 6e  rience has shown
4e70: 20 74 68 61 74 20 6d 61 6e 79 20 6f 66 0a 2a 2a   that many of.**
4e80: 20 74 68 65 73 65 20 72 65 73 75 6c 74 20 63 6f   these result co
4e90: 64 65 73 20 61 72 65 20 74 6f 6f 20 63 6f 61 72  des are too coar
4ea0: 73 65 2d 67 72 61 69 6e 65 64 2e 20 20 54 68 65  se-grained.  The
4eb0: 79 20 64 6f 20 6e 6f 74 20 70 72 6f 76 69 64 65  y do not provide
4ec0: 20 61 73 0a 2a 2a 20 6d 75 63 68 20 69 6e 66 6f   as.** much info
4ed0: 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 70 72  rmation about pr
4ee0: 6f 62 6c 65 6d 73 20 61 73 20 70 72 6f 67 72 61  oblems as progra
4ef0: 6d 6d 65 72 73 20 6d 69 67 68 74 20 6c 69 6b 65  mmers might like
4f00: 2e 20 20 49 6e 20 61 6e 20 65 66 66 6f 72 74 20  .  In an effort 
4f10: 74 6f 0a 2a 2a 20 61 64 64 72 65 73 73 20 74 68  to.** address th
4f20: 69 73 2c 20 6e 65 77 65 72 20 76 65 72 73 69 6f  is, newer versio
4f30: 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 28 76 65  ns of SQLite (ve
4f40: 72 73 69 6f 6e 20 33 2e 33 2e 38 20 61 6e 64 20  rsion 3.3.8 and 
4f50: 6c 61 74 65 72 29 20 69 6e 63 6c 75 64 65 0a 2a  later) include.*
4f60: 2a 20 73 75 70 70 6f 72 74 20 66 6f 72 20 61 64  * support for ad
4f70: 64 69 74 69 6f 6e 61 6c 20 72 65 73 75 6c 74 20  ditional result 
4f80: 63 6f 64 65 73 20 74 68 61 74 20 70 72 6f 76 69  codes that provi
4f90: 64 65 20 6d 6f 72 65 20 64 65 74 61 69 6c 65 64  de more detailed
4fa0: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20   information.** 
4fb0: 61 62 6f 75 74 20 65 72 72 6f 72 73 2e 20 54 68  about errors. Th
4fc0: 65 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c  e extended resul
4fd0: 74 20 63 6f 64 65 73 20 61 72 65 20 65 6e 61 62  t codes are enab
4fe0: 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64 0a  led or disabled.
4ff0: 2a 2a 20 6f 6e 20 61 20 70 65 72 20 64 61 74 61  ** on a per data
5000: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
5010: 62 61 73 69 73 20 75 73 69 6e 67 20 74 68 65 0a  basis using the.
5020: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 74 65  ** [sqlite3_exte
5030: 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65  nded_result_code
5040: 73 28 29 5d 20 41 50 49 2e 0a 2a 2a 0a 2a 2a 20  s()] API..**.** 
5050: 53 6f 6d 65 20 6f 66 20 74 68 65 20 61 76 61 69  Some of the avai
5060: 6c 61 62 6c 65 20 65 78 74 65 6e 64 65 64 20 72  lable extended r
5070: 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 20  esult codes are 
5080: 6c 69 73 74 65 64 20 68 65 72 65 2e 0a 2a 2a 20  listed here..** 
5090: 4f 6e 65 20 6d 61 79 20 65 78 70 65 63 74 20 74  One may expect t
50a0: 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 65 78 74  he number of ext
50b0: 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
50c0: 65 73 20 77 69 6c 6c 20 62 65 20 65 78 70 61 6e  es will be expan
50d0: 64 0a 2a 2a 20 6f 76 65 72 20 74 69 6d 65 2e 20  d.** over time. 
50e0: 20 53 6f 66 74 77 61 72 65 20 74 68 61 74 20 75   Software that u
50f0: 73 65 73 20 65 78 74 65 6e 64 65 64 20 72 65 73  ses extended res
5100: 75 6c 74 20 63 6f 64 65 73 20 73 68 6f 75 6c 64  ult codes should
5110: 20 65 78 70 65 63 74 0a 2a 2a 20 74 6f 20 73 65   expect.** to se
5120: 65 20 6e 65 77 20 72 65 73 75 6c 74 20 63 6f 64  e new result cod
5130: 65 73 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c  es in future rel
5140: 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e  eases of SQLite.
5150: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54  .**.** The SQLIT
5160: 45 5f 4f 4b 20 72 65 73 75 6c 74 20 63 6f 64 65  E_OK result code
5170: 20 77 69 6c 6c 20 6e 65 76 65 72 20 62 65 20 65   will never be e
5180: 78 74 65 6e 64 65 64 2e 20 20 49 74 20 77 69 6c  xtended.  It wil
5190: 6c 20 61 6c 77 61 79 73 0a 2a 2a 20 62 65 20 65  l always.** be e
51a0: 78 61 63 74 6c 79 20 7a 65 72 6f 2e 0a 2a 2a 0a  xactly zero..**.
51b0: 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
51c0: 2a 0a 2a 2a 20 7b 48 31 30 32 32 33 7d 20 54 68  *.** {H10223} Th
51d0: 65 20 73 79 6d 62 6f 6c 69 63 20 6e 61 6d 65 20  e symbolic name 
51e0: 66 6f 72 20 61 6e 20 65 78 74 65 6e 64 65 64 20  for an extended 
51f0: 72 65 73 75 6c 74 20 63 6f 64 65 20 73 68 61 6c  result code shal
5200: 6c 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 20 20  l contains.**   
5210: 20 20 20 20 20 20 20 61 20 72 65 6c 61 74 65 64         a related
5220: 20 70 72 69 6d 61 72 79 20 72 65 73 75 6c 74 20   primary result 
5230: 63 6f 64 65 20 61 73 20 61 20 70 72 65 66 69 78  code as a prefix
5240: 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 32 32 34 7d  ..**.** {H10224}
5250: 20 50 72 69 6d 61 72 79 20 72 65 73 75 6c 74 20   Primary result 
5260: 63 6f 64 65 20 6e 61 6d 65 73 20 73 68 61 6c 6c  code names shall
5270: 20 63 6f 6e 74 61 69 6e 20 61 20 73 69 6e 67 6c   contain a singl
5280: 65 20 22 5f 22 20 63 68 61 72 61 63 74 65 72 2e  e "_" character.
5290: 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 32 32 35 7d 20  .**.** {H10225} 
52a0: 45 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  Extended result 
52b0: 63 6f 64 65 20 6e 61 6d 65 73 20 73 68 61 6c 6c  code names shall
52c0: 20 63 6f 6e 74 61 69 6e 20 74 77 6f 20 6f 72 20   contain two or 
52d0: 6d 6f 72 65 20 22 5f 22 20 63 68 61 72 61 63 74  more "_" charact
52e0: 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 32  ers..**.** {H102
52f0: 32 36 7d 20 54 68 65 20 6e 75 6d 65 72 69 63 20  26} The numeric 
5300: 76 61 6c 75 65 20 6f 66 20 61 6e 20 65 78 74 65  value of an exte
5310: 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
5320: 20 73 68 61 6c 6c 20 63 6f 6e 74 61 69 6e 20 74   shall contain t
5330: 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e  he.**          n
5340: 75 6d 65 72 69 63 20 76 61 6c 75 65 20 6f 66 20  umeric value of 
5350: 69 74 73 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  its correspondin
5360: 67 20 70 72 69 6d 61 72 79 20 72 65 73 75 6c 74  g primary result
5370: 20 63 6f 64 65 20 69 6e 0a 2a 2a 20 20 20 20 20   code in.**     
5380: 20 20 20 20 20 69 74 73 20 6c 65 61 73 74 20 73       its least s
5390: 69 67 6e 69 66 69 63 61 6e 74 20 38 20 62 69 74  ignificant 8 bit
53a0: 73 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  s..*/.#define SQ
53b0: 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20  LITE_IOERR_READ 
53c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51               (SQ
53d0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 3c  LITE_IOERR | (1<
53e0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
53f0: 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f  ITE_IOERR_SHORT_
5400: 52 45 41 44 20 20 20 20 20 20 20 20 28 53 51 4c  READ        (SQL
5410: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 3c 3c  ITE_IOERR | (2<<
5420: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5430: 54 45 5f 49 4f 45 52 52 5f 57 52 49 54 45 20 20  TE_IOERR_WRITE  
5440: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
5450: 54 45 5f 49 4f 45 52 52 20 7c 20 28 33 3c 3c 38  TE_IOERR | (3<<8
5460: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5470: 45 5f 49 4f 45 52 52 5f 46 53 59 4e 43 20 20 20  E_IOERR_FSYNC   
5480: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5490: 45 5f 49 4f 45 52 52 20 7c 20 28 34 3c 3c 38 29  E_IOERR | (4<<8)
54a0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
54b0: 5f 49 4f 45 52 52 5f 44 49 52 5f 46 53 59 4e 43  _IOERR_DIR_FSYNC
54c0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
54d0: 5f 49 4f 45 52 52 20 7c 20 28 35 3c 3c 38 29 29  _IOERR | (5<<8))
54e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
54f0: 49 4f 45 52 52 5f 54 52 55 4e 43 41 54 45 20 20  IOERR_TRUNCATE  
5500: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5510: 49 4f 45 52 52 20 7c 20 28 36 3c 3c 38 29 29 0a  IOERR | (6<<8)).
5520: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
5530: 4f 45 52 52 5f 46 53 54 41 54 20 20 20 20 20 20  OERR_FSTAT      
5540: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
5550: 4f 45 52 52 20 7c 20 28 37 3c 3c 38 29 29 0a 23  OERR | (7<<8)).#
5560: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5570: 45 52 52 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20  ERR_UNLOCK      
5580: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5590: 45 52 52 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64  ERR | (8<<8)).#d
55a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
55b0: 52 52 5f 52 44 4c 4f 43 4b 20 20 20 20 20 20 20  RR_RDLOCK       
55c0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
55d0: 52 52 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65  RR | (9<<8)).#de
55e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
55f0: 52 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 20  R_DELETE        
5600: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
5610: 52 20 7c 20 28 31 30 3c 3c 38 29 29 0a 23 64 65  R | (10<<8)).#de
5620: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
5630: 52 5f 42 4c 4f 43 4b 45 44 20 20 20 20 20 20 20  R_BLOCKED       
5640: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
5650: 52 20 7c 20 28 31 31 3c 3c 38 29 29 0a 23 64 65  R | (11<<8)).#de
5660: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
5670: 52 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 20  R_NOMEM         
5680: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
5690: 52 20 7c 20 28 31 32 3c 3c 38 29 29 0a 23 64 65  R | (12<<8)).#de
56a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
56b0: 52 5f 41 43 43 45 53 53 20 20 20 20 20 20 20 20  R_ACCESS        
56c0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
56d0: 52 20 7c 20 28 31 33 3c 3c 38 29 29 0a 23 64 65  R | (13<<8)).#de
56e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
56f0: 52 5f 43 48 45 43 4b 52 45 53 45 52 56 45 44 4c  R_CHECKRESERVEDL
5700: 4f 43 4b 20 28 53 51 4c 49 54 45 5f 49 4f 45 52  OCK (SQLITE_IOER
5710: 52 20 7c 20 28 31 34 3c 3c 38 29 29 0a 23 64 65  R | (14<<8)).#de
5720: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
5730: 52 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20  R_LOCK          
5740: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
5750: 52 20 7c 20 28 31 35 3c 3c 38 29 29 0a 0a 2f 2a  R | (15<<8))../*
5760: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c  .** CAPI3REF: Fl
5770: 61 67 73 20 46 6f 72 20 46 69 6c 65 20 4f 70 65  ags For File Ope
5780: 6e 20 4f 70 65 72 61 74 69 6f 6e 73 20 7b 48 31  n Operations {H1
5790: 30 32 33 30 7d 20 3c 48 31 31 31 32 30 3e 20 3c  0230} <H11120> <
57a0: 48 31 32 37 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68  H12700>.**.** Th
57b0: 65 73 65 20 62 69 74 20 76 61 6c 75 65 73 20 61  ese bit values a
57c0: 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20  re intended for 
57d0: 75 73 65 20 69 6e 20 74 68 65 0a 2a 2a 20 33 72  use in the.** 3r
57e0: 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  d parameter to t
57f0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  he [sqlite3_open
5800: 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65  _v2()] interface
5810: 20 61 6e 64 0a 2a 2a 20 69 6e 20 74 68 65 20 34   and.** in the 4
5820: 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
5830: 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64  the xOpen method
5840: 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69   of the.** [sqli
5850: 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e  te3_vfs] object.
5860: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
5870: 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59  TE_OPEN_READONLY
5880: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
5890: 30 30 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  001.#define SQLI
58a0: 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54  TE_OPEN_READWRIT
58b0: 45 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30  E        0x00000
58c0: 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  002.#define SQLI
58d0: 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 20 20  TE_OPEN_CREATE  
58e0: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
58f0: 30 30 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  004.#define SQLI
5900: 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e  TE_OPEN_DELETEON
5910: 43 4c 4f 53 45 20 20 20 20 30 78 30 30 30 30 30  CLOSE    0x00000
5920: 30 30 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  008.#define SQLI
5930: 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56  TE_OPEN_EXCLUSIV
5940: 45 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30  E        0x00000
5950: 30 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  010.#define SQLI
5960: 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 20  TE_OPEN_MAIN_DB 
5970: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
5980: 31 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  100.#define SQLI
5990: 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 20  TE_OPEN_TEMP_DB 
59a0: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
59b0: 32 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  200.#define SQLI
59c0: 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e  TE_OPEN_TRANSIEN
59d0: 54 5f 44 42 20 20 20 20 20 30 78 30 30 30 30 30  T_DB     0x00000
59e0: 34 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  400.#define SQLI
59f0: 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55  TE_OPEN_MAIN_JOU
5a00: 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30 30  RNAL     0x00000
5a10: 38 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  800.#define SQLI
5a20: 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55  TE_OPEN_TEMP_JOU
5a30: 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30 31  RNAL     0x00001
5a40: 30 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  000.#define SQLI
5a50: 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e  TE_OPEN_SUBJOURN
5a60: 41 4c 20 20 20 20 20 20 20 30 78 30 30 30 30 32  AL       0x00002
5a70: 30 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  000.#define SQLI
5a80: 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a  TE_OPEN_MASTER_J
5a90: 4f 55 52 4e 41 4c 20 20 20 30 78 30 30 30 30 34  OURNAL   0x00004
5aa0: 30 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  000.#define SQLI
5ab0: 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 20  TE_OPEN_NOMUTEX 
5ac0: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 38           0x00008
5ad0: 30 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  000.#define SQLI
5ae0: 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45  TE_OPEN_FULLMUTE
5af0: 58 20 20 20 20 20 20 20 20 30 78 30 30 30 31 30  X        0x00010
5b00: 30 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  000../*.** CAPI3
5b10: 52 45 46 3a 20 44 65 76 69 63 65 20 43 68 61 72  REF: Device Char
5b20: 61 63 74 65 72 69 73 74 69 63 73 20 7b 48 31 30  acteristics {H10
5b30: 32 34 30 7d 20 3c 48 31 31 31 32 30 3e 0a 2a 2a  240} <H11120>.**
5b40: 0a 2a 2a 20 54 68 65 20 78 44 65 76 69 63 65 43  .** The xDeviceC
5b50: 61 70 61 62 69 6c 69 74 69 65 73 20 6d 65 74 68  apabilities meth
5b60: 6f 64 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  od of the [sqlit
5b70: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a  e3_io_methods].*
5b80: 2a 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 73  * object returns
5b90: 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63   an integer whic
5ba0: 68 20 69 73 20 61 20 76 65 63 74 6f 72 20 6f 66  h is a vector of
5bb0: 20 74 68 65 20 74 68 65 73 65 0a 2a 2a 20 62 69   the these.** bi
5bc0: 74 20 76 61 6c 75 65 73 20 65 78 70 72 65 73 73  t values express
5bd0: 69 6e 67 20 49 2f 4f 20 63 68 61 72 61 63 74 65  ing I/O characte
5be0: 72 69 73 74 69 63 73 20 6f 66 20 74 68 65 20 6d  ristics of the m
5bf0: 61 73 73 20 73 74 6f 72 61 67 65 0a 2a 2a 20 64  ass storage.** d
5c00: 65 76 69 63 65 20 74 68 61 74 20 68 6f 6c 64 73  evice that holds
5c10: 20 74 68 65 20 66 69 6c 65 20 74 68 61 74 20 74   the file that t
5c20: 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  he [sqlite3_io_m
5c30: 65 74 68 6f 64 73 5d 0a 2a 2a 20 72 65 66 65 72  ethods].** refer
5c40: 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  s to..**.** The 
5c50: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
5c60: 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61  MIC property mea
5c70: 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74  ns that all writ
5c80: 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a  es of.** any siz
5c90: 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54  e are atomic.  T
5ca0: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
5cb0: 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73  ATOMICnnn values
5cc0: 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72  .** mean that wr
5cd0: 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74  ites of blocks t
5ce0: 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65  hat are nnn byte
5cf0: 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a  s in size and.**
5d00: 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20   are aligned to 
5d10: 61 6e 20 61 64 64 72 65 73 73 20 77 68 69 63 68  an address which
5d20: 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d   is an integer m
5d30: 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e  ultiple of.** nn
5d40: 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54  n are atomic.  T
5d50: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
5d60: 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75  SAFE_APPEND valu
5d70: 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20  e means.** that 
5d80: 77 68 65 6e 20 64 61 74 61 20 69 73 20 61 70 70  when data is app
5d90: 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c  ended to a file,
5da0: 20 74 68 65 20 64 61 74 61 20 69 73 20 61 70 70   the data is app
5db0: 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74  ended.** first t
5dc0: 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20  hen the size of 
5dd0: 74 68 65 20 66 69 6c 65 20 69 73 20 65 78 74 65  the file is exte
5de0: 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20  nded, never the 
5df0: 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f  other.** way aro
5e00: 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45  und.  The SQLITE
5e10: 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41  _IOCAP_SEQUENTIA
5e20: 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73  L property means
5e30: 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61   that.** informa
5e40: 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20  tion is written 
5e50: 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73  to disk in the s
5e60: 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c  ame order as cal
5e70: 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28  ls.** to xWrite(
5e80: 29 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  )..*/.#define SQ
5e90: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
5ea0: 43 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30  C          0x000
5eb0: 30 30 30 30 31 0a 23 64 65 66 69 6e 65 20 53 51  00001.#define SQ
5ec0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
5ed0: 43 35 31 32 20 20 20 20 20 20 20 30 78 30 30 30  C512       0x000
5ee0: 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51  00002.#define SQ
5ef0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
5f00: 43 31 4b 20 20 20 20 20 20 20 20 30 78 30 30 30  C1K        0x000
5f10: 30 30 30 30 34 0a 23 64 65 66 69 6e 65 20 53 51  00004.#define SQ
5f20: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
5f30: 43 32 4b 20 20 20 20 20 20 20 20 30 78 30 30 30  C2K        0x000
5f40: 30 30 30 30 38 0a 23 64 65 66 69 6e 65 20 53 51  00008.#define SQ
5f50: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
5f60: 43 34 4b 20 20 20 20 20 20 20 20 30 78 30 30 30  C4K        0x000
5f70: 30 30 30 31 30 0a 23 64 65 66 69 6e 65 20 53 51  00010.#define SQ
5f80: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
5f90: 43 38 4b 20 20 20 20 20 20 20 20 30 78 30 30 30  C8K        0x000
5fa0: 30 30 30 32 30 0a 23 64 65 66 69 6e 65 20 53 51  00020.#define SQ
5fb0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
5fc0: 43 31 36 4b 20 20 20 20 20 20 20 30 78 30 30 30  C16K       0x000
5fd0: 30 30 30 34 30 0a 23 64 65 66 69 6e 65 20 53 51  00040.#define SQ
5fe0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
5ff0: 43 33 32 4b 20 20 20 20 20 20 20 30 78 30 30 30  C32K       0x000
6000: 30 30 30 38 30 0a 23 64 65 66 69 6e 65 20 53 51  00080.#define SQ
6010: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
6020: 43 36 34 4b 20 20 20 20 20 20 20 30 78 30 30 30  C64K       0x000
6030: 30 30 31 30 30 0a 23 64 65 66 69 6e 65 20 53 51  00100.#define SQ
6040: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f  LITE_IOCAP_SAFE_
6050: 41 50 50 45 4e 44 20 20 20 20 20 30 78 30 30 30  APPEND     0x000
6060: 30 30 32 30 30 0a 23 64 65 66 69 6e 65 20 53 51  00200.#define SQ
6070: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45  LITE_IOCAP_SEQUE
6080: 4e 54 49 41 4c 20 20 20 20 20 20 30 78 30 30 30  NTIAL      0x000
6090: 30 30 34 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  00400../*.** CAP
60a0: 49 33 52 45 46 3a 20 46 69 6c 65 20 4c 6f 63 6b  I3REF: File Lock
60b0: 69 6e 67 20 4c 65 76 65 6c 73 20 7b 48 31 30 32  ing Levels {H102
60c0: 35 30 7d 20 3c 48 31 31 31 32 30 3e 20 3c 48 31  50} <H11120> <H1
60d0: 31 33 31 30 3e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  1310>.**.** SQLi
60e0: 74 65 20 75 73 65 73 20 6f 6e 65 20 6f 66 20 74  te uses one of t
60f0: 68 65 73 65 20 69 6e 74 65 67 65 72 20 76 61 6c  hese integer val
6100: 75 65 73 20 61 73 20 74 68 65 20 73 65 63 6f 6e  ues as the secon
6110: 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f  d.** argument to
6120: 20 63 61 6c 6c 73 20 69 74 20 6d 61 6b 65 73 20   calls it makes 
6130: 74 6f 20 74 68 65 20 78 4c 6f 63 6b 28 29 20 61  to the xLock() a
6140: 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 6d 65 74  nd xUnlock() met
6150: 68 6f 64 73 0a 2a 2a 20 6f 66 20 61 6e 20 5b 73  hods.** of an [s
6160: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
6170: 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 23 64  s] object..*/.#d
6180: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43  efine SQLITE_LOC
6190: 4b 5f 4e 4f 4e 45 20 20 20 20 20 20 20 20 20 20  K_NONE          
61a0: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
61b0: 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 20 20 20 20  _LOCK_SHARED    
61c0: 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51      1.#define SQ
61d0: 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56  LITE_LOCK_RESERV
61e0: 45 44 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e  ED      2.#defin
61f0: 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45  e SQLITE_LOCK_PE
6200: 4e 44 49 4e 47 20 20 20 20 20 20 20 33 0a 23 64  NDING       3.#d
6210: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43  efine SQLITE_LOC
6220: 4b 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20 20  K_EXCLUSIVE     
6230: 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  4../*.** CAPI3RE
6240: 46 3a 20 53 79 6e 63 68 72 6f 6e 69 7a 61 74 69  F: Synchronizati
6250: 6f 6e 20 54 79 70 65 20 46 6c 61 67 73 20 7b 48  on Type Flags {H
6260: 31 30 32 36 30 7d 20 3c 48 31 31 31 32 30 3e 0a  10260} <H11120>.
6270: 2a 2a 0a 2a 2a 20 57 68 65 6e 20 53 51 4c 69 74  **.** When SQLit
6280: 65 20 69 6e 76 6f 6b 65 73 20 74 68 65 20 78 53  e invokes the xS
6290: 79 6e 63 28 29 20 6d 65 74 68 6f 64 20 6f 66 20  ync() method of 
62a0: 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69  an.** [sqlite3_i
62b0: 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63  o_methods] objec
62c0: 74 20 69 74 20 75 73 65 73 20 61 20 63 6f 6d 62  t it uses a comb
62d0: 69 6e 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 74 68  ination of.** th
62e0: 65 73 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75  ese integer valu
62f0: 65 73 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  es as the second
6300: 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a   argument..**.**
6310: 20 57 68 65 6e 20 74 68 65 20 53 51 4c 49 54 45   When the SQLITE
6320: 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 66  _SYNC_DATAONLY f
6330: 6c 61 67 20 69 73 20 75 73 65 64 2c 20 69 74 20  lag is used, it 
6340: 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 0a 2a  means that the.*
6350: 2a 20 73 79 6e 63 20 6f 70 65 72 61 74 69 6f 6e  * sync operation
6360: 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20 66   only needs to f
6370: 6c 75 73 68 20 64 61 74 61 20 74 6f 20 6d 61 73  lush data to mas
6380: 73 20 73 74 6f 72 61 67 65 2e 20 20 49 6e 6f 64  s storage.  Inod
6390: 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  e.** information
63a0: 20 6e 65 65 64 20 6e 6f 74 20 62 65 20 66 6c 75   need not be flu
63b0: 73 68 65 64 2e 20 54 68 65 20 53 51 4c 49 54 45  shed. The SQLITE
63c0: 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 66 6c 61  _SYNC_NORMAL fla
63d0: 67 20 6d 65 61 6e 73 0a 2a 2a 20 74 6f 20 75 73  g means.** to us
63e0: 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29  e normal fsync()
63f0: 20 73 65 6d 61 6e 74 69 63 73 2e 20 54 68 65 20   semantics. The 
6400: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c  SQLITE_SYNC_FULL
6410: 20 66 6c 61 67 20 6d 65 61 6e 73 0a 2a 2a 20 74   flag means.** t
6420: 6f 20 75 73 65 20 4d 61 63 20 4f 53 2d 58 20 73  o use Mac OS-X s
6430: 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 20 69 6e  tyle fullsync in
6440: 73 74 65 61 64 20 6f 66 20 66 73 79 6e 63 28 29  stead of fsync()
6450: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
6460: 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20  ITE_SYNC_NORMAL 
6470: 20 20 20 20 20 20 20 30 78 30 30 30 30 32 0a 23         0x00002.#
6480: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59  define SQLITE_SY
6490: 4e 43 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 20  NC_FULL         
64a0: 20 30 78 30 30 30 30 33 0a 23 64 65 66 69 6e 65   0x00003.#define
64b0: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54   SQLITE_SYNC_DAT
64c0: 41 4f 4e 4c 59 20 20 20 20 20 20 30 78 30 30 30  AONLY      0x000
64d0: 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  10../*.** CAPI3R
64e0: 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65  EF: OS Interface
64f0: 20 4f 70 65 6e 20 46 69 6c 65 20 48 61 6e 64 6c   Open File Handl
6500: 65 20 7b 48 31 31 31 31 30 7d 20 3c 53 32 30 31  e {H11110} <S201
6510: 31 30 3e 0a 2a 2a 0a 2a 2a 20 41 6e 20 5b 73 71  10>.**.** An [sq
6520: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
6530: 63 74 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e  ct represents an
6540: 20 6f 70 65 6e 20 66 69 6c 65 20 69 6e 20 74 68   open file in th
6550: 65 20 4f 53 0a 2a 2a 20 69 6e 74 65 72 66 61 63  e OS.** interfac
6560: 65 20 6c 61 79 65 72 2e 20 20 49 6e 64 69 76 69  e layer.  Indivi
6570: 64 75 61 6c 20 4f 53 20 69 6e 74 65 72 66 61 63  dual OS interfac
6580: 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
6590: 73 20 77 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74  s will.** want t
65a0: 6f 20 73 75 62 63 6c 61 73 73 20 74 68 69 73 20  o subclass this 
65b0: 6f 62 6a 65 63 74 20 62 79 20 61 70 70 65 6e 64  object by append
65c0: 69 6e 67 20 61 64 64 69 74 69 6f 6e 61 6c 20 66  ing additional f
65d0: 69 65 6c 64 73 0a 2a 2a 20 66 6f 72 20 74 68 65  ields.** for the
65e0: 69 72 20 6f 77 6e 20 75 73 65 2e 20 20 54 68 65  ir own use.  The
65f0: 20 70 4d 65 74 68 6f 64 73 20 65 6e 74 72 79 20   pMethods entry 
6600: 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
6610: 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69  an.** [sqlite3_i
6620: 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63  o_methods] objec
6630: 74 20 74 68 61 74 20 64 65 66 69 6e 65 73 20 6d  t that defines m
6640: 65 74 68 6f 64 73 20 66 6f 72 20 70 65 72 66 6f  ethods for perfo
6650: 72 6d 69 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65  rming.** I/O ope
6660: 72 61 74 69 6f 6e 73 20 6f 6e 20 74 68 65 20 6f  rations on the o
6670: 70 65 6e 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70  pen file..*/.typ
6680: 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
6690: 74 65 33 5f 66 69 6c 65 20 73 71 6c 69 74 65 33  te3_file sqlite3
66a0: 5f 66 69 6c 65 3b 0a 73 74 72 75 63 74 20 73 71  _file;.struct sq
66b0: 6c 69 74 65 33 5f 66 69 6c 65 20 7b 0a 20 20 63  lite3_file {.  c
66c0: 6f 6e 73 74 20 73 74 72 75 63 74 20 73 71 6c 69  onst struct sqli
66d0: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 2a  te3_io_methods *
66e0: 70 4d 65 74 68 6f 64 73 3b 20 20 2f 2a 20 4d 65  pMethods;  /* Me
66f0: 74 68 6f 64 73 20 66 6f 72 20 61 6e 20 6f 70 65  thods for an ope
6700: 6e 20 66 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a  n file */.};../*
6710: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53  .** CAPI3REF: OS
6720: 20 49 6e 74 65 72 66 61 63 65 20 46 69 6c 65 20   Interface File 
6730: 56 69 72 74 75 61 6c 20 4d 65 74 68 6f 64 73 20  Virtual Methods 
6740: 4f 62 6a 65 63 74 20 7b 48 31 31 31 32 30 7d 20  Object {H11120} 
6750: 3c 53 32 30 31 31 30 3e 0a 2a 2a 0a 2a 2a 20 45  <S20110>.**.** E
6760: 76 65 72 79 20 66 69 6c 65 20 6f 70 65 6e 65 64  very file opened
6770: 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33   by the [sqlite3
6780: 5f 76 66 73 5d 20 78 4f 70 65 6e 20 6d 65 74 68  _vfs] xOpen meth
6790: 6f 64 20 70 6f 70 75 6c 61 74 65 73 20 61 6e 0a  od populates an.
67a0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ** [sqlite3_file
67b0: 5d 20 6f 62 6a 65 63 74 20 28 6f 72 2c 20 6d 6f  ] object (or, mo
67c0: 72 65 20 63 6f 6d 6d 6f 6e 6c 79 2c 20 61 20 73  re commonly, a s
67d0: 75 62 63 6c 61 73 73 20 6f 66 20 74 68 65 0a 2a  ubclass of the.*
67e0: 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  * [sqlite3_file]
67f0: 20 6f 62 6a 65 63 74 29 20 77 69 74 68 20 61 20   object) with a 
6800: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
6810: 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f  stance of this o
6820: 62 6a 65 63 74 2e 0a 2a 2a 20 54 68 69 73 20 6f  bject..** This o
6830: 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 68  bject defines th
6840: 65 20 6d 65 74 68 6f 64 73 20 75 73 65 64 20 74  e methods used t
6850: 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f 75  o perform variou
6860: 73 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20  s operations.** 
6870: 61 67 61 69 6e 73 74 20 74 68 65 20 6f 70 65 6e  against the open
6880: 20 66 69 6c 65 20 72 65 70 72 65 73 65 6e 74 65   file represente
6890: 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65  d by the [sqlite
68a0: 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 2e 0a  3_file] object..
68b0: 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73 20  **.** The flags 
68c0: 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 53 79 6e  argument to xSyn
68d0: 63 20 6d 61 79 20 62 65 20 6f 6e 65 20 6f 66 20  c may be one of 
68e0: 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52  [SQLITE_SYNC_NOR
68f0: 4d 41 4c 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49  MAL] or.** [SQLI
6900: 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 5d 2e 20 20  TE_SYNC_FULL].  
6910: 54 68 65 20 66 69 72 73 74 20 63 68 6f 69 63 65  The first choice
6920: 20 69 73 20 74 68 65 20 6e 6f 72 6d 61 6c 20 66   is the normal f
6930: 73 79 6e 63 28 29 2e 0a 2a 2a 20 54 68 65 20 73  sync()..** The s
6940: 65 63 6f 6e 64 20 63 68 6f 69 63 65 20 69 73 20  econd choice is 
6950: 61 20 4d 61 63 20 4f 53 2d 58 20 73 74 79 6c 65  a Mac OS-X style
6960: 20 66 75 6c 6c 73 79 6e 63 2e 20 20 54 68 65 20   fullsync.  The 
6970: 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54  [SQLITE_SYNC_DAT
6980: 41 4f 4e 4c 59 5d 0a 2a 2a 20 66 6c 61 67 20 6d  AONLY].** flag m
6990: 61 79 20 62 65 20 4f 52 65 64 20 69 6e 20 74 6f  ay be ORed in to
69a0: 20 69 6e 64 69 63 61 74 65 20 74 68 61 74 20 6f   indicate that o
69b0: 6e 6c 79 20 74 68 65 20 64 61 74 61 20 6f 66 20  nly the data of 
69c0: 74 68 65 20 66 69 6c 65 0a 2a 2a 20 61 6e 64 20  the file.** and 
69d0: 6e 6f 74 20 69 74 73 20 69 6e 6f 64 65 20 6e 65  not its inode ne
69e0: 65 64 73 20 74 6f 20 62 65 20 73 79 6e 63 65 64  eds to be synced
69f0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 74 65  ..**.** The inte
6a00: 67 65 72 20 76 61 6c 75 65 73 20 74 6f 20 78 4c  ger values to xL
6a10: 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63  ock() and xUnloc
6a20: 6b 28 29 20 61 72 65 20 6f 6e 65 20 6f 66 0a 2a  k() are one of.*
6a30: 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b  * <ul>.** <li> [
6a40: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45  SQLITE_LOCK_NONE
6a50: 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  ],.** <li> [SQLI
6a60: 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 5d 2c  TE_LOCK_SHARED],
6a70: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
6a80: 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c  _LOCK_RESERVED],
6a90: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
6aa0: 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20  _LOCK_PENDING], 
6ab0: 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  or.** <li> [SQLI
6ac0: 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56  TE_LOCK_EXCLUSIV
6ad0: 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20  E]..** </ul>.** 
6ae0: 78 4c 6f 63 6b 28 29 20 69 6e 63 72 65 61 73 65  xLock() increase
6af0: 73 20 74 68 65 20 6c 6f 63 6b 2e 20 78 55 6e 6c  s the lock. xUnl
6b00: 6f 63 6b 28 29 20 64 65 63 72 65 61 73 65 73 20  ock() decreases 
6b10: 74 68 65 20 6c 6f 63 6b 2e 0a 2a 2a 20 54 68 65  the lock..** The
6b20: 20 78 43 68 65 63 6b 52 65 73 65 72 76 65 64 4c   xCheckReservedL
6b30: 6f 63 6b 28 29 20 6d 65 74 68 6f 64 20 63 68 65  ock() method che
6b40: 63 6b 73 20 77 68 65 74 68 65 72 20 61 6e 79 20  cks whether any 
6b50: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
6b60: 69 6f 6e 2c 0a 2a 2a 20 65 69 74 68 65 72 20 69  ion,.** either i
6b70: 6e 20 74 68 69 73 20 70 72 6f 63 65 73 73 20 6f  n this process o
6b80: 72 20 69 6e 20 73 6f 6d 65 20 6f 74 68 65 72 20  r in some other 
6b90: 70 72 6f 63 65 73 73 2c 20 69 73 20 68 6f 6c 64  process, is hold
6ba0: 69 6e 67 20 61 20 52 45 53 45 52 56 45 44 2c 0a  ing a RESERVED,.
6bb0: 2a 2a 20 50 45 4e 44 49 4e 47 2c 20 6f 72 20 45  ** PENDING, or E
6bc0: 58 43 4c 55 53 49 56 45 20 6c 6f 63 6b 20 6f 6e  XCLUSIVE lock on
6bd0: 20 74 68 65 20 66 69 6c 65 2e 20 20 49 74 20 72   the file.  It r
6be0: 65 74 75 72 6e 73 20 74 72 75 65 0a 2a 2a 20 69  eturns true.** i
6bf0: 66 20 73 75 63 68 20 61 20 6c 6f 63 6b 20 65 78  f such a lock ex
6c00: 69 73 74 73 20 61 6e 64 20 66 61 6c 73 65 20 6f  ists and false o
6c10: 74 68 65 72 77 69 73 65 2e 0a 2a 2a 0a 2a 2a 20  therwise..**.** 
6c20: 54 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  The xFileControl
6c30: 28 29 20 6d 65 74 68 6f 64 20 69 73 20 61 20 67  () method is a g
6c40: 65 6e 65 72 69 63 20 69 6e 74 65 72 66 61 63 65  eneric interface
6c50: 20 74 68 61 74 20 61 6c 6c 6f 77 73 20 63 75 73   that allows cus
6c60: 74 6f 6d 0a 2a 2a 20 56 46 53 20 69 6d 70 6c 65  tom.** VFS imple
6c70: 6d 65 6e 74 61 74 69 6f 6e 73 20 74 6f 20 64 69  mentations to di
6c80: 72 65 63 74 6c 79 20 63 6f 6e 74 72 6f 6c 20 61  rectly control a
6c90: 6e 20 6f 70 65 6e 20 66 69 6c 65 20 75 73 69 6e  n open file usin
6ca0: 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  g the.** [sqlite
6cb0: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
6cc0: 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 20 54 68  ] interface.  Th
6cd0: 65 20 73 65 63 6f 6e 64 20 22 6f 70 22 20 61 72  e second "op" ar
6ce0: 67 75 6d 65 6e 74 20 69 73 20 61 6e 0a 2a 2a 20  gument is an.** 
6cf0: 69 6e 74 65 67 65 72 20 6f 70 63 6f 64 65 2e 20  integer opcode. 
6d00: 20 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d   The third argum
6d10: 65 6e 74 20 69 73 20 61 20 67 65 6e 65 72 69 63  ent is a generic
6d20: 20 70 6f 69 6e 74 65 72 20 69 6e 74 65 6e 64 65   pointer intende
6d30: 64 20 74 6f 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f  d to.** point to
6d40: 20 61 20 73 74 72 75 63 74 75 72 65 20 74 68 61   a structure tha
6d50: 74 20 6d 61 79 20 63 6f 6e 74 61 69 6e 20 61 72  t may contain ar
6d60: 67 75 6d 65 6e 74 73 20 6f 72 20 73 70 61 63 65  guments or space
6d70: 20 69 6e 20 77 68 69 63 68 20 74 6f 0a 2a 2a 20   in which to.** 
6d80: 77 72 69 74 65 20 72 65 74 75 72 6e 20 76 61 6c  write return val
6d90: 75 65 73 2e 20 20 50 6f 74 65 6e 74 69 61 6c 20  ues.  Potential 
6da0: 75 73 65 73 20 66 6f 72 20 78 46 69 6c 65 43 6f  uses for xFileCo
6db0: 6e 74 72 6f 6c 28 29 20 6d 69 67 68 74 20 62 65  ntrol() might be
6dc0: 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f  .** functions to
6dd0: 20 65 6e 61 62 6c 65 20 62 6c 6f 63 6b 69 6e 67   enable blocking
6de0: 20 6c 6f 63 6b 73 20 77 69 74 68 20 74 69 6d 65   locks with time
6df0: 6f 75 74 73 2c 20 74 6f 20 63 68 61 6e 67 65 20  outs, to change 
6e00: 74 68 65 0a 2a 2a 20 6c 6f 63 6b 69 6e 67 20 73  the.** locking s
6e10: 74 72 61 74 65 67 79 20 28 66 6f 72 20 65 78 61  trategy (for exa
6e20: 6d 70 6c 65 20 74 6f 20 75 73 65 20 64 6f 74 2d  mple to use dot-
6e30: 66 69 6c 65 20 6c 6f 63 6b 73 29 2c 20 74 6f 20  file locks), to 
6e40: 69 6e 71 75 69 72 65 0a 2a 2a 20 61 62 6f 75 74  inquire.** about
6e50: 20 74 68 65 20 73 74 61 74 75 73 20 6f 66 20 61   the status of a
6e60: 20 6c 6f 63 6b 2c 20 6f 72 20 74 6f 20 62 72 65   lock, or to bre
6e70: 61 6b 20 73 74 61 6c 65 20 6c 6f 63 6b 73 2e 20  ak stale locks. 
6e80: 20 54 68 65 20 53 51 4c 69 74 65 0a 2a 2a 20 63   The SQLite.** c
6e90: 6f 72 65 20 72 65 73 65 72 76 65 73 20 61 6c 6c  ore reserves all
6ea0: 20 6f 70 63 6f 64 65 73 20 6c 65 73 73 20 74 68   opcodes less th
6eb0: 61 6e 20 31 30 30 20 66 6f 72 20 69 74 73 20 6f  an 100 for its o
6ec0: 77 6e 20 75 73 65 2e 0a 2a 2a 20 41 20 5b 53 51  wn use..** A [SQ
6ed0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53  LITE_FCNTL_LOCKS
6ee0: 54 41 54 45 20 7c 20 6c 69 73 74 20 6f 66 20 6f  TATE | list of o
6ef0: 70 63 6f 64 65 73 5d 20 6c 65 73 73 20 74 68 61  pcodes] less tha
6f00: 6e 20 31 30 30 20 69 73 20 61 76 61 69 6c 61 62  n 100 is availab
6f10: 6c 65 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69  le..** Applicati
6f20: 6f 6e 73 20 74 68 61 74 20 64 65 66 69 6e 65 20  ons that define 
6f30: 61 20 63 75 73 74 6f 6d 20 78 46 69 6c 65 43 6f  a custom xFileCo
6f40: 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 73 68 6f  ntrol method sho
6f50: 75 6c 64 20 75 73 65 20 6f 70 63 6f 64 65 73 0a  uld use opcodes.
6f60: 2a 2a 20 67 72 65 61 74 65 72 20 74 68 61 6e 20  ** greater than 
6f70: 31 30 30 20 74 6f 20 61 76 6f 69 64 20 63 6f 6e  100 to avoid con
6f80: 66 6c 69 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  flicts..**.** Th
6f90: 65 20 78 53 65 63 74 6f 72 53 69 7a 65 28 29 20  e xSectorSize() 
6fa0: 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 74  method returns t
6fb0: 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20 6f  he sector size o
6fc0: 66 20 74 68 65 0a 2a 2a 20 64 65 76 69 63 65 20  f the.** device 
6fd0: 74 68 61 74 20 75 6e 64 65 72 6c 69 65 73 20 74  that underlies t
6fe0: 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20 73 65  he file.  The se
6ff0: 63 74 6f 72 20 73 69 7a 65 20 69 73 20 74 68 65  ctor size is the
7000: 0a 2a 2a 20 6d 69 6e 69 6d 75 6d 20 77 72 69 74  .** minimum writ
7010: 65 20 74 68 61 74 20 63 61 6e 20 62 65 20 70 65  e that can be pe
7020: 72 66 6f 72 6d 65 64 20 77 69 74 68 6f 75 74 20  rformed without 
7030: 64 69 73 74 75 72 62 69 6e 67 0a 2a 2a 20 6f 74  disturbing.** ot
7040: 68 65 72 20 62 79 74 65 73 20 69 6e 20 74 68 65  her bytes in the
7050: 20 66 69 6c 65 2e 20 20 54 68 65 20 78 44 65 76   file.  The xDev
7060: 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69  iceCharacteristi
7070: 63 73 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72  cs().** method r
7080: 65 74 75 72 6e 73 20 61 20 62 69 74 20 76 65 63  eturns a bit vec
7090: 74 6f 72 20 64 65 73 63 72 69 62 69 6e 67 20 62  tor describing b
70a0: 65 68 61 76 69 6f 72 73 20 6f 66 20 74 68 65 0a  ehaviors of the.
70b0: 2a 2a 20 75 6e 64 65 72 6c 79 69 6e 67 20 64 65  ** underlying de
70c0: 76 69 63 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  vice:.**.** <ul>
70d0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
70e0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 5d 0a 2a  _IOCAP_ATOMIC].*
70f0: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
7100: 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 32 5d 0a  OCAP_ATOMIC512].
7110: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
7120: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b 5d 0a  IOCAP_ATOMIC1K].
7130: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
7140: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 5d 0a  IOCAP_ATOMIC2K].
7150: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
7160: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b 5d 0a  IOCAP_ATOMIC4K].
7170: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
7180: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b 5d 0a  IOCAP_ATOMIC8K].
7190: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
71a0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b 5d  IOCAP_ATOMIC16K]
71b0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
71c0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b  _IOCAP_ATOMIC32K
71d0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
71e0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34  E_IOCAP_ATOMIC64
71f0: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
7200: 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50  TE_IOCAP_SAFE_AP
7210: 50 45 4e 44 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  PEND].** <li> [S
7220: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55  QLITE_IOCAP_SEQU
7230: 45 4e 54 49 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e  ENTIAL].** </ul>
7240: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54  .**.** The SQLIT
7250: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70  E_IOCAP_ATOMIC p
7260: 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68  roperty means th
7270: 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f 66  at all writes of
7280: 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72 65  .** any size are
7290: 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51   atomic.  The SQ
72a0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
72b0: 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d  Cnnn values.** m
72c0: 65 61 6e 20 74 68 61 74 20 77 72 69 74 65 73 20  ean that writes 
72d0: 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20 61  of blocks that a
72e0: 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20  re nnn bytes in 
72f0: 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20  size and.** are 
7300: 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61 64  aligned to an ad
7310: 64 72 65 73 73 20 77 68 69 63 68 20 69 73 20 61  dress which is a
7320: 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69 70  n integer multip
7330: 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65  le of.** nnn are
7340: 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51   atomic.  The SQ
7350: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f  LITE_IOCAP_SAFE_
7360: 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65 61  APPEND value mea
7370: 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e 20  ns.** that when 
7380: 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64  data is appended
7390: 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65 20   to a file, the 
73a0: 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64  data is appended
73b0: 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20 74  .** first then t
73c0: 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 66  he size of the f
73d0: 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64 2c  ile is extended,
73e0: 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65 72   never the other
73f0: 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e 20  .** way around. 
7400: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
7410: 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72 6f  P_SEQUENTIAL pro
7420: 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74  perty means that
7430: 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  .** information 
7440: 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69  is written to di
7450: 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20 6f  sk in the same o
7460: 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a  rder as calls.**
7470: 20 74 6f 20 78 57 72 69 74 65 28 29 2e 0a 2a 2f   to xWrite()..*/
7480: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
7490: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
74a0: 64 73 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  ds sqlite3_io_me
74b0: 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71  thods;.struct sq
74c0: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
74d0: 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f   {.  int iVersio
74e0: 6e 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f 73  n;.  int (*xClos
74f0: 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  e)(sqlite3_file*
7500: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 65 61 64  );.  int (*xRead
7510: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
7520: 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74   void*, int iAmt
7530: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  , sqlite3_int64 
7540: 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a  iOfst);.  int (*
7550: 78 57 72 69 74 65 29 28 73 71 6c 69 74 65 33 5f  xWrite)(sqlite3_
7560: 66 69 6c 65 2a 2c 20 63 6f 6e 73 74 20 76 6f 69  file*, const voi
7570: 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71  d*, int iAmt, sq
7580: 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73  lite3_int64 iOfs
7590: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 54 72 75  t);.  int (*xTru
75a0: 6e 63 61 74 65 29 28 73 71 6c 69 74 65 33 5f 66  ncate)(sqlite3_f
75b0: 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e  ile*, sqlite3_in
75c0: 74 36 34 20 73 69 7a 65 29 3b 0a 20 20 69 6e 74  t64 size);.  int
75d0: 20 28 2a 78 53 79 6e 63 29 28 73 71 6c 69 74 65   (*xSync)(sqlite
75e0: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 66 6c 61  3_file*, int fla
75f0: 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69  gs);.  int (*xFi
7600: 6c 65 53 69 7a 65 29 28 73 71 6c 69 74 65 33 5f  leSize)(sqlite3_
7610: 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69  file*, sqlite3_i
7620: 6e 74 36 34 20 2a 70 53 69 7a 65 29 3b 0a 20 20  nt64 *pSize);.  
7630: 69 6e 74 20 28 2a 78 4c 6f 63 6b 29 28 73 71 6c  int (*xLock)(sql
7640: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29  ite3_file*, int)
7650: 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e 6c 6f 63  ;.  int (*xUnloc
7660: 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  k)(sqlite3_file*
7670: 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a  , int);.  int (*
7680: 78 43 68 65 63 6b 52 65 73 65 72 76 65 64 4c 6f  xCheckReservedLo
7690: 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ck)(sqlite3_file
76a0: 2a 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 74 29  *, int *pResOut)
76b0: 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 43  ;.  int (*xFileC
76c0: 6f 6e 74 72 6f 6c 29 28 73 71 6c 69 74 65 33 5f  ontrol)(sqlite3_
76d0: 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 70 2c 20 76  file*, int op, v
76e0: 6f 69 64 20 2a 70 41 72 67 29 3b 0a 20 20 69 6e  oid *pArg);.  in
76f0: 74 20 28 2a 78 53 65 63 74 6f 72 53 69 7a 65 29  t (*xSectorSize)
7700: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b  (sqlite3_file*);
7710: 0a 20 20 69 6e 74 20 28 2a 78 44 65 76 69 63 65  .  int (*xDevice
7720: 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 29  Characteristics)
7730: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b  (sqlite3_file*);
7740: 0a 20 20 2f 2a 20 41 64 64 69 74 69 6f 6e 61 6c  .  /* Additional
7750: 20 6d 65 74 68 6f 64 73 20 6d 61 79 20 62 65 20   methods may be 
7760: 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20  added in future 
7770: 72 65 6c 65 61 73 65 73 20 2a 2f 0a 7d 3b 0a 0a  releases */.};..
7780: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
7790: 53 74 61 6e 64 61 72 64 20 46 69 6c 65 20 43 6f  Standard File Co
77a0: 6e 74 72 6f 6c 20 4f 70 63 6f 64 65 73 20 7b 48  ntrol Opcodes {H
77b0: 31 31 33 31 30 7d 20 3c 53 33 30 38 30 30 3e 0a  11310} <S30800>.
77c0: 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65  **.** These inte
77d0: 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 61 72  ger constants ar
77e0: 65 20 6f 70 63 6f 64 65 73 20 66 6f 72 20 74 68  e opcodes for th
77f0: 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d  e xFileControl m
7800: 65 74 68 6f 64 0a 2a 2a 20 6f 66 20 74 68 65 20  ethod.** of the 
7810: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
7820: 6f 64 73 5d 20 6f 62 6a 65 63 74 20 61 6e 64 20  ods] object and 
7830: 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33  for the [sqlite3
7840: 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d  _file_control()]
7850: 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  .** interface..*
7860: 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  *.** The [SQLITE
7870: 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45  _FCNTL_LOCKSTATE
7880: 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64  ] opcode is used
7890: 20 66 6f 72 20 64 65 62 75 67 67 69 6e 67 2e 20   for debugging. 
78a0: 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20   This.** opcode 
78b0: 63 61 75 73 65 73 20 74 68 65 20 78 46 69 6c 65  causes the xFile
78c0: 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 74  Control method t
78d0: 6f 20 77 72 69 74 65 20 74 68 65 20 63 75 72 72  o write the curr
78e0: 65 6e 74 20 73 74 61 74 65 20 6f 66 0a 2a 2a 20  ent state of.** 
78f0: 74 68 65 20 6c 6f 63 6b 20 28 6f 6e 65 20 6f 66  the lock (one of
7900: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f   [SQLITE_LOCK_NO
7910: 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  NE], [SQLITE_LOC
7920: 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 5b 53  K_SHARED],.** [S
7930: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52  QLITE_LOCK_RESER
7940: 56 45 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f  VED], [SQLITE_LO
7950: 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 20  CK_PENDING], or 
7960: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43  [SQLITE_LOCK_EXC
7970: 4c 55 53 49 56 45 5d 29 0a 2a 2a 20 69 6e 74 6f  LUSIVE]).** into
7980: 20 61 6e 20 69 6e 74 65 67 65 72 20 74 68 61 74   an integer that
7990: 20 74 68 65 20 70 41 72 67 20 61 72 67 75 6d 65   the pArg argume
79a0: 6e 74 20 70 6f 69 6e 74 73 20 74 6f 2e 20 54 68  nt points to. Th
79b0: 69 73 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a  is capability.**
79c0: 20 69 73 20 75 73 65 64 20 64 75 72 69 6e 67 20   is used during 
79d0: 74 65 73 74 69 6e 67 20 61 6e 64 20 6f 6e 6c 79  testing and only
79e0: 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73 75 70   needs to be sup
79f0: 70 6f 72 74 65 64 20 77 68 65 6e 20 53 51 4c 49  ported when SQLI
7a00: 54 45 5f 54 45 53 54 0a 2a 2a 20 69 73 20 64 65  TE_TEST.** is de
7a10: 66 69 6e 65 64 2e 0a 2a 2f 0a 23 64 65 66 69 6e  fined..*/.#defin
7a20: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c  e SQLITE_FCNTL_L
7a30: 4f 43 4b 53 54 41 54 45 20 20 20 20 20 20 20 20  OCKSTATE        
7a40: 31 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  1../*.** CAPI3RE
7a50: 46 3a 20 4d 75 74 65 78 20 48 61 6e 64 6c 65 20  F: Mutex Handle 
7a60: 7b 48 31 37 31 31 30 7d 20 3c 53 32 30 31 33 30  {H17110} <S20130
7a70: 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d 75 74 65  >.**.** The mute
7a80: 78 20 6d 6f 64 75 6c 65 20 77 69 74 68 69 6e 20  x module within 
7a90: 53 51 4c 69 74 65 20 64 65 66 69 6e 65 73 20 5b  SQLite defines [
7aa0: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 74  sqlite3_mutex] t
7ab0: 6f 20 62 65 20 61 6e 0a 2a 2a 20 61 62 73 74 72  o be an.** abstr
7ac0: 61 63 74 20 74 79 70 65 20 66 6f 72 20 61 20 6d  act type for a m
7ad0: 75 74 65 78 20 6f 62 6a 65 63 74 2e 20 20 54 68  utex object.  Th
7ae0: 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 6e 65  e SQLite core ne
7af0: 76 65 72 20 6c 6f 6f 6b 73 0a 2a 2a 20 61 74 20  ver looks.** at 
7b00: 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70  the internal rep
7b10: 72 65 73 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61  resentation of a
7b20: 6e 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  n [sqlite3_mutex
7b30: 5d 2e 20 20 49 74 20 6f 6e 6c 79 0a 2a 2a 20 64  ].  It only.** d
7b40: 65 61 6c 73 20 77 69 74 68 20 70 6f 69 6e 74 65  eals with pointe
7b50: 72 73 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  rs to the [sqlit
7b60: 65 33 5f 6d 75 74 65 78 5d 20 6f 62 6a 65 63 74  e3_mutex] object
7b70: 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74 65 78 65 73 20  ..**.** Mutexes 
7b80: 61 72 65 20 63 72 65 61 74 65 64 20 75 73 69 6e  are created usin
7b90: 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  g [sqlite3_mutex
7ba0: 5f 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 74 79  _alloc()]..*/.ty
7bb0: 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
7bc0: 69 74 65 33 5f 6d 75 74 65 78 20 73 71 6c 69 74  ite3_mutex sqlit
7bd0: 65 33 5f 6d 75 74 65 78 3b 0a 0a 2f 2a 0a 2a 2a  e3_mutex;../*.**
7be0: 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e   CAPI3REF: OS In
7bf0: 74 65 72 66 61 63 65 20 4f 62 6a 65 63 74 20 7b  terface Object {
7c00: 48 31 31 31 34 30 7d 20 3c 53 32 30 31 30 30 3e  H11140} <S20100>
7c10: 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e  .**.** An instan
7c20: 63 65 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65  ce of the sqlite
7c30: 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 64 65 66  3_vfs object def
7c40: 69 6e 65 73 20 74 68 65 20 69 6e 74 65 72 66 61  ines the interfa
7c50: 63 65 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68  ce between.** th
7c60: 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 61 6e  e SQLite core an
7c70: 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67  d the underlying
7c80: 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65   operating syste
7c90: 6d 2e 20 20 54 68 65 20 22 76 66 73 22 0a 2a 2a  m.  The "vfs".**
7ca0: 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   in the name of 
7cb0: 74 68 65 20 6f 62 6a 65 63 74 20 73 74 61 6e 64  the object stand
7cc0: 73 20 66 6f 72 20 22 76 69 72 74 75 61 6c 20 66  s for "virtual f
7cd0: 69 6c 65 20 73 79 73 74 65 6d 22 2e 0a 2a 2a 0a  ile system"..**.
7ce0: 2a 2a 20 54 68 65 20 76 61 6c 75 65 20 6f 66 20  ** The value of 
7cf0: 74 68 65 20 69 56 65 72 73 69 6f 6e 20 66 69 65  the iVersion fie
7d00: 6c 64 20 69 73 20 69 6e 69 74 69 61 6c 6c 79 20  ld is initially 
7d10: 31 20 62 75 74 20 6d 61 79 20 62 65 20 6c 61 72  1 but may be lar
7d20: 67 65 72 20 69 6e 0a 2a 2a 20 66 75 74 75 72 65  ger in.** future
7d30: 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
7d40: 69 74 65 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c  ite.  Additional
7d50: 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61   fields may be a
7d60: 70 70 65 6e 64 65 64 20 74 6f 20 74 68 69 73 0a  ppended to this.
7d70: 2a 2a 20 6f 62 6a 65 63 74 20 77 68 65 6e 20 74  ** object when t
7d80: 68 65 20 69 56 65 72 73 69 6f 6e 20 76 61 6c 75  he iVersion valu
7d90: 65 20 69 73 20 69 6e 63 72 65 61 73 65 64 2e 20  e is increased. 
7da0: 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 73   Note that the s
7db0: 74 72 75 63 74 75 72 65 0a 2a 2a 20 6f 66 20 74  tructure.** of t
7dc0: 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f  he sqlite3_vfs o
7dd0: 62 6a 65 63 74 20 63 68 61 6e 67 65 73 20 69 6e  bject changes in
7de0: 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e   the transaction
7df0: 20 62 65 74 77 65 65 6e 0a 2a 2a 20 53 51 4c 69   between.** SQLi
7e00: 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 39  te version 3.5.9
7e10: 20 61 6e 64 20 33 2e 36 2e 30 20 61 6e 64 20 79   and 3.6.0 and y
7e20: 65 74 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20  et the iVersion 
7e30: 66 69 65 6c 64 20 77 61 73 20 6e 6f 74 0a 2a 2a  field was not.**
7e40: 20 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a 0a 2a 2a   modified..**.**
7e50: 20 54 68 65 20 73 7a 4f 73 46 69 6c 65 20 66 69   The szOsFile fi
7e60: 65 6c 64 20 69 73 20 74 68 65 20 73 69 7a 65 20  eld is the size 
7e70: 6f 66 20 74 68 65 20 73 75 62 63 6c 61 73 73 65  of the subclasse
7e80: 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  d [sqlite3_file]
7e90: 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 75 73  .** structure us
7ea0: 65 64 20 62 79 20 74 68 69 73 20 56 46 53 2e 20  ed by this VFS. 
7eb0: 20 6d 78 50 61 74 68 6e 61 6d 65 20 69 73 20 74   mxPathname is t
7ec0: 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  he maximum lengt
7ed0: 68 20 6f 66 0a 2a 2a 20 61 20 70 61 74 68 6e 61  h of.** a pathna
7ee0: 6d 65 20 69 6e 20 74 68 69 73 20 56 46 53 2e 0a  me in this VFS..
7ef0: 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65 72 65 64  **.** Registered
7f00: 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a   sqlite3_vfs obj
7f10: 65 63 74 73 20 61 72 65 20 6b 65 70 74 20 6f 6e  ects are kept on
7f20: 20 61 20 6c 69 6e 6b 65 64 20 6c 69 73 74 20 66   a linked list f
7f30: 6f 72 6d 65 64 20 62 79 0a 2a 2a 20 74 68 65 20  ormed by.** the 
7f40: 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e 20 20  pNext pointer.  
7f50: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  The [sqlite3_vfs
7f60: 5f 72 65 67 69 73 74 65 72 28 29 5d 0a 2a 2a 20  _register()].** 
7f70: 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  and [sqlite3_vfs
7f80: 5f 75 6e 72 65 67 69 73 74 65 72 28 29 5d 20 69  _unregister()] i
7f90: 6e 74 65 72 66 61 63 65 73 20 6d 61 6e 61 67 65  nterfaces manage
7fa0: 20 74 68 69 73 20 6c 69 73 74 0a 2a 2a 20 69 6e   this list.** in
7fb0: 20 61 20 74 68 72 65 61 64 2d 73 61 66 65 20 77   a thread-safe w
7fc0: 61 79 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65  ay.  The [sqlite
7fd0: 33 5f 76 66 73 5f 66 69 6e 64 28 29 5d 20 69 6e  3_vfs_find()] in
7fe0: 74 65 72 66 61 63 65 0a 2a 2a 20 73 65 61 72 63  terface.** searc
7ff0: 68 65 73 20 74 68 65 20 6c 69 73 74 2e 20 20 4e  hes the list.  N
8000: 65 69 74 68 65 72 20 74 68 65 20 61 70 70 6c 69  either the appli
8010: 63 61 74 69 6f 6e 20 63 6f 64 65 20 6e 6f 72 20  cation code nor 
8020: 74 68 65 20 56 46 53 0a 2a 2a 20 69 6d 70 6c 65  the VFS.** imple
8030: 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75 6c 64  mentation should
8040: 20 75 73 65 20 74 68 65 20 70 4e 65 78 74 20 70   use the pNext p
8050: 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68  ointer..**.** Th
8060: 65 20 70 4e 65 78 74 20 66 69 65 6c 64 20 69 73  e pNext field is
8070: 20 74 68 65 20 6f 6e 6c 79 20 66 69 65 6c 64 20   the only field 
8080: 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76  in the sqlite3_v
8090: 66 73 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20  fs.** structure 
80a0: 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c  that SQLite will
80b0: 20 65 76 65 72 20 6d 6f 64 69 66 79 2e 20 20 53   ever modify.  S
80c0: 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e 6c 79 20  QLite will only 
80d0: 61 63 63 65 73 73 0a 2a 2a 20 6f 72 20 6d 6f 64  access.** or mod
80e0: 69 66 79 20 74 68 69 73 20 66 69 65 6c 64 20 77  ify this field w
80f0: 68 69 6c 65 20 68 6f 6c 64 69 6e 67 20 61 20 70  hile holding a p
8100: 61 72 74 69 63 75 6c 61 72 20 73 74 61 74 69 63  articular static
8110: 20 6d 75 74 65 78 2e 0a 2a 2a 20 54 68 65 20 61   mutex..** The a
8120: 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c  pplication shoul
8130: 64 20 6e 65 76 65 72 20 6d 6f 64 69 66 79 20 61  d never modify a
8140: 6e 79 74 68 69 6e 67 20 77 69 74 68 69 6e 20 74  nything within t
8150: 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a  he sqlite3_vfs.*
8160: 2a 20 6f 62 6a 65 63 74 20 6f 6e 63 65 20 74 68  * object once th
8170: 65 20 6f 62 6a 65 63 74 20 68 61 73 20 62 65 65  e object has bee
8180: 6e 20 72 65 67 69 73 74 65 72 65 64 2e 0a 2a 2a  n registered..**
8190: 0a 2a 2a 20 54 68 65 20 7a 4e 61 6d 65 20 66 69  .** The zName fi
81a0: 65 6c 64 20 68 6f 6c 64 73 20 74 68 65 20 6e 61  eld holds the na
81b0: 6d 65 20 6f 66 20 74 68 65 20 56 46 53 20 6d 6f  me of the VFS mo
81c0: 64 75 6c 65 2e 20 20 54 68 65 20 6e 61 6d 65 20  dule.  The name 
81d0: 6d 75 73 74 0a 2a 2a 20 62 65 20 75 6e 69 71 75  must.** be uniqu
81e0: 65 20 61 63 72 6f 73 73 20 61 6c 6c 20 56 46 53  e across all VFS
81f0: 20 6d 6f 64 75 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20   modules..**.** 
8200: 7b 48 31 31 31 34 31 7d 20 53 51 4c 69 74 65 20  {H11141} SQLite 
8210: 77 69 6c 6c 20 67 75 61 72 61 6e 74 65 65 20 74  will guarantee t
8220: 68 61 74 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d  hat the zFilenam
8230: 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78  e parameter to x
8240: 4f 70 65 6e 0a 2a 2a 20 69 73 20 65 69 74 68 65  Open.** is eithe
8250: 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  r a NULL pointer
8260: 20 6f 72 20 73 74 72 69 6e 67 20 6f 62 74 61 69   or string obtai
8270: 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 78 46 75 6c  ned.** from xFul
8280: 6c 50 61 74 68 6e 61 6d 65 28 29 2e 20 20 53 51  lPathname().  SQ
8290: 4c 69 74 65 20 66 75 72 74 68 65 72 20 67 75 61  Lite further gua
82a0: 72 61 6e 74 65 65 73 20 74 68 61 74 0a 2a 2a 20  rantees that.** 
82b0: 74 68 65 20 73 74 72 69 6e 67 20 77 69 6c 6c 20  the string will 
82c0: 62 65 20 76 61 6c 69 64 20 61 6e 64 20 75 6e 63  be valid and unc
82d0: 68 61 6e 67 65 64 20 75 6e 74 69 6c 20 78 43 6c  hanged until xCl
82e0: 6f 73 65 28 29 20 69 73 0a 2a 2a 20 63 61 6c 6c  ose() is.** call
82f0: 65 64 2e 20 7b 45 4e 44 7d 20 20 42 65 63 61 75  ed. {END}  Becau
8300: 73 65 20 6f 66 20 74 68 65 20 70 72 65 76 69 6f  se of the previo
8310: 75 73 20 73 65 6e 74 65 6e 73 65 2c 0a 2a 2a 20  us sentense,.** 
8320: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  the [sqlite3_fil
8330: 65 5d 20 63 61 6e 20 73 61 66 65 6c 79 20 73 74  e] can safely st
8340: 6f 72 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  ore a pointer to
8350: 20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65   the.** filename
8360: 20 69 66 20 69 74 20 6e 65 65 64 73 20 74 6f 20   if it needs to 
8370: 72 65 6d 65 6d 62 65 72 20 74 68 65 20 66 69 6c  remember the fil
8380: 65 6e 61 6d 65 20 66 6f 72 20 73 6f 6d 65 20 72  ename for some r
8390: 65 61 73 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65  eason..** If the
83a0: 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d   zFilename param
83b0: 65 74 65 72 20 69 73 20 78 4f 70 65 6e 20 69 73  eter is xOpen is
83c0: 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
83d0: 74 68 65 6e 20 78 4f 70 65 6e 0a 2a 2a 20 6d 75  then xOpen.** mu
83e0: 73 74 20 69 6e 76 69 74 65 20 69 74 73 20 6f 77  st invite its ow
83f0: 6e 20 74 65 6d 70 6f 72 61 72 79 20 6e 61 6d 65  n temporary name
8400: 20 66 6f 72 20 74 68 65 20 66 69 6c 65 2e 20 20   for the file.  
8410: 57 68 65 6e 65 76 65 72 20 74 68 65 20 0a 2a 2a  Whenever the .**
8420: 20 78 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d   xFilename param
8430: 65 74 65 72 20 69 73 20 4e 55 4c 4c 20 69 74 20  eter is NULL it 
8440: 77 69 6c 6c 20 61 6c 73 6f 20 62 65 20 74 68 65  will also be the
8450: 20 63 61 73 65 20 74 68 61 74 20 74 68 65 0a 2a   case that the.*
8460: 2a 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65  * flags paramete
8470: 72 20 77 69 6c 6c 20 69 6e 63 6c 75 64 65 20 5b  r will include [
8480: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45  SQLITE_OPEN_DELE
8490: 54 45 4f 4e 43 4c 4f 53 45 5d 2e 0a 2a 2a 0a 2a  TEONCLOSE]..**.*
84a0: 2a 20 7b 48 31 31 31 34 32 7d 20 54 68 65 20 66  * {H11142} The f
84b0: 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f  lags argument to
84c0: 20 78 4f 70 65 6e 28 29 20 69 6e 63 6c 75 64 65   xOpen() include
84d0: 73 20 61 6c 6c 20 62 69 74 73 20 73 65 74 20 69  s all bits set i
84e0: 6e 0a 2a 2a 20 74 68 65 20 66 6c 61 67 73 20 61  n.** the flags a
84f0: 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69  rgument to [sqli
8500: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 20  te3_open_v2()]. 
8510: 20 4f 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f   Or if [sqlite3_
8520: 6f 70 65 6e 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73  open()].** or [s
8530: 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d  qlite3_open16()]
8540: 20 69 73 20 75 73 65 64 2c 20 74 68 65 6e 20 66   is used, then f
8550: 6c 61 67 73 20 69 6e 63 6c 75 64 65 73 20 61 74  lags includes at
8560: 20 6c 65 61 73 74 0a 2a 2a 20 5b 53 51 4c 49 54   least.** [SQLIT
8570: 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45  E_OPEN_READWRITE
8580: 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  ] | [SQLITE_OPEN
8590: 5f 43 52 45 41 54 45 5d 2e 20 7b 45 4e 44 7d 0a  _CREATE]. {END}.
85a0: 2a 2a 20 49 66 20 78 4f 70 65 6e 28 29 20 6f 70  ** If xOpen() op
85b0: 65 6e 73 20 61 20 66 69 6c 65 20 72 65 61 64 2d  ens a file read-
85c0: 6f 6e 6c 79 20 74 68 65 6e 20 69 74 20 73 65 74  only then it set
85d0: 73 20 2a 70 4f 75 74 46 6c 61 67 73 20 74 6f 0a  s *pOutFlags to.
85e0: 2a 2a 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49  ** include [SQLI
85f0: 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59  TE_OPEN_READONLY
8600: 5d 2e 20 20 4f 74 68 65 72 20 62 69 74 73 20 69  ].  Other bits i
8610: 6e 20 2a 70 4f 75 74 46 6c 61 67 73 20 6d 61 79  n *pOutFlags may
8620: 20 62 65 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 7b   be set..**.** {
8630: 48 31 31 31 34 33 7d 20 53 51 4c 69 74 65 20 77  H11143} SQLite w
8640: 69 6c 6c 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65  ill also add one
8650: 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e   of the followin
8660: 67 20 66 6c 61 67 73 20 74 6f 20 74 68 65 20 78  g flags to the x
8670: 4f 70 65 6e 28 29 0a 2a 2a 20 63 61 6c 6c 2c 20  Open().** call, 
8680: 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65  depending on the
8690: 20 6f 62 6a 65 63 74 20 62 65 69 6e 67 20 6f 70   object being op
86a0: 65 6e 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  ened:.**.** <ul>
86b0: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
86c0: 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 0a  E_OPEN_MAIN_DB].
86d0: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
86e0: 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e  _OPEN_MAIN_JOURN
86f0: 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  AL].** <li>  [SQ
8700: 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44  LITE_OPEN_TEMP_D
8710: 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  B].** <li>  [SQL
8720: 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f  ITE_OPEN_TEMP_JO
8730: 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20  URNAL].** <li>  
8740: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41  [SQLITE_OPEN_TRA
8750: 4e 53 49 45 4e 54 5f 44 42 5d 0a 2a 2a 20 3c 6c  NSIENT_DB].** <l
8760: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
8770: 5f 53 55 42 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20  _SUBJOURNAL].** 
8780: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
8790: 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41  EN_MASTER_JOURNA
87a0: 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 20 7b 45 4e 44  L].** </ul> {END
87b0: 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 6c 65  }.**.** The file
87c0: 20 49 2f 4f 20 69 6d 70 6c 65 6d 65 6e 74 61 74   I/O implementat
87d0: 69 6f 6e 20 63 61 6e 20 75 73 65 20 74 68 65 20  ion can use the 
87e0: 6f 62 6a 65 63 74 20 74 79 70 65 20 66 6c 61 67  object type flag
87f0: 73 20 74 6f 0a 2a 2a 20 63 68 61 6e 67 65 20 74  s to.** change t
8800: 68 65 20 77 61 79 20 69 74 20 64 65 61 6c 73 20  he way it deals 
8810: 77 69 74 68 20 66 69 6c 65 73 2e 20 20 46 6f 72  with files.  For
8820: 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70   example, an app
8830: 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 74 68 61 74  lication.** that
8840: 20 64 6f 65 73 20 6e 6f 74 20 63 61 72 65 20 61   does not care a
8850: 62 6f 75 74 20 63 72 61 73 68 20 72 65 63 6f 76  bout crash recov
8860: 65 72 79 20 6f 72 20 72 6f 6c 6c 62 61 63 6b 20  ery or rollback 
8870: 6d 69 67 68 74 20 6d 61 6b 65 0a 2a 2a 20 74 68  might make.** th
8880: 65 20 6f 70 65 6e 20 6f 66 20 61 20 6a 6f 75 72  e open of a jour
8890: 6e 61 6c 20 66 69 6c 65 20 61 20 6e 6f 2d 6f 70  nal file a no-op
88a0: 2e 20 20 57 72 69 74 65 73 20 74 6f 20 74 68 69  .  Writes to thi
88b0: 73 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 0a  s journal would.
88c0: 2a 2a 20 61 6c 73 6f 20 62 65 20 6e 6f 2d 6f 70  ** also be no-op
88d0: 73 2c 20 61 6e 64 20 61 6e 79 20 61 74 74 65 6d  s, and any attem
88e0: 70 74 20 74 6f 20 72 65 61 64 20 74 68 65 20 6a  pt to read the j
88f0: 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 20 72 65 74  ournal would ret
8900: 75 72 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f  urn.** SQLITE_IO
8910: 45 52 52 2e 20 20 4f 72 20 74 68 65 20 69 6d 70  ERR.  Or the imp
8920: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 69 67 68  lementation migh
8930: 74 20 72 65 63 6f 67 6e 69 7a 65 20 74 68 61 74  t recognize that
8940: 20 61 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66   a database.** f
8950: 69 6c 65 20 77 69 6c 6c 20 62 65 20 64 6f 69 6e  ile will be doin
8960: 67 20 70 61 67 65 2d 61 6c 69 67 6e 65 64 20 73  g page-aligned s
8970: 65 63 74 6f 72 20 72 65 61 64 73 20 61 6e 64 20  ector reads and 
8980: 77 72 69 74 65 73 20 69 6e 20 61 20 72 61 6e 64  writes in a rand
8990: 6f 6d 0a 2a 2a 20 6f 72 64 65 72 20 61 6e 64 20  om.** order and 
89a0: 73 65 74 20 75 70 20 69 74 73 20 49 2f 4f 20 73  set up its I/O s
89b0: 75 62 73 79 73 74 65 6d 20 61 63 63 6f 72 64 69  ubsystem accordi
89c0: 6e 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  ngly..**.** SQLi
89d0: 74 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 61 64  te might also ad
89e0: 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c  d one of the fol
89f0: 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20 74 6f 20  lowing flags to 
8a00: 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64  the xOpen method
8a10: 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
8a20: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45  <li> [SQLITE_OPE
8a30: 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d  N_DELETEONCLOSE]
8a40: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
8a50: 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d  _OPEN_EXCLUSIVE]
8a60: 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
8a70: 7b 48 31 31 31 34 35 7d 20 54 68 65 20 5b 53 51  {H11145} The [SQ
8a80: 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45  LITE_OPEN_DELETE
8a90: 4f 4e 43 4c 4f 53 45 5d 20 66 6c 61 67 20 6d 65  ONCLOSE] flag me
8aa0: 61 6e 73 20 74 68 65 20 66 69 6c 65 20 73 68 6f  ans the file sho
8ab0: 75 6c 64 20 62 65 0a 2a 2a 20 64 65 6c 65 74 65  uld be.** delete
8ac0: 64 20 77 68 65 6e 20 69 74 20 69 73 20 63 6c 6f  d when it is clo
8ad0: 73 65 64 2e 20 20 7b 48 31 31 31 34 36 7d 20 54  sed.  {H11146} T
8ae0: 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
8af0: 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a  DELETEONCLOSE].*
8b00: 2a 20 77 69 6c 6c 20 62 65 20 73 65 74 20 66 6f  * will be set fo
8b10: 72 20 54 45 4d 50 20 20 64 61 74 61 62 61 73 65  r TEMP  database
8b20: 73 2c 20 6a 6f 75 72 6e 61 6c 73 20 61 6e 64 20  s, journals and 
8b30: 66 6f 72 20 73 75 62 6a 6f 75 72 6e 61 6c 73 2e  for subjournals.
8b40: 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 31 34 37 7d 20  .**.** {H11147} 
8b50: 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  The [SQLITE_OPEN
8b60: 5f 45 58 43 4c 55 53 49 56 45 5d 20 66 6c 61 67  _EXCLUSIVE] flag
8b70: 20 6d 65 61 6e 73 20 74 68 65 20 66 69 6c 65 20   means the file 
8b80: 73 68 6f 75 6c 64 20 62 65 20 6f 70 65 6e 65 64  should be opened
8b90: 0a 2a 2a 20 66 6f 72 20 65 78 63 6c 75 73 69 76  .** for exclusiv
8ba0: 65 20 61 63 63 65 73 73 2e 20 20 54 68 69 73 20  e access.  This 
8bb0: 66 6c 61 67 20 69 73 20 73 65 74 20 66 6f 72 20  flag is set for 
8bc0: 61 6c 6c 20 66 69 6c 65 73 20 65 78 63 65 70 74  all files except
8bd0: 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6d 61 69 6e  .** for the main
8be0: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2e 0a   database file..
8bf0: 2a 2a 0a 2a 2a 20 7b 48 31 31 31 34 38 7d 20 41  **.** {H11148} A
8c00: 74 20 6c 65 61 73 74 20 73 7a 4f 73 46 69 6c 65  t least szOsFile
8c10: 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79   bytes of memory
8c20: 20 61 72 65 20 61 6c 6c 6f 63 61 74 65 64 20 62   are allocated b
8c30: 79 20 53 51 4c 69 74 65 0a 2a 2a 20 74 6f 20 68  y SQLite.** to h
8c40: 6f 6c 64 20 74 68 65 20 20 5b 73 71 6c 69 74 65  old the  [sqlite
8c50: 33 5f 66 69 6c 65 5d 20 73 74 72 75 63 74 75 72  3_file] structur
8c60: 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  e passed as the 
8c70: 74 68 69 72 64 0a 2a 2a 20 61 72 67 75 6d 65 6e  third.** argumen
8c80: 74 20 74 6f 20 78 4f 70 65 6e 2e 20 7b 45 4e 44  t to xOpen. {END
8c90: 7d 20 20 54 68 65 20 78 4f 70 65 6e 20 6d 65 74  }  The xOpen met
8ca0: 68 6f 64 20 64 6f 65 73 20 6e 6f 74 20 68 61 76  hod does not hav
8cb0: 65 20 74 6f 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65  e to.** allocate
8cc0: 20 74 68 65 20 73 74 72 75 63 74 75 72 65 3b 20   the structure; 
8cd0: 69 74 20 73 68 6f 75 6c 64 20 6a 75 73 74 20 66  it should just f
8ce0: 69 6c 6c 20 69 74 20 69 6e 2e 0a 2a 2a 0a 2a 2a  ill it in..**.**
8cf0: 20 7b 48 31 31 31 34 39 7d 20 54 68 65 20 66 6c   {H11149} The fl
8d00: 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ags argument to 
8d10: 78 41 63 63 65 73 73 28 29 20 6d 61 79 20 62 65  xAccess() may be
8d20: 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f   [SQLITE_ACCESS_
8d30: 45 58 49 53 54 53 5d 0a 2a 2a 20 74 6f 20 74 65  EXISTS].** to te
8d40: 73 74 20 66 6f 72 20 74 68 65 20 65 78 69 73 74  st for the exist
8d50: 65 6e 63 65 20 6f 66 20 61 20 66 69 6c 65 2c 20  ence of a file, 
8d60: 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53  or [SQLITE_ACCES
8d70: 53 5f 52 45 41 44 57 52 49 54 45 5d 20 74 6f 0a  S_READWRITE] to.
8d80: 2a 2a 20 74 65 73 74 20 77 68 65 74 68 65 72 20  ** test whether 
8d90: 61 20 66 69 6c 65 20 69 73 20 72 65 61 64 61 62  a file is readab
8da0: 6c 65 20 61 6e 64 20 77 72 69 74 61 62 6c 65 2c  le and writable,
8db0: 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 45   or [SQLITE_ACCE
8dc0: 53 53 5f 52 45 41 44 5d 0a 2a 2a 20 74 6f 20 74  SS_READ].** to t
8dd0: 65 73 74 20 77 68 65 74 68 65 72 20 61 20 66 69  est whether a fi
8de0: 6c 65 20 69 73 20 61 74 20 6c 65 61 73 74 20 72  le is at least r
8df0: 65 61 64 61 62 6c 65 2e 20 7b 45 4e 44 7d 20 20  eadable. {END}  
8e00: 54 68 65 20 66 69 6c 65 20 63 61 6e 20 62 65 20  The file can be 
8e10: 61 0a 2a 2a 20 64 69 72 65 63 74 6f 72 79 2e 0a  a.** directory..
8e20: 2a 2a 0a 2a 2a 20 7b 48 31 31 31 35 30 7d 20 53  **.** {H11150} S
8e30: 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 77 61 79  QLite will alway
8e40: 73 20 61 6c 6c 6f 63 61 74 65 20 61 74 20 6c 65  s allocate at le
8e50: 61 73 74 20 6d 78 50 61 74 68 6e 61 6d 65 2b 31  ast mxPathname+1
8e60: 20 62 79 74 65 73 20 66 6f 72 20 74 68 65 0a 2a   bytes for the.*
8e70: 2a 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 20  * output buffer 
8e80: 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 2e 20 7b  xFullPathname. {
8e90: 48 31 31 31 35 31 7d 20 54 68 65 20 65 78 61 63  H11151} The exac
8ea0: 74 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6f 75  t size of the ou
8eb0: 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 69  tput buffer.** i
8ec0: 73 20 61 6c 73 6f 20 70 61 73 73 65 64 20 61 73  s also passed as
8ed0: 20 61 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20   a parameter to 
8ee0: 62 6f 74 68 20 20 6d 65 74 68 6f 64 73 2e 20 7b  both  methods. {
8ef0: 45 4e 44 7d 20 20 49 66 20 74 68 65 20 6f 75 74  END}  If the out
8f00: 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 69 73  put buffer.** is
8f10: 20 6e 6f 74 20 6c 61 72 67 65 20 65 6e 6f 75 67   not large enoug
8f20: 68 2c 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f  h, [SQLITE_CANTO
8f30: 50 45 4e 5d 20 73 68 6f 75 6c 64 20 62 65 20 72  PEN] should be r
8f40: 65 74 75 72 6e 65 64 2e 20 53 69 6e 63 65 20 74  eturned. Since t
8f50: 68 69 73 20 69 73 0a 2a 2a 20 68 61 6e 64 6c 65  his is.** handle
8f60: 64 20 61 73 20 61 20 66 61 74 61 6c 20 65 72 72  d as a fatal err
8f70: 6f 72 20 62 79 20 53 51 4c 69 74 65 2c 20 76 66  or by SQLite, vf
8f80: 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  s implementation
8f90: 73 20 73 68 6f 75 6c 64 20 65 6e 64 65 61 76 6f  s should endeavo
8fa0: 72 0a 2a 2a 20 74 6f 20 70 72 65 76 65 6e 74 20  r.** to prevent 
8fb0: 74 68 69 73 20 62 79 20 73 65 74 74 69 6e 67 20  this by setting 
8fc0: 6d 78 50 61 74 68 6e 61 6d 65 20 74 6f 20 61 20  mxPathname to a 
8fd0: 73 75 66 66 69 63 69 65 6e 74 6c 79 20 6c 61 72  sufficiently lar
8fe0: 67 65 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20  ge value..**.** 
8ff0: 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28  The xRandomness(
9000: 29 2c 20 78 53 6c 65 65 70 28 29 2c 20 61 6e 64  ), xSleep(), and
9010: 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29 20   xCurrentTime() 
9020: 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 61 72  interfaces.** ar
9030: 65 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 61  e not strictly a
9040: 20 70 61 72 74 20 6f 66 20 74 68 65 20 66 69 6c   part of the fil
9050: 65 73 79 73 74 65 6d 2c 20 62 75 74 20 74 68 65  esystem, but the
9060: 79 20 61 72 65 0a 2a 2a 20 69 6e 63 6c 75 64 65  y are.** include
9070: 64 20 69 6e 20 74 68 65 20 56 46 53 20 73 74 72  d in the VFS str
9080: 75 63 74 75 72 65 20 66 6f 72 20 63 6f 6d 70 6c  ucture for compl
9090: 65 74 65 6e 65 73 73 2e 0a 2a 2a 20 54 68 65 20  eteness..** The 
90a0: 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 20 66 75  xRandomness() fu
90b0: 6e 63 74 69 6f 6e 20 61 74 74 65 6d 70 74 73 20  nction attempts 
90c0: 74 6f 20 72 65 74 75 72 6e 20 6e 42 79 74 65 73  to return nBytes
90d0: 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 67 6f 6f   bytes.** of goo
90e0: 64 2d 71 75 61 6c 69 74 79 20 72 61 6e 64 6f 6d  d-quality random
90f0: 6e 65 73 73 20 69 6e 74 6f 20 7a 4f 75 74 2e 20  ness into zOut. 
9100: 20 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   The return valu
9110: 65 20 69 73 0a 2a 2a 20 74 68 65 20 61 63 74 75  e is.** the actu
9120: 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  al number of byt
9130: 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73  es of randomness
9140: 20 6f 62 74 61 69 6e 65 64 2e 0a 2a 2a 20 54 68   obtained..** Th
9150: 65 20 78 53 6c 65 65 70 28 29 20 6d 65 74 68 6f  e xSleep() metho
9160: 64 20 63 61 75 73 65 73 20 74 68 65 20 63 61 6c  d causes the cal
9170: 6c 69 6e 67 20 74 68 72 65 61 64 20 74 6f 20 73  ling thread to s
9180: 6c 65 65 70 20 66 6f 72 20 61 74 0a 2a 2a 20 6c  leep for at.** l
9190: 65 61 73 74 20 74 68 65 20 6e 75 6d 62 65 72 20  east the number 
91a0: 6f 66 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73 20  of microseconds 
91b0: 67 69 76 65 6e 2e 20 20 54 68 65 20 78 43 75 72  given.  The xCur
91c0: 72 65 6e 74 54 69 6d 65 28 29 0a 2a 2a 20 6d 65  rentTime().** me
91d0: 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20 4a  thod returns a J
91e0: 75 6c 69 61 6e 20 44 61 79 20 4e 75 6d 62 65 72  ulian Day Number
91f0: 20 66 6f 72 20 74 68 65 20 63 75 72 72 65 6e 74   for the current
9200: 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65 2e 0a   date and time..
9210: 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
9220: 74 20 73 71 6c 69 74 65 33 5f 76 66 73 20 73 71  t sqlite3_vfs sq
9230: 6c 69 74 65 33 5f 76 66 73 3b 0a 73 74 72 75 63  lite3_vfs;.struc
9240: 74 20 73 71 6c 69 74 65 33 5f 76 66 73 20 7b 0a  t sqlite3_vfs {.
9250: 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 20    int iVersion; 
9260: 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 74             /* St
9270: 72 75 63 74 75 72 65 20 76 65 72 73 69 6f 6e 20  ructure version 
9280: 6e 75 6d 62 65 72 20 2a 2f 0a 20 20 69 6e 74 20  number */.  int 
9290: 73 7a 4f 73 46 69 6c 65 3b 20 20 20 20 20 20 20  szOsFile;       
92a0: 20 20 20 20 20 2f 2a 20 53 69 7a 65 20 6f 66 20       /* Size of 
92b0: 73 75 62 63 6c 61 73 73 65 64 20 73 71 6c 69 74  subclassed sqlit
92c0: 65 33 5f 66 69 6c 65 20 2a 2f 0a 20 20 69 6e 74  e3_file */.  int
92d0: 20 6d 78 50 61 74 68 6e 61 6d 65 3b 20 20 20 20   mxPathname;    
92e0: 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d        /* Maximum
92f0: 20 66 69 6c 65 20 70 61 74 68 6e 61 6d 65 20 6c   file pathname l
9300: 65 6e 67 74 68 20 2a 2f 0a 20 20 73 71 6c 69 74  ength */.  sqlit
9310: 65 33 5f 76 66 73 20 2a 70 4e 65 78 74 3b 20 20  e3_vfs *pNext;  
9320: 20 20 20 20 2f 2a 20 4e 65 78 74 20 72 65 67 69      /* Next regi
9330: 73 74 65 72 65 64 20 56 46 53 20 2a 2f 0a 20 20  stered VFS */.  
9340: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
9350: 65 3b 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65  e;       /* Name
9360: 20 6f 66 20 74 68 69 73 20 76 69 72 74 75 61 6c   of this virtual
9370: 20 66 69 6c 65 20 73 79 73 74 65 6d 20 2a 2f 0a   file system */.
9380: 20 20 76 6f 69 64 20 2a 70 41 70 70 44 61 74 61    void *pAppData
9390: 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 50 6f  ;          /* Po
93a0: 69 6e 74 65 72 20 74 6f 20 61 70 70 6c 69 63 61  inter to applica
93b0: 74 69 6f 6e 2d 73 70 65 63 69 66 69 63 20 64 61  tion-specific da
93c0: 74 61 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 4f  ta */.  int (*xO
93d0: 70 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 66 73  pen)(sqlite3_vfs
93e0: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
93f0: 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33 5f 66 69  Name, sqlite3_fi
9400: 6c 65 2a 2c 0a 20 20 20 20 20 20 20 20 20 20 20  le*,.           
9410: 20 20 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 69      int flags, i
9420: 6e 74 20 2a 70 4f 75 74 46 6c 61 67 73 29 3b 0a  nt *pOutFlags);.
9430: 20 20 69 6e 74 20 28 2a 78 44 65 6c 65 74 65 29    int (*xDelete)
9440: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
9450: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
9460: 2c 20 69 6e 74 20 73 79 6e 63 44 69 72 29 3b 0a  , int syncDir);.
9470: 20 20 69 6e 74 20 28 2a 78 41 63 63 65 73 73 29    int (*xAccess)
9480: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
9490: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
94a0: 2c 20 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74  , int flags, int
94b0: 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e   *pResOut);.  in
94c0: 74 20 28 2a 78 46 75 6c 6c 50 61 74 68 6e 61 6d  t (*xFullPathnam
94d0: 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  e)(sqlite3_vfs*,
94e0: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
94f0: 6d 65 2c 20 69 6e 74 20 6e 4f 75 74 2c 20 63 68  me, int nOut, ch
9500: 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 76 6f 69  ar *zOut);.  voi
9510: 64 20 2a 28 2a 78 44 6c 4f 70 65 6e 29 28 73 71  d *(*xDlOpen)(sq
9520: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73  lite3_vfs*, cons
9530: 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61 6d  t char *zFilenam
9540: 65 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c  e);.  void (*xDl
9550: 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33 5f 76  Error)(sqlite3_v
9560: 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20  fs*, int nByte, 
9570: 63 68 61 72 20 2a 7a 45 72 72 4d 73 67 29 3b 0a  char *zErrMsg);.
9580: 20 20 76 6f 69 64 20 2a 28 2a 78 44 6c 53 79 6d    void *(*xDlSym
9590: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 76  )(sqlite3_vfs*,v
95a0: 6f 69 64 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  oid*, const char
95b0: 20 2a 7a 53 79 6d 62 6f 6c 29 3b 0a 20 20 76 6f   *zSymbol);.  vo
95c0: 69 64 20 28 2a 78 44 6c 43 6c 6f 73 65 29 28 73  id (*xDlClose)(s
95d0: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 76 6f 69  qlite3_vfs*, voi
95e0: 64 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 61  d*);.  int (*xRa
95f0: 6e 64 6f 6d 6e 65 73 73 29 28 73 71 6c 69 74 65  ndomness)(sqlite
9600: 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74  3_vfs*, int nByt
9610: 65 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a  e, char *zOut);.
9620: 20 20 69 6e 74 20 28 2a 78 53 6c 65 65 70 29 28    int (*xSleep)(
9630: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e  sqlite3_vfs*, in
9640: 74 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73 29 3b  t microseconds);
9650: 0a 20 20 69 6e 74 20 28 2a 78 43 75 72 72 65 6e  .  int (*xCurren
9660: 74 54 69 6d 65 29 28 73 71 6c 69 74 65 33 5f 76  tTime)(sqlite3_v
9670: 66 73 2a 2c 20 64 6f 75 62 6c 65 2a 29 3b 0a 20  fs*, double*);. 
9680: 20 69 6e 74 20 28 2a 78 47 65 74 4c 61 73 74 45   int (*xGetLastE
9690: 72 72 6f 72 29 28 73 71 6c 69 74 65 33 5f 76 66  rror)(sqlite3_vf
96a0: 73 2a 2c 20 69 6e 74 2c 20 63 68 61 72 20 2a 29  s*, int, char *)
96b0: 3b 0a 20 20 2f 2a 20 4e 65 77 20 66 69 65 6c 64  ;.  /* New field
96c0: 73 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65  s may be appende
96d0: 64 20 69 6e 20 66 69 67 75 72 65 20 76 65 72 73  d in figure vers
96e0: 69 6f 6e 73 2e 20 20 54 68 65 20 69 56 65 72 73  ions.  The iVers
96f0: 69 6f 6e 0a 20 20 2a 2a 20 76 61 6c 75 65 20 77  ion.  ** value w
9700: 69 6c 6c 20 69 6e 63 72 65 6d 65 6e 74 20 77 68  ill increment wh
9710: 65 6e 65 76 65 72 20 74 68 69 73 20 68 61 70 70  enever this happ
9720: 65 6e 73 2e 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a  ens. */.};../*.*
9730: 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67  * CAPI3REF: Flag
9740: 73 20 66 6f 72 20 74 68 65 20 78 41 63 63 65 73  s for the xAcces
9750: 73 20 56 46 53 20 6d 65 74 68 6f 64 20 7b 48 31  s VFS method {H1
9760: 31 31 39 30 7d 20 3c 48 31 31 31 34 30 3e 0a 2a  1190} <H11140>.*
9770: 2a 0a 2a 2a 20 7b 48 31 31 31 39 31 7d 20 54 68  *.** {H11191} Th
9780: 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73  ese integer cons
9790: 74 61 6e 74 73 20 63 61 6e 20 62 65 20 75 73 65  tants can be use
97a0: 64 20 61 73 20 74 68 65 20 74 68 69 72 64 20 70  d as the third p
97b0: 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74  arameter to.** t
97c0: 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f  he xAccess metho
97d0: 64 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33  d of an [sqlite3
97e0: 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 20 7b 45  _vfs] object. {E
97f0: 4e 44 7d 20 20 54 68 65 79 20 64 65 74 65 72 6d  ND}  They determ
9800: 69 6e 65 0a 2a 2a 20 77 68 61 74 20 6b 69 6e 64  ine.** what kind
9810: 20 6f 66 20 70 65 72 6d 69 73 73 69 6f 6e 73 20   of permissions 
9820: 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68  the xAccess meth
9830: 6f 64 20 69 73 20 6c 6f 6f 6b 69 6e 67 20 66 6f  od is looking fo
9840: 72 2e 0a 2a 2a 20 7b 48 31 31 31 39 32 7d 20 57  r..** {H11192} W
9850: 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53  ith SQLITE_ACCES
9860: 53 5f 45 58 49 53 54 53 2c 20 74 68 65 20 78 41  S_EXISTS, the xA
9870: 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20  ccess method.** 
9880: 73 69 6d 70 6c 79 20 63 68 65 63 6b 73 20 77 68  simply checks wh
9890: 65 74 68 65 72 20 74 68 65 20 66 69 6c 65 20 65  ether the file e
98a0: 78 69 73 74 73 2e 0a 2a 2a 20 7b 48 31 31 31 39  xists..** {H1119
98b0: 33 7d 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41  3} With SQLITE_A
98c0: 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 2c  CCESS_READWRITE,
98d0: 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74   the xAccess met
98e0: 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68  hod.** checks wh
98f0: 65 74 68 65 72 20 74 68 65 20 66 69 6c 65 20 69  ether the file i
9900: 73 20 62 6f 74 68 20 72 65 61 64 61 62 6c 65 20  s both readable 
9910: 61 6e 64 20 77 72 69 74 61 62 6c 65 2e 0a 2a 2a  and writable..**
9920: 20 7b 48 31 31 31 39 34 7d 20 57 69 74 68 20 53   {H11194} With S
9930: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
9940: 44 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 6d  D, the xAccess m
9950: 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20  ethod.** checks 
9960: 77 68 65 74 68 65 72 20 74 68 65 20 66 69 6c 65  whether the file
9970: 20 69 73 20 72 65 61 64 61 62 6c 65 2e 0a 2a 2f   is readable..*/
9980: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
9990: 41 43 43 45 53 53 5f 45 58 49 53 54 53 20 20 20  ACCESS_EXISTS   
99a0: 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   0.#define SQLIT
99b0: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49  E_ACCESS_READWRI
99c0: 54 45 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c  TE 1.#define SQL
99d0: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 20  ITE_ACCESS_READ 
99e0: 20 20 20 20 20 32 0a 0a 2f 2a 0a 2a 2a 20 43 41       2../*.** CA
99f0: 50 49 33 52 45 46 3a 20 49 6e 69 74 69 61 6c 69  PI3REF: Initiali
9a00: 7a 65 20 54 68 65 20 53 51 4c 69 74 65 20 4c 69  ze The SQLite Li
9a10: 62 72 61 72 79 20 7b 48 31 30 31 33 30 7d 20 3c  brary {H10130} <
9a20: 53 32 30 30 30 30 3e 3c 53 33 30 31 30 30 3e 0a  S20000><S30100>.
9a30: 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
9a40: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72  3_initialize() r
9a50: 6f 75 74 69 6e 65 20 69 6e 69 74 69 61 6c 69 7a  outine initializ
9a60: 65 73 20 74 68 65 0a 2a 2a 20 53 51 4c 69 74 65  es the.** SQLite
9a70: 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65 20 73   library.  The s
9a80: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
9a90: 29 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 64 65 61  ) routine.** dea
9aa0: 6c 6c 6f 63 61 74 65 73 20 61 6e 79 20 72 65 73  llocates any res
9ab0: 6f 75 72 63 65 73 20 74 68 61 74 20 77 65 72 65  ources that were
9ac0: 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 73 71   allocated by sq
9ad0: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
9ae0: 28 29 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c  ()..**.** A call
9af0: 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74   to sqlite3_init
9b00: 69 61 6c 69 7a 65 28 29 20 69 73 20 61 6e 20 22  ialize() is an "
9b10: 65 66 66 65 63 74 69 76 65 22 20 63 61 6c 6c 20  effective" call 
9b20: 69 66 20 69 74 20 69 73 0a 2a 2a 20 74 68 65 20  if it is.** the 
9b30: 66 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74  first time sqlit
9b40: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
9b50: 69 73 20 69 6e 76 6f 6b 65 64 20 64 75 72 69 6e  is invoked durin
9b60: 67 20 74 68 65 20 6c 69 66 65 74 69 6d 65 20 6f  g the lifetime o
9b70: 66 0a 2a 2a 20 74 68 65 20 70 72 6f 63 65 73 73  f.** the process
9b80: 2c 20 6f 72 20 69 66 20 69 74 20 69 73 20 74 68  , or if it is th
9b90: 65 20 66 69 72 73 74 20 74 69 6d 65 20 73 71 6c  e first time sql
9ba0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
9bb0: 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20  ) is invoked.** 
9bc0: 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 61 6c 6c  following a call
9bd0: 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74   to sqlite3_shut
9be0: 64 6f 77 6e 28 29 2e 20 20 4f 6e 6c 79 20 61 6e  down().  Only an
9bf0: 20 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c 0a   effective call.
9c00: 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 69 6e  ** of sqlite3_in
9c10: 69 74 69 61 6c 69 7a 65 28 29 20 64 6f 65 73 20  itialize() does 
9c20: 61 6e 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  any initializati
9c30: 6f 6e 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 63  on.  All other c
9c40: 61 6c 6c 73 0a 2a 2a 20 61 72 65 20 68 61 72 6d  alls.** are harm
9c50: 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 0a  less no-ops..**.
9c60: 2a 2a 20 41 6d 6f 6e 67 20 6f 74 68 65 72 20 74  ** Among other t
9c70: 68 69 6e 67 73 2c 20 73 71 6c 69 74 65 33 5f 69  hings, sqlite3_i
9c80: 6e 69 74 69 61 6c 69 7a 65 28 29 20 73 68 61 6c  nitialize() shal
9c90: 6c 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69  l invoke.** sqli
9ca0: 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20  te3_os_init().  
9cb0: 53 69 6d 69 6c 61 72 6c 79 2c 20 73 71 6c 69 74  Similarly, sqlit
9cc0: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a  e3_shutdown().**
9cd0: 20 73 68 61 6c 6c 20 69 6e 76 6f 6b 65 20 73 71   shall invoke sq
9ce0: 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 0a  lite3_os_end()..
9cf0: 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
9d00: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72  3_initialize() r
9d10: 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 53  outine returns S
9d20: 51 4c 49 54 45 5f 4f 4b 20 6f 6e 20 73 75 63 63  QLITE_OK on succ
9d30: 65 73 73 2e 0a 2a 2a 20 49 66 20 66 6f 72 20 73  ess..** If for s
9d40: 6f 6d 65 20 72 65 61 73 6f 6e 2c 20 73 71 6c 69  ome reason, sqli
9d50: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
9d60: 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 69 6e   is unable to in
9d70: 69 74 69 61 6c 69 7a 65 0a 2a 2a 20 74 68 65 20  itialize.** the 
9d80: 6c 69 62 72 61 72 79 20 28 70 65 72 68 61 70 73  library (perhaps
9d90: 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20 74 6f   it is unable to
9da0: 20 61 6c 6c 6f 63 61 74 65 20 61 20 6e 65 65 64   allocate a need
9db0: 65 64 20 72 65 73 6f 75 72 63 65 20 73 75 63 68  ed resource such
9dc0: 0a 2a 2a 20 61 73 20 61 20 6d 75 74 65 78 29 20  .** as a mutex) 
9dd0: 69 74 20 72 65 74 75 72 6e 73 20 61 6e 20 5b 65  it returns an [e
9de0: 72 72 6f 72 20 63 6f 64 65 5d 20 6f 74 68 65 72  rror code] other
9df0: 20 74 68 61 6e 20 53 51 4c 49 54 45 5f 4f 4b 2e   than SQLITE_OK.
9e00: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
9e10: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
9e20: 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65  routine is calle
9e30: 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20  d internally by 
9e40: 6d 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 53 51  many other.** SQ
9e50: 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20  Lite interfaces 
9e60: 73 6f 20 74 68 61 74 20 61 6e 20 61 70 70 6c 69  so that an appli
9e70: 63 61 74 69 6f 6e 20 75 73 75 61 6c 6c 79 20 64  cation usually d
9e80: 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 0a  oes not need to.
9e90: 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65  ** invoke sqlite
9ea0: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64  3_initialize() d
9eb0: 69 72 65 63 74 6c 79 2e 20 20 46 6f 72 20 65 78  irectly.  For ex
9ec0: 61 6d 70 6c 65 2c 20 5b 73 71 6c 69 74 65 33 5f  ample, [sqlite3_
9ed0: 6f 70 65 6e 28 29 5d 0a 2a 2a 20 63 61 6c 6c 73  open()].** calls
9ee0: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
9ef0: 69 7a 65 28 29 20 73 6f 20 74 68 65 20 53 51 4c  ize() so the SQL
9f00: 69 74 65 20 6c 69 62 72 61 72 79 20 77 69 6c 6c  ite library will
9f10: 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c   be automaticall
9f20: 79 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a 65 64  y.** initialized
9f30: 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 6f   when [sqlite3_o
9f40: 70 65 6e 28 29 5d 20 69 73 20 63 61 6c 6c 65 64  pen()] is called
9f50: 20 69 66 20 69 74 20 68 61 73 20 6e 6f 74 20 62   if it has not b
9f60: 65 20 69 6e 69 74 69 61 6c 69 7a 65 64 0a 2a 2a  e initialized.**
9f70: 20 61 6c 72 65 61 64 79 2e 20 20 48 6f 77 65 76   already.  Howev
9f80: 65 72 2c 20 69 66 20 53 51 4c 69 74 65 20 69 73  er, if SQLite is
9f90: 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74   compiled with t
9fa0: 68 65 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41  he SQLITE_OMIT_A
9fb0: 55 54 4f 49 4e 49 54 0a 2a 2a 20 63 6f 6d 70 69  UTOINIT.** compi
9fc0: 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20  le-time option, 
9fd0: 74 68 65 6e 20 74 68 65 20 61 75 74 6f 6d 61 74  then the automat
9fe0: 69 63 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  ic calls to sqli
9ff0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
a000: 0a 2a 2a 20 61 72 65 20 6f 6d 69 74 74 65 64 20  .** are omitted 
a010: 61 6e 64 20 74 68 65 20 61 70 70 6c 69 63 61 74  and the applicat
a020: 69 6f 6e 20 6d 75 73 74 20 63 61 6c 6c 20 73 71  ion must call sq
a030: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
a040: 28 29 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 70  () directly.** p
a050: 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61 6e  rior to using an
a060: 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69  y other SQLite i
a070: 6e 74 65 72 66 61 63 65 2e 20 20 46 6f 72 20 6d  nterface.  For m
a080: 61 78 69 6d 75 6d 20 70 6f 72 74 61 62 69 6c 69  aximum portabili
a090: 74 79 2c 0a 2a 2a 20 69 74 20 69 73 20 72 65 63  ty,.** it is rec
a0a0: 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70  ommended that ap
a0b0: 70 6c 69 63 61 74 69 6f 6e 73 20 61 6c 77 61 79  plications alway
a0c0: 73 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33  s invoke sqlite3
a0d0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a  _initialize().**
a0e0: 20 64 69 72 65 63 74 6c 79 20 70 72 69 6f 72 20   directly prior 
a0f0: 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68  to using any oth
a100: 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  er SQLite interf
a110: 61 63 65 2e 20 20 46 75 74 75 72 65 20 72 65 6c  ace.  Future rel
a120: 65 61 73 65 73 0a 2a 2a 20 6f 66 20 53 51 4c 69  eases.** of SQLi
a130: 74 65 20 6d 61 79 20 72 65 71 75 69 72 65 20 74  te may require t
a140: 68 69 73 2e 20 20 49 6e 20 6f 74 68 65 72 20 77  his.  In other w
a150: 6f 72 64 73 2c 20 74 68 65 20 62 65 68 61 76 69  ords, the behavi
a160: 6f 72 20 65 78 68 69 62 69 74 65 64 0a 2a 2a 20  or exhibited.** 
a170: 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63  when SQLite is c
a180: 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 53 51 4c  ompiled with SQL
a190: 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49  ITE_OMIT_AUTOINI
a1a0: 54 20 6d 69 67 68 74 20 62 65 63 6f 6d 65 20 74  T might become t
a1b0: 68 65 0a 2a 2a 20 64 65 66 61 75 6c 74 20 62 65  he.** default be
a1c0: 68 61 76 69 6f 72 20 69 6e 20 73 6f 6d 65 20 66  havior in some f
a1d0: 75 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66  uture release of
a1e0: 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54   SQLite..**.** T
a1f0: 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  he sqlite3_os_in
a200: 69 74 28 29 20 72 6f 75 74 69 6e 65 20 64 6f 65  it() routine doe
a210: 73 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 74  s operating-syst
a220: 65 6d 20 73 70 65 63 69 66 69 63 0a 2a 2a 20 69  em specific.** i
a230: 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66  nitialization of
a240: 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72   the SQLite libr
a250: 61 72 79 2e 20 20 54 68 65 20 73 71 6c 69 74 65  ary.  The sqlite
a260: 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 72 6f  3_os_end().** ro
a270: 75 74 69 6e 65 20 75 6e 64 6f 65 73 20 74 68 65  utine undoes the
a280: 20 65 66 66 65 63 74 20 6f 66 20 73 71 6c 69 74   effect of sqlit
a290: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20 54  e3_os_init().  T
a2a0: 79 70 69 63 61 6c 20 74 61 73 6b 73 0a 2a 2a 20  ypical tasks.** 
a2b0: 70 65 72 66 6f 72 6d 65 64 20 62 79 20 74 68 65  performed by the
a2c0: 73 65 20 72 6f 75 74 69 6e 65 73 20 69 6e 63 6c  se routines incl
a2d0: 75 64 65 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f  ude allocation o
a2e0: 72 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a  r deallocation.*
a2f0: 2a 20 6f 66 20 73 74 61 74 69 63 20 72 65 73 6f  * of static reso
a300: 75 72 63 65 73 2c 20 69 6e 69 74 69 61 6c 69 7a  urces, initializ
a310: 61 74 69 6f 6e 20 6f 66 20 67 6c 6f 62 61 6c 20  ation of global 
a320: 76 61 72 69 61 62 6c 65 73 2c 0a 2a 2a 20 73 65  variables,.** se
a330: 74 74 69 6e 67 20 75 70 20 61 20 64 65 66 61 75  tting up a defau
a340: 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  lt [sqlite3_vfs]
a350: 20 6d 6f 64 75 6c 65 2c 20 6f 72 20 73 65 74 74   module, or sett
a360: 69 6e 67 20 75 70 0a 2a 2a 20 61 20 64 65 66 61  ing up.** a defa
a370: 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ult configuratio
a380: 6e 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  n using [sqlite3
a390: 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a 2a 0a 2a  _config()]..**.*
a3a0: 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
a3b0: 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 20 69  n should never i
a3c0: 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 73 71 6c  nvoke either sql
a3d0: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a  ite3_os_init().*
a3e0: 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f  * or sqlite3_os_
a3f0: 65 6e 64 28 29 20 64 69 72 65 63 74 6c 79 2e 20  end() directly. 
a400: 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
a410: 20 73 68 6f 75 6c 64 20 6f 6e 6c 79 20 69 6e 76   should only inv
a420: 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69  oke.** sqlite3_i
a430: 6e 69 74 69 61 6c 69 7a 65 28 29 20 61 6e 64 20  nitialize() and 
a440: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
a450: 28 29 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33  ().  The sqlite3
a460: 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 69 6e  _os_init().** in
a470: 74 65 72 66 61 63 65 20 69 73 20 63 61 6c 6c 65  terface is calle
a480: 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  d automatically 
a490: 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  by sqlite3_initi
a4a0: 61 6c 69 7a 65 28 29 20 61 6e 64 0a 2a 2a 20 73  alize() and.** s
a4b0: 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20  qlite3_os_end() 
a4c0: 69 73 20 63 61 6c 6c 65 64 20 62 79 20 73 71 6c  is called by sql
a4d0: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e  ite3_shutdown().
a4e0: 20 20 41 70 70 72 6f 70 72 69 61 74 65 0a 2a 2a    Appropriate.**
a4f0: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
a500: 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f   for sqlite3_os_
a510: 69 6e 69 74 28 29 20 61 6e 64 20 73 71 6c 69 74  init() and sqlit
a520: 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 61  e3_os_end().** a
a530: 72 65 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51  re built into SQ
a540: 4c 69 74 65 20 77 68 65 6e 20 69 74 20 69 73 20  Lite when it is 
a550: 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20 75 6e 69  compiled for uni
a560: 78 2c 20 77 69 6e 64 6f 77 73 2c 20 6f 72 20 6f  x, windows, or o
a570: 73 2f 32 2e 0a 2a 2a 20 57 68 65 6e 20 62 75 69  s/2..** When bui
a580: 6c 74 20 66 6f 72 20 6f 74 68 65 72 20 70 6c 61  lt for other pla
a590: 74 66 6f 72 6d 73 20 28 75 73 69 6e 67 20 74 68  tforms (using th
a5a0: 65 20 53 51 4c 49 54 45 5f 4f 53 5f 4f 54 48 45  e SQLITE_OS_OTHE
a5b0: 52 3d 31 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  R=1 compile-time
a5c0: 0a 2a 2a 20 6f 70 74 69 6f 6e 29 20 74 68 65 20  .** option) the 
a5d0: 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74  application must
a5e0: 20 73 75 70 70 6c 79 20 61 20 73 75 69 74 61 62   supply a suitab
a5f0: 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  le implementatio
a600: 6e 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  n for.** sqlite3
a610: 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73  _os_init() and s
a620: 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e  qlite3_os_end().
a630: 20 20 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e    An application
a640: 2d 73 75 70 70 6c 69 65 64 0a 2a 2a 20 69 6d 70  -supplied.** imp
a650: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73  lementation of s
a660: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
a670: 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65   or sqlite3_os_e
a680: 6e 64 28 29 0a 2a 2a 20 6d 75 73 74 20 72 65 74  nd().** must ret
a690: 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 6f 6e  urn SQLITE_OK on
a6a0: 20 73 75 63 63 65 73 73 20 61 6e 64 20 73 6f 6d   success and som
a6b0: 65 20 6f 74 68 65 72 20 5b 65 72 72 6f 72 20 63  e other [error c
a6c0: 6f 64 65 5d 20 75 70 6f 6e 0a 2a 2a 20 66 61 69  ode] upon.** fai
a6d0: 6c 75 72 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  lure..*/.int sql
a6e0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
a6f0: 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74  void);.int sqlit
a700: 65 33 5f 73 68 75 74 64 6f 77 6e 28 76 6f 69 64  e3_shutdown(void
a710: 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f  );.int sqlite3_o
a720: 73 5f 69 6e 69 74 28 76 6f 69 64 29 3b 0a 69 6e  s_init(void);.in
a730: 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  t sqlite3_os_end
a740: 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  (void);../*.** C
a750: 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75  API3REF: Configu
a760: 72 69 6e 67 20 54 68 65 20 53 51 4c 69 74 65 20  ring The SQLite 
a770: 4c 69 62 72 61 72 79 20 7b 48 31 30 31 34 35 7d  Library {H10145}
a780: 20 3c 53 32 30 30 30 30 3e 3c 53 33 30 32 30 30   <S20000><S30200
a790: 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41  >.** EXPERIMENTA
a7a0: 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  L.**.** The sqli
a7b0: 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74  te3_config() int
a7c0: 65 72 66 61 63 65 20 69 73 20 75 73 65 64 20 74  erface is used t
a7d0: 6f 20 6d 61 6b 65 20 67 6c 6f 62 61 6c 20 63 6f  o make global co
a7e0: 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63  nfiguration.** c
a7f0: 68 61 6e 67 65 73 20 74 6f 20 53 51 4c 69 74 65  hanges to SQLite
a800: 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 74 75 6e   in order to tun
a810: 65 20 53 51 4c 69 74 65 20 74 6f 20 74 68 65 20  e SQLite to the 
a820: 73 70 65 63 69 66 69 63 20 6e 65 65 64 73 20 6f  specific needs o
a830: 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61  f.** the applica
a840: 74 69 6f 6e 2e 20 20 54 68 65 20 64 65 66 61 75  tion.  The defau
a850: 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  lt configuration
a860: 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20   is recommended 
a870: 66 6f 72 20 6d 6f 73 74 0a 2a 2a 20 61 70 70 6c  for most.** appl
a880: 69 63 61 74 69 6f 6e 73 20 61 6e 64 20 73 6f 20  ications and so 
a890: 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20  this routine is 
a8a0: 75 73 75 61 6c 6c 79 20 6e 6f 74 20 6e 65 63 65  usually not nece
a8b0: 73 73 61 72 79 2e 20 20 49 74 20 69 73 0a 2a 2a  ssary.  It is.**
a8c0: 20 70 72 6f 76 69 64 65 64 20 74 6f 20 73 75 70   provided to sup
a8d0: 70 6f 72 74 20 72 61 72 65 20 61 70 70 6c 69 63  port rare applic
a8e0: 61 74 69 6f 6e 73 20 77 69 74 68 20 75 6e 75 73  ations with unus
a8f0: 75 61 6c 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a  ual needs..**.**
a900: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e   The sqlite3_con
a910: 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20  fig() interface 
a920: 69 73 20 6e 6f 74 20 74 68 72 65 61 64 73 61 66  is not threadsaf
a930: 65 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61 74  e.  The applicat
a940: 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e 73 75  ion.** must insu
a950: 72 65 20 74 68 61 74 20 6e 6f 20 6f 74 68 65 72  re that no other
a960: 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
a970: 65 73 20 61 72 65 20 69 6e 76 6f 6b 65 64 20 62  es are invoked b
a980: 79 20 6f 74 68 65 72 0a 2a 2a 20 74 68 72 65 61  y other.** threa
a990: 64 73 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33  ds while sqlite3
a9a0: 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 72 75 6e  _config() is run
a9b0: 6e 69 6e 67 2e 20 20 46 75 72 74 68 65 72 6d 6f  ning.  Furthermo
a9c0: 72 65 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66  re, sqlite3_conf
a9d0: 69 67 28 29 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79  ig().** may only
a9e0: 20 62 65 20 69 6e 76 6f 6b 65 64 20 70 72 69 6f   be invoked prio
a9f0: 72 20 74 6f 20 6c 69 62 72 61 72 79 20 69 6e 69  r to library ini
aa00: 74 69 61 6c 69 7a 61 74 69 6f 6e 20 75 73 69 6e  tialization usin
aa10: 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6e  g.** [sqlite3_in
aa20: 69 74 69 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61  itialize()] or a
aa30: 66 74 65 72 20 73 68 75 74 64 6f 77 6e 20 62 79  fter shutdown by
aa40: 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f   [sqlite3_shutdo
aa50: 77 6e 28 29 5d 2e 0a 2a 2a 20 4e 6f 74 65 2c 20  wn()]..** Note, 
aa60: 68 6f 77 65 76 65 72 2c 20 74 68 61 74 20 73 71  however, that sq
aa70: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 63  lite3_config() c
aa80: 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 73 20  an be called as 
aa90: 70 61 72 74 20 6f 66 20 74 68 65 0a 2a 2a 20 69  part of the.** i
aaa0: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
aab0: 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d   an application-
aac0: 64 65 66 69 6e 65 64 20 5b 73 71 6c 69 74 65 33  defined [sqlite3
aad0: 5f 6f 73 5f 69 6e 69 74 28 29 5d 2e 0a 2a 2a 0a  _os_init()]..**.
aae0: 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67  ** The first arg
aaf0: 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33  ument to sqlite3
ab00: 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 61 6e 20  _config() is an 
ab10: 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 53 51 4c 49  integer.** [SQLI
ab20: 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45  TE_CONFIG_SINGLE
ab30: 54 48 52 45 41 44 20 7c 20 63 6f 6e 66 69 67 75  THREAD | configu
ab40: 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 20 74  ration option] t
ab50: 68 61 74 20 64 65 74 65 72 6d 69 6e 65 73 0a 2a  hat determines.*
ab60: 2a 20 77 68 61 74 20 70 72 6f 70 65 72 74 79 20  * what property 
ab70: 6f 66 20 53 51 4c 69 74 65 20 69 73 20 74 6f 20  of SQLite is to 
ab80: 62 65 20 63 6f 6e 66 69 67 75 72 65 64 2e 20 20  be configured.  
ab90: 53 75 62 73 65 71 75 65 6e 74 20 61 72 67 75 6d  Subsequent argum
aba0: 65 6e 74 73 0a 2a 2a 20 76 61 72 79 20 64 65 70  ents.** vary dep
abb0: 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 5b 53  ending on the [S
abc0: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e  QLITE_CONFIG_SIN
abd0: 47 4c 45 54 48 52 45 41 44 20 7c 20 63 6f 6e 66  GLETHREAD | conf
abe0: 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
abf0: 5d 0a 2a 2a 20 69 6e 20 74 68 65 20 66 69 72 73  ].** in the firs
ac00: 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a  t argument..**.*
ac10: 2a 20 57 68 65 6e 20 61 20 63 6f 6e 66 69 67 75  * When a configu
ac20: 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73  ration option is
ac30: 20 73 65 74 2c 20 73 71 6c 69 74 65 33 5f 63 6f   set, sqlite3_co
ac40: 6e 66 69 67 28 29 20 72 65 74 75 72 6e 73 20 53  nfig() returns S
ac50: 51 4c 49 54 45 5f 4f 4b 2e 0a 2a 2a 20 49 66 20  QLITE_OK..** If 
ac60: 74 68 65 20 6f 70 74 69 6f 6e 20 69 73 20 75 6e  the option is un
ac70: 6b 6e 6f 77 6e 20 6f 72 20 53 51 4c 69 74 65 20  known or SQLite 
ac80: 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 73 65 74  is unable to set
ac90: 20 74 68 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 74   the option.** t
aca0: 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65  hen this routine
acb0: 20 72 65 74 75 72 6e 73 20 61 20 6e 6f 6e 2d 7a   returns a non-z
acc0: 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  ero [error code]
acd0: 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 50 45  ..*/.SQLITE_EXPE
ace0: 52 49 4d 45 4e 54 41 4c 20 69 6e 74 20 73 71 6c  RIMENTAL int sql
acf0: 69 74 65 33 5f 63 6f 6e 66 69 67 28 69 6e 74 2c  ite3_config(int,
ad00: 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   ...);../*.** CA
ad10: 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72  PI3REF: Configur
ad20: 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
ad30: 63 74 69 6f 6e 73 20 20 7b 48 31 30 31 38 30 7d  ctions  {H10180}
ad40: 20 3c 53 32 30 30 30 30 3e 0a 2a 2a 20 45 58 50   <S20000>.** EXP
ad50: 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20  ERIMENTAL.**.** 
ad60: 54 68 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 63  The sqlite3_db_c
ad70: 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63  onfig() interfac
ad80: 65 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b  e is used to mak
ad90: 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a  e configuration.
ada0: 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 61 20  ** changes to a 
adb0: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
adc0: 74 69 6f 6e 5d 2e 20 20 54 68 65 20 69 6e 74 65  tion].  The inte
add0: 72 66 61 63 65 20 69 73 20 73 69 6d 69 6c 61 72  rface is similar
ade0: 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
adf0: 63 6f 6e 66 69 67 28 29 5d 20 65 78 63 65 70 74  config()] except
ae00: 20 74 68 61 74 20 74 68 65 20 63 68 61 6e 67 65   that the change
ae10: 73 20 61 70 70 6c 79 20 74 6f 20 61 20 73 69 6e  s apply to a sin
ae20: 67 6c 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  gle.** [database
ae30: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 73 70   connection] (sp
ae40: 65 63 69 66 69 65 64 20 69 6e 20 74 68 65 20 66  ecified in the f
ae50: 69 72 73 74 20 61 72 67 75 6d 65 6e 74 29 2e 20  irst argument). 
ae60: 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   The.** sqlite3_
ae70: 64 62 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65  db_config() inte
ae80: 72 66 61 63 65 20 63 61 6e 20 6f 6e 6c 79 20 62  rface can only b
ae90: 65 20 75 73 65 64 20 69 6d 6d 65 64 69 61 74 65  e used immediate
aea0: 6c 79 20 61 66 74 65 72 0a 2a 2a 20 74 68 65 20  ly after.** the 
aeb0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
aec0: 69 6f 6e 20 69 73 20 63 72 65 61 74 65 64 20 75  ion is created u
aed0: 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6f 70  sing [sqlite3_op
aee0: 65 6e 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  en()],.** [sqlit
aef0: 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 6f 72  e3_open16()], or
af00: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
af10: 32 28 29 5d 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68  2()].  .**.** Th
af20: 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
af30: 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f  t to sqlite3_db_
af40: 63 6f 6e 66 69 67 28 44 2c 56 2c 2e 2e 2e 29 20  config(D,V,...) 
af50: 20 69 73 20 74 68 65 0a 2a 2a 20 63 6f 6e 66 69   is the.** confi
af60: 67 75 72 61 74 69 6f 6e 20 76 65 72 62 20 2d 20  guration verb - 
af70: 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 64 65 20  an integer code 
af80: 74 68 61 74 20 69 6e 64 69 63 61 74 65 73 20 77  that indicates w
af90: 68 61 74 0a 2a 2a 20 61 73 70 65 63 74 20 6f 66  hat.** aspect of
afa0: 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
afb0: 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62 65  onnection] is be
afc0: 69 6e 67 20 63 6f 6e 66 69 67 75 72 65 64 2e 0a  ing configured..
afd0: 2a 2a 20 54 68 65 20 6f 6e 6c 79 20 63 68 6f 69  ** The only choi
afe0: 63 65 20 66 6f 72 20 74 68 69 73 20 76 61 6c 75  ce for this valu
aff0: 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 44 42 43  e is [SQLITE_DBC
b000: 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d  ONFIG_LOOKASIDE]
b010: 2e 0a 2a 2a 20 4e 65 77 20 76 65 72 62 73 20 61  ..** New verbs a
b020: 72 65 20 6c 69 6b 65 6c 79 20 74 6f 20 62 65 20  re likely to be 
b030: 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20  added in future 
b040: 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69  releases of SQLi
b050: 74 65 2e 0a 2a 2a 20 41 64 64 69 74 69 6f 6e 61  te..** Additiona
b060: 6c 20 61 72 67 75 6d 65 6e 74 73 20 64 65 70 65  l arguments depe
b070: 6e 64 20 6f 6e 20 74 68 65 20 76 65 72 62 2e 0a  nd on the verb..
b080: 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 50 45 52 49  */.SQLITE_EXPERI
b090: 4d 45 4e 54 41 4c 20 69 6e 74 20 73 71 6c 69 74  MENTAL int sqlit
b0a0: 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 73 71 6c  e3_db_config(sql
b0b0: 69 74 65 33 2a 2c 20 69 6e 74 20 6f 70 2c 20 2e  ite3*, int op, .
b0c0: 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ..);../*.** CAPI
b0d0: 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c  3REF: Memory All
b0e0: 6f 63 61 74 69 6f 6e 20 52 6f 75 74 69 6e 65 73  ocation Routines
b0f0: 20 7b 48 31 30 31 35 35 7d 20 3c 53 32 30 31 32   {H10155} <S2012
b100: 30 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54  0>.** EXPERIMENT
b110: 41 4c 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74  AL.**.** An inst
b120: 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a  ance of this obj
b130: 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20  ect defines the 
b140: 69 6e 74 65 72 66 61 63 65 20 62 65 74 77 65 65  interface betwee
b150: 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20  n SQLite.** and 
b160: 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79  low-level memory
b170: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74   allocation rout
b180: 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  ines..**.** This
b190: 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 20   object is used 
b1a0: 69 6e 20 6f 6e 6c 79 20 6f 6e 65 20 70 6c 61 63  in only one plac
b1b0: 65 20 69 6e 20 74 68 65 20 53 51 4c 69 74 65 20  e in the SQLite 
b1c0: 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 41 20  interface..** A 
b1d0: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
b1e0: 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f  stance of this o
b1f0: 62 6a 65 63 74 20 69 73 20 74 68 65 20 61 72 67  bject is the arg
b200: 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 5b 73 71 6c  ument to.** [sql
b210: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77  ite3_config()] w
b220: 68 65 6e 20 74 68 65 20 63 6f 6e 66 69 67 75 72  hen the configur
b230: 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 0a  ation option is.
b240: 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ** [SQLITE_CONFI
b250: 47 5f 4d 41 4c 4c 4f 43 5d 2e 20 20 42 79 20 63  G_MALLOC].  By c
b260: 72 65 61 74 69 6e 67 20 61 6e 20 69 6e 73 74 61  reating an insta
b270: 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65  nce of this obje
b280: 63 74 0a 2a 2a 20 61 6e 64 20 70 61 73 73 69 6e  ct.** and passin
b290: 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  g it to [sqlite3
b2a0: 5f 63 6f 6e 66 69 67 28 29 5d 20 64 75 72 69 6e  _config()] durin
b2b0: 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c  g configuration,
b2c0: 20 61 6e 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69   an.** applicati
b2d0: 6f 6e 20 63 61 6e 20 73 70 65 63 69 66 79 20 61  on can specify a
b2e0: 6e 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6d 65  n alternative me
b2f0: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
b300: 73 75 62 73 79 73 74 65 6d 0a 2a 2a 20 66 6f 72  subsystem.** for
b310: 20 53 51 4c 69 74 65 20 74 6f 20 75 73 65 20 66   SQLite to use f
b320: 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 64 79  or all of its dy
b330: 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 6e 65 65  namic memory nee
b340: 64 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74  ds..**.** Note t
b350: 68 61 74 20 53 51 4c 69 74 65 20 63 6f 6d 65 73  hat SQLite comes
b360: 20 77 69 74 68 20 61 20 62 75 69 6c 74 2d 69 6e   with a built-in
b370: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
b380: 72 20 74 68 61 74 20 69 73 0a 2a 2a 20 70 65 72  r that is.** per
b390: 66 65 63 74 6c 79 20 61 64 65 71 75 61 74 65 20  fectly adequate 
b3a0: 66 6f 72 20 74 68 65 20 6f 76 65 72 77 68 65 6c  for the overwhel
b3b0: 6d 69 6e 67 20 6d 61 6a 6f 72 69 74 79 20 6f 66  ming majority of
b3c0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a   applications.**
b3d0: 20 61 6e 64 20 74 68 61 74 20 74 68 69 73 20 6f   and that this o
b3e0: 62 6a 65 63 74 20 69 73 20 6f 6e 6c 79 20 75 73  bject is only us
b3f0: 65 66 75 6c 20 74 6f 20 61 20 74 69 6e 79 20 6d  eful to a tiny m
b400: 69 6e 6f 72 69 74 79 20 6f 66 20 61 70 70 6c 69  inority of appli
b410: 63 61 74 69 6f 6e 73 0a 2a 2a 20 77 69 74 68 20  cations.** with 
b420: 73 70 65 63 69 61 6c 69 7a 65 64 20 6d 65 6d 6f  specialized memo
b430: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65  ry allocation re
b440: 71 75 69 72 65 6d 65 6e 74 73 2e 20 20 54 68 69  quirements.  Thi
b450: 73 20 6f 62 6a 65 63 74 20 69 73 0a 2a 2a 20 61  s object is.** a
b460: 6c 73 6f 20 75 73 65 64 20 64 75 72 69 6e 67 20  lso used during 
b470: 74 65 73 74 69 6e 67 20 6f 66 20 53 51 4c 69 74  testing of SQLit
b480: 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 73 70  e in order to sp
b490: 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e 61  ecify an alterna
b4a0: 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61  tive.** memory a
b4b0: 6c 6c 6f 63 61 74 6f 72 20 74 68 61 74 20 73 69  llocator that si
b4c0: 6d 75 6c 61 74 65 73 20 6d 65 6d 6f 72 79 20 6f  mulates memory o
b4d0: 75 74 2d 6f 66 2d 6d 65 6d 6f 72 79 20 63 6f 6e  ut-of-memory con
b4e0: 64 69 74 69 6f 6e 73 20 69 6e 0a 2a 2a 20 6f 72  ditions in.** or
b4f0: 64 65 72 20 74 6f 20 76 65 72 69 66 79 20 74 68  der to verify th
b500: 61 74 20 53 51 4c 69 74 65 20 72 65 63 6f 76 65  at SQLite recove
b510: 72 73 20 67 72 61 63 65 66 75 6c 6c 79 20 66 72  rs gracefully fr
b520: 6f 6d 20 73 75 63 68 0a 2a 2a 20 63 6f 6e 64 69  om such.** condi
b530: 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  tions..**.** The
b540: 20 78 4d 61 6c 6c 6f 63 2c 20 78 46 72 65 65 2c   xMalloc, xFree,
b550: 20 61 6e 64 20 78 52 65 61 6c 6c 6f 63 20 6d 65   and xRealloc me
b560: 74 68 6f 64 73 20 6d 75 73 74 20 77 6f 72 6b 20  thods must work 
b570: 6c 69 6b 65 20 74 68 65 0a 2a 2a 20 6d 61 6c 6c  like the.** mall
b580: 6f 63 28 29 2c 20 66 72 65 65 28 29 2c 20 61 6e  oc(), free(), an
b590: 64 20 72 65 61 6c 6c 6f 63 28 29 20 66 75 6e 63  d realloc() func
b5a0: 74 69 6f 6e 73 20 66 72 6f 6d 20 74 68 65 20 73  tions from the s
b5b0: 74 61 6e 64 61 72 64 20 6c 69 62 72 61 72 79 2e  tandard library.
b5c0: 0a 2a 2a 0a 2a 2a 20 78 53 69 7a 65 20 73 68 6f  .**.** xSize sho
b5d0: 75 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20 61  uld return the a
b5e0: 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f 66  llocated size of
b5f0: 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
b600: 74 69 6f 6e 0a 2a 2a 20 70 72 65 76 69 6f 75 73  tion.** previous
b610: 6c 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ly obtained from
b620: 20 78 4d 61 6c 6c 6f 63 20 6f 72 20 78 52 65 61   xMalloc or xRea
b630: 6c 6c 6f 63 2e 20 20 54 68 65 20 61 6c 6c 6f 63  lloc.  The alloc
b640: 61 74 65 64 20 73 69 7a 65 0a 2a 2a 20 69 73 20  ated size.** is 
b650: 61 6c 77 61 79 73 20 61 74 20 6c 65 61 73 74 20  always at least 
b660: 61 73 20 62 69 67 20 61 73 20 74 68 65 20 72 65  as big as the re
b670: 71 75 65 73 74 65 64 20 73 69 7a 65 20 62 75 74  quested size but
b680: 20 6d 61 79 20 62 65 20 6c 61 72 67 65 72 2e 0a   may be larger..
b690: 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 6f 75 6e 64  **.** The xRound
b6a0: 75 70 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e  up method return
b6b0: 73 20 77 68 61 74 20 77 6f 75 6c 64 20 62 65 20  s what would be 
b6c0: 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69  the allocated si
b6d0: 7a 65 20 6f 66 0a 2a 2a 20 61 20 6d 65 6d 6f 72  ze of.** a memor
b6e0: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 67 69 76  y allocation giv
b6f0: 65 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  en a particular 
b700: 72 65 71 75 65 73 74 65 64 20 73 69 7a 65 2e 20  requested size. 
b710: 20 4d 6f 73 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20   Most memory.** 
b720: 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64  allocators round
b730: 20 75 70 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63   up memory alloc
b740: 61 74 69 6f 6e 73 20 61 74 20 6c 65 61 73 74 20  ations at least 
b750: 74 6f 20 74 68 65 20 6e 65 78 74 20 6d 75 6c 74  to the next mult
b760: 69 70 6c 65 0a 2a 2a 20 6f 66 20 38 2e 20 20 53  iple.** of 8.  S
b770: 6f 6d 65 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72  ome allocators r
b780: 6f 75 6e 64 20 75 70 20 74 6f 20 61 20 6c 61 72  ound up to a lar
b790: 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 72 20  ger multiple or 
b7a0: 74 6f 20 61 20 70 6f 77 65 72 20 6f 66 20 32 2e  to a power of 2.
b7b0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 49 6e 69 74  .**.** The xInit
b7c0: 20 6d 65 74 68 6f 64 20 69 6e 69 74 69 61 6c 69   method initiali
b7d0: 7a 65 73 20 74 68 65 20 6d 65 6d 6f 72 79 20 61  zes the memory a
b7e0: 6c 6c 6f 63 61 74 6f 72 2e 20 20 28 46 6f 72 20  llocator.  (For 
b7f0: 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 69 74 20 6d  example,.** it m
b800: 69 67 68 74 20 61 6c 6c 6f 63 61 74 65 20 61 6e  ight allocate an
b810: 79 20 72 65 71 75 69 72 65 20 6d 75 74 65 78 65  y require mutexe
b820: 73 20 6f 72 20 69 6e 69 74 69 61 6c 69 7a 65 20  s or initialize 
b830: 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 0a 2a 2a  internal data.**
b840: 20 73 74 72 75 63 74 75 72 65 73 2e 20 20 54 68   structures.  Th
b850: 65 20 78 53 68 75 74 64 6f 77 6e 20 6d 65 74 68  e xShutdown meth
b860: 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64 20 28 69  od is invoked (i
b870: 6e 64 69 72 65 63 74 6c 79 29 20 62 79 0a 2a 2a  ndirectly) by.**
b880: 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f   [sqlite3_shutdo
b890: 77 6e 28 29 5d 20 61 6e 64 20 73 68 6f 75 6c 64  wn()] and should
b8a0: 20 64 65 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20   deallocate any 
b8b0: 72 65 73 6f 75 72 63 65 73 20 61 63 71 75 69 72  resources acquir
b8c0: 65 64 0a 2a 2a 20 62 79 20 78 49 6e 69 74 2e 20  ed.** by xInit. 
b8d0: 20 54 68 65 20 70 41 70 70 44 61 74 61 20 70 6f   The pAppData po
b8e0: 69 6e 74 65 72 20 69 73 20 75 73 65 64 20 61 73  inter is used as
b8f0: 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65   the only parame
b900: 74 65 72 20 74 6f 0a 2a 2a 20 78 49 6e 69 74 20  ter to.** xInit 
b910: 61 6e 64 20 78 53 68 75 74 64 6f 77 6e 2e 0a 2a  and xShutdown..*
b920: 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
b930: 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74   sqlite3_mem_met
b940: 68 6f 64 73 20 73 71 6c 69 74 65 33 5f 6d 65 6d  hods sqlite3_mem
b950: 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74  _methods;.struct
b960: 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74   sqlite3_mem_met
b970: 68 6f 64 73 20 7b 0a 20 20 76 6f 69 64 20 2a 28  hods {.  void *(
b980: 2a 78 4d 61 6c 6c 6f 63 29 28 69 6e 74 29 3b 20  *xMalloc)(int); 
b990: 20 20 20 20 20 20 20 20 2f 2a 20 4d 65 6d 6f 72          /* Memor
b9a0: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 75 6e  y allocation fun
b9b0: 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20  ction */.  void 
b9c0: 28 2a 78 46 72 65 65 29 28 76 6f 69 64 2a 29 3b  (*xFree)(void*);
b9d0: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46 72 65            /* Fre
b9e0: 65 20 61 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61  e a prior alloca
b9f0: 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a  tion */.  void *
ba00: 28 2a 78 52 65 61 6c 6c 6f 63 29 28 76 6f 69 64  (*xRealloc)(void
ba10: 2a 2c 69 6e 74 29 3b 20 20 2f 2a 20 52 65 73 69  *,int);  /* Resi
ba20: 7a 65 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e  ze an allocation
ba30: 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 69 7a   */.  int (*xSiz
ba40: 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20  e)(void*);      
ba50: 20 20 20 20 20 2f 2a 20 52 65 74 75 72 6e 20 74       /* Return t
ba60: 68 65 20 73 69 7a 65 20 6f 66 20 61 6e 20 61 6c  he size of an al
ba70: 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e  location */.  in
ba80: 74 20 28 2a 78 52 6f 75 6e 64 75 70 29 28 69 6e  t (*xRoundup)(in
ba90: 74 29 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20  t);          /* 
baa0: 52 6f 75 6e 64 20 75 70 20 72 65 71 75 65 73 74  Round up request
bab0: 20 73 69 7a 65 20 74 6f 20 61 6c 6c 6f 63 61 74   size to allocat
bac0: 69 6f 6e 20 73 69 7a 65 20 2a 2f 0a 20 20 69 6e  ion size */.  in
bad0: 74 20 28 2a 78 49 6e 69 74 29 28 76 6f 69 64 2a  t (*xInit)(void*
bae0: 29 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  );           /* 
baf0: 49 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20 6d  Initialize the m
bb00: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20  emory allocator 
bb10: 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 53 68 75  */.  void (*xShu
bb20: 74 64 6f 77 6e 29 28 76 6f 69 64 2a 29 3b 20 20  tdown)(void*);  
bb30: 20 20 20 20 2f 2a 20 44 65 69 6e 69 74 69 61 6c      /* Deinitial
bb40: 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 61  ize the memory a
bb50: 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f  llocator */.  vo
bb60: 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20  id *pAppData;   
bb70: 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
bb80: 41 72 67 75 6d 65 6e 74 20 74 6f 20 78 49 6e 69  Argument to xIni
bb90: 74 28 29 20 61 6e 64 20 78 53 68 75 74 64 6f 77  t() and xShutdow
bba0: 6e 28 29 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a  n() */.};../*.**
bbb0: 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69   CAPI3REF: Confi
bbc0: 67 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73  guration Options
bbd0: 20 7b 48 31 30 31 36 30 7d 20 3c 53 32 30 30 30   {H10160} <S2000
bbe0: 30 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54  0>.** EXPERIMENT
bbf0: 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63  AL.**.** These c
bc00: 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 74 68 65  onstants are the
bc10: 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 74 65 67   available integ
bc20: 65 72 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  er configuration
bc30: 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a   options that.**
bc40: 20 63 61 6e 20 62 65 20 70 61 73 73 65 64 20 61   can be passed a
bc50: 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  s the first argu
bc60: 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c  ment to the [sql
bc70: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69  ite3_config()] i
bc80: 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  nterface..**.** 
bc90: 4e 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  New configuratio
bca0: 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65  n options may be
bcb0: 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65   added in future
bcc0: 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c   releases of SQL
bcd0: 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67  ite..** Existing
bce0: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
bcf0: 70 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20  ptions might be 
bd00: 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41  discontinued.  A
bd10: 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73  pplications.** s
bd20: 68 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20  hould check the 
bd30: 72 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d  return code from
bd40: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
bd50: 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65  ()] to make sure
bd60: 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c   that.** the cal
bd70: 6c 20 77 6f 72 6b 65 64 2e 20 20 54 68 65 20 5b  l worked.  The [
bd80: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
bd90: 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c  ] interface will
bda0: 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e   return a.** non
bdb0: 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64  -zero [error cod
bdc0: 65 5d 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69  e] if a disconti
bdd0: 6e 75 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72  nued or unsuppor
bde0: 74 65 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ted configuratio
bdf0: 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69  n option.** is i
be00: 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64  nvoked..**.** <d
be10: 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  l>.** <dt>SQLITE
be20: 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48  _CONFIG_SINGLETH
be30: 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  READ</dt>.** <dd
be40: 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72  >There are no ar
be50: 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20  guments to this 
be60: 6f 70 74 69 6f 6e 2e 20 20 54 68 69 73 20 6f 70  option.  This op
be70: 74 69 6f 6e 20 64 69 73 61 62 6c 65 73 0a 2a 2a  tion disables.**
be80: 20 61 6c 6c 20 6d 75 74 65 78 69 6e 67 20 61 6e   all mutexing an
be90: 64 20 70 75 74 73 20 53 51 4c 69 74 65 20 69 6e  d puts SQLite in
bea0: 74 6f 20 61 20 6d 6f 64 65 20 77 68 65 72 65 20  to a mode where 
beb0: 69 74 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 75  it can only be u
bec0: 73 65 64 0a 2a 2a 20 62 79 20 61 20 73 69 6e 67  sed.** by a sing
bed0: 6c 65 20 74 68 72 65 61 64 2e 3c 2f 64 64 3e 0a  le thread.</dd>.
bee0: 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
bef0: 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
bf00: 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  EAD</dt>.** <dd>
bf10: 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67  There are no arg
bf20: 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f  uments to this o
bf30: 70 74 69 6f 6e 2e 20 20 54 68 69 73 20 6f 70 74  ption.  This opt
bf40: 69 6f 6e 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20  ion disables.** 
bf50: 6d 75 74 65 78 69 6e 67 20 6f 6e 20 5b 64 61 74  mutexing on [dat
bf60: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
bf70: 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20  ] and [prepared 
bf80: 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63  statement] objec
bf90: 74 73 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69  ts..** The appli
bfa0: 63 61 74 69 6f 6e 20 69 73 20 72 65 73 70 6f 6e  cation is respon
bfb0: 73 69 62 6c 65 20 66 6f 72 20 73 65 72 69 61 6c  sible for serial
bfc0: 69 7a 69 6e 67 20 61 63 63 65 73 73 20 74 6f 0a  izing access to.
bfd0: 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
bfe0: 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70  nections] and [p
bff0: 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
c000: 74 73 5d 2e 20 20 42 75 74 20 6f 74 68 65 72 20  ts].  But other 
c010: 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72 65 20 65  mutexes.** are e
c020: 6e 61 62 6c 65 64 20 73 6f 20 74 68 61 74 20 53  nabled so that S
c030: 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 73 61  QLite will be sa
c040: 66 65 20 74 6f 20 75 73 65 20 69 6e 20 61 20 6d  fe to use in a m
c050: 75 6c 74 69 2d 74 68 72 65 61 64 65 64 0a 2a 2a  ulti-threaded.**
c060: 20 65 6e 76 69 72 6f 6e 6d 65 6e 74 20 61 73 20   environment as 
c070: 6c 6f 6e 67 20 61 73 20 6e 6f 20 74 77 6f 20 74  long as no two t
c080: 68 72 65 61 64 73 20 61 74 74 65 6d 70 74 20 74  hreads attempt t
c090: 6f 20 75 73 65 20 74 68 65 20 73 61 6d 65 0a 2a  o use the same.*
c0a0: 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
c0b0: 65 63 74 69 6f 6e 5d 20 61 74 20 74 68 65 20 73  ection] at the s
c0c0: 61 6d 65 20 74 69 6d 65 2e 20 20 53 65 65 20 74  ame time.  See t
c0d0: 68 65 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  he [threading mo
c0e0: 64 65 5d 0a 2a 2a 20 64 6f 63 75 6d 65 6e 74 61  de].** documenta
c0f0: 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69 6f  tion for additio
c100: 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e  nal information.
c110: 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
c120: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45  SQLITE_CONFIG_SE
c130: 52 49 41 4c 49 5a 45 44 3c 2f 64 74 3e 0a 2a 2a  RIALIZED</dt>.**
c140: 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e   <dd>There are n
c150: 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74  o arguments to t
c160: 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 54 68 69  his option.  Thi
c170: 73 20 6f 70 74 69 6f 6e 20 65 6e 61 62 6c 65 73  s option enables
c180: 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 65 73 20  .** all mutexes 
c190: 69 6e 63 6c 75 64 69 6e 67 20 74 68 65 20 72 65  including the re
c1a0: 63 75 72 73 69 76 65 0a 2a 2a 20 6d 75 74 65 78  cursive.** mutex
c1b0: 65 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20  es on [database 
c1c0: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20  connection] and 
c1d0: 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
c1e0: 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a  ent] objects..**
c1f0: 20 49 6e 20 74 68 69 73 20 6d 6f 64 65 20 28 77   In this mode (w
c200: 68 69 63 68 20 69 73 20 74 68 65 20 64 65 66 61  hich is the defa
c210: 75 6c 74 20 77 68 65 6e 20 53 51 4c 69 74 65 20  ult when SQLite 
c220: 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
c230: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  .** [SQLITE_THRE
c240: 41 44 53 41 46 45 3d 31 5d 29 20 74 68 65 20 53  ADSAFE=1]) the S
c250: 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77 69  QLite library wi
c260: 6c 6c 20 69 74 73 65 6c 66 20 73 65 72 69 61 6c  ll itself serial
c270: 69 7a 65 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f  ize access.** to
c280: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
c290: 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65  ctions] and [pre
c2a0: 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73  pared statements
c2b0: 5d 20 73 6f 20 74 68 61 74 20 74 68 65 0a 2a 2a  ] so that the.**
c2c0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 20   application is 
c2d0: 66 72 65 65 20 74 6f 20 75 73 65 20 74 68 65 20  free to use the 
c2e0: 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63  same [database c
c2f0: 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 72 20 74 68  onnection] or th
c300: 65 0a 2a 2a 20 73 61 6d 65 20 5b 70 72 65 70 61  e.** same [prepa
c310: 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69  red statement] i
c320: 6e 20 64 69 66 66 65 72 65 6e 74 20 74 68 72 65  n different thre
c330: 61 64 73 20 61 74 20 74 68 65 20 73 61 6d 65 20  ads at the same 
c340: 74 69 6d 65 2e 0a 2a 2a 20 53 65 65 20 74 68 65  time..** See the
c350: 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
c360: 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20  ] documentation 
c370: 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69  for additional i
c380: 6e 66 6f 72 6d 61 74 69 6f 6e 2e 3c 2f 64 64 3e  nformation.</dd>
c390: 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
c3a0: 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 3c  E_CONFIG_MALLOC<
c3b0: 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73  /dt>.** <dd>This
c3c0: 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
c3d0: 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
c3e0: 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74  which is a point
c3f0: 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74  er to an.** inst
c400: 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c  ance of the [sql
c410: 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
c420: 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 68  ] structure.  Th
c430: 65 20 61 72 67 75 6d 65 6e 74 20 73 70 65 63 69  e argument speci
c440: 66 69 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74  fies.** alternat
c450: 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65  ive low-level me
c460: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
c470: 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75  routines to be u
c480: 73 65 64 20 69 6e 20 70 6c 61 63 65 20 6f 66 0a  sed in place of.
c490: 2a 2a 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c  ** the memory al
c4a0: 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65  location routine
c4b0: 73 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c  s built into SQL
c4c0: 69 74 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ite.</dd>.**.** 
c4d0: 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
c4e0: 47 5f 47 45 54 4d 41 4c 4c 4f 43 3c 2f 64 74 3e  G_GETMALLOC</dt>
c4f0: 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74  .** <dd>This opt
c500: 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
c510: 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63  le argument whic
c520: 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  h is a pointer t
c530: 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65  o an.** instance
c540: 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
c550: 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74  _mem_methods] st
c560: 72 75 63 74 75 72 65 2e 20 20 54 68 65 20 5b 73  ructure.  The [s
c570: 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
c580: 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65  ds].** structure
c590: 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20   is filled with 
c5a0: 74 68 65 20 63 75 72 72 65 6e 74 6c 79 20 64 65  the currently de
c5b0: 66 69 6e 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c  fined memory all
c5c0: 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73  ocation routines
c5d0: 2e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e  ..** This option
c5e0: 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
c5f0: 6f 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66  overload the def
c600: 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ault memory allo
c610: 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e  cation.** routin
c620: 65 73 20 77 69 74 68 20 61 20 77 72 61 70 70 65  es with a wrappe
c630: 72 20 74 68 61 74 20 73 69 6d 75 6c 61 74 69 6f  r that simulatio
c640: 6e 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ns memory alloca
c650: 74 69 6f 6e 20 66 61 69 6c 75 72 65 20 6f 72 0a  tion failure or.
c660: 2a 2a 20 74 72 61 63 6b 73 20 6d 65 6d 6f 72 79  ** tracks memory
c670: 20 75 73 61 67 65 2c 20 66 6f 72 20 65 78 61 6d   usage, for exam
c680: 70 6c 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ple.</dd>.**.** 
c690: 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
c6a0: 47 5f 4d 45 4d 53 54 41 54 55 53 3c 2f 64 74 3e  G_MEMSTATUS</dt>
c6b0: 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74  .** <dd>This opt
c6c0: 69 6f 6e 20 74 61 6b 65 73 20 73 69 6e 67 6c 65  ion takes single
c6d0: 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 79 70   argument of typ
c6e0: 65 20 69 6e 74 2c 20 69 6e 74 65 72 70 72 65 74  e int, interpret
c6f0: 65 64 20 61 73 20 61 20 0a 2a 2a 20 62 6f 6f 6c  ed as a .** bool
c700: 65 61 6e 2c 20 77 68 69 63 68 20 65 6e 61 62 6c  ean, which enabl
c710: 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74  es or disables t
c720: 68 65 20 63 6f 6c 6c 65 63 74 69 6f 6e 20 6f 66  he collection of
c730: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
c740: 6f 6e 20 0a 2a 2a 20 73 74 61 74 69 73 74 69 63  on .** statistic
c750: 73 2e 20 57 68 65 6e 20 64 69 73 61 62 6c 65 64  s. When disabled
c760: 2c 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  , the following 
c770: 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
c780: 73 20 62 65 63 6f 6d 65 20 0a 2a 2a 20 6e 6f 6e  s become .** non
c790: 2d 6f 70 65 72 61 74 69 6f 6e 61 6c 3a 0a 2a 2a  -operational:.**
c7a0: 20 20 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69     <ul>.**   <li
c7b0: 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  > [sqlite3_memor
c7c0: 79 5f 75 73 65 64 28 29 5d 0a 2a 2a 20 20 20 3c  y_used()].**   <
c7d0: 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  li> [sqlite3_mem
c7e0: 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d  ory_highwater()]
c7f0: 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69  .**   <li> [sqli
c800: 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69  te3_soft_heap_li
c810: 6d 69 74 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e  mit()].**   <li>
c820: 20 5b 73 71 6c 69 74 65 33 5f 73 74 61 74 75 73   [sqlite3_status
c830: 28 29 5d 0a 2a 2a 20 20 20 3c 2f 75 6c 3e 0a 2a  ()].**   </ul>.*
c840: 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  * </dd>.**.** <d
c850: 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
c860: 53 43 52 41 54 43 48 3c 2f 64 74 3e 0a 2a 2a 20  SCRATCH</dt>.** 
c870: 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20  <dd>This option 
c880: 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61 74  specifies a stat
c890: 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72  ic memory buffer
c8a0: 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e   that SQLite can
c8b0: 20 75 73 65 20 66 6f 72 0a 2a 2a 20 73 63 72 61   use for.** scra
c8c0: 74 63 68 20 6d 65 6d 6f 72 79 2e 20 20 54 68 65  tch memory.  The
c8d0: 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72 67  re are three arg
c8e0: 75 6d 65 6e 74 73 3a 20 20 41 20 70 6f 69 6e 74  uments:  A point
c8f0: 65 72 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79  er to the memory
c900: 2c 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66  , the.** size of
c910: 20 65 61 63 68 20 73 63 72 61 74 63 68 20 62 75   each scratch bu
c920: 66 66 65 72 20 28 73 7a 29 2c 20 61 6e 64 20 74  ffer (sz), and t
c930: 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 75 66  he number of buf
c940: 66 65 72 73 20 28 4e 29 2e 20 20 54 68 65 20 73  fers (N).  The s
c950: 7a 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6d 75  z.** argument mu
c960: 73 74 20 62 65 20 61 20 6d 75 6c 74 69 70 6c 65  st be a multiple
c970: 20 6f 66 20 31 36 2e 20 54 68 65 20 73 7a 20 70   of 16. The sz p
c980: 61 72 61 6d 65 74 65 72 20 73 68 6f 75 6c 64 20  arameter should 
c990: 62 65 20 61 20 66 65 77 20 62 79 74 65 73 0a 2a  be a few bytes.*
c9a0: 2a 20 6c 61 72 67 65 72 20 74 68 61 6e 20 74 68  * larger than th
c9b0: 65 20 61 63 74 75 61 6c 20 73 63 72 61 74 63 68  e actual scratch
c9c0: 20 73 70 61 63 65 20 72 65 71 75 69 72 65 64 20   space required 
c9d0: 64 75 65 20 69 6e 74 65 72 6e 61 6c 20 6f 76 65  due internal ove
c9e0: 72 68 65 61 64 2e 0a 2a 2a 20 54 68 65 20 66 69  rhead..** The fi
c9f0: 72 73 74 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  rst.** argument 
ca00: 73 68 6f 75 6c 64 20 70 6f 69 6e 74 20 74 6f 20  should point to 
ca10: 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 66  an allocation of
ca20: 20 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62   at least sz*N b
ca30: 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a  ytes of memory..
ca40: 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75  ** SQLite will u
ca50: 73 65 20 6e 6f 20 6d 6f 72 65 20 74 68 61 6e 20  se no more than 
ca60: 6f 6e 65 20 73 63 72 61 74 63 68 20 62 75 66 66  one scratch buff
ca70: 65 72 20 61 74 20 6f 6e 63 65 20 70 65 72 20 74  er at once per t
ca80: 68 72 65 61 64 2c 20 73 6f 0a 2a 2a 20 4e 20 73  hread, so.** N s
ca90: 68 6f 75 6c 64 20 62 65 20 73 65 74 20 74 6f 20  hould be set to 
caa0: 74 68 65 20 65 78 70 65 63 74 65 64 20 6d 61 78  the expected max
cab0: 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74  imum number of t
cac0: 68 72 65 61 64 73 2e 20 20 54 68 65 20 73 7a 0a  hreads.  The sz.
cad0: 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 73 68 6f  ** parameter sho
cae0: 75 6c 64 20 62 65 20 36 20 74 69 6d 65 73 20 74  uld be 6 times t
caf0: 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6c  he size of the l
cb00: 61 72 67 65 73 74 20 64 61 74 61 62 61 73 65 20  argest database 
cb10: 70 61 67 65 20 73 69 7a 65 2e 0a 2a 2a 20 53 63  page size..** Sc
cb20: 72 61 74 63 68 20 62 75 66 66 65 72 73 20 61 72  ratch buffers ar
cb30: 65 20 75 73 65 64 20 61 73 20 70 61 72 74 20 6f  e used as part o
cb40: 66 20 74 68 65 20 62 74 72 65 65 20 62 61 6c 61  f the btree bala
cb50: 6e 63 65 20 6f 70 65 72 61 74 69 6f 6e 2e 20 20  nce operation.  
cb60: 49 66 0a 2a 2a 20 54 68 65 20 62 74 72 65 65 20  If.** The btree 
cb70: 62 61 6c 61 6e 63 65 72 20 6e 65 65 64 73 20 61  balancer needs a
cb80: 64 64 69 74 69 6f 6e 61 6c 20 6d 65 6d 6f 72 79  dditional memory
cb90: 20 62 65 79 6f 6e 64 20 77 68 61 74 20 69 73 20   beyond what is 
cba0: 70 72 6f 76 69 64 65 64 20 62 79 0a 2a 2a 20 73  provided by.** s
cbb0: 63 72 61 74 63 68 20 62 75 66 66 65 72 73 20 6f  cratch buffers o
cbc0: 72 20 69 66 20 6e 6f 20 73 63 72 61 74 63 68 20  r if no scratch 
cbd0: 62 75 66 66 65 72 20 73 70 61 63 65 20 69 73 20  buffer space is 
cbe0: 73 70 65 63 69 66 69 65 64 2c 20 74 68 65 6e 20  specified, then 
cbf0: 53 51 4c 69 74 65 0a 2a 2a 20 67 6f 65 73 20 74  SQLite.** goes t
cc00: 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  o [sqlite3_mallo
cc10: 63 28 29 5d 20 74 6f 20 6f 62 74 61 69 6e 20 74  c()] to obtain t
cc20: 68 65 20 6d 65 6d 6f 72 79 20 69 74 20 6e 65 65  he memory it nee
cc30: 64 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  ds.</dd>.**.** <
cc40: 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
cc50: 5f 50 41 47 45 43 41 43 48 45 3c 2f 64 74 3e 0a  _PAGECACHE</dt>.
cc60: 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69  ** <dd>This opti
cc70: 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 20 73  on specifies a s
cc80: 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66  tatic memory buf
cc90: 66 65 72 20 74 68 61 74 20 53 51 4c 69 74 65 20  fer that SQLite 
cca0: 63 61 6e 20 75 73 65 20 66 6f 72 0a 2a 2a 20 74  can use for.** t
ccb0: 68 65 20 64 61 74 61 62 61 73 65 20 70 61 67 65  he database page
ccc0: 20 63 61 63 68 65 2e 20 20 54 68 65 72 65 20 61   cache.  There a
ccd0: 72 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e  re three argumen
cce0: 74 73 3a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f  ts: A pointer to
ccf0: 20 74 68 65 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20   the.** memory, 
cd00: 74 68 65 20 73 69 7a 65 20 6f 66 20 65 61 63 68  the size of each
cd10: 20 70 61 67 65 20 62 75 66 66 65 72 20 28 73 7a   page buffer (sz
cd20: 29 2c 20 61 6e 64 20 74 68 65 20 6e 75 6d 62 65  ), and the numbe
cd30: 72 20 6f 66 20 70 61 67 65 73 20 28 4e 29 2e 0a  r of pages (N)..
cd40: 2a 2a 20 54 68 65 20 73 7a 20 61 72 67 75 6d 65  ** The sz argume
cd50: 6e 74 20 6d 75 73 74 20 62 65 20 61 20 70 6f 77  nt must be a pow
cd60: 65 72 20 6f 66 20 74 77 6f 20 62 65 74 77 65 65  er of two betwee
cd70: 6e 20 35 31 32 20 61 6e 64 20 33 32 37 36 38 2e  n 512 and 32768.
cd80: 20 20 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 61    The first.** a
cd90: 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 70  rgument should p
cda0: 6f 69 6e 74 20 74 6f 20 61 6e 20 61 6c 6c 6f 63  oint to an alloc
cdb0: 61 74 69 6f 6e 20 6f 66 20 61 74 20 6c 65 61 73  ation of at leas
cdc0: 74 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20  t sz*N bytes of 
cdd0: 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 53 51 4c 69 74  memory..** SQLit
cde0: 65 20 77 69 6c 6c 20 75 73 65 20 74 68 65 20 6d  e will use the m
cdf0: 65 6d 6f 72 79 20 70 72 6f 76 69 64 65 64 20 62  emory provided b
ce00: 79 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  y the first argu
ce10: 6d 65 6e 74 20 74 6f 20 73 61 74 69 73 66 79 20  ment to satisfy 
ce20: 69 74 73 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6e 65  its.** memory ne
ce30: 65 64 73 20 66 6f 72 20 74 68 65 20 66 69 72 73  eds for the firs
ce40: 74 20 4e 20 70 61 67 65 73 20 74 68 61 74 20 69  t N pages that i
ce50: 74 20 61 64 64 73 20 74 6f 20 63 61 63 68 65 2e  t adds to cache.
ce60: 20 20 49 66 20 61 64 64 69 74 69 6f 6e 61 6c 0a    If additional.
ce70: 2a 2a 20 70 61 67 65 20 63 61 63 68 65 20 6d 65  ** page cache me
ce80: 6d 6f 72 79 20 69 73 20 6e 65 65 64 65 64 20 62  mory is needed b
ce90: 65 79 6f 6e 64 20 77 68 61 74 20 69 73 20 70 72  eyond what is pr
cea0: 6f 76 69 64 65 64 20 62 79 20 74 68 69 73 20 6f  ovided by this o
ceb0: 70 74 69 6f 6e 2c 20 74 68 65 6e 0a 2a 2a 20 53  ption, then.** S
cec0: 51 4c 69 74 65 20 67 6f 65 73 20 74 6f 20 5b 73  QLite goes to [s
ced0: 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
cee0: 20 66 6f 72 20 74 68 65 20 61 64 64 69 74 69 6f   for the additio
cef0: 6e 61 6c 20 73 74 6f 72 61 67 65 20 73 70 61 63  nal storage spac
cf00: 65 2e 0a 2a 2a 20 54 68 65 20 69 6d 70 6c 65 6d  e..** The implem
cf10: 65 6e 74 61 74 69 6f 6e 20 6d 69 67 68 74 20 75  entation might u
cf20: 73 65 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f  se one or more o
cf30: 66 20 74 68 65 20 4e 20 62 75 66 66 65 72 73 20  f the N buffers 
cf40: 74 6f 20 68 6f 6c 64 20 0a 2a 2a 20 6d 65 6d 6f  to hold .** memo
cf50: 72 79 20 61 63 63 6f 75 6e 74 69 6e 67 20 69 6e  ry accounting in
cf60: 66 6f 72 6d 61 74 69 6f 6e 2e 20 3c 2f 64 64 3e  formation. </dd>
cf70: 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
cf80: 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 3c 2f 64  E_CONFIG_HEAP</d
cf90: 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f  t>.** <dd>This o
cfa0: 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20  ption specifies 
cfb0: 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20  a static memory 
cfc0: 62 75 66 66 65 72 20 74 68 61 74 20 53 51 4c 69  buffer that SQLi
cfd0: 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 66  te will use.** f
cfe0: 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 64 79  or all of its dy
cff0: 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 61 6c 6c  namic memory all
d000: 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 20 62 65  ocation needs be
d010: 79 6f 6e 64 20 74 68 6f 73 65 20 70 72 6f 76 69  yond those provi
d020: 64 65 64 0a 2a 2a 20 66 6f 72 20 62 79 20 5b 53  ded.** for by [S
d030: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52  QLITE_CONFIG_SCR
d040: 41 54 43 48 5d 20 61 6e 64 20 5b 53 51 4c 49 54  ATCH] and [SQLIT
d050: 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43  E_CONFIG_PAGECAC
d060: 48 45 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72  HE]..** There ar
d070: 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74  e three argument
d080: 73 3a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20  s: A pointer to 
d090: 74 68 65 20 6d 65 6d 6f 72 79 2c 20 74 68 65 20  the memory, the 
d0a0: 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 62 79 74  number of.** byt
d0b0: 65 73 20 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79  es in the memory
d0c0: 20 62 75 66 66 65 72 2c 20 61 6e 64 20 74 68 65   buffer, and the
d0d0: 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74   minimum allocat
d0e0: 69 6f 6e 20 73 69 7a 65 2e 20 20 49 66 0a 2a 2a  ion size.  If.**
d0f0: 20 74 68 65 20 66 69 72 73 74 20 70 6f 69 6e 74   the first point
d100: 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 79 20 70  er (the memory p
d110: 6f 69 6e 74 65 72 29 20 69 73 20 4e 55 4c 4c 2c  ointer) is NULL,
d120: 20 74 68 65 6e 20 53 51 4c 69 74 65 20 72 65 76   then SQLite rev
d130: 65 72 74 73 0a 2a 2a 20 74 6f 20 75 73 69 6e 67  erts.** to using
d140: 20 69 74 73 20 64 65 66 61 75 6c 74 20 6d 65 6d   its default mem
d150: 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 28 74  ory allocator (t
d160: 68 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63  he system malloc
d170: 28 29 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  () implementatio
d180: 6e 29 2c 0a 2a 2a 20 75 6e 64 6f 69 6e 67 20 61  n),.** undoing a
d190: 6e 79 20 70 72 69 6f 72 20 69 6e 76 6f 63 61 74  ny prior invocat
d1a0: 69 6f 6e 20 6f 66 20 5b 53 51 4c 49 54 45 5f 43  ion of [SQLITE_C
d1b0: 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 2e 20 20  ONFIG_MALLOC].  
d1c0: 49 66 20 74 68 65 0a 2a 2a 20 6d 65 6d 6f 72 79  If the.** memory
d1d0: 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20   pointer is not 
d1e0: 4e 55 4c 4c 20 61 6e 64 20 65 69 74 68 65 72 20  NULL and either 
d1f0: 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d  [SQLITE_ENABLE_M
d200: 45 4d 53 59 53 33 5d 20 6f 72 0a 2a 2a 20 5b 53  EMSYS3] or.** [S
d210: 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d  QLITE_ENABLE_MEM
d220: 53 59 53 35 5d 20 61 72 65 20 64 65 66 69 6e 65  SYS5] are define
d230: 64 2c 20 74 68 65 6e 20 74 68 65 20 61 6c 74 65  d, then the alte
d240: 72 6e 61 74 69 76 65 20 6d 65 6d 6f 72 79 0a 2a  rnative memory.*
d250: 2a 20 61 6c 6c 6f 63 61 74 6f 72 20 69 73 20 65  * allocator is e
d260: 6e 67 61 67 65 64 20 74 6f 20 68 61 6e 64 6c 65  ngaged to handle
d270: 20 61 6c 6c 20 6f 66 20 53 51 4c 69 74 65 73 20   all of SQLites 
d280: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
d290: 6e 20 6e 65 65 64 73 2e 3c 2f 64 64 3e 0a 2a 2a  n needs.</dd>.**
d2a0: 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  .** <dt>SQLITE_C
d2b0: 4f 4e 46 49 47 5f 4d 55 54 45 58 3c 2f 64 74 3e  ONFIG_MUTEX</dt>
d2c0: 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74  .** <dd>This opt
d2d0: 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
d2e0: 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63  le argument whic
d2f0: 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  h is a pointer t
d300: 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65  o an.** instance
d310: 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
d320: 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20  _mutex_methods] 
d330: 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 20  structure.  The 
d340: 61 72 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69  argument specifi
d350: 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76  es.** alternativ
d360: 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 75 74 65  e low-level mute
d370: 78 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65  x routines to be
d380: 20 75 73 65 64 20 69 6e 20 70 6c 61 63 65 0a 2a   used in place.*
d390: 2a 20 74 68 65 20 6d 75 74 65 78 20 72 6f 75 74  * the mutex rout
d3a0: 69 6e 65 73 20 62 75 69 6c 74 20 69 6e 74 6f 20  ines built into 
d3b0: 53 51 4c 69 74 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a  SQLite.</dd>.**.
d3c0: 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ** <dt>SQLITE_CO
d3d0: 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 3c 2f 64  NFIG_GETMUTEX</d
d3e0: 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f  t>.** <dd>This o
d3f0: 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
d400: 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68  ngle argument wh
d410: 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ich is a pointer
d420: 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e   to an.** instan
d430: 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ce of the [sqlit
d440: 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73  e3_mutex_methods
d450: 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 68  ] structure.  Th
d460: 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 75  e.** [sqlite3_mu
d470: 74 65 78 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20  tex_methods].** 
d480: 73 74 72 75 63 74 75 72 65 20 69 73 20 66 69 6c  structure is fil
d490: 6c 65 64 20 77 69 74 68 20 74 68 65 20 63 75 72  led with the cur
d4a0: 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 6d  rently defined m
d4b0: 75 74 65 78 20 72 6f 75 74 69 6e 65 73 2e 0a 2a  utex routines..*
d4c0: 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61  * This option ca
d4d0: 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65  n be used to ove
d4e0: 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c  rload the defaul
d4f0: 74 20 6d 75 74 65 78 20 61 6c 6c 6f 63 61 74 69  t mutex allocati
d500: 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77  on.** routines w
d510: 69 74 68 20 61 20 77 72 61 70 70 65 72 20 75 73  ith a wrapper us
d520: 65 64 20 74 6f 20 74 72 61 63 6b 20 6d 75 74 65  ed to track mute
d530: 78 20 75 73 61 67 65 20 66 6f 72 20 70 65 72 66  x usage for perf
d540: 6f 72 6d 61 6e 63 65 0a 2a 2a 20 70 72 6f 66 69  ormance.** profi
d550: 6c 69 6e 67 20 6f 72 20 74 65 73 74 69 6e 67 2c  ling or testing,
d560: 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e 3c 2f 64   for example.</d
d570: 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
d580: 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  ITE_CONFIG_LOOKA
d590: 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  SIDE</dt>.** <dd
d5a0: 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b  >This option tak
d5b0: 65 73 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73  es two arguments
d5c0: 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65 20   that determine 
d5d0: 74 68 65 20 64 65 66 61 75 6c 74 0a 2a 2a 20 6d  the default.** m
d5e0: 65 6d 6f 72 79 20 61 6c 6c 63 61 74 69 6f 6e 20  emory allcation 
d5f0: 6c 6f 6f 6b 61 73 69 64 65 20 6f 70 74 69 6d 69  lookaside optimi
d600: 7a 61 74 69 6f 6e 2e 20 20 54 68 65 20 66 69 72  zation.  The fir
d610: 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  st argument is t
d620: 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61  he.** size of ea
d630: 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66  ch lookaside buf
d640: 66 65 72 20 73 6c 6f 74 20 61 6e 64 20 74 68 65  fer slot and the
d650: 20 73 65 63 6f 6e 64 20 69 73 20 74 68 65 20 6e   second is the n
d660: 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74  umber of.** slot
d670: 73 20 61 6c 6c 6f 63 61 74 65 64 20 74 6f 20 65  s allocated to e
d680: 61 63 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ach database con
d690: 6e 65 63 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a  nection.</dd>.**
d6a0: 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65  .** </dl>.*/.#de
d6b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
d6c0: 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 20  IG_SINGLETHREAD 
d6d0: 20 31 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64   1  /* nil */.#d
d6e0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
d6f0: 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 20  FIG_MULTITHREAD 
d700: 20 20 32 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23    2  /* nil */.#
d710: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
d720: 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 20  NFIG_SERIALIZED 
d730: 20 20 20 33 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a     3  /* nil */.
d740: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
d750: 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20 20 20 20  ONFIG_MALLOC    
d760: 20 20 20 20 34 20 20 2f 2a 20 73 71 6c 69 74 65      4  /* sqlite
d770: 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a  3_mem_methods* *
d780: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
d790: 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f  _CONFIG_GETMALLO
d7a0: 43 20 20 20 20 20 35 20 20 2f 2a 20 73 71 6c 69  C     5  /* sqli
d7b0: 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a  te3_mem_methods*
d7c0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
d7d0: 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43  TE_CONFIG_SCRATC
d7e0: 48 20 20 20 20 20 20 20 36 20 20 2f 2a 20 76 6f  H       6  /* vo
d7f0: 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74  id*, int sz, int
d800: 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51   N */.#define SQ
d810: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45  LITE_CONFIG_PAGE
d820: 43 41 43 48 45 20 20 20 20 20 37 20 20 2f 2a 20  CACHE     7  /* 
d830: 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69  void*, int sz, i
d840: 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20  nt N */.#define 
d850: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45  SQLITE_CONFIG_HE
d860: 41 50 20 20 20 20 20 20 20 20 20 20 38 20 20 2f  AP          8  /
d870: 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 42 79  * void*, int nBy
d880: 74 65 2c 20 69 6e 74 20 6d 69 6e 20 2a 2f 0a 23  te, int min */.#
d890: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
d8a0: 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 20 20  NFIG_MEMSTATUS  
d8b0: 20 20 20 39 20 20 2f 2a 20 62 6f 6f 6c 65 61 6e     9  /* boolean
d8c0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
d8d0: 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20  TE_CONFIG_MUTEX 
d8e0: 20 20 20 20 20 20 20 31 30 20 20 2f 2a 20 73 71         10  /* sq
d8f0: 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68  lite3_mutex_meth
d900: 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ods* */.#define 
d910: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
d920: 54 4d 55 54 45 58 20 20 20 20 20 31 31 20 20 2f  TMUTEX     11  /
d930: 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  * sqlite3_mutex_
d940: 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66  methods* */.#def
d950: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
d960: 47 5f 43 48 55 4e 4b 41 4c 4c 4f 43 20 20 20 31  G_CHUNKALLOC   1
d970: 32 20 20 2f 2a 20 69 6e 74 20 74 68 72 65 73 68  2  /* int thresh
d980: 6f 6c 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  old */.#define S
d990: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f  QLITE_CONFIG_LOO
d9a0: 4b 41 53 49 44 45 20 20 20 20 31 33 20 20 2f 2a  KASIDE    13  /*
d9b0: 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 0a 2f 2a 0a   int int */../*.
d9c0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e  ** CAPI3REF: Con
d9d0: 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f  figuration Optio
d9e0: 6e 73 20 7b 48 31 30 31 37 30 7d 20 3c 53 32 30  ns {H10170} <S20
d9f0: 30 30 30 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 45  000>.** EXPERIME
da00: 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  NTAL.**.** These
da10: 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 74   constants are t
da20: 68 65 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 74  he available int
da30: 65 67 65 72 20 63 6f 6e 66 69 67 75 72 61 74 69  eger configurati
da40: 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a  on options that.
da50: 2a 2a 20 63 61 6e 20 62 65 20 70 61 73 73 65 64  ** can be passed
da60: 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61   as the second a
da70: 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b  rgument to the [
da80: 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
da90: 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a  g()] interface..
daa0: 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67  **.** New config
dab0: 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20  uration options 
dac0: 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20  may be added in 
dad0: 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20  future releases 
dae0: 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78  of SQLite..** Ex
daf0: 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 72 61  isting configura
db00: 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67  tion options mig
db10: 68 74 20 62 65 20 64 69 73 63 6f 6e 74 69 6e 75  ht be discontinu
db20: 65 64 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e  ed.  Application
db30: 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65 63  s.** should chec
db40: 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64  k the return cod
db50: 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  e from [sqlite3_
db60: 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20  db_config()] to 
db70: 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74 0a 2a  make sure that.*
db80: 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65  * the call worke
db90: 64 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33  d.  The [sqlite3
dba0: 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e  _db_config()] in
dbb0: 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65 74  terface will ret
dbc0: 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72  urn a.** non-zer
dbd0: 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  o [error code] i
dbe0: 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65 64  f a discontinued
dbf0: 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64 20   or unsupported 
dc00: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
dc10: 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b  tion.** is invok
dc20: 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a  ed..**.** <dl>.*
dc30: 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43  * <dt>SQLITE_DBC
dc40: 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c  ONFIG_LOOKASIDE<
dc50: 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73  /dt>.** <dd>This
dc60: 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 68   option takes th
dc70: 72 65 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 61  ree additional a
dc80: 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 64 65  rguments that de
dc90: 74 65 72 6d 69 6e 65 20 74 68 65 20 0a 2a 2a 20  termine the .** 
dca0: 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72  [lookaside memor
dcb0: 79 20 61 6c 6c 6f 63 61 74 6f 72 5d 20 63 6f 6e  y allocator] con
dcc0: 66 69 67 75 72 61 74 69 6f 6e 20 66 6f 72 20 74  figuration for t
dcd0: 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
dce0: 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 54 68 65  nection]..** The
dcf0: 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
dd00: 28 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d  (the third param
dd10: 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33  eter to [sqlite3
dd20: 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 73  _db_config()] is
dd30: 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f   a.** pointer to
dd40: 20 61 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72   a memory buffer
dd50: 20 74 6f 20 75 73 65 20 66 6f 72 20 6c 6f 6f 6b   to use for look
dd60: 61 73 69 64 65 20 6d 65 6d 6f 72 79 2e 20 20 54  aside memory.  T
dd70: 68 65 20 66 69 72 73 74 0a 2a 2a 20 61 72 67 75  he first.** argu
dd80: 6d 65 6e 74 20 6d 61 79 20 62 65 20 4e 55 4c 4c  ment may be NULL
dd90: 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 53   in which case S
dda0: 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 6c 6f 63  QLite will alloc
ddb0: 61 74 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64  ate the lookasid
ddc0: 65 0a 2a 2a 20 62 75 66 66 65 72 20 69 74 73 65  e.** buffer itse
ddd0: 6c 66 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  lf using [sqlite
dde0: 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 20 54 68  3_malloc()].  Th
ddf0: 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
de00: 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65  t is the.** size
de10: 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69   of each lookasi
de20: 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74 20 61  de buffer slot a
de30: 6e 64 20 74 68 65 20 74 68 69 72 64 20 61 72 67  nd the third arg
de40: 75 6d 65 6e 74 20 69 73 20 74 68 65 20 6e 75 6d  ument is the num
de50: 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 2e  ber of.** slots.
de60: 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68    The size of th
de70: 65 20 62 75 66 66 65 72 20 69 6e 20 74 68 65 20  e buffer in the 
de80: 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d  first argument m
de90: 75 73 74 20 62 65 20 67 72 65 61 74 65 72 20 74  ust be greater t
dea0: 68 61 6e 0a 2a 2a 20 6f 72 20 65 71 75 61 6c 20  han.** or equal 
deb0: 74 6f 20 74 68 65 20 70 72 6f 64 75 63 74 20 6f  to the product o
dec0: 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64  f the second and
ded0: 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 73   third arguments
dee0: 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64  .</dd>.**.** </d
def0: 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  l>.*/.#define SQ
df00: 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f  LITE_DBCONFIG_LO
df10: 4f 4b 41 53 49 44 45 20 20 20 20 31 30 30 31 20  OKASIDE    1001 
df20: 20 2f 2a 20 76 6f 69 64 2a 20 69 6e 74 20 69 6e   /* void* int in
df30: 74 20 2a 2f 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  t */.../*.** CAP
df40: 49 33 52 45 46 3a 20 45 6e 61 62 6c 65 20 4f 72  I3REF: Enable Or
df50: 20 44 69 73 61 62 6c 65 20 45 78 74 65 6e 64 65   Disable Extende
df60: 64 20 52 65 73 75 6c 74 20 43 6f 64 65 73 20 7b  d Result Codes {
df70: 48 31 32 32 30 30 7d 20 3c 53 31 30 37 30 30 3e  H12200} <S10700>
df80: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
df90: 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75  e3_extended_resu
dfa0: 6c 74 5f 63 6f 64 65 73 28 29 20 72 6f 75 74 69  lt_codes() routi
dfb0: 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69  ne enables or di
dfc0: 73 61 62 6c 65 73 20 74 68 65 0a 2a 2a 20 5b 65  sables the.** [e
dfd0: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
dfe0: 6f 64 65 73 5d 20 66 65 61 74 75 72 65 20 6f 66  odes] feature of
dff0: 20 53 51 4c 69 74 65 2e 20 54 68 65 20 65 78 74   SQLite. The ext
e000: 65 6e 64 65 64 20 72 65 73 75 6c 74 0a 2a 2a 20  ended result.** 
e010: 63 6f 64 65 73 20 61 72 65 20 64 69 73 61 62 6c  codes are disabl
e020: 65 64 20 62 79 20 64 65 66 61 75 6c 74 20 66 6f  ed by default fo
e030: 72 20 68 69 73 74 6f 72 69 63 61 6c 20 63 6f 6d  r historical com
e040: 70 61 74 69 62 69 6c 69 74 79 20 63 6f 6e 73 69  patibility consi
e050: 64 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a  derations..**.**
e060: 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
e070: 2a 2a 20 7b 48 31 32 32 30 31 7d 20 45 61 63 68  ** {H12201} Each
e080: 20 6e 65 77 20 5b 64 61 74 61 62 61 73 65 20 63   new [database c
e090: 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 68 61 6c 6c  onnection] shall
e0a0: 20 68 61 76 65 20 74 68 65 0a 2a 2a 20 20 20 20   have the.**    
e0b0: 20 20 20 20 20 20 5b 65 78 74 65 6e 64 65 64 20        [extended 
e0c0: 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 66 65  result codes] fe
e0d0: 61 74 75 72 65 20 64 69 73 61 62 6c 65 64 20 62  ature disabled b
e0e0: 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a  y default..**.**
e0f0: 20 7b 48 31 32 32 30 32 7d 20 54 68 65 20 5b 73   {H12202} The [s
e100: 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f  qlite3_extended_
e110: 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 44 2c 46  result_codes(D,F
e120: 29 5d 20 69 6e 74 65 72 66 61 63 65 20 73 68 61  )] interface sha
e130: 6c 6c 20 65 6e 61 62 6c 65 0a 2a 2a 20 20 20 20  ll enable.**    
e140: 20 20 20 20 20 20 5b 65 78 74 65 6e 64 65 64 20        [extended 
e150: 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 66 6f  result codes] fo
e160: 72 20 74 68 65 20 20 5b 64 61 74 61 62 61 73 65  r the  [database
e170: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a   connection] D.*
e180: 2a 20 20 20 20 20 20 20 20 20 20 69 66 20 74 68  *          if th
e190: 65 20 46 20 70 61 72 61 6d 65 74 65 72 20 69 73  e F parameter is
e1a0: 20 74 72 75 65 2c 20 6f 72 20 64 69 73 61 62 6c   true, or disabl
e1b0: 65 20 74 68 65 6d 20 69 66 20 46 20 69 73 20 66  e them if F is f
e1c0: 61 6c 73 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  alse..*/.int sql
e1d0: 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65  ite3_extended_re
e1e0: 73 75 6c 74 5f 63 6f 64 65 73 28 73 71 6c 69 74  sult_codes(sqlit
e1f0: 65 33 2a 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b  e3*, int onoff);
e200: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
e210: 3a 20 4c 61 73 74 20 49 6e 73 65 72 74 20 52 6f  : Last Insert Ro
e220: 77 69 64 20 7b 48 31 32 32 32 30 7d 20 3c 53 31  wid {H12220} <S1
e230: 30 37 30 30 3e 0a 2a 2a 0a 2a 2a 20 45 61 63 68  0700>.**.** Each
e240: 20 65 6e 74 72 79 20 69 6e 20 61 6e 20 53 51 4c   entry in an SQL
e250: 69 74 65 20 74 61 62 6c 65 20 68 61 73 20 61 20  ite table has a 
e260: 75 6e 69 71 75 65 20 36 34 2d 62 69 74 20 73 69  unique 64-bit si
e270: 67 6e 65 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20  gned.** integer 
e280: 6b 65 79 20 63 61 6c 6c 65 64 20 74 68 65 20 22  key called the "
e290: 72 6f 77 69 64 22 2e 20 54 68 65 20 72 6f 77 69  rowid". The rowi
e2a0: 64 20 69 73 20 61 6c 77 61 79 73 20 61 76 61 69  d is always avai
e2b0: 6c 61 62 6c 65 0a 2a 2a 20 61 73 20 61 6e 20 75  lable.** as an u
e2c0: 6e 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e  ndeclared column
e2d0: 20 6e 61 6d 65 64 20 52 4f 57 49 44 2c 20 4f 49   named ROWID, OI
e2e0: 44 2c 20 6f 72 20 5f 52 4f 57 49 44 5f 20 61 73  D, or _ROWID_ as
e2f0: 20 6c 6f 6e 67 20 61 73 20 74 68 6f 73 65 0a 2a   long as those.*
e300: 2a 20 6e 61 6d 65 73 20 61 72 65 20 6e 6f 74 20  * names are not 
e310: 61 6c 73 6f 20 75 73 65 64 20 62 79 20 65 78 70  also used by exp
e320: 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64  licitly declared
e330: 20 63 6f 6c 75 6d 6e 73 2e 20 49 66 0a 2a 2a 20   columns. If.** 
e340: 74 68 65 20 74 61 62 6c 65 20 68 61 73 20 61 20  the table has a 
e350: 63 6f 6c 75 6d 6e 20 6f 66 20 74 79 70 65 20 49  column of type I
e360: 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59 20 4b  NTEGER PRIMARY K
e370: 45 59 20 74 68 65 6e 20 74 68 61 74 20 63 6f 6c  EY then that col
e380: 75 6d 6e 0a 2a 2a 20 69 73 20 61 6e 6f 74 68 65  umn.** is anothe
e390: 72 20 61 6c 69 61 73 20 66 6f 72 20 74 68 65 20  r alias for the 
e3a0: 72 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  rowid..**.** Thi
e3b0: 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  s routine return
e3c0: 73 20 74 68 65 20 72 6f 77 69 64 20 6f 66 20 74  s the rowid of t
e3d0: 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 0a 2a  he most recent.*
e3e0: 2a 20 73 75 63 63 65 73 73 66 75 6c 20 49 4e 53  * successful INS
e3f0: 45 52 54 20 69 6e 74 6f 20 74 68 65 20 64 61 74  ERT into the dat
e400: 61 62 61 73 65 20 66 72 6f 6d 20 74 68 65 20 5b  abase from the [
e410: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
e420: 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65 20 66  ion].** in the f
e430: 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 20 20  irst argument.  
e440: 49 66 20 6e 6f 20 73 75 63 63 65 73 73 66 75 6c  If no successful
e450: 20 49 4e 53 45 52 54 73 0a 2a 2a 20 68 61 76 65   INSERTs.** have
e460: 20 65 76 65 72 20 6f 63 63 75 72 72 65 64 20 6f   ever occurred o
e470: 6e 20 74 68 61 74 20 64 61 74 61 62 61 73 65 20  n that database 
e480: 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 7a 65 72 6f  connection, zero
e490: 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
e4a0: 0a 2a 2a 20 49 66 20 61 6e 20 49 4e 53 45 52 54  .** If an INSERT
e4b0: 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20 61   occurs within a
e4c0: 20 74 72 69 67 67 65 72 2c 20 74 68 65 6e 20 74   trigger, then t
e4d0: 68 65 20 72 6f 77 69 64 20 6f 66 20 74 68 65 20  he rowid of the 
e4e0: 69 6e 73 65 72 74 65 64 0a 2a 2a 20 72 6f 77 20  inserted.** row 
e4f0: 69 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74  is returned by t
e500: 68 69 73 20 72 6f 75 74 69 6e 65 20 61 73 20 6c  his routine as l
e510: 6f 6e 67 20 61 73 20 74 68 65 20 74 72 69 67 67  ong as the trigg
e520: 65 72 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a  er is running..*
e530: 2a 20 42 75 74 20 6f 6e 63 65 20 74 68 65 20 74  * But once the t
e540: 72 69 67 67 65 72 20 74 65 72 6d 69 6e 61 74 65  rigger terminate
e550: 73 2c 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  s, the value ret
e560: 75 72 6e 65 64 20 62 79 20 74 68 69 73 20 72 6f  urned by this ro
e570: 75 74 69 6e 65 0a 2a 2a 20 72 65 76 65 72 74 73  utine.** reverts
e580: 20 74 6f 20 74 68 65 20 6c 61 73 74 20 76 61 6c   to the last val
e590: 75 65 20 69 6e 73 65 72 74 65 64 20 62 65 66 6f  ue inserted befo
e5a0: 72 65 20 74 68 65 20 74 72 69 67 67 65 72 20 66  re the trigger f
e5b0: 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 49  ired..**.** An I
e5c0: 4e 53 45 52 54 20 74 68 61 74 20 66 61 69 6c 73  NSERT that fails
e5d0: 20 64 75 65 20 74 6f 20 61 20 63 6f 6e 73 74 72   due to a constr
e5e0: 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 69  aint violation i
e5f0: 73 20 6e 6f 74 20 61 0a 2a 2a 20 73 75 63 63 65  s not a.** succe
e600: 73 73 66 75 6c 20 49 4e 53 45 52 54 20 61 6e 64  ssful INSERT and
e610: 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65   does not change
e620: 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
e630: 6e 65 64 20 62 79 20 74 68 69 73 0a 2a 2a 20 72  ned by this.** r
e640: 6f 75 74 69 6e 65 2e 20 20 54 68 75 73 20 49 4e  outine.  Thus IN
e650: 53 45 52 54 20 4f 52 20 46 41 49 4c 2c 20 49 4e  SERT OR FAIL, IN
e660: 53 45 52 54 20 4f 52 20 49 47 4e 4f 52 45 2c 20  SERT OR IGNORE, 
e670: 49 4e 53 45 52 54 20 4f 52 20 52 4f 4c 4c 42 41  INSERT OR ROLLBA
e680: 43 4b 2c 0a 2a 2a 20 61 6e 64 20 49 4e 53 45 52  CK,.** and INSER
e690: 54 20 4f 52 20 41 42 4f 52 54 20 6d 61 6b 65 20  T OR ABORT make 
e6a0: 6e 6f 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68  no changes to th
e6b0: 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f  e return value o
e6c0: 66 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e  f this.** routin
e6d0: 65 20 77 68 65 6e 20 74 68 65 69 72 20 69 6e 73  e when their ins
e6e0: 65 72 74 69 6f 6e 20 66 61 69 6c 73 2e 20 20 57  ertion fails.  W
e6f0: 68 65 6e 20 49 4e 53 45 52 54 20 4f 52 20 52 45  hen INSERT OR RE
e700: 50 4c 41 43 45 0a 2a 2a 20 65 6e 63 6f 75 6e 74  PLACE.** encount
e710: 65 72 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74  ers a constraint
e720: 20 76 69 6f 6c 61 74 69 6f 6e 2c 20 69 74 20 64   violation, it d
e730: 6f 65 73 20 6e 6f 74 20 66 61 69 6c 2e 20 20 54  oes not fail.  T
e740: 68 65 0a 2a 2a 20 49 4e 53 45 52 54 20 63 6f 6e  he.** INSERT con
e750: 74 69 6e 75 65 73 20 74 6f 20 63 6f 6d 70 6c 65  tinues to comple
e760: 74 69 6f 6e 20 61 66 74 65 72 20 64 65 6c 65 74  tion after delet
e770: 69 6e 67 20 72 6f 77 73 20 74 68 61 74 20 63 61  ing rows that ca
e780: 75 73 65 64 0a 2a 2a 20 74 68 65 20 63 6f 6e 73  used.** the cons
e790: 74 72 61 69 6e 74 20 70 72 6f 62 6c 65 6d 20 73  traint problem s
e7a0: 6f 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c  o INSERT OR REPL
e7b0: 41 43 45 20 77 69 6c 6c 20 61 6c 77 61 79 73 20  ACE will always 
e7c0: 63 68 61 6e 67 65 0a 2a 2a 20 74 68 65 20 72 65  change.** the re
e7d0: 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68  turn value of th
e7e0: 69 73 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  is interface..**
e7f0: 0a 2a 2a 20 46 6f 72 20 74 68 65 20 70 75 72 70  .** For the purp
e800: 6f 73 65 73 20 6f 66 20 74 68 69 73 20 72 6f 75  oses of this rou
e810: 74 69 6e 65 2c 20 61 6e 20 49 4e 53 45 52 54 20  tine, an INSERT 
e820: 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 74 6f  is considered to
e830: 0a 2a 2a 20 62 65 20 73 75 63 63 65 73 73 66 75  .** be successfu
e840: 6c 20 65 76 65 6e 20 69 66 20 69 74 20 69 73 20  l even if it is 
e850: 73 75 62 73 65 71 75 65 6e 74 6c 79 20 72 6f 6c  subsequently rol
e860: 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20  led back..**.** 
e870: 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
e880: 2a 20 7b 48 31 32 32 32 31 7d 20 54 68 65 20 5b  * {H12221} The [
e890: 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73  sqlite3_last_ins
e8a0: 65 72 74 5f 72 6f 77 69 64 28 29 5d 20 66 75 6e  ert_rowid()] fun
e8b0: 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68  ction returns th
e8c0: 65 20 72 6f 77 69 64 0a 2a 2a 20 20 20 20 20 20  e rowid.**      
e8d0: 20 20 20 20 6f 66 20 74 68 65 20 6d 6f 73 74 20      of the most 
e8e0: 72 65 63 65 6e 74 20 73 75 63 63 65 73 73 66 75  recent successfu
e8f0: 6c 20 49 4e 53 45 52 54 20 70 65 72 66 6f 72 6d  l INSERT perform
e900: 65 64 20 6f 6e 20 74 68 65 20 73 61 6d 65 0a 2a  ed on the same.*
e910: 2a 20 20 20 20 20 20 20 20 20 20 5b 64 61 74 61  *          [data
e920: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
e930: 20 61 6e 64 20 77 69 74 68 69 6e 20 74 68 65 20   and within the 
e940: 73 61 6d 65 20 6f 72 20 68 69 67 68 65 72 20 6c  same or higher l
e950: 65 76 65 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20  evel.**         
e960: 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74   trigger context
e970: 2c 20 6f 72 20 7a 65 72 6f 20 69 66 20 74 68 65  , or zero if the
e980: 72 65 20 68 61 76 65 20 62 65 65 6e 20 6e 6f 20  re have been no 
e990: 71 75 61 6c 69 66 79 69 6e 67 20 69 6e 73 65 72  qualifying inser
e9a0: 74 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 32  ts..**.** {H1222
e9b0: 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  3} The [sqlite3_
e9c0: 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69  last_insert_rowi
e9d0: 64 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20 72 65  d()] function re
e9e0: 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20  turns the.**    
e9f0: 20 20 20 20 20 20 73 61 6d 65 20 76 61 6c 75 65        same value
ea00: 20 77 68 65 6e 20 63 61 6c 6c 65 64 20 66 72 6f   when called fro
ea10: 6d 20 74 68 65 20 73 61 6d 65 20 74 72 69 67 67  m the same trigg
ea20: 65 72 20 63 6f 6e 74 65 78 74 0a 2a 2a 20 20 20  er context.**   
ea30: 20 20 20 20 20 20 20 69 6d 6d 65 64 69 61 74 65         immediate
ea40: 6c 79 20 62 65 66 6f 72 65 20 61 6e 64 20 61 66  ly before and af
ea50: 74 65 72 20 61 20 52 4f 4c 4c 42 41 43 4b 2e 0a  ter a ROLLBACK..
ea60: 2a 2a 0a 2a 2a 20 41 53 53 55 4d 50 54 49 4f 4e  **.** ASSUMPTION
ea70: 53 3a 0a 2a 2a 0a 2a 2a 20 7b 41 31 32 32 33 32  S:.**.** {A12232
ea80: 7d 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20  } If a separate 
ea90: 74 68 72 65 61 64 20 70 65 72 66 6f 72 6d 73 20  thread performs 
eaa0: 61 20 6e 65 77 20 49 4e 53 45 52 54 20 6f 6e 20  a new INSERT on 
eab0: 74 68 65 20 73 61 6d 65 0a 2a 2a 20 20 20 20 20  the same.**     
eac0: 20 20 20 20 20 64 61 74 61 62 61 73 65 20 63 6f       database co
ead0: 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65 20 74  nnection while t
eae0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74  he [sqlite3_last
eaf0: 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d  _insert_rowid()]
eb00: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 75 6e  .**          fun
eb10: 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67  ction is running
eb20: 20 61 6e 64 20 74 68 75 73 20 63 68 61 6e 67 65   and thus change
eb30: 73 20 74 68 65 20 6c 61 73 74 20 69 6e 73 65 72  s the last inser
eb40: 74 20 72 6f 77 69 64 2c 0a 2a 2a 20 20 20 20 20  t rowid,.**     
eb50: 20 20 20 20 20 74 68 65 6e 20 74 68 65 20 76 61       then the va
eb60: 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20  lue returned by 
eb70: 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e  [sqlite3_last_in
eb80: 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 20 69 73  sert_rowid()] is
eb90: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 75 6e 70  .**          unp
eba0: 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6d  redictable and m
ebb0: 69 67 68 74 20 6e 6f 74 20 65 71 75 61 6c 20 65  ight not equal e
ebc0: 69 74 68 65 72 20 74 68 65 20 6f 6c 64 20 6f 72  ither the old or
ebd0: 20 74 68 65 20 6e 65 77 0a 2a 2a 20 20 20 20 20   the new.**     
ebe0: 20 20 20 20 20 6c 61 73 74 20 69 6e 73 65 72 74       last insert
ebf0: 20 72 6f 77 69 64 2e 0a 2a 2f 0a 73 71 6c 69 74   rowid..*/.sqlit
ec00: 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e3_int64 sqlite3
ec10: 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77  _last_insert_row
ec20: 69 64 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f  id(sqlite3*);../
ec30: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
ec40: 6f 75 6e 74 20 54 68 65 20 4e 75 6d 62 65 72 20  ount The Number 
ec50: 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64  Of Rows Modified
ec60: 20 7b 48 31 32 32 34 30 7d 20 3c 53 31 30 36 30   {H12240} <S1060
ec70: 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75  0>.**.** This fu
ec80: 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74  nction returns t
ec90: 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 64 61 74  he number of dat
eca0: 61 62 61 73 65 20 72 6f 77 73 20 74 68 61 74 20  abase rows that 
ecb0: 77 65 72 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20  were changed.** 
ecc0: 6f 72 20 69 6e 73 65 72 74 65 64 20 6f 72 20 64  or inserted or d
ecd0: 65 6c 65 74 65 64 20 62 79 20 74 68 65 20 6d 6f  eleted by the mo
ece0: 73 74 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70  st recently comp
ecf0: 6c 65 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d  leted SQL statem
ed00: 65 6e 74 0a 2a 2a 20 6f 6e 20 74 68 65 20 5b 64  ent.** on the [d
ed10: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
ed20: 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20 62 79  on] specified by
ed30: 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   the first param
ed40: 65 74 65 72 2e 0a 2a 2a 20 4f 6e 6c 79 20 63 68  eter..** Only ch
ed50: 61 6e 67 65 73 20 74 68 61 74 20 61 72 65 20 64  anges that are d
ed60: 69 72 65 63 74 6c 79 20 73 70 65 63 69 66 69 65  irectly specifie
ed70: 64 20 62 79 20 74 68 65 20 49 4e 53 45 52 54 2c  d by the INSERT,
ed80: 20 55 50 44 41 54 45 2c 0a 2a 2a 20 6f 72 20 44   UPDATE,.** or D
ed90: 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20  ELETE statement 
eda0: 61 72 65 20 63 6f 75 6e 74 65 64 2e 20 20 41 75  are counted.  Au
edb0: 78 69 6c 69 61 72 79 20 63 68 61 6e 67 65 73 20  xiliary changes 
edc0: 63 61 75 73 65 64 20 62 79 0a 2a 2a 20 74 72 69  caused by.** tri
edd0: 67 67 65 72 73 20 61 72 65 20 6e 6f 74 20 63 6f  ggers are not co
ede0: 75 6e 74 65 64 2e 20 55 73 65 20 74 68 65 20 5b  unted. Use the [
edf0: 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68  sqlite3_total_ch
ee00: 61 6e 67 65 73 28 29 5d 20 66 75 6e 63 74 69 6f  anges()] functio
ee10: 6e 0a 2a 2a 20 74 6f 20 66 69 6e 64 20 74 68 65  n.** to find the
ee20: 20 74 6f 74 61 6c 20 6e 75 6d 62 65 72 20 6f 66   total number of
ee30: 20 63 68 61 6e 67 65 73 20 69 6e 63 6c 75 64 69   changes includi
ee40: 6e 67 20 63 68 61 6e 67 65 73 20 63 61 75 73 65  ng changes cause
ee50: 64 20 62 79 20 74 72 69 67 67 65 72 73 2e 0a 2a  d by triggers..*
ee60: 2a 0a 2a 2a 20 41 20 22 72 6f 77 20 63 68 61 6e  *.** A "row chan
ee70: 67 65 22 20 69 73 20 61 20 63 68 61 6e 67 65 20  ge" is a change 
ee80: 74 6f 20 61 20 73 69 6e 67 6c 65 20 72 6f 77 20  to a single row 
ee90: 6f 66 20 61 20 73 69 6e 67 6c 65 20 74 61 62 6c  of a single tabl
eea0: 65 0a 2a 2a 20 63 61 75 73 65 64 20 62 79 20 61  e.** caused by a
eeb0: 6e 20 49 4e 53 45 52 54 2c 20 44 45 4c 45 54 45  n INSERT, DELETE
eec0: 2c 20 6f 72 20 55 50 44 41 54 45 20 73 74 61 74  , or UPDATE stat
eed0: 65 6d 65 6e 74 2e 20 20 52 6f 77 73 20 74 68 61  ement.  Rows tha
eee0: 74 0a 2a 2a 20 61 72 65 20 63 68 61 6e 67 65 64  t.** are changed
eef0: 20 61 73 20 73 69 64 65 20 65 66 66 65 63 74 73   as side effects
ef00: 20 6f 66 20 52 45 50 4c 41 43 45 20 63 6f 6e 73   of REPLACE cons
ef10: 74 72 61 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f  traint resolutio
ef20: 6e 2c 0a 2a 2a 20 72 6f 6c 6c 62 61 63 6b 2c 20  n,.** rollback, 
ef30: 41 42 4f 52 54 20 70 72 6f 63 65 73 73 69 6e 67  ABORT processing
ef40: 2c 20 44 52 4f 50 20 54 41 42 4c 45 2c 20 6f 72  , DROP TABLE, or
ef50: 20 62 79 20 61 6e 79 20 6f 74 68 65 72 0a 2a 2a   by any other.**
ef60: 20 6d 65 63 68 61 6e 69 73 6d 73 20 64 6f 20 6e   mechanisms do n
ef70: 6f 74 20 63 6f 75 6e 74 20 61 73 20 64 69 72 65  ot count as dire
ef80: 63 74 20 72 6f 77 20 63 68 61 6e 67 65 73 2e 0a  ct row changes..
ef90: 2a 2a 0a 2a 2a 20 41 20 22 74 72 69 67 67 65 72  **.** A "trigger
efa0: 20 63 6f 6e 74 65 78 74 22 20 69 73 20 61 20 73   context" is a s
efb0: 63 6f 70 65 20 6f 66 20 65 78 65 63 75 74 69 6f  cope of executio
efc0: 6e 20 74 68 61 74 20 62 65 67 69 6e 73 20 61 6e  n that begins an
efd0: 64 0a 2a 2a 20 65 6e 64 73 20 77 69 74 68 20 74  d.** ends with t
efe0: 68 65 20 73 63 72 69 70 74 20 6f 66 20 61 20 74  he script of a t
eff0: 72 69 67 67 65 72 2e 20 20 4d 6f 73 74 20 53 51  rigger.  Most SQ
f000: 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65  L statements are
f010: 0a 2a 2a 20 65 76 61 6c 75 61 74 65 64 20 6f 75  .** evaluated ou
f020: 74 73 69 64 65 20 6f 66 20 61 6e 79 20 74 72 69  tside of any tri
f030: 67 67 65 72 2e 20 20 54 68 69 73 20 69 73 20 74  gger.  This is t
f040: 68 65 20 22 74 6f 70 20 6c 65 76 65 6c 22 0a 2a  he "top level".*
f050: 2a 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78  * trigger contex
f060: 74 2e 20 20 49 66 20 61 20 74 72 69 67 67 65 72  t.  If a trigger
f070: 20 66 69 72 65 73 20 66 72 6f 6d 20 74 68 65 20   fires from the 
f080: 74 6f 70 20 6c 65 76 65 6c 2c 20 61 0a 2a 2a 20  top level, a.** 
f090: 6e 65 77 20 74 72 69 67 67 65 72 20 63 6f 6e 74  new trigger cont
f0a0: 65 78 74 20 69 73 20 65 6e 74 65 72 65 64 20 66  ext is entered f
f0b0: 6f 72 20 74 68 65 20 64 75 72 61 74 69 6f 6e 20  or the duration 
f0c0: 6f 66 20 74 68 61 74 20 6f 6e 65 0a 2a 2a 20 74  of that one.** t
f0d0: 72 69 67 67 65 72 2e 20 20 53 75 62 74 72 69 67  rigger.  Subtrig
f0e0: 67 65 72 73 20 63 72 65 61 74 65 20 73 75 62 63  gers create subc
f0f0: 6f 6e 74 65 78 74 73 20 66 6f 72 20 74 68 65 69  ontexts for thei
f100: 72 20 64 75 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  r duration..**.*
f110: 2a 20 43 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74  * Calling [sqlit
f120: 65 33 5f 65 78 65 63 28 29 5d 20 6f 72 20 5b 73  e3_exec()] or [s
f130: 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 72  qlite3_step()] r
f140: 65 63 75 72 73 69 76 65 6c 79 20 64 6f 65 73 0a  ecursively does.
f150: 2a 2a 20 6e 6f 74 20 63 72 65 61 74 65 20 61 20  ** not create a 
f160: 6e 65 77 20 74 72 69 67 67 65 72 20 63 6f 6e 74  new trigger cont
f170: 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ext..**.** This 
f180: 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
f190: 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 64   the number of d
f1a0: 69 72 65 63 74 20 72 6f 77 20 63 68 61 6e 67 65  irect row change
f1b0: 73 20 69 6e 20 74 68 65 0a 2a 2a 20 6d 6f 73 74  s in the.** most
f1c0: 20 72 65 63 65 6e 74 20 49 4e 53 45 52 54 2c 20   recent INSERT, 
f1d0: 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54  UPDATE, or DELET
f1e0: 45 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68  E statement with
f1f0: 69 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 74  in the same.** t
f200: 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 0a  rigger context..
f210: 2a 2a 0a 2a 2a 20 54 68 75 73 2c 20 77 68 65 6e  **.** Thus, when
f220: 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65   called from the
f230: 20 74 6f 70 20 6c 65 76 65 6c 2c 20 74 68 69 73   top level, this
f240: 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
f250: 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20  s the.** number 
f260: 6f 66 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68  of changes in th
f270: 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 49 4e  e most recent IN
f280: 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72  SERT, UPDATE, or
f290: 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20   DELETE.** that 
f2a0: 61 6c 73 6f 20 6f 63 63 75 72 72 65 64 20 61 74  also occurred at
f2b0: 20 74 68 65 20 74 6f 70 20 6c 65 76 65 6c 2e 20   the top level. 
f2c0: 20 57 69 74 68 69 6e 20 74 68 65 20 62 6f 64 79   Within the body
f2d0: 20 6f 66 20 61 20 74 72 69 67 67 65 72 2c 0a 2a   of a trigger,.*
f2e0: 2a 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 68  * the sqlite3_ch
f2f0: 61 6e 67 65 73 28 29 20 69 6e 74 65 72 66 61 63  anges() interfac
f300: 65 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20  e can be called 
f310: 74 6f 20 66 69 6e 64 20 74 68 65 20 6e 75 6d 62  to find the numb
f320: 65 72 20 6f 66 0a 2a 2a 20 63 68 61 6e 67 65 73  er of.** changes
f330: 20 69 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63   in the most rec
f340: 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20  ently completed 
f350: 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20  INSERT, UPDATE, 
f360: 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 73 74 61  or DELETE.** sta
f370: 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 74 68  tement within th
f380: 65 20 62 6f 64 79 20 6f 66 20 74 68 65 20 73 61  e body of the sa
f390: 6d 65 20 74 72 69 67 67 65 72 2e 0a 2a 2a 20 48  me trigger..** H
f3a0: 6f 77 65 76 65 72 2c 20 74 68 65 20 6e 75 6d 62  owever, the numb
f3b0: 65 72 20 72 65 74 75 72 6e 65 64 20 64 6f 65 73  er returned does
f3c0: 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 63 68 61   not include cha
f3d0: 6e 67 65 73 0a 2a 2a 20 63 61 75 73 65 64 20 62  nges.** caused b
f3e0: 79 20 73 75 62 74 72 69 67 67 65 72 73 20 73 69  y subtriggers si
f3f0: 6e 63 65 20 74 68 6f 73 65 20 68 61 76 65 20 74  nce those have t
f400: 68 65 69 72 20 6f 77 6e 20 63 6f 6e 74 65 78 74  heir own context
f410: 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 69  ..**.** SQLite i
f420: 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 63 6f  mplements the co
f430: 6d 6d 61 6e 64 20 22 44 45 4c 45 54 45 20 46 52  mmand "DELETE FR
f440: 4f 4d 20 74 61 62 6c 65 22 20 77 69 74 68 6f 75  OM table" withou
f450: 74 20 61 20 57 48 45 52 45 20 63 6c 61 75 73 65  t a WHERE clause
f460: 0a 2a 2a 20 62 79 20 64 72 6f 70 70 69 6e 67 20  .** by dropping 
f470: 61 6e 64 20 72 65 63 72 65 61 74 69 6e 67 20 74  and recreating t
f480: 68 65 20 74 61 62 6c 65 2e 20 20 28 54 68 69 73  he table.  (This
f490: 20 69 73 20 6d 75 63 68 20 66 61 73 74 65 72 20   is much faster 
f4a0: 74 68 61 6e 20 67 6f 69 6e 67 0a 2a 2a 20 74 68  than going.** th
f4b0: 72 6f 75 67 68 20 61 6e 64 20 64 65 6c 65 74 69  rough and deleti
f4c0: 6e 67 20 69 6e 64 69 76 69 64 75 61 6c 20 65 6c  ng individual el
f4d0: 65 6d 65 6e 74 73 20 66 72 6f 6d 20 74 68 65 20  ements from the 
f4e0: 74 61 62 6c 65 2e 29 20 20 42 65 63 61 75 73 65  table.)  Because
f4f0: 20 6f 66 20 74 68 69 73 0a 2a 2a 20 6f 70 74 69   of this.** opti
f500: 6d 69 7a 61 74 69 6f 6e 2c 20 74 68 65 20 64 65  mization, the de
f510: 6c 65 74 69 6f 6e 73 20 69 6e 20 22 44 45 4c 45  letions in "DELE
f520: 54 45 20 46 52 4f 4d 20 74 61 62 6c 65 22 20 61  TE FROM table" a
f530: 72 65 20 6e 6f 74 20 72 6f 77 20 63 68 61 6e 67  re not row chang
f540: 65 73 20 61 6e 64 0a 2a 2a 20 77 69 6c 6c 20 6e  es and.** will n
f550: 6f 74 20 62 65 20 63 6f 75 6e 74 65 64 20 62 79  ot be counted by
f560: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 68 61   the sqlite3_cha
f570: 6e 67 65 73 28 29 20 6f 72 20 5b 73 71 6c 69 74  nges() or [sqlit
f580: 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73  e3_total_changes
f590: 28 29 5d 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73  ()].** functions
f5a0: 2c 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20  , regardless of 
f5b0: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 65 6c  the number of el
f5c0: 65 6d 65 6e 74 73 20 74 68 61 74 20 77 65 72 65  ements that were
f5d0: 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 69   originally.** i
f5e0: 6e 20 74 68 65 20 74 61 62 6c 65 2e 20 20 54 6f  n the table.  To
f5f0: 20 67 65 74 20 61 6e 20 61 63 63 75 72 61 74 65   get an accurate
f600: 20 63 6f 75 6e 74 20 6f 66 20 74 68 65 20 6e 75   count of the nu
f610: 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 64 65 6c  mber of rows del
f620: 65 74 65 64 2c 20 75 73 65 0a 2a 2a 20 22 44 45  eted, use.** "DE
f630: 4c 45 54 45 20 46 52 4f 4d 20 74 61 62 6c 65 20  LETE FROM table 
f640: 57 48 45 52 45 20 31 22 20 69 6e 73 74 65 61 64  WHERE 1" instead
f650: 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  ..**.** INVARIAN
f660: 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 34  TS:.**.** {H1224
f670: 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  1} The [sqlite3_
f680: 63 68 61 6e 67 65 73 28 29 5d 20 66 75 6e 63 74  changes()] funct
f690: 69 6f 6e 20 73 68 61 6c 6c 20 72 65 74 75 72 6e  ion shall return
f6a0: 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a   the number of.*
f6b0: 2a 20 20 20 20 20 20 20 20 20 20 72 6f 77 20 63  *          row c
f6c0: 68 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 79  hanges caused by
f6d0: 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
f6e0: 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c   INSERT, UPDATE,
f6f0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20  .**          or 
f700: 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74  DELETE statement
f710: 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74   on the same dat
f720: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
f730: 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20   and.**         
f740: 20 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65   within the same
f750: 20 6f 72 20 68 69 67 68 65 72 20 74 72 69 67 67   or higher trigg
f760: 65 72 20 63 6f 6e 74 65 78 74 2c 20 6f 72 20 7a  er context, or z
f770: 65 72 6f 20 69 66 20 74 68 65 72 65 20 68 61 76  ero if there hav
f780: 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 6f  e.**          no
f790: 74 20 62 65 65 6e 20 61 6e 79 20 71 75 61 6c 69  t been any quali
f7a0: 66 79 69 6e 67 20 72 6f 77 20 63 68 61 6e 67 65  fying row change
f7b0: 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 34 33  s..**.** {H12243
f7c0: 7d 20 53 74 61 74 65 6d 65 6e 74 73 20 6f 66 20  } Statements of 
f7d0: 74 68 65 20 66 6f 72 6d 20 22 44 45 4c 45 54 45  the form "DELETE
f7e0: 20 46 52 4f 4d 20 74 61 62 6c 65 6e 61 6d 65 22   FROM tablename"
f7f0: 20 77 69 74 68 20 6e 6f 0a 2a 2a 20 20 20 20 20   with no.**     
f800: 20 20 20 20 20 57 48 45 52 45 20 63 6c 61 75 73       WHERE claus
f810: 65 20 73 68 61 6c 6c 20 63 61 75 73 65 20 73 75  e shall cause su
f820: 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74  bsequent calls t
f830: 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  o.**          [s
f840: 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29  qlite3_changes()
f850: 5d 20 74 6f 20 72 65 74 75 72 6e 20 7a 65 72 6f  ] to return zero
f860: 2c 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20  , regardless of 
f870: 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
f880: 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 6f  number of rows o
f890: 72 69 67 69 6e 61 6c 6c 79 20 69 6e 20 74 68 65  riginally in the
f8a0: 20 74 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 41 53   table..**.** AS
f8b0: 53 55 4d 50 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a  SUMPTIONS:.**.**
f8c0: 20 7b 41 31 32 32 35 32 7d 20 49 66 20 61 20 73   {A12252} If a s
f8d0: 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20 6d  eparate thread m
f8e0: 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 6e 20  akes changes on 
f8f0: 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73  the same databas
f900: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20  e connection.** 
f910: 20 20 20 20 20 20 20 20 20 77 68 69 6c 65 20 5b           while [
f920: 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28  sqlite3_changes(
f930: 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68  )] is running th
f940: 65 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  en the value ret
f950: 75 72 6e 65 64 0a 2a 2a 20 20 20 20 20 20 20 20  urned.**        
f960: 20 20 69 73 20 75 6e 70 72 65 64 69 63 74 61 62    is unpredictab
f970: 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69  le and not meani
f980: 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ngful..*/.int sq
f990: 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 73 71  lite3_changes(sq
f9a0: 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  lite3*);../*.** 
f9b0: 43 41 50 49 33 52 45 46 3a 20 54 6f 74 61 6c 20  CAPI3REF: Total 
f9c0: 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d  Number Of Rows M
f9d0: 6f 64 69 66 69 65 64 20 7b 48 31 32 32 36 30 7d  odified {H12260}
f9e0: 20 3c 53 31 30 36 30 30 3e 0a 2a 2a 0a 2a 2a 20   <S10600>.**.** 
f9f0: 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65  This function re
fa00: 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
fa10: 20 6f 66 20 72 6f 77 20 63 68 61 6e 67 65 73 20   of row changes 
fa20: 63 61 75 73 65 64 20 62 79 20 49 4e 53 45 52 54  caused by INSERT
fa30: 2c 0a 2a 2a 20 55 50 44 41 54 45 20 6f 72 20 44  ,.** UPDATE or D
fa40: 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 73  ELETE statements
fa50: 20 73 69 6e 63 65 20 74 68 65 20 5b 64 61 74 61   since the [data
fa60: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
fa70: 20 77 61 73 20 6f 70 65 6e 65 64 2e 0a 2a 2a 20   was opened..** 
fa80: 54 68 65 20 63 6f 75 6e 74 20 69 6e 63 6c 75 64  The count includ
fa90: 65 73 20 61 6c 6c 20 63 68 61 6e 67 65 73 20 66  es all changes f
faa0: 72 6f 6d 20 61 6c 6c 20 74 72 69 67 67 65 72 20  rom all trigger 
fab0: 63 6f 6e 74 65 78 74 73 2e 20 20 48 6f 77 65 76  contexts.  Howev
fac0: 65 72 2c 0a 2a 2a 20 74 68 65 20 63 6f 75 6e 74  er,.** the count
fad0: 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64   does not includ
fae0: 65 20 63 68 61 6e 67 65 73 20 75 73 65 64 20 74  e changes used t
faf0: 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 52 45 50 4c  o implement REPL
fb00: 41 43 45 20 63 6f 6e 73 74 72 61 69 6e 74 73 2c  ACE constraints,
fb10: 0a 2a 2a 20 64 6f 20 72 6f 6c 6c 62 61 63 6b 73  .** do rollbacks
fb20: 20 6f 72 20 41 42 4f 52 54 20 70 72 6f 63 65 73   or ABORT proces
fb30: 73 69 6e 67 2c 20 6f 72 20 44 52 4f 50 20 74 61  sing, or DROP ta
fb40: 62 6c 65 20 70 72 6f 63 65 73 73 69 6e 67 2e 0a  ble processing..
fb50: 2a 2a 20 54 68 65 20 63 68 61 6e 67 65 73 20 61  ** The changes a
fb60: 72 65 20 63 6f 75 6e 74 65 64 20 61 73 20 73 6f  re counted as so
fb70: 6f 6e 20 61 73 20 74 68 65 20 73 74 61 74 65 6d  on as the statem
fb80: 65 6e 74 20 74 68 61 74 20 6d 61 6b 65 73 20 74  ent that makes t
fb90: 68 65 6d 20 69 73 0a 2a 2a 20 63 6f 6d 70 6c 65  hem is.** comple
fba0: 74 65 64 20 28 77 68 65 6e 20 74 68 65 20 73 74  ted (when the st
fbb0: 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 69  atement handle i
fbc0: 73 20 70 61 73 73 65 64 20 74 6f 20 5b 73 71 6c  s passed to [sql
fbd0: 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72  ite3_reset()] or
fbe0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  .** [sqlite3_fin
fbf0: 61 6c 69 7a 65 28 29 5d 29 2e 0a 2a 2a 0a 2a 2a  alize()])..**.**
fc00: 20 53 51 4c 69 74 65 20 69 6d 70 6c 65 6d 65 6e   SQLite implemen
fc10: 74 73 20 74 68 65 20 63 6f 6d 6d 61 6e 64 20 22  ts the command "
fc20: 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 61 62 6c  DELETE FROM tabl
fc30: 65 22 20 77 69 74 68 6f 75 74 20 61 20 57 48 45  e" without a WHE
fc40: 52 45 20 63 6c 61 75 73 65 0a 2a 2a 20 62 79 20  RE clause.** by 
fc50: 64 72 6f 70 70 69 6e 67 20 61 6e 64 20 72 65 63  dropping and rec
fc60: 72 65 61 74 69 6e 67 20 74 68 65 20 74 61 62 6c  reating the tabl
fc70: 65 2e 20 20 28 54 68 69 73 20 69 73 20 6d 75 63  e.  (This is muc
fc80: 68 20 66 61 73 74 65 72 20 74 68 61 6e 20 67 6f  h faster than go
fc90: 69 6e 67 0a 2a 2a 20 74 68 72 6f 75 67 68 20 61  ing.** through a
fca0: 6e 64 20 64 65 6c 65 74 69 6e 67 20 69 6e 64 69  nd deleting indi
fcb0: 76 69 64 75 61 6c 20 65 6c 65 6d 65 6e 74 73 20  vidual elements 
fcc0: 66 72 6f 6d 20 74 68 65 20 74 61 62 6c 65 2e 29  from the table.)
fcd0: 20 20 42 65 63 61 75 73 65 20 6f 66 20 74 68 69    Because of thi
fce0: 73 0a 2a 2a 20 6f 70 74 69 6d 69 7a 61 74 69 6f  s.** optimizatio
fcf0: 6e 2c 20 74 68 65 20 64 65 6c 65 74 69 6f 6e 73  n, the deletions
fd00: 20 69 6e 20 22 44 45 4c 45 54 45 20 46 52 4f 4d   in "DELETE FROM
fd10: 20 74 61 62 6c 65 22 20 61 72 65 20 6e 6f 74 20   table" are not 
fd20: 72 6f 77 20 63 68 61 6e 67 65 73 20 61 6e 64 0a  row changes and.
fd30: 2a 2a 20 77 69 6c 6c 20 6e 6f 74 20 62 65 20 63  ** will not be c
fd40: 6f 75 6e 74 65 64 20 62 79 20 74 68 65 20 73 71  ounted by the sq
fd50: 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20  lite3_changes() 
fd60: 6f 72 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61  or [sqlite3_tota
fd70: 6c 5f 63 68 61 6e 67 65 73 28 29 5d 0a 2a 2a 20  l_changes()].** 
fd80: 66 75 6e 63 74 69 6f 6e 73 2c 20 72 65 67 61 72  functions, regar
fd90: 64 6c 65 73 73 20 6f 66 20 74 68 65 20 6e 75 6d  dless of the num
fda0: 62 65 72 20 6f 66 20 65 6c 65 6d 65 6e 74 73 20  ber of elements 
fdb0: 74 68 61 74 20 77 65 72 65 20 6f 72 69 67 69 6e  that were origin
fdc0: 61 6c 6c 79 0a 2a 2a 20 69 6e 20 74 68 65 20 74  ally.** in the t
fdd0: 61 62 6c 65 2e 20 20 54 6f 20 67 65 74 20 61 6e  able.  To get an
fde0: 20 61 63 63 75 72 61 74 65 20 63 6f 75 6e 74 20   accurate count 
fdf0: 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  of the number of
fe00: 20 72 6f 77 73 20 64 65 6c 65 74 65 64 2c 20 75   rows deleted, u
fe10: 73 65 0a 2a 2a 20 22 44 45 4c 45 54 45 20 46 52  se.** "DELETE FR
fe20: 4f 4d 20 74 61 62 6c 65 20 57 48 45 52 45 20 31  OM table WHERE 1
fe30: 22 20 69 6e 73 74 65 61 64 2e 0a 2a 2a 0a 2a 2a  " instead..**.**
fe40: 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73   See also the [s
fe50: 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29  qlite3_changes()
fe60: 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a  ] interface..**.
fe70: 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
fe80: 2a 0a 2a 2a 20 7b 48 31 32 32 36 31 7d 20 54 68  *.** {H12261} Th
fe90: 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c  e [sqlite3_total
fea0: 5f 63 68 61 6e 67 65 73 28 29 5d 20 72 65 74 75  _changes()] retu
feb0: 72 6e 73 20 74 68 65 20 74 6f 74 61 6c 20 6e 75  rns the total nu
fec0: 6d 62 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  mber.**         
fed0: 20 6f 66 20 72 6f 77 20 63 68 61 6e 67 65 73 20   of row changes 
fee0: 63 61 75 73 65 64 20 62 79 20 49 4e 53 45 52 54  caused by INSERT
fef0: 2c 20 55 50 44 41 54 45 2c 20 61 6e 64 2f 6f 72  , UPDATE, and/or
ff00: 20 44 45 4c 45 54 45 0a 2a 2a 20 20 20 20 20 20   DELETE.**      
ff10: 20 20 20 20 73 74 61 74 65 6d 65 6e 74 73 20 6f      statements o
ff20: 6e 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61  n the same [data
ff30: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
ff40: 2c 20 69 6e 20 61 6e 79 0a 2a 2a 20 20 20 20 20  , in any.**     
ff50: 20 20 20 20 20 74 72 69 67 67 65 72 20 63 6f 6e       trigger con
ff60: 74 65 78 74 2c 20 73 69 6e 63 65 20 74 68 65 20  text, since the 
ff70: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
ff80: 69 6f 6e 20 77 61 73 20 63 72 65 61 74 65 64 2e  ion was created.
ff90: 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 36 33 7d 20  .**.** {H12263} 
ffa0: 53 74 61 74 65 6d 65 6e 74 73 20 6f 66 20 74 68  Statements of th
ffb0: 65 20 66 6f 72 6d 20 22 44 45 4c 45 54 45 20 46  e form "DELETE F
ffc0: 52 4f 4d 20 74 61 62 6c 65 6e 61 6d 65 22 20 77  ROM tablename" w
ffd0: 69 74 68 20 6e 6f 0a 2a 2a 20 20 20 20 20 20 20  ith no.**       
ffe0: 20 20 20 57 48 45 52 45 20 63 6c 61 75 73 65 20     WHERE clause 
fff0: 73 68 61 6c 6c 20 6e 6f 74 20 63 68 61 6e 67 65  shall not change
10000 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
10010 6e 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ned.**          
10020 62 79 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61  by [sqlite3_tota
10030 6c 5f 63 68 61 6e 67 65 73 28 29 5d 2e 0a 2a 2a  l_changes()]..**
10040 0a 2a 2a 20 41 53 53 55 4d 50 54 49 4f 4e 53 3a  .** ASSUMPTIONS:
10050 0a 2a 2a 0a 2a 2a 20 7b 41 31 32 32 36 34 7d 20  .**.** {A12264} 
10060 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68  If a separate th
10070 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67  read makes chang
10080 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64  es on the same d
10090 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
100a0 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77  on.**          w
100b0 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f  hile [sqlite3_to
100c0 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 69  tal_changes()] i
100d0 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74  s running then t
100e0 68 65 20 76 61 6c 75 65 0a 2a 2a 20 20 20 20 20  he value.**     
100f0 20 20 20 20 20 72 65 74 75 72 6e 65 64 20 69 73       returned is
10100 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61   unpredictable a
10110 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75  nd not meaningfu
10120 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  l..*/.int sqlite
10130 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28  3_total_changes(
10140 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a  sqlite3*);../*.*
10150 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 74 65  * CAPI3REF: Inte
10160 72 72 75 70 74 20 41 20 4c 6f 6e 67 2d 52 75 6e  rrupt A Long-Run
10170 6e 69 6e 67 20 51 75 65 72 79 20 7b 48 31 32 32  ning Query {H122
10180 37 30 7d 20 3c 53 33 30 35 30 30 3e 0a 2a 2a 0a  70} <S30500>.**.
10190 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e  ** This function
101a0 20 63 61 75 73 65 73 20 61 6e 79 20 70 65 6e 64   causes any pend
101b0 69 6e 67 20 64 61 74 61 62 61 73 65 20 6f 70 65  ing database ope
101c0 72 61 74 69 6f 6e 20 74 6f 20 61 62 6f 72 74 20  ration to abort 
101d0 61 6e 64 0a 2a 2a 20 72 65 74 75 72 6e 20 61 74  and.** return at
101e0 20 69 74 73 20 65 61 72 6c 69 65 73 74 20 6f 70   its earliest op
101f0 70 6f 72 74 75 6e 69 74 79 2e 20 54 68 69 73 20  portunity. This 
10200 72 6f 75 74 69 6e 65 20 69 73 20 74 79 70 69 63  routine is typic
10210 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 69  ally.** called i
10220 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f 20 61 20  n response to a 
10230 75 73 65 72 20 61 63 74 69 6f 6e 20 73 75 63 68  user action such
10240 20 61 73 20 70 72 65 73 73 69 6e 67 20 22 43 61   as pressing "Ca
10250 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20 43 74 72 6c  ncel".** or Ctrl
10260 2d 43 20 77 68 65 72 65 20 74 68 65 20 75 73 65  -C where the use
10270 72 20 77 61 6e 74 73 20 61 20 6c 6f 6e 67 20 71  r wants a long q
10280 75 65 72 79 20 6f 70 65 72 61 74 69 6f 6e 20 74  uery operation t
10290 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d 6d 65 64 69  o halt.** immedi
102a0 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 49 74 20  ately..**.** It 
102b0 69 73 20 73 61 66 65 20 74 6f 20 63 61 6c 6c 20  is safe to call 
102c0 74 68 69 73 20 72 6f 75 74 69 6e 65 20 66 72 6f  this routine fro
102d0 6d 20 61 20 74 68 72 65 61 64 20 64 69 66 66 65  m a thread diffe
102e0 72 65 6e 74 20 66 72 6f 6d 20 74 68 65 0a 2a 2a  rent from the.**
102f0 20 74 68 72 65 61 64 20 74 68 61 74 20 69 73 20   thread that is 
10300 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e  currently runnin
10310 67 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6f  g the database o
10320 70 65 72 61 74 69 6f 6e 2e 20 20 42 75 74 20 69  peration.  But i
10330 74 0a 2a 2a 20 69 73 20 6e 6f 74 20 73 61 66 65  t.** is not safe
10340 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f   to call this ro
10350 75 74 69 6e 65 20 77 69 74 68 20 61 20 5b 64 61  utine with a [da
10360 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
10370 6e 5d 20 74 68 61 74 0a 2a 2a 20 69 73 20 63 6c  n] that.** is cl
10380 6f 73 65 64 20 6f 72 20 6d 69 67 68 74 20 63 6c  osed or might cl
10390 6f 73 65 20 62 65 66 6f 72 65 20 73 71 6c 69 74  ose before sqlit
103a0 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 72  e3_interrupt() r
103b0 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 66  eturns..**.** If
103c0 20 61 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f   an SQL operatio
103d0 6e 20 69 73 20 76 65 72 79 20 6e 65 61 72 6c 79  n is very nearly
103e0 20 66 69 6e 69 73 68 65 64 20 61 74 20 74 68 65   finished at the
103f0 20 74 69 6d 65 20 77 68 65 6e 0a 2a 2a 20 73 71   time when.** sq
10400 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
10410 29 20 69 73 20 63 61 6c 6c 65 64 2c 20 74 68 65  ) is called, the
10420 6e 20 69 74 20 6d 69 67 68 74 20 6e 6f 74 20 68  n it might not h
10430 61 76 65 20 61 6e 20 6f 70 70 6f 72 74 75 6e 69  ave an opportuni
10440 74 79 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 74 65  ty.** to be inte
10450 72 72 75 70 74 65 64 20 61 6e 64 20 6d 69 67 68  rrupted and migh
10460 74 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 63 6f  t continue to co
10470 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  mpletion..**.** 
10480 41 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e  An SQL operation
10490 20 74 68 61 74 20 69 73 20 69 6e 74 65 72 72 75   that is interru
104a0 70 74 65 64 20 77 69 6c 6c 20 72 65 74 75 72 6e  pted will return
104b0 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55   [SQLITE_INTERRU
104c0 50 54 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20 69  PT]..** If the i
104d0 6e 74 65 72 72 75 70 74 65 64 20 53 51 4c 20 6f  nterrupted SQL o
104e0 70 65 72 61 74 69 6f 6e 20 69 73 20 61 6e 20 49  peration is an I
104f0 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f  NSERT, UPDATE, o
10500 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74  r DELETE.** that
10510 20 69 73 20 69 6e 73 69 64 65 20 61 6e 20 65 78   is inside an ex
10520 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69  plicit transacti
10530 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 65 6e 74  on, then the ent
10540 69 72 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 0a  ire transaction.
10550 2a 2a 20 77 69 6c 6c 20 62 65 20 72 6f 6c 6c 65  ** will be rolle
10560 64 20 62 61 63 6b 20 61 75 74 6f 6d 61 74 69 63  d back automatic
10570 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61  ally..**.** A ca
10580 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e  ll to sqlite3_in
10590 74 65 72 72 75 70 74 28 29 20 68 61 73 20 6e 6f  terrupt() has no
105a0 20 65 66 66 65 63 74 20 6f 6e 20 53 51 4c 20 73   effect on SQL s
105b0 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61  tatements.** tha
105c0 74 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66  t are started af
105d0 74 65 72 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  ter sqlite3_inte
105e0 72 72 75 70 74 28 29 20 72 65 74 75 72 6e 73 2e  rrupt() returns.
105f0 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
10600 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 37 31  S:.**.** {H12271
10610 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 69  } The [sqlite3_i
10620 6e 74 65 72 72 75 70 74 28 29 5d 20 69 6e 74 65  nterrupt()] inte
10630 72 66 61 63 65 20 77 69 6c 6c 20 66 6f 72 63 65  rface will force
10640 20 61 6c 6c 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20   all running.** 
10650 20 20 20 20 20 20 20 20 20 53 51 4c 20 73 74 61           SQL sta
10660 74 65 6d 65 6e 74 73 20 61 73 73 6f 63 69 61 74  tements associat
10670 65 64 20 77 69 74 68 20 74 68 65 20 73 61 6d 65  ed with the same
10680 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
10690 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  tion.**         
106a0 20 74 6f 20 68 61 6c 74 20 61 66 74 65 72 20 70   to halt after p
106b0 72 6f 63 65 73 73 69 6e 67 20 61 74 20 6d 6f 73  rocessing at mos
106c0 74 20 6f 6e 65 20 61 64 64 69 74 69 6f 6e 61 6c  t one additional
106d0 20 72 6f 77 20 6f 66 20 64 61 74 61 2e 0a 2a 2a   row of data..**
106e0 0a 2a 2a 20 7b 48 31 32 32 37 32 7d 20 41 6e 79  .** {H12272} Any
106f0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74   SQL statement t
10700 68 61 74 20 69 73 20 69 6e 74 65 72 72 75 70 74  hat is interrupt
10710 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 69  ed by [sqlite3_i
10720 6e 74 65 72 72 75 70 74 28 29 5d 0a 2a 2a 20 20  nterrupt()].**  
10730 20 20 20 20 20 20 20 20 77 69 6c 6c 20 72 65 74          will ret
10740 75 72 6e 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45  urn [SQLITE_INTE
10750 52 52 55 50 54 5d 2e 0a 2a 2a 0a 2a 2a 20 41 53  RRUPT]..**.** AS
10760 53 55 4d 50 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a  SUMPTIONS:.**.**
10770 20 7b 41 31 32 32 37 39 7d 20 49 66 20 74 68 65   {A12279} If the
10780 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
10790 74 69 6f 6e 20 63 6c 6f 73 65 73 20 77 68 69 6c  tion closes whil
107a0 65 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  e [sqlite3_inter
107b0 72 75 70 74 28 29 5d 0a 2a 2a 20 20 20 20 20 20  rupt()].**      
107c0 20 20 20 20 69 73 20 72 75 6e 6e 69 6e 67 20 74      is running t
107d0 68 65 6e 20 62 61 64 20 74 68 69 6e 67 73 20 77  hen bad things w
107e0 69 6c 6c 20 6c 69 6b 65 6c 79 20 68 61 70 70 65  ill likely happe
107f0 6e 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74  n..*/.void sqlit
10800 65 33 5f 69 6e 74 65 72 72 75 70 74 28 73 71 6c  e3_interrupt(sql
10810 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ite3*);../*.** C
10820 41 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69  API3REF: Determi
10830 6e 65 20 49 66 20 41 6e 20 53 51 4c 20 53 74 61  ne If An SQL Sta
10840 74 65 6d 65 6e 74 20 49 73 20 43 6f 6d 70 6c 65  tement Is Comple
10850 74 65 20 7b 48 31 30 35 31 30 7d 20 3c 53 37 30  te {H10510} <S70
10860 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  200>.**.** These
10870 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73   routines are us
10880 65 66 75 6c 20 66 6f 72 20 63 6f 6d 6d 61 6e 64  eful for command
10890 2d 6c 69 6e 65 20 69 6e 70 75 74 20 74 6f 20 64  -line input to d
108a0 65 74 65 72 6d 69 6e 65 20 69 66 20 74 68 65 0a  etermine if the.
108b0 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20 65 6e 74  ** currently ent
108c0 65 72 65 64 20 74 65 78 74 20 73 65 65 6d 73 20  ered text seems 
108d0 74 6f 20 66 6f 72 6d 20 63 6f 6d 70 6c 65 74 65  to form complete
108e0 20 61 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74   a SQL statement
108f0 20 6f 72 0a 2a 2a 20 69 66 20 61 64 64 69 74 69   or.** if additi
10900 6f 6e 61 6c 20 69 6e 70 75 74 20 69 73 20 6e 65  onal input is ne
10910 65 64 65 64 20 62 65 66 6f 72 65 20 73 65 6e 64  eded before send
10920 69 6e 67 20 74 68 65 20 74 65 78 74 20 69 6e 74  ing the text int
10930 6f 0a 2a 2a 20 53 51 4c 69 74 65 20 66 6f 72 20  o.** SQLite for 
10940 70 61 72 73 69 6e 67 2e 20 20 54 68 65 73 65 20  parsing.  These 
10950 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
10960 74 72 75 65 20 69 66 20 74 68 65 20 69 6e 70 75  true if the inpu
10970 74 20 73 74 72 69 6e 67 0a 2a 2a 20 61 70 70 65  t string.** appe
10980 61 72 73 20 74 6f 20 62 65 20 61 20 63 6f 6d 70  ars to be a comp
10990 6c 65 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65  lete SQL stateme
109a0 6e 74 2e 20 20 41 20 73 74 61 74 65 6d 65 6e 74  nt.  A statement
109b0 20 69 73 20 6a 75 64 67 65 64 20 74 6f 20 62 65   is judged to be
109c0 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 69 66 20  .** complete if 
109d0 69 74 20 65 6e 64 73 20 77 69 74 68 20 61 20 73  it ends with a s
109e0 65 6d 69 63 6f 6c 6f 6e 20 74 6f 6b 65 6e 20 61  emicolon token a
109f0 6e 64 20 69 73 20 6e 6f 74 20 61 20 66 72 61 67  nd is not a frag
10a00 6d 65 6e 74 20 6f 66 20 61 0a 2a 2a 20 43 52 45  ment of a.** CRE
10a10 41 54 45 20 54 52 49 47 47 45 52 20 73 74 61 74  ATE TRIGGER stat
10a20 65 6d 65 6e 74 2e 20 20 53 65 6d 69 63 6f 6c 6f  ement.  Semicolo
10a30 6e 73 20 74 68 61 74 20 61 72 65 20 65 6d 62 65  ns that are embe
10a40 64 64 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 73  dded within.** s
10a50 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 73 20 6f  tring literals o
10a60 72 20 71 75 6f 74 65 64 20 69 64 65 6e 74 69 66  r quoted identif
10a70 69 65 72 20 6e 61 6d 65 73 20 6f 72 20 63 6f 6d  ier names or com
10a80 6d 65 6e 74 73 20 61 72 65 20 6e 6f 74 0a 2a 2a  ments are not.**
10a90 20 69 6e 64 65 70 65 6e 64 65 6e 74 20 74 6f 6b   independent tok
10aa0 65 6e 73 20 28 74 68 65 79 20 61 72 65 20 70 61  ens (they are pa
10ab0 72 74 20 6f 66 20 74 68 65 20 74 6f 6b 65 6e 20  rt of the token 
10ac0 69 6e 20 77 68 69 63 68 20 74 68 65 79 20 61 72  in which they ar
10ad0 65 0a 2a 2a 20 65 6d 62 65 64 64 65 64 29 20 61  e.** embedded) a
10ae0 6e 64 20 74 68 75 73 20 64 6f 20 6e 6f 74 20 63  nd thus do not c
10af0 6f 75 6e 74 20 61 73 20 61 20 73 74 61 74 65 6d  ount as a statem
10b00 65 6e 74 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a  ent terminator..
10b10 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
10b20 69 6e 65 73 20 64 6f 20 6e 6f 74 20 70 61 72 73  ines do not pars
10b30 65 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  e the SQL statem
10b40 65 6e 74 73 20 74 68 75 73 0a 2a 2a 20 77 69 6c  ents thus.** wil
10b50 6c 20 6e 6f 74 20 64 65 74 65 63 74 20 73 79 6e  l not detect syn
10b60 74 61 63 74 69 63 61 6c 6c 79 20 69 6e 63 6f 72  tactically incor
10b70 72 65 63 74 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20  rect SQL..**.** 
10b80 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
10b90 2a 20 7b 48 31 30 35 31 31 7d 20 41 20 73 75 63  * {H10511} A suc
10ba0 63 65 73 73 66 75 6c 20 65 76 61 6c 75 61 74 69  cessful evaluati
10bb0 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 63  on of [sqlite3_c
10bc0 6f 6d 70 6c 65 74 65 28 29 5d 20 6f 72 0a 2a 2a  omplete()] or.**
10bd0 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
10be0 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 5d  e3_complete16()]
10bf0 20 66 75 6e 63 74 69 6f 6e 73 20 73 68 61 6c 6c   functions shall
10c00 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74  .**          ret
10c10 75 72 6e 20 61 20 6e 75 6d 65 72 69 63 20 31 20  urn a numeric 1 
10c20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74  if and only if t
10c30 68 65 20 6c 61 73 74 20 6e 6f 6e 2d 77 68 69 74  he last non-whit
10c40 65 73 70 61 63 65 0a 2a 2a 20 20 20 20 20 20 20  espace.**       
10c50 20 20 20 74 6f 6b 65 6e 20 69 6e 20 74 68 65 69     token in thei
10c60 72 20 69 6e 70 75 74 20 69 73 20 61 20 73 65 6d  r input is a sem
10c70 69 63 6f 6c 6f 6e 20 74 68 61 74 20 69 73 20 6e  icolon that is n
10c80 6f 74 20 69 6e 20 62 65 74 77 65 65 6e 0a 2a 2a  ot in between.**
10c90 20 20 20 20 20 20 20 20 20 20 74 68 65 20 42 45            the BE
10ca0 47 49 4e 20 61 6e 64 20 45 4e 44 20 6f 66 20 61  GIN and END of a
10cb0 20 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20   CREATE TRIGGER 
10cc0 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a  statement..**.**
10cd0 20 7b 48 31 30 35 31 32 7d 20 49 66 20 61 20 6d   {H10512} If a m
10ce0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
10cf0 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 64 75   error occurs du
10d00 72 69 6e 67 20 61 6e 20 69 6e 76 6f 63 61 74 69  ring an invocati
10d10 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  on.**          o
10d20 66 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c  f [sqlite3_compl
10d30 65 74 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  ete()] or [sqlit
10d40 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 5d  e3_complete16()]
10d50 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 20 20 20   then the.**    
10d60 20 20 20 20 20 20 72 6f 75 74 69 6e 65 20 73 68        routine sh
10d70 61 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  all return [SQLI
10d80 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a  TE_NOMEM]..**.**
10d90 20 41 53 53 55 4d 50 54 49 4f 4e 53 3a 0a 2a 2a   ASSUMPTIONS:.**
10da0 0a 2a 2a 20 7b 41 31 30 35 31 32 7d 20 54 68 65  .** {A10512} The
10db0 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74   input to [sqlit
10dc0 65 33 5f 63 6f 6d 70 6c 65 74 65 28 29 5d 20 6d  e3_complete()] m
10dd0 75 73 74 20 62 65 20 61 20 7a 65 72 6f 2d 74 65  ust be a zero-te
10de0 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 20 20 20 20  rminated.**     
10df0 20 20 20 20 20 55 54 46 2d 38 20 73 74 72 69 6e       UTF-8 strin
10e00 67 2e 0a 2a 2a 0a 2a 2a 20 7b 41 31 30 35 31 33  g..**.** {A10513
10e10 7d 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20 5b  } The input to [
10e20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
10e30 31 36 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20  16()] must be a 
10e40 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a  zero-terminated.
10e50 2a 2a 20 20 20 20 20 20 20 20 20 20 55 54 46 2d  **          UTF-
10e60 31 36 20 73 74 72 69 6e 67 20 69 6e 20 6e 61 74  16 string in nat
10e70 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a  ive byte order..
10e80 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  */.int sqlite3_c
10e90 6f 6d 70 6c 65 74 65 28 63 6f 6e 73 74 20 63 68  omplete(const ch
10ea0 61 72 20 2a 73 71 6c 29 3b 0a 69 6e 74 20 73 71  ar *sql);.int sq
10eb0 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36  lite3_complete16
10ec0 28 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  (const void *sql
10ed0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
10ee0 45 46 3a 20 52 65 67 69 73 74 65 72 20 41 20 43  EF: Register A C
10ef0 61 6c 6c 62 61 63 6b 20 54 6f 20 48 61 6e 64 6c  allback To Handl
10f00 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20 45 72  e SQLITE_BUSY Er
10f10 72 6f 72 73 20 7b 48 31 32 33 31 30 7d 20 3c 53  rors {H12310} <S
10f20 34 30 34 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69  40400>.**.** Thi
10f30 73 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61  s routine sets a
10f40 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
10f50 6f 6e 20 74 68 61 74 20 6d 69 67 68 74 20 62 65  on that might be
10f60 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65   invoked wheneve
10f70 72 0a 2a 2a 20 61 6e 20 61 74 74 65 6d 70 74 20  r.** an attempt 
10f80 69 73 20 6d 61 64 65 20 74 6f 20 6f 70 65 6e 20  is made to open 
10f90 61 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65  a database table
10fa0 20 74 68 61 74 20 61 6e 6f 74 68 65 72 20 74 68   that another th
10fb0 72 65 61 64 0a 2a 2a 20 6f 72 20 70 72 6f 63 65  read.** or proce
10fc0 73 73 20 68 61 73 20 6c 6f 63 6b 65 64 2e 0a 2a  ss has locked..*
10fd0 2a 0a 2a 2a 20 49 66 20 74 68 65 20 62 75 73 79  *.** If the busy
10fe0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c   callback is NUL
10ff0 4c 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f  L, then [SQLITE_
11000 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45  BUSY] or [SQLITE
11010 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a  _IOERR_BLOCKED].
11020 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 69  ** is returned i
11030 6d 6d 65 64 69 61 74 65 6c 79 20 75 70 6f 6e 20  mmediately upon 
11040 65 6e 63 6f 75 6e 74 65 72 69 6e 67 20 74 68 65  encountering the
11050 20 6c 6f 63 6b 2e 20 49 66 20 74 68 65 20 62 75   lock. If the bu
11060 73 79 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69  sy callback.** i
11070 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e  s not NULL, then
11080 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 77 69   the callback wi
11090 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69  ll be invoked wi
110a0 74 68 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73  th two arguments
110b0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73  ..**.** The firs
110c0 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  t argument to th
110d0 65 20 68 61 6e 64 6c 65 72 20 69 73 20 61 20 63  e handler is a c
110e0 6f 70 79 20 6f 66 20 74 68 65 20 76 6f 69 64 2a  opy of the void*
110f0 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68 0a 2a   pointer which.*
11100 2a 20 69 73 20 74 68 65 20 74 68 69 72 64 20 61  * is the third a
11110 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
11120 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28  e3_busy_handler(
11130 29 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 61  ).  The second a
11140 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74 68  rgument to.** th
11150 65 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61  e handler callba
11160 63 6b 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72  ck is the number
11170 20 6f 66 20 74 69 6d 65 73 20 74 68 61 74 20 74   of times that t
11180 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  he busy handler 
11190 68 61 73 0a 2a 2a 20 62 65 65 6e 20 69 6e 76 6f  has.** been invo
111a0 6b 65 64 20 66 6f 72 20 74 68 69 73 20 6c 6f 63  ked for this loc
111b0 6b 69 6e 67 20 65 76 65 6e 74 2e 20 20 49 66 20  king event.  If 
111c0 74 68 65 0a 2a 2a 20 62 75 73 79 20 63 61 6c 6c  the.** busy call
111d0 62 61 63 6b 20 72 65 74 75 72 6e 73 20 30 2c 20  back returns 0, 
111e0 74 68 65 6e 20 6e 6f 20 61 64 64 69 74 69 6f 6e  then no addition
111f0 61 6c 20 61 74 74 65 6d 70 74 73 20 61 72 65 20  al attempts are 
11200 6d 61 64 65 20 74 6f 0a 2a 2a 20 61 63 63 65 73  made to.** acces
11210 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 61  s the database a
11220 6e 64 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  nd [SQLITE_BUSY]
11230 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52   or [SQLITE_IOER
11240 52 5f 42 4c 4f 43 4b 45 44 5d 20 69 73 20 72 65  R_BLOCKED] is re
11250 74 75 72 6e 65 64 2e 0a 2a 2a 20 49 66 20 74 68  turned..** If th
11260 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  e callback retur
11270 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65  ns non-zero, the
11280 6e 20 61 6e 6f 74 68 65 72 20 61 74 74 65 6d 70  n another attemp
11290 74 0a 2a 2a 20 69 73 20 6d 61 64 65 20 74 6f 20  t.** is made to 
112a0 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  open the databas
112b0 65 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e  e for reading an
112c0 64 20 74 68 65 20 63 79 63 6c 65 20 72 65 70 65  d the cycle repe
112d0 61 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70  ats..**.** The p
112e0 72 65 73 65 6e 63 65 20 6f 66 20 61 20 62 75 73  resence of a bus
112f0 79 20 68 61 6e 64 6c 65 72 20 64 6f 65 73 20 6e  y handler does n
11300 6f 74 20 67 75 61 72 61 6e 74 65 65 20 74 68 61  ot guarantee tha
11310 74 20 69 74 20 77 69 6c 6c 20 62 65 20 69 6e 76  t it will be inv
11320 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e 20 74 68 65  oked.** when the
11330 72 65 20 69 73 20 6c 6f 63 6b 20 63 6f 6e 74 65  re is lock conte
11340 6e 74 69 6f 6e 2e 20 49 66 20 53 51 4c 69 74 65  ntion. If SQLite
11350 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68 61 74   determines that
11360 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62 75   invoking the bu
11370 73 79 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 63 6f  sy.** handler co
11380 75 6c 64 20 72 65 73 75 6c 74 20 69 6e 20 61 20  uld result in a 
11390 64 65 61 64 6c 6f 63 6b 2c 20 69 74 20 77 69 6c  deadlock, it wil
113a0 6c 20 67 6f 20 61 68 65 61 64 20 61 6e 64 20 72  l go ahead and r
113b0 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55  eturn [SQLITE_BU
113c0 53 59 5d 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54  SY].** or [SQLIT
113d0 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d  E_IOERR_BLOCKED]
113e0 20 69 6e 73 74 65 61 64 20 6f 66 20 69 6e 76 6f   instead of invo
113f0 6b 69 6e 67 20 74 68 65 20 62 75 73 79 20 68 61  king the busy ha
11400 6e 64 6c 65 72 2e 0a 2a 2a 20 43 6f 6e 73 69 64  ndler..** Consid
11410 65 72 20 61 20 73 63 65 6e 61 72 69 6f 20 77 68  er a scenario wh
11420 65 72 65 20 6f 6e 65 20 70 72 6f 63 65 73 73 20  ere one process 
11430 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 61  is holding a rea
11440 64 20 6c 6f 63 6b 20 74 68 61 74 0a 2a 2a 20 69  d lock that.** i
11450 74 20 69 73 20 74 72 79 69 6e 67 20 74 6f 20 70  t is trying to p
11460 72 6f 6d 6f 74 65 20 74 6f 20 61 20 72 65 73 65  romote to a rese
11470 72 76 65 64 20 6c 6f 63 6b 20 61 6e 64 0a 2a 2a  rved lock and.**
11480 20 61 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73   a second proces
11490 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72  s is holding a r
114a0 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 74 68 61  eserved lock tha
114b0 74 20 69 74 20 69 73 20 74 72 79 69 6e 67 0a 2a  t it is trying.*
114c0 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20  * to promote to 
114d0 61 6e 20 65 78 63 6c 75 73 69 76 65 20 6c 6f 63  an exclusive loc
114e0 6b 2e 20 20 54 68 65 20 66 69 72 73 74 20 70 72  k.  The first pr
114f0 6f 63 65 73 73 20 63 61 6e 6e 6f 74 20 70 72 6f  ocess cannot pro
11500 63 65 65 64 0a 2a 2a 20 62 65 63 61 75 73 65 20  ceed.** because 
11510 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79  it is blocked by
11520 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20   the second and 
11530 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65  the second proce
11540 73 73 20 63 61 6e 6e 6f 74 0a 2a 2a 20 70 72 6f  ss cannot.** pro
11550 63 65 65 64 20 62 65 63 61 75 73 65 20 69 74 20  ceed because it 
11560 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68  is blocked by th
11570 65 20 66 69 72 73 74 2e 20 20 49 66 20 62 6f 74  e first.  If bot
11580 68 20 70 72 6f 63 65 73 73 65 73 0a 2a 2a 20 69  h processes.** i
11590 6e 76 6f 6b 65 20 74 68 65 20 62 75 73 79 20 68  nvoke the busy h
115a0 61 6e 64 6c 65 72 73 2c 20 6e 65 69 74 68 65 72  andlers, neither
115b0 20 77 69 6c 6c 20 6d 61 6b 65 20 61 6e 79 20 70   will make any p
115c0 72 6f 67 72 65 73 73 2e 20 20 54 68 65 72 65 66  rogress.  Theref
115d0 6f 72 65 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 72  ore,.** SQLite r
115e0 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 42  eturns [SQLITE_B
115f0 55 53 59 5d 20 66 6f 72 20 74 68 65 20 66 69 72  USY] for the fir
11600 73 74 20 70 72 6f 63 65 73 73 2c 20 68 6f 70 69  st process, hopi
11610 6e 67 20 74 68 61 74 20 74 68 69 73 0a 2a 2a 20  ng that this.** 
11620 77 69 6c 6c 20 69 6e 64 75 63 65 20 74 68 65 20  will induce the 
11630 66 69 72 73 74 20 70 72 6f 63 65 73 73 20 74 6f  first process to
11640 20 72 65 6c 65 61 73 65 20 69 74 73 20 72 65 61   release its rea
11650 64 20 6c 6f 63 6b 20 61 6e 64 20 61 6c 6c 6f 77  d lock and allow
11660 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64 20 70  .** the second p
11670 72 6f 63 65 73 73 20 74 6f 20 70 72 6f 63 65 65  rocess to procee
11680 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 66  d..**.** The def
11690 61 75 6c 74 20 62 75 73 79 20 63 61 6c 6c 62 61  ault busy callba
116a0 63 6b 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  ck is NULL..**.*
116b0 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 42 55  * The [SQLITE_BU
116c0 53 59 5d 20 65 72 72 6f 72 20 69 73 20 63 6f 6e  SY] error is con
116d0 76 65 72 74 65 64 20 74 6f 20 5b 53 51 4c 49 54  verted to [SQLIT
116e0 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d  E_IOERR_BLOCKED]
116f0 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74 65 20  .** when SQLite 
11700 69 73 20 69 6e 20 74 68 65 20 6d 69 64 64 6c 65  is in the middle
11710 20 6f 66 20 61 20 6c 61 72 67 65 20 74 72 61 6e   of a large tran
11720 73 61 63 74 69 6f 6e 20 77 68 65 72 65 20 61 6c  saction where al
11730 6c 20 74 68 65 0a 2a 2a 20 63 68 61 6e 67 65 73  l the.** changes
11740 20 77 69 6c 6c 20 6e 6f 74 20 66 69 74 20 69 6e   will not fit in
11750 74 6f 20 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79  to the in-memory
11760 20 63 61 63 68 65 2e 20 20 53 51 4c 69 74 65 20   cache.  SQLite 
11770 77 69 6c 6c 0a 2a 2a 20 61 6c 72 65 61 64 79 20  will.** already 
11780 68 6f 6c 64 20 61 20 52 45 53 45 52 56 45 44 20  hold a RESERVED 
11790 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 64 61 74 61  lock on the data
117a0 62 61 73 65 20 66 69 6c 65 2c 20 62 75 74 20 69  base file, but i
117b0 74 20 6e 65 65 64 73 0a 2a 2a 20 74 6f 20 70 72  t needs.** to pr
117c0 6f 6d 6f 74 65 20 74 68 69 73 20 6c 6f 63 6b 20  omote this lock 
117d0 74 6f 20 45 58 43 4c 55 53 49 56 45 20 73 6f 20  to EXCLUSIVE so 
117e0 74 68 61 74 20 69 74 20 63 61 6e 20 73 70 69 6c  that it can spil
117f0 6c 20 63 61 63 68 65 0a 2a 2a 20 70 61 67 65 73  l cache.** pages
11800 20 69 6e 74 6f 20 74 68 65 20 64 61 74 61 62 61   into the databa
11810 73 65 20 66 69 6c 65 20 77 69 74 68 6f 75 74 20  se file without 
11820 68 61 72 6d 20 74 6f 20 63 6f 6e 63 75 72 72 65  harm to concurre
11830 6e 74 0a 2a 2a 20 72 65 61 64 65 72 73 2e 20 20  nt.** readers.  
11840 49 66 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20  If it is unable 
11850 74 6f 20 70 72 6f 6d 6f 74 65 20 74 68 65 20 6c  to promote the l
11860 6f 63 6b 2c 20 74 68 65 6e 20 74 68 65 20 69 6e  ock, then the in
11870 2d 6d 65 6d 6f 72 79 0a 2a 2a 20 63 61 63 68 65  -memory.** cache
11880 20 77 69 6c 6c 20 62 65 20 6c 65 66 74 20 69 6e   will be left in
11890 20 61 6e 20 69 6e 63 6f 6e 73 69 73 74 65 6e 74   an inconsistent
118a0 20 73 74 61 74 65 20 61 6e 64 20 73 6f 20 74 68   state and so th
118b0 65 20 65 72 72 6f 72 0a 2a 2a 20 63 6f 64 65 20  e error.** code 
118c0 69 73 20 70 72 6f 6d 6f 74 65 64 20 66 72 6f 6d  is promoted from
118d0 20 74 68 65 20 72 65 6c 61 74 69 76 65 6c 79 20   the relatively 
118e0 62 65 6e 69 67 6e 20 5b 53 51 4c 49 54 45 5f 42  benign [SQLITE_B
118f0 55 53 59 5d 20 74 6f 0a 2a 2a 20 74 68 65 20 6d  USY] to.** the m
11900 6f 72 65 20 73 65 76 65 72 65 20 5b 53 51 4c 49  ore severe [SQLI
11910 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44  TE_IOERR_BLOCKED
11920 5d 2e 20 20 54 68 69 73 20 65 72 72 6f 72 20 63  ].  This error c
11930 6f 64 65 20 70 72 6f 6d 6f 74 69 6f 6e 0a 2a 2a  ode promotion.**
11940 20 66 6f 72 63 65 73 20 61 6e 20 61 75 74 6f 6d   forces an autom
11950 61 74 69 63 20 72 6f 6c 6c 62 61 63 6b 20 6f 66  atic rollback of
11960 20 74 68 65 20 63 68 61 6e 67 65 73 2e 20 20 53   the changes.  S
11970 65 65 20 74 68 65 0a 2a 2a 20 3c 61 20 68 72 65  ee the.** <a hre
11980 66 3d 22 2f 63 76 73 74 72 61 63 2f 77 69 6b 69  f="/cvstrac/wiki
11990 3f 70 3d 43 6f 72 72 75 70 74 69 6f 6e 46 6f 6c  ?p=CorruptionFol
119a0 6c 6f 77 69 6e 67 42 75 73 79 45 72 72 6f 72 22  lowingBusyError"
119b0 3e 0a 2a 2a 20 43 6f 72 72 75 70 74 69 6f 6e 46  >.** CorruptionF
119c0 6f 6c 6c 6f 77 69 6e 67 42 75 73 79 45 72 72 6f  ollowingBusyErro
119d0 72 3c 2f 61 3e 20 77 69 6b 69 20 70 61 67 65 20  r</a> wiki page 
119e0 66 6f 72 20 61 20 64 69 73 63 75 73 73 69 6f 6e  for a discussion
119f0 20 6f 66 20 77 68 79 0a 2a 2a 20 74 68 69 73 20   of why.** this 
11a00 69 73 20 69 6d 70 6f 72 74 61 6e 74 2e 0a 2a 2a  is important..**
11a10 0a 2a 2a 20 54 68 65 72 65 20 63 61 6e 20 6f 6e  .** There can on
11a20 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62  ly be a single b
11a30 75 73 79 20 68 61 6e 64 6c 65 72 20 64 65 66 69  usy handler defi
11a40 6e 65 64 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20  ned for each.** 
11a50 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
11a60 74 69 6f 6e 5d 2e 20 20 53 65 74 74 69 6e 67 20  tion].  Setting 
11a70 61 20 6e 65 77 20 62 75 73 79 20 68 61 6e 64 6c  a new busy handl
11a80 65 72 20 63 6c 65 61 72 73 20 61 6e 79 0a 2a 2a  er clears any.**
11a90 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65 74 20   previously set 
11aa0 68 61 6e 64 6c 65 72 2e 20 20 4e 6f 74 65 20 74  handler.  Note t
11ab0 68 61 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c  hat calling [sql
11ac0 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75  ite3_busy_timeou
11ad0 74 28 29 5d 0a 2a 2a 20 77 69 6c 6c 20 61 6c 73  t()].** will als
11ae0 6f 20 73 65 74 20 6f 72 20 63 6c 65 61 72 20 74  o set or clear t
11af0 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e  he busy handler.
11b00 0a 2a 2a 0a 2a 2a 20 54 68 65 20 62 75 73 79 20  .**.** The busy 
11b10 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 20  callback should 
11b20 6e 6f 74 20 74 61 6b 65 20 61 6e 79 20 61 63 74  not take any act
11b30 69 6f 6e 73 20 77 68 69 63 68 20 6d 6f 64 69 66  ions which modif
11b40 79 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73  y the.** databas
11b50 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61  e connection tha
11b60 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75  t invoked the bu
11b70 73 79 20 68 61 6e 64 6c 65 72 2e 20 20 41 6e 79  sy handler.  Any
11b80 20 73 75 63 68 20 61 63 74 69 6f 6e 73 0a 2a 2a   such actions.**
11b90 20 72 65 73 75 6c 74 20 69 6e 20 75 6e 64 65 66   result in undef
11ba0 69 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a  ined behavior..*
11bb0 2a 20 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  * .** INVARIANTS
11bc0 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33 31 31 7d  :.**.** {H12311}
11bd0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 75   The [sqlite3_bu
11be0 73 79 5f 68 61 6e 64 6c 65 72 28 44 2c 43 2c 41  sy_handler(D,C,A
11bf0 29 5d 20 66 75 6e 63 74 69 6f 6e 20 73 68 61 6c  )] function shal
11c00 6c 20 72 65 70 6c 61 63 65 0a 2a 2a 20 20 20 20  l replace.**    
11c10 20 20 20 20 20 20 62 75 73 79 20 63 61 6c 6c 62        busy callb
11c20 61 63 6b 20 69 6e 20 74 68 65 20 5b 64 61 74 61  ack in the [data
11c30 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
11c40 20 44 20 77 69 74 68 20 61 20 6e 65 77 0a 2a 2a   D with a new.**
11c50 20 20 20 20 20 20 20 20 20 20 61 20 6e 65 77 20            a new 
11c60 62 75 73 79 20 68 61 6e 64 6c 65 72 20 43 20 61  busy handler C a
11c70 6e 64 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  nd application d
11c80 61 74 61 20 70 6f 69 6e 74 65 72 20 41 2e 0a 2a  ata pointer A..*
11c90 2a 0a 2a 2a 20 7b 48 31 32 33 31 32 7d 20 4e 65  *.** {H12312} Ne
11ca0 77 6c 79 20 63 72 65 61 74 65 64 20 5b 64 61 74  wly created [dat
11cb0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
11cc0 73 5d 20 73 68 61 6c 6c 20 68 61 76 65 20 61 20  s] shall have a 
11cd0 62 75 73 79 0a 2a 2a 20 20 20 20 20 20 20 20 20  busy.**         
11ce0 20 68 61 6e 64 6c 65 72 20 6f 66 20 4e 55 4c 4c   handler of NULL
11cf0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33 31 34 7d  ..**.** {H12314}
11d00 20 57 68 65 6e 20 74 77 6f 20 6f 72 20 6d 6f 72   When two or mor
11d10 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
11d20 65 63 74 69 6f 6e 73 5d 20 73 68 61 72 65 20 61  ections] share a
11d30 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
11d40 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61  lite3_enable_sha
11d50 72 65 64 5f 63 61 63 68 65 20 7c 20 63 6f 6d 6d  red_cache | comm
11d60 6f 6e 20 63 61 63 68 65 5d 2c 0a 2a 2a 20 20 20  on cache],.**   
11d70 20 20 20 20 20 20 20 74 68 65 20 62 75 73 79 20         the busy 
11d80 68 61 6e 64 6c 65 72 20 66 6f 72 20 74 68 65 20  handler for the 
11d90 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
11da0 69 6f 6e 20 63 75 72 72 65 6e 74 6c 79 20 75 73  ion currently us
11db0 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ing.**          
11dc0 74 68 65 20 63 61 63 68 65 20 73 68 61 6c 6c 20  the cache shall 
11dd0 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20  be invoked when 
11de0 74 68 65 20 63 61 63 68 65 20 65 6e 63 6f 75 6e  the cache encoun
11df0 74 65 72 73 20 61 20 6c 6f 63 6b 2e 0a 2a 2a 0a  ters a lock..**.
11e00 2a 2a 20 7b 48 31 32 33 31 36 7d 20 49 66 20 61  ** {H12316} If a
11e10 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 63 61   busy handler ca
11e20 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 7a  llback returns z
11e30 65 72 6f 2c 20 74 68 65 6e 20 74 68 65 20 53 51  ero, then the SQ
11e40 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 0a 2a  Lite interface.*
11e50 2a 20 20 20 20 20 20 20 20 20 20 74 68 61 74 20  *          that 
11e60 70 72 6f 76 6f 6b 65 64 20 74 68 65 20 6c 6f 63  provoked the loc
11e70 6b 69 6e 67 20 65 76 65 6e 74 20 73 68 61 6c 6c  king event shall
11e80 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
11e90 42 55 53 59 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  BUSY]..**.** {H1
11ea0 32 33 31 38 7d 20 53 51 4c 69 74 65 20 73 68 61  2318} SQLite sha
11eb0 6c 6c 20 69 6e 76 6f 6b 65 73 20 74 68 65 20 62  ll invokes the b
11ec0 75 73 79 20 68 61 6e 64 6c 65 72 20 77 69 74 68  usy handler with
11ed0 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 20 77   two arguments w
11ee0 68 69 63 68 0a 2a 2a 20 20 20 20 20 20 20 20 20  hich.**         
11ef0 20 61 72 65 20 61 20 63 6f 70 79 20 6f 66 20 74   are a copy of t
11f00 68 65 20 70 6f 69 6e 74 65 72 20 73 75 70 70 6c  he pointer suppl
11f10 69 65 64 20 62 79 20 74 68 65 20 33 72 64 20 70  ied by the 3rd p
11f20 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 20  arameter to.**  
11f30 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
11f40 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 5d  _busy_handler()]
11f50 20 61 6e 64 20 61 20 63 6f 75 6e 74 20 6f 66 20   and a count of 
11f60 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 70 72  the number of pr
11f70 69 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ior.**          
11f80 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74  invocations of t
11f90 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  he busy handler 
11fa0 66 6f 72 20 74 68 65 20 73 61 6d 65 20 6c 6f 63  for the same loc
11fb0 6b 69 6e 67 20 65 76 65 6e 74 2e 0a 2a 2a 0a 2a  king event..**.*
11fc0 2a 20 41 53 53 55 4d 50 54 49 4f 4e 53 3a 0a 2a  * ASSUMPTIONS:.*
11fd0 2a 0a 2a 2a 20 7b 41 31 32 33 31 39 7d 20 41 20  *.** {A12319} A 
11fe0 62 75 73 79 20 68 61 6e 64 6c 65 72 20 6d 75 73  busy handler mus
11ff0 74 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65 20  t not close the 
12000 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
12010 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ion.**          
12020 6f 72 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  or [prepared sta
12030 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 6e 76  tement] that inv
12040 6f 6b 65 64 20 74 68 65 20 62 75 73 79 20 68 61  oked the busy ha
12050 6e 64 6c 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ndler..*/.int sq
12060 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c  lite3_busy_handl
12070 65 72 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74  er(sqlite3*, int
12080 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 29 2c 20  (*)(void*,int), 
12090 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  void*);../*.** C
120a0 41 50 49 33 52 45 46 3a 20 53 65 74 20 41 20 42  API3REF: Set A B
120b0 75 73 79 20 54 69 6d 65 6f 75 74 20 7b 48 31 32  usy Timeout {H12
120c0 33 34 30 7d 20 3c 53 34 30 34 31 30 3e 0a 2a 2a  340} <S40410>.**
120d0 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65  .** This routine
120e0 20 73 65 74 73 20 61 20 5b 73 71 6c 69 74 65 33   sets a [sqlite3
120f0 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 20 7c 20  _busy_handler | 
12100 62 75 73 79 20 68 61 6e 64 6c 65 72 5d 20 74 68  busy handler] th
12110 61 74 20 73 6c 65 65 70 73 0a 2a 2a 20 66 6f 72  at sleeps.** for
12120 20 61 20 73 70 65 63 69 66 69 65 64 20 61 6d 6f   a specified amo
12130 75 6e 74 20 6f 66 20 74 69 6d 65 20 77 68 65 6e  unt of time when
12140 20 61 20 74 61 62 6c 65 20 69 73 20 6c 6f 63 6b   a table is lock
12150 65 64 2e 20 20 54 68 65 20 68 61 6e 64 6c 65 72  ed.  The handler
12160 0a 2a 2a 20 77 69 6c 6c 20 73 6c 65 65 70 20 6d  .** will sleep m
12170 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 75 6e  ultiple times un
12180 74 69 6c 20 61 74 20 6c 65 61 73 74 20 22 6d 73  til at least "ms
12190 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f  " milliseconds o
121a0 66 20 73 6c 65 65 70 69 6e 67 0a 2a 2a 20 68 61  f sleeping.** ha
121b0 76 65 20 61 63 63 75 6d 75 6c 61 74 65 64 2e 20  ve accumulated. 
121c0 7b 48 31 32 33 34 33 7d 20 41 66 74 65 72 20 22  {H12343} After "
121d0 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73  ms" milliseconds
121e0 20 6f 66 20 73 6c 65 65 70 69 6e 67 2c 0a 2a 2a   of sleeping,.**
121f0 20 74 68 65 20 68 61 6e 64 6c 65 72 20 72 65 74   the handler ret
12200 75 72 6e 73 20 30 20 77 68 69 63 68 20 63 61 75  urns 0 which cau
12210 73 65 73 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  ses [sqlite3_ste
12220 70 28 29 5d 20 74 6f 20 72 65 74 75 72 6e 0a 2a  p()] to return.*
12230 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20  * [SQLITE_BUSY] 
12240 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  or [SQLITE_IOERR
12250 5f 42 4c 4f 43 4b 45 44 5d 2e 0a 2a 2a 0a 2a 2a  _BLOCKED]..**.**
12260 20 43 61 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f   Calling this ro
12270 75 74 69 6e 65 20 77 69 74 68 20 61 6e 20 61 72  utine with an ar
12280 67 75 6d 65 6e 74 20 6c 65 73 73 20 74 68 61 6e  gument less than
12290 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72   or equal to zer
122a0 6f 0a 2a 2a 20 74 75 72 6e 73 20 6f 66 66 20 61  o.** turns off a
122b0 6c 6c 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73  ll busy handlers
122c0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 63 61  ..**.** There ca
122d0 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67  n only be a sing
122e0 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  le busy handler 
122f0 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72  for a particular
12300 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
12310 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 79 20 61 6e  nnection] any an
12320 79 20 67 69 76 65 6e 20 6d 6f 6d 65 6e 74 2e 20  y given moment. 
12330 20 49 66 20 61 6e 6f 74 68 65 72 20 62 75 73 79   If another busy
12340 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 61 73 20   handler.** was 
12350 64 65 66 69 6e 65 64 20 20 28 75 73 69 6e 67 20  defined  (using 
12360 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61  [sqlite3_busy_ha
12370 6e 64 6c 65 72 28 29 5d 29 20 70 72 69 6f 72 20  ndler()]) prior 
12380 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 74 68  to calling.** th
12390 69 73 20 72 6f 75 74 69 6e 65 2c 20 74 68 61 74  is routine, that
123a0 20 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e 64   other busy hand
123b0 6c 65 72 20 69 73 20 63 6c 65 61 72 65 64 2e 0a  ler is cleared..
123c0 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
123d0 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33 34 31 7d  :.**.** {H12341}
123e0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 75   The [sqlite3_bu
123f0 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 66 75  sy_timeout()] fu
12400 6e 63 74 69 6f 6e 20 73 68 61 6c 6c 20 6f 76 65  nction shall ove
12410 72 72 69 64 65 20 61 6e 79 20 70 72 69 6f 72 0a  rride any prior.
12420 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
12430 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75  ite3_busy_timeou
12440 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  t()] or [sqlite3
12450 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 5d  _busy_handler()]
12460 20 73 65 74 74 69 6e 67 0a 2a 2a 20 20 20 20 20   setting.**     
12470 20 20 20 20 20 6f 6e 20 74 68 65 20 73 61 6d 65       on the same
12480 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
12490 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48  ction]..**.** {H
124a0 31 32 33 34 33 7d 20 49 66 20 74 68 65 20 32 6e  12343} If the 2n
124b0 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  d parameter to [
124c0 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d  sqlite3_busy_tim
124d0 65 6f 75 74 28 29 5d 20 69 73 20 6c 65 73 73 20  eout()] is less 
124e0 74 68 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  than.**         
124f0 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72   or equal to zer
12500 6f 2c 20 74 68 65 6e 20 74 68 65 20 62 75 73 79  o, then the busy
12510 20 68 61 6e 64 6c 65 72 20 73 68 61 6c 6c 20 62   handler shall b
12520 65 20 63 6c 65 61 72 65 64 20 73 6f 20 74 68 61  e cleared so tha
12530 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6c  t.**          al
12540 6c 20 73 75 62 73 65 71 75 65 6e 74 20 6c 6f 63  l subsequent loc
12550 6b 69 6e 67 20 65 76 65 6e 74 73 20 69 6d 6d 65  king events imme
12560 64 69 61 74 65 6c 79 20 72 65 74 75 72 6e 20 5b  diately return [
12570 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a  SQLITE_BUSY]..**
12580 0a 2a 2a 20 7b 48 31 32 33 34 34 7d 20 49 66 20  .** {H12344} If 
12590 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65  the 2nd paramete
125a0 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 75  r to [sqlite3_bu
125b0 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 69 73  sy_timeout()] is
125c0 20 61 20 70 6f 73 69 74 69 76 65 0a 2a 2a 20 20   a positive.**  
125d0 20 20 20 20 20 20 20 20 6e 75 6d 62 65 72 20 4e          number N
125e0 2c 20 74 68 65 6e 20 61 20 62 75 73 79 20 68 61  , then a busy ha
125f0 6e 64 6c 65 72 20 73 68 61 6c 6c 20 62 65 20 73  ndler shall be s
12600 65 74 20 74 68 61 74 20 72 65 70 65 61 74 65 64  et that repeated
12610 6c 79 20 63 61 6c 6c 73 0a 2a 2a 20 20 20 20 20  ly calls.**     
12620 20 20 20 20 20 74 68 65 20 78 53 6c 65 65 70 28       the xSleep(
12630 29 20 6d 65 74 68 6f 64 20 69 6e 20 74 68 65 20  ) method in the 
12640 5b 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 56  [sqlite3_vfs | V
12650 46 53 20 69 6e 74 65 72 66 61 63 65 5d 20 75 6e  FS interface] un
12660 74 69 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  til.**          
12670 65 69 74 68 65 72 20 74 68 65 20 6c 6f 63 6b 20  either the lock 
12680 63 6c 65 61 72 73 20 6f 72 20 75 6e 74 69 6c 20  clears or until 
12690 74 68 65 20 63 75 6d 75 6c 61 74 69 76 65 20 73  the cumulative s
126a0 6c 65 65 70 20 74 69 6d 65 0a 2a 2a 20 20 20 20  leep time.**    
126b0 20 20 20 20 20 20 72 65 70 6f 72 74 65 64 20 62        reported b
126c0 61 63 6b 20 62 79 20 78 53 6c 65 65 70 28 29 20  ack by xSleep() 
126d0 65 78 63 65 65 64 73 20 4e 20 6d 69 6c 6c 69 73  exceeds N millis
126e0 65 63 6f 6e 64 73 2e 0a 2a 2f 0a 69 6e 74 20 73  econds..*/.int s
126f0 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65  qlite3_busy_time
12700 6f 75 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e  out(sqlite3*, in
12710 74 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  t ms);../*.** CA
12720 50 49 33 52 45 46 3a 20 43 6f 6e 76 65 6e 69 65  PI3REF: Convenie
12730 6e 63 65 20 52 6f 75 74 69 6e 65 73 20 46 6f 72  nce Routines For
12740 20 52 75 6e 6e 69 6e 67 20 51 75 65 72 69 65 73   Running Queries
12750 20 7b 48 31 32 33 37 30 7d 20 3c 53 31 30 30 30   {H12370} <S1000
12760 30 3e 0a 2a 2a 0a 2a 2a 20 44 65 66 69 6e 69 74  0>.**.** Definit
12770 69 6f 6e 3a 20 41 20 3c 62 3e 72 65 73 75 6c 74  ion: A <b>result
12780 20 74 61 62 6c 65 3c 2f 62 3e 20 69 73 20 6d 65   table</b> is me
12790 6d 6f 72 79 20 64 61 74 61 20 73 74 72 75 63 74  mory data struct
127a0 75 72 65 20 63 72 65 61 74 65 64 20 62 79 20 74  ure created by t
127b0 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 67  he.** [sqlite3_g
127c0 65 74 5f 74 61 62 6c 65 28 29 5d 20 69 6e 74 65  et_table()] inte
127d0 72 66 61 63 65 2e 20 20 41 20 72 65 73 75 6c 74  rface.  A result
127e0 20 74 61 62 6c 65 20 72 65 63 6f 72 64 73 20 74   table records t
127f0 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 71  he.** complete q
12800 75 65 72 79 20 72 65 73 75 6c 74 73 20 66 72 6f  uery results fro
12810 6d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 71 75  m one or more qu
12820 65 72 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  eries..**.** The
12830 20 74 61 62 6c 65 20 63 6f 6e 63 65 70 74 75 61   table conceptua
12840 6c 6c 79 20 68 61 73 20 61 20 6e 75 6d 62 65 72  lly has a number
12850 20 6f 66 20 72 6f 77 73 20 61 6e 64 20 63 6f 6c   of rows and col
12860 75 6d 6e 73 2e 20 20 42 75 74 0a 2a 2a 20 74 68  umns.  But.** th
12870 65 73 65 20 6e 75 6d 62 65 72 73 20 61 72 65 20  ese numbers are 
12880 6e 6f 74 20 70 61 72 74 20 6f 66 20 74 68 65 20  not part of the 
12890 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 74 73  result table its
128a0 65 6c 66 2e 20 20 54 68 65 73 65 0a 2a 2a 20 6e  elf.  These.** n
128b0 75 6d 62 65 72 73 20 61 72 65 20 6f 62 74 61 69  umbers are obtai
128c0 6e 65 64 20 73 65 70 61 72 61 74 65 6c 79 2e 20  ned separately. 
128d0 20 4c 65 74 20 4e 20 62 65 20 74 68 65 20 6e 75   Let N be the nu
128e0 6d 62 65 72 20 6f 66 20 72 6f 77 73 0a 2a 2a 20  mber of rows.** 
128f0 61 6e 64 20 4d 20 62 65 20 74 68 65 20 6e 75 6d  and M be the num
12900 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 2e 0a  ber of columns..
12910 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74  **.** A result t
12920 61 62 6c 65 20 69 73 20 61 6e 20 61 72 72 61 79  able is an array
12930 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20   of pointers to 
12940 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
12950 55 54 46 2d 38 20 73 74 72 69 6e 67 73 2e 0a 2a  UTF-8 strings..*
12960 2a 20 54 68 65 72 65 20 61 72 65 20 28 4e 2b 31  * There are (N+1
12970 29 2a 4d 20 65 6c 65 6d 65 6e 74 73 20 69 6e 20  )*M elements in 
12980 74 68 65 20 61 72 72 61 79 2e 20 20 54 68 65 20  the array.  The 
12990 66 69 72 73 74 20 4d 20 70 6f 69 6e 74 65 72 73  first M pointers
129a0 20 70 6f 69 6e 74 0a 2a 2a 20 74 6f 20 7a 65 72   point.** to zer
129b0 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72  o-terminated str
129c0 69 6e 67 73 20 74 68 61 74 20 20 63 6f 6e 74 61  ings that  conta
129d0 69 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20  in the names of 
129e0 74 68 65 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20  the columns..** 
129f0 54 68 65 20 72 65 6d 61 69 6e 69 6e 67 20 65 6e  The remaining en
12a00 74 72 69 65 73 20 61 6c 6c 20 70 6f 69 6e 74 20  tries all point 
12a10 74 6f 20 71 75 65 72 79 20 72 65 73 75 6c 74 73  to query results
12a20 2e 20 20 4e 55 4c 4c 20 76 61 6c 75 65 73 20 72  .  NULL values r
12a30 65 73 75 6c 74 0a 2a 2a 20 69 6e 20 4e 55 4c 4c  esult.** in NULL
12a40 20 70 6f 69 6e 74 65 72 73 2e 20 20 41 6c 6c 20   pointers.  All 
12a50 6f 74 68 65 72 20 76 61 6c 75 65 73 20 61 72 65  other values are
12a60 20 69 6e 20 74 68 65 69 72 20 55 54 46 2d 38 20   in their UTF-8 
12a70 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a  zero-terminated.
12a80 2a 2a 20 73 74 72 69 6e 67 20 72 65 70 72 65 73  ** string repres
12a90 65 6e 74 61 74 69 6f 6e 20 61 73 20 72 65 74 75  entation as retu
12aa0 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  rned by [sqlite3
12ab0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2e  _column_text()].
12ac0 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20  .**.** A result 
12ad0 74 61 62 6c 65 20 6d 69 67 68 74 20 63 6f 6e 73  table might cons
12ae0 69 73 74 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f  ist of one or mo
12af0 72 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  re memory alloca
12b00 74 69 6f 6e 73 2e 0a 2a 2a 20 49 74 20 69 73 20  tions..** It is 
12b10 6e 6f 74 20 73 61 66 65 20 74 6f 20 70 61 73 73  not safe to pass
12b20 20 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20   a result table 
12b30 64 69 72 65 63 74 6c 79 20 74 6f 20 5b 73 71 6c  directly to [sql
12b40 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a  ite3_free()]..**
12b50 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20   A result table 
12b60 73 68 6f 75 6c 64 20 62 65 20 64 65 61 6c 6c 6f  should be deallo
12b70 63 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c  cated using [sql
12b80 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28  ite3_free_table(
12b90 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 73 20 61 6e 20  )]..**.** As an 
12ba0 65 78 61 6d 70 6c 65 20 6f 66 20 74 68 65 20 72  example of the r
12bb0 65 73 75 6c 74 20 74 61 62 6c 65 20 66 6f 72 6d  esult table form
12bc0 61 74 2c 20 73 75 70 70 6f 73 65 20 61 20 71 75  at, suppose a qu
12bd0 65 72 79 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73  ery result.** is
12be0 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a   as follows:.**.
12bf0 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
12c00 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20 4e  pre>.**        N
12c10 61 6d 65 20 20 20 20 20 20 20 20 7c 20 41 67 65  ame        | Age
12c20 0a 2a 2a 20 20 20 20 20 20 20 20 2d 2d 2d 2d 2d  .**        -----
12c30 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
12c40 2d 2d 0a 2a 2a 20 20 20 20 20 20 20 20 41 6c 69  --.**        Ali
12c50 63 65 20 20 20 20 20 20 20 7c 20 34 33 0a 2a 2a  ce       | 43.**
12c60 20 20 20 20 20 20 20 20 42 6f 62 20 20 20 20 20          Bob     
12c70 20 20 20 20 7c 20 32 38 0a 2a 2a 20 20 20 20 20      | 28.**     
12c80 20 20 20 43 69 6e 64 79 20 20 20 20 20 20 20 7c     Cindy       |
12c90 20 32 31 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62   21.** </pre></b
12ca0 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
12cb0 20 54 68 65 72 65 20 61 72 65 20 74 77 6f 20 63   There are two c
12cc0 6f 6c 75 6d 6e 20 28 4d 3d 3d 32 29 20 61 6e 64  olumn (M==2) and
12cd0 20 74 68 72 65 65 20 72 6f 77 73 20 28 4e 3d 3d   three rows (N==
12ce0 33 29 2e 20 20 54 68 75 73 20 74 68 65 0a 2a 2a  3).  Thus the.**
12cf0 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 68 61   result table ha
12d00 73 20 38 20 65 6e 74 72 69 65 73 2e 20 20 53 75  s 8 entries.  Su
12d10 70 70 6f 73 65 20 74 68 65 20 72 65 73 75 6c 74  ppose the result
12d20 20 74 61 62 6c 65 20 69 73 20 73 74 6f 72 65 64   table is stored
12d30 0a 2a 2a 20 69 6e 20 61 6e 20 61 72 72 61 79 20  .** in an array 
12d40 6e 61 6d 65 73 20 61 7a 52 65 73 75 6c 74 2e 20  names azResult. 
12d50 20 54 68 65 6e 20 61 7a 52 65 73 75 6c 74 20 68   Then azResult h
12d60 6f 6c 64 73 20 74 68 69 73 20 63 6f 6e 74 65 6e  olds this conten
12d70 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  t:.**.** <blockq
12d80 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20  uote><pre>.**   
12d90 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
12da0 31 3b 30 5d 20 3d 20 22 4e 61 6d 65 22 3b 0a 2a  1;0] = "Name";.*
12db0 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
12dc0 74 26 23 39 31 3b 31 5d 20 3d 20 22 41 67 65 22  t&#91;1] = "Age"
12dd0 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
12de0 73 75 6c 74 26 23 39 31 3b 32 5d 20 3d 20 22 41  sult&#91;2] = "A
12df0 6c 69 63 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20  lice";.**       
12e00 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 33 5d   azResult&#91;3]
12e10 20 3d 20 22 34 33 22 3b 0a 2a 2a 20 20 20 20 20   = "43";.**     
12e20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
12e30 34 5d 20 3d 20 22 42 6f 62 22 3b 0a 2a 2a 20 20  4] = "Bob";.**  
12e40 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
12e50 39 31 3b 35 5d 20 3d 20 22 32 38 22 3b 0a 2a 2a  91;5] = "28";.**
12e60 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
12e70 26 23 39 31 3b 36 5d 20 3d 20 22 43 69 6e 64 79  &#91;6] = "Cindy
12e80 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
12e90 65 73 75 6c 74 26 23 39 31 3b 37 5d 20 3d 20 22  esult&#91;7] = "
12ea0 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  21";.** </pre></
12eb0 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
12ec0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65  * The sqlite3_ge
12ed0 74 5f 74 61 62 6c 65 28 29 20 66 75 6e 63 74 69  t_table() functi
12ee0 6f 6e 20 65 76 61 6c 75 61 74 65 73 20 6f 6e 65  on evaluates one
12ef0 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 73 65 6d 69   or more.** semi
12f00 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 65 64 20  colon-separated 
12f10 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69  SQL statements i
12f20 6e 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69  n the zero-termi
12f30 6e 61 74 65 64 20 55 54 46 2d 38 0a 2a 2a 20 73  nated UTF-8.** s
12f40 74 72 69 6e 67 20 6f 66 20 69 74 73 20 32 6e 64  tring of its 2nd
12f50 20 70 61 72 61 6d 65 74 65 72 2e 20 20 49 74 20   parameter.  It 
12f60 72 65 74 75 72 6e 73 20 61 20 72 65 73 75 6c 74  returns a result
12f70 20 74 61 62 6c 65 20 74 6f 20 74 68 65 0a 2a 2a   table to the.**
12f80 20 70 6f 69 6e 74 65 72 20 67 69 76 65 6e 20 69   pointer given i
12f90 6e 20 69 74 73 20 33 72 64 20 70 61 72 61 6d 65  n its 3rd parame
12fa0 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72  ter..**.** After
12fb0 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e   the calling fun
12fc0 63 74 69 6f 6e 20 68 61 73 20 66 69 6e 69 73 68  ction has finish
12fd0 65 64 20 75 73 69 6e 67 20 74 68 65 20 72 65 73  ed using the res
12fe0 75 6c 74 2c 20 69 74 20 73 68 6f 75 6c 64 0a 2a  ult, it should.*
12ff0 2a 20 70 61 73 73 20 74 68 65 20 70 6f 69 6e 74  * pass the point
13000 65 72 20 74 6f 20 74 68 65 20 72 65 73 75 6c 74  er to the result
13010 20 74 61 62 6c 65 20 74 6f 20 73 71 6c 69 74 65   table to sqlite
13020 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 20 69  3_free_table() i
13030 6e 20 6f 72 64 65 72 20 74 6f 0a 2a 2a 20 72 65  n order to.** re
13040 6c 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79  lease the memory
13050 20 74 68 61 74 20 77 61 73 20 6d 61 6c 6c 6f 63   that was malloc
13060 65 64 2e 20 20 42 65 63 61 75 73 65 20 6f 66 20  ed.  Because of 
13070 74 68 65 20 77 61 79 20 74 68 65 0a 2a 2a 20 5b  the way the.** [
13080 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
13090 5d 20 68 61 70 70 65 6e 73 20 77 69 74 68 69 6e  ] happens within
130a0 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62   sqlite3_get_tab
130b0 6c 65 28 29 2c 20 74 68 65 20 63 61 6c 6c 69 6e  le(), the callin
130c0 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75  g.** function mu
130d0 73 74 20 6e 6f 74 20 74 72 79 20 74 6f 20 63 61  st not try to ca
130e0 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ll [sqlite3_free
130f0 28 29 5d 20 64 69 72 65 63 74 6c 79 2e 20 20 4f  ()] directly.  O
13100 6e 6c 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  nly.** [sqlite3_
13110 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 20 69 73  free_table()] is
13120 20 61 62 6c 65 20 74 6f 20 72 65 6c 65 61 73 65   able to release
13130 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 70   the memory prop
13140 65 72 6c 79 20 61 6e 64 20 73 61 66 65 6c 79 2e  erly and safely.
13150 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
13160 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 69  e3_get_table() i
13170 6e 74 65 72 66 61 63 65 20 69 73 20 69 6d 70 6c  nterface is impl
13180 65 6d 65 6e 74 65 64 20 61 73 20 61 20 77 72 61  emented as a wra
13190 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b  pper around.** [
131a0 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2e  sqlite3_exec()].
131b0 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65    The sqlite3_ge
131c0 74 5f 74 61 62 6c 65 28 29 20 72 6f 75 74 69 6e  t_table() routin
131d0 65 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20  e does not have 
131e0 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 61 6e 79  access.** to any
131f0 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 20 73   internal data s
13200 74 72 75 63 74 75 72 65 73 20 6f 66 20 53 51 4c  tructures of SQL
13210 69 74 65 2e 20 20 49 74 20 75 73 65 73 20 6f 6e  ite.  It uses on
13220 6c 79 20 74 68 65 20 70 75 62 6c 69 63 0a 2a 2a  ly the public.**
13230 20 69 6e 74 65 72 66 61 63 65 20 64 65 66 69 6e   interface defin
13240 65 64 20 68 65 72 65 2e 20 20 41 73 20 61 20 63  ed here.  As a c
13250 6f 6e 73 65 71 75 65 6e 63 65 2c 20 65 72 72 6f  onsequence, erro
13260 72 73 20 74 68 61 74 20 6f 63 63 75 72 20 69 6e  rs that occur in
13270 20 74 68 65 0a 2a 2a 20 77 72 61 70 70 65 72 20   the.** wrapper 
13280 6c 61 79 65 72 20 6f 75 74 73 69 64 65 20 6f 66  layer outside of
13290 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 5b 73   the internal [s
132a0 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 63  qlite3_exec()] c
132b0 61 6c 6c 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72  all are not.** r
132c0 65 66 6c 65 63 74 65 64 20 69 6e 20 73 75 62 73  eflected in subs
132d0 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20  equent calls to 
132e0 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65  [sqlite3_errcode
132f0 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
13300 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a  errmsg()]..**.**
13310 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
13320 2a 2a 20 7b 48 31 32 33 37 31 7d 20 49 66 20 61  ** {H12371} If a
13330 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61   [sqlite3_get_ta
13340 62 6c 65 28 29 5d 20 66 61 69 6c 73 20 61 20 6d  ble()] fails a m
13350 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
13360 2c 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20  , then.**       
13370 20 20 20 69 74 20 73 68 61 6c 6c 20 66 72 65 65     it shall free
13380 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c   the result tabl
13390 65 20 75 6e 64 65 72 20 63 6f 6e 73 74 72 75 63  e under construc
133a0 74 69 6f 6e 2c 20 61 62 6f 72 74 20 74 68 65 0a  tion, abort the.
133b0 2a 2a 20 20 20 20 20 20 20 20 20 20 71 75 65 72  **          quer
133c0 79 20 69 6e 20 70 72 6f 63 65 73 73 2c 20 73 6b  y in process, sk
133d0 69 70 20 61 6e 79 20 73 75 62 73 65 71 75 65 6e  ip any subsequen
133e0 74 20 71 75 65 72 69 65 73 2c 20 73 65 74 20 74  t queries, set t
133f0 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 2a  he.**          *
13400 70 61 7a 52 65 73 75 6c 74 20 6f 75 74 70 75 74  pazResult output
13410 20 70 6f 69 6e 74 65 72 20 74 6f 20 4e 55 4c 4c   pointer to NULL
13420 20 61 6e 64 20 72 65 74 75 72 6e 20 5b 53 51 4c   and return [SQL
13430 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a  ITE_NOMEM]..**.*
13440 2a 20 7b 48 31 32 33 37 33 7d 20 49 66 20 74 68  * {H12373} If th
13450 65 20 70 6e 43 6f 6c 75 6d 6e 20 70 61 72 61 6d  e pnColumn param
13460 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33  eter to [sqlite3
13470 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 69 73  _get_table()] is
13480 20 6e 6f 74 20 4e 55 4c 4c 0a 2a 2a 20 20 20 20   not NULL.**    
13490 20 20 20 20 20 20 74 68 65 6e 20 61 20 73 75 63        then a suc
134a0 63 65 73 73 66 75 6c 20 69 6e 76 6f 63 61 74 69  cessful invocati
134b0 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 67  on of [sqlite3_g
134c0 65 74 5f 74 61 62 6c 65 28 29 5d 20 73 68 61 6c  et_table()] shal
134d0 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 72  l.**          wr
134e0 69 74 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  ite the number o
134f0 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65  f columns in the
13500 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 73  .**          res
13510 75 6c 74 20 73 65 74 20 6f 66 20 74 68 65 20 71  ult set of the q
13520 75 65 72 79 20 69 6e 74 6f 20 2a 70 6e 43 6f 6c  uery into *pnCol
13530 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33  umn..**.** {H123
13540 37 34 7d 20 49 66 20 74 68 65 20 70 6e 52 6f 77  74} If the pnRow
13550 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73   parameter to [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 69 73 20 6e 6f 74 20 4e 55 4c 4c 0a  ()] is not NULL.
13580 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 6e  **          then
13590 20 61 20 73 75 63 63 65 73 73 66 75 6c 20 69 6e   a successful in
135a0 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c  vocation of [sql
135b0 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
135c0 5d 20 73 68 61 6c 6c 0a 2a 2a 20 20 20 20 20 20  ] shall.**      
135d0 20 20 20 20 77 72 69 74 65 73 20 74 68 65 20 6e      writes the n
135e0 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 69 6e  umber of rows in
135f0 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
13600 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 74   result set of t
13610 68 65 20 71 75 65 72 79 20 69 6e 74 6f 20 2a 70  he query into *p
13620 6e 52 6f 77 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  nRow..**.** {H12
13630 33 37 36 7d 20 41 20 73 75 63 63 65 73 73 66 75  376} A successfu
13640 6c 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20  l invocation of 
13650 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62  [sqlite3_get_tab
13660 6c 65 28 29 5d 20 74 68 61 74 20 63 6f 6d 70 75  le()] that compu
13670 74 65 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  tes.**          
13680 4e 20 72 6f 77 73 20 6f 66 20 72 65 73 75 6c 74  N rows of result
13690 20 77 69 74 68 20 43 20 63 6f 6c 75 6d 6e 73 20   with C columns 
136a0 70 65 72 20 72 6f 77 20 73 68 61 6c 6c 20 6d 61  per row shall ma
136b0 6b 65 20 2a 70 61 7a 52 65 73 75 6c 74 0a 2a 2a  ke *pazResult.**
136c0 20 20 20 20 20 20 20 20 20 20 70 6f 69 6e 74 20            point 
136d0 74 6f 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70  to an array of p
136e0 6f 69 6e 74 65 72 73 20 74 6f 20 28 4e 2b 31 29  ointers to (N+1)
136f0 2a 43 20 73 74 72 69 6e 67 73 20 77 68 65 72 65  *C strings where
13700 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 20 20   the first.**   
13710 20 20 20 20 20 20 20 43 20 73 74 72 69 6e 67 73         C strings
13720 20 61 72 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65   are column name
13730 73 20 61 73 20 6f 62 74 61 69 6e 65 64 20 66 72  s as obtained fr
13740 6f 6d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  om.**          [
13750 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
13760 61 6d 65 28 29 5d 20 61 6e 64 20 74 68 65 20 72  ame()] and the r
13770 65 73 74 20 61 72 65 20 63 6f 6c 75 6d 6e 20 72  est are column r
13780 65 73 75 6c 74 20 76 61 6c 75 65 73 0a 2a 2a 20  esult values.** 
13790 20 20 20 20 20 20 20 20 20 6f 62 74 61 69 6e 65           obtaine
137a0 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
137b0 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a  column_text()]..
137c0 2a 2a 0a 2a 2a 20 7b 48 31 32 33 37 39 7d 20 54  **.** {H12379} T
137d0 68 65 20 76 61 6c 75 65 73 20 69 6e 20 74 68 65  he values in the
137e0 20 70 61 7a 52 65 73 75 6c 74 20 61 72 72 61 79   pazResult array
137f0 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71   returned by [sq
13800 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
13810 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73  )].**          s
13820 68 61 6c 6c 20 72 65 6d 61 69 6e 20 76 61 6c 69  hall remain vali
13830 64 20 75 6e 74 69 6c 20 63 6c 65 61 72 65 64 20  d until cleared 
13840 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  by [sqlite3_free
13850 5f 74 61 62 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a  _table()]..**.**
13860 20 7b 48 31 32 33 38 32 7d 20 57 68 65 6e 20 61   {H12382} When a
13870 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 64  n error occurs d
13880 75 72 69 6e 67 20 65 76 61 6c 75 61 74 69 6f 6e  uring evaluation
13890 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 67 65 74   of [sqlite3_get
138a0 5f 74 61 62 6c 65 28 29 5d 0a 2a 2a 20 20 20 20  _table()].**    
138b0 20 20 20 20 20 20 74 68 65 20 66 75 6e 63 74 69        the functi
138c0 6f 6e 20 73 68 61 6c 6c 20 73 65 74 20 2a 70 61  on shall set *pa
138d0 7a 52 65 73 75 6c 74 20 74 6f 20 4e 55 4c 4c 2c  zResult to NULL,
138e0 20 77 72 69 74 65 20 61 6e 20 65 72 72 6f 72 20   write an error 
138f0 6d 65 73 73 61 67 65 0a 2a 2a 20 20 20 20 20 20  message.**      
13900 20 20 20 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20      into memory 
13910 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73  obtained from [s
13920 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
13930 2c 20 6d 61 6b 65 0a 2a 2a 20 20 20 20 20 20 20  , make.**       
13940 20 20 20 2a 2a 70 7a 45 72 72 6d 73 67 20 70 6f     **pzErrmsg po
13950 69 6e 74 20 74 6f 20 74 68 61 74 20 65 72 72 6f  int to that erro
13960 72 20 6d 65 73 73 61 67 65 2c 20 61 6e 64 20 72  r message, and r
13970 65 74 75 72 6e 20 61 0a 2a 2a 20 20 20 20 20 20  eturn a.**      
13980 20 20 20 20 61 70 70 72 6f 70 72 69 61 74 65 20      appropriate 
13990 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2f  [error code]..*/
139a0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 65 74  .int sqlite3_get
139b0 5f 74 61 62 6c 65 28 0a 20 20 73 71 6c 69 74 65  _table(.  sqlite
139c0 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
139d0 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62  /* An open datab
139e0 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  ase */.  const c
139f0 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 2f  har *zSql,     /
13a00 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 76 61 6c  * SQL to be eval
13a10 75 61 74 65 64 20 2a 2f 0a 20 20 63 68 61 72 20  uated */.  char 
13a20 2a 2a 2a 70 61 7a 52 65 73 75 6c 74 2c 20 20 20  ***pazResult,   
13a30 20 2f 2a 20 52 65 73 75 6c 74 73 20 6f 66 20 74   /* Results of t
13a40 68 65 20 71 75 65 72 79 20 2a 2f 0a 20 20 69 6e  he query */.  in
13a50 74 20 2a 70 6e 52 6f 77 2c 20 20 20 20 20 20 20  t *pnRow,       
13a60 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66      /* Number of
13a70 20 72 65 73 75 6c 74 20 72 6f 77 73 20 77 72 69   result rows wri
13a80 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 69  tten here */.  i
13a90 6e 74 20 2a 70 6e 43 6f 6c 75 6d 6e 2c 20 20 20  nt *pnColumn,   
13aa0 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f       /* Number o
13ab0 66 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 73  f result columns
13ac0 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f   written here */
13ad0 0a 20 20 63 68 61 72 20 2a 2a 70 7a 45 72 72 6d  .  char **pzErrm
13ae0 73 67 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f  sg       /* Erro
13af0 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68 65  r msg written he
13b00 72 65 20 2a 2f 0a 29 3b 0a 76 6f 69 64 20 73 71  re */.);.void sq
13b10 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65  lite3_free_table
13b20 28 63 68 61 72 20 2a 2a 72 65 73 75 6c 74 29 3b  (char **result);
13b30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
13b40 3a 20 46 6f 72 6d 61 74 74 65 64 20 53 74 72 69  : Formatted Stri
13b50 6e 67 20 50 72 69 6e 74 69 6e 67 20 46 75 6e 63  ng Printing Func
13b60 74 69 6f 6e 73 20 7b 48 31 37 34 30 30 7d 20 3c  tions {H17400} <
13b70 53 37 30 30 30 30 3e 3c 53 32 30 30 30 30 3e 0a  S70000><S20000>.
13b80 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
13b90 69 6e 65 73 20 61 72 65 20 77 6f 72 6b 61 6c 69  ines are workali
13ba0 6b 65 73 20 6f 66 20 74 68 65 20 22 70 72 69 6e  kes of the "prin
13bb0 74 66 28 29 22 20 66 61 6d 69 6c 79 20 6f 66 20  tf()" family of 
13bc0 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 66 72 6f  functions.** fro
13bd0 6d 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43  m the standard C
13be0 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20   library..**.** 
13bf0 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 70 72 69  The sqlite3_mpri
13c00 6e 74 66 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ntf() and sqlite
13c10 33 5f 76 6d 70 72 69 6e 74 66 28 29 20 72 6f 75  3_vmprintf() rou
13c20 74 69 6e 65 73 20 77 72 69 74 65 20 74 68 65 69  tines write thei
13c30 72 0a 2a 2a 20 72 65 73 75 6c 74 73 20 69 6e 74  r.** results int
13c40 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65  o memory obtaine
13c50 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
13c60 6d 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a 20 54 68  malloc()]..** Th
13c70 65 20 73 74 72 69 6e 67 73 20 72 65 74 75 72 6e  e strings return
13c80 65 64 20 62 79 20 74 68 65 73 65 20 74 77 6f 20  ed by these two 
13c90 72 6f 75 74 69 6e 65 73 20 73 68 6f 75 6c 64 20  routines should 
13ca0 62 65 0a 2a 2a 20 72 65 6c 65 61 73 65 64 20 62  be.** released b
13cb0 79 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  y [sqlite3_free(
13cc0 29 5d 2e 20 20 42 6f 74 68 20 72 6f 75 74 69 6e  )].  Both routin
13cd0 65 73 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 4e  es return a.** N
13ce0 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 20 5b  ULL pointer if [
13cf0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
13d00 5d 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61  ] is unable to a
13d10 6c 6c 6f 63 61 74 65 20 65 6e 6f 75 67 68 0a 2a  llocate enough.*
13d20 2a 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64  * memory to hold
13d30 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73   the resulting s
13d40 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20  tring..**.** In 
13d50 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
13d60 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 73 69  () routine is si
13d70 6d 69 6c 61 72 20 74 6f 20 22 73 6e 70 72 69 6e  milar to "snprin
13d80 74 66 28 29 22 20 66 72 6f 6d 0a 2a 2a 20 74 68  tf()" from.** th
13d90 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62  e standard C lib
13da0 72 61 72 79 2e 20 20 54 68 65 20 72 65 73 75 6c  rary.  The resul
13db0 74 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e 74  t is written int
13dc0 6f 20 74 68 65 0a 2a 2a 20 62 75 66 66 65 72 20  o the.** buffer 
13dd0 73 75 70 70 6c 69 65 64 20 61 73 20 74 68 65 20  supplied as the 
13de0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
13df0 20 77 68 6f 73 65 20 73 69 7a 65 20 69 73 20 67   whose size is g
13e00 69 76 65 6e 20 62 79 0a 2a 2a 20 74 68 65 20 66  iven by.** the f
13e10 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e 20  irst parameter. 
13e20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 6f 72  Note that the or
13e30 64 65 72 20 6f 66 20 74 68 65 0a 2a 2a 20 66 69  der of the.** fi
13e40 72 73 74 20 74 77 6f 20 70 61 72 61 6d 65 74 65  rst two paramete
13e50 72 73 20 69 73 20 72 65 76 65 72 73 65 64 20 66  rs is reversed f
13e60 72 6f 6d 20 73 6e 70 72 69 6e 74 66 28 29 2e 20  rom snprintf(). 
13e70 20 54 68 69 73 20 69 73 20 61 6e 0a 2a 2a 20 68   This is an.** h
13e80 69 73 74 6f 72 69 63 61 6c 20 61 63 63 69 64 65  istorical accide
13e90 6e 74 20 74 68 61 74 20 63 61 6e 6e 6f 74 20 62  nt that cannot b
13ea0 65 20 66 69 78 65 64 20 77 69 74 68 6f 75 74 20  e fixed without 
13eb0 62 72 65 61 6b 69 6e 67 0a 2a 2a 20 62 61 63 6b  breaking.** back
13ec0 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c  wards compatibil
13ed0 69 74 79 2e 20 20 4e 6f 74 65 20 61 6c 73 6f 20  ity.  Note also 
13ee0 74 68 61 74 20 73 71 6c 69 74 65 33 5f 73 6e 70  that sqlite3_snp
13ef0 72 69 6e 74 66 28 29 0a 2a 2a 20 72 65 74 75 72  rintf().** retur
13f00 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
13f10 69 74 73 20 62 75 66 66 65 72 20 69 6e 73 74 65  its buffer inste
13f20 61 64 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72  ad of the number
13f30 20 6f 66 0a 2a 2a 20 63 68 61 72 61 63 74 65 72   of.** character
13f40 73 20 61 63 74 75 61 6c 6c 79 20 77 72 69 74 74  s actually writt
13f50 65 6e 20 69 6e 74 6f 20 74 68 65 20 62 75 66 66  en into the buff
13f60 65 72 2e 20 20 57 65 20 61 64 6d 69 74 20 74 68  er.  We admit th
13f70 61 74 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72  at.** the number
13f80 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 20 77   of characters w
13f90 72 69 74 74 65 6e 20 77 6f 75 6c 64 20 62 65 20  ritten would be 
13fa0 61 20 6d 6f 72 65 20 75 73 65 66 75 6c 20 72 65  a more useful re
13fb0 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 62 75  turn.** value bu
13fc0 74 20 77 65 20 63 61 6e 6e 6f 74 20 63 68 61 6e  t we cannot chan
13fd0 67 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74  ge the implement
13fe0 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33  ation of sqlite3
13ff0 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 6e  _snprintf().** n
14000 6f 77 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b  ow without break
14010 69 6e 67 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  ing compatibilit
14020 79 2e 0a 2a 2a 0a 2a 2a 20 41 73 20 6c 6f 6e 67  y..**.** As long
14030 20 61 73 20 74 68 65 20 62 75 66 66 65 72 20 73   as the buffer s
14040 69 7a 65 20 69 73 20 67 72 65 61 74 65 72 20 74  ize is greater t
14050 68 61 6e 20 7a 65 72 6f 2c 20 73 71 6c 69 74 65  han zero, sqlite
14060 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20  3_snprintf().** 
14070 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 20  guarantees that 
14080 74 68 65 20 62 75 66 66 65 72 20 69 73 20 61 6c  the buffer is al
14090 77 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  ways zero-termin
140a0 61 74 65 64 2e 20 20 54 68 65 20 66 69 72 73 74  ated.  The first
140b0 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 22 6e  .** parameter "n
140c0 22 20 69 73 20 74 68 65 20 74 6f 74 61 6c 20 73  " is the total s
140d0 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66 65  ize of the buffe
140e0 72 2c 20 69 6e 63 6c 75 64 69 6e 67 20 73 70 61  r, including spa
140f0 63 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 7a 65  ce for.** the ze
14100 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20  ro terminator.  
14110 53 6f 20 74 68 65 20 6c 6f 6e 67 65 73 74 20 73  So the longest s
14120 74 72 69 6e 67 20 74 68 61 74 20 63 61 6e 20 62  tring that can b
14130 65 20 63 6f 6d 70 6c 65 74 65 6c 79 0a 2a 2a 20  e completely.** 
14140 77 72 69 74 74 65 6e 20 77 69 6c 6c 20 62 65 20  written will be 
14150 6e 2d 31 20 63 68 61 72 61 63 74 65 72 73 2e 0a  n-1 characters..
14160 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
14170 69 6e 65 73 20 61 6c 6c 20 69 6d 70 6c 65 6d 65  ines all impleme
14180 6e 74 20 73 6f 6d 65 20 61 64 64 69 74 69 6f 6e  nt some addition
14190 61 6c 20 66 6f 72 6d 61 74 74 69 6e 67 0a 2a 2a  al formatting.**
141a0 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 20 61 72   options that ar
141b0 65 20 75 73 65 66 75 6c 20 66 6f 72 20 63 6f 6e  e useful for con
141c0 73 74 72 75 63 74 69 6e 67 20 53 51 4c 20 73 74  structing SQL st
141d0 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 41 6c 6c  atements..** All
141e0 20 6f 66 20 74 68 65 20 75 73 75 61 6c 20 70 72   of the usual pr
141f0 69 6e 74 66 28 29 20 66 6f 72 6d 61 74 74 69 6e  intf() formattin
14200 67 20 6f 70 74 69 6f 6e 73 20 61 70 70 6c 79 2e  g options apply.
14210 20 20 49 6e 20 61 64 64 69 74 69 6f 6e 2c 20 74    In addition, t
14220 68 65 72 65 0a 2a 2a 20 69 73 20 61 72 65 20 22  here.** is are "
14230 25 71 22 2c 20 22 25 51 22 2c 20 61 6e 64 20 22  %q", "%Q", and "
14240 25 7a 22 20 6f 70 74 69 6f 6e 73 2e 0a 2a 2a 0a  %z" options..**.
14250 2a 2a 20 54 68 65 20 25 71 20 6f 70 74 69 6f 6e  ** The %q option
14260 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 73 20 69   works like %s i
14270 6e 20 74 68 61 74 20 69 74 20 73 75 62 73 74 69  n that it substi
14280 74 75 74 65 73 20 61 20 6e 75 6c 6c 2d 74 65 72  tutes a null-ter
14290 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e  minated.** strin
142a0 67 20 66 72 6f 6d 20 74 68 65 20 61 72 67 75 6d  g from the argum
142b0 65 6e 74 20 6c 69 73 74 2e 20 20 42 75 74 20 25  ent list.  But %
142c0 71 20 61 6c 73 6f 20 64 6f 75 62 6c 65 73 20 65  q also doubles e
142d0 76 65 72 79 20 27 5c 27 27 20 63 68 61 72 61 63  very '\'' charac
142e0 74 65 72 2e 0a 2a 2a 20 25 71 20 69 73 20 64 65  ter..** %q is de
142f0 73 69 67 6e 65 64 20 66 6f 72 20 75 73 65 20 69  signed for use i
14300 6e 73 69 64 65 20 61 20 73 74 72 69 6e 67 20 6c  nside a string l
14310 69 74 65 72 61 6c 2e 20 20 42 79 20 64 6f 75 62  iteral.  By doub
14320 6c 69 6e 67 20 65 61 63 68 20 27 5c 27 27 0a 2a  ling each '\''.*
14330 2a 20 63 68 61 72 61 63 74 65 72 20 69 74 20 65  * character it e
14340 73 63 61 70 65 73 20 74 68 61 74 20 63 68 61 72  scapes that char
14350 61 63 74 65 72 20 61 6e 64 20 61 6c 6c 6f 77 73  acter and allows
14360 20 69 74 20 74 6f 20 62 65 20 69 6e 73 65 72 74   it to be insert
14370 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 73  ed into.** the s
14380 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72  tring..**.** For
14390 20 65 78 61 6d 70 6c 65 2c 20 61 73 73 75 6d 65   example, assume
143a0 20 74 68 65 20 73 74 72 69 6e 67 20 76 61 72 69   the string vari
143b0 61 62 6c 65 20 7a 54 65 78 74 20 63 6f 6e 74 61  able zText conta
143c0 69 6e 73 20 74 65 78 74 20 61 73 20 66 6f 6c 6c  ins text as foll
143d0 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  ows:.**.** <bloc
143e0 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
143f0 20 63 68 61 72 20 2a 7a 54 65 78 74 20 3d 20 22   char *zText = "
14400 49 74 27 73 20 61 20 68 61 70 70 79 20 64 61 79  It's a happy day
14410 21 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62  !";.** </pre></b
14420 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
14430 20 4f 6e 65 20 63 61 6e 20 75 73 65 20 74 68 69   One can use thi
14440 73 20 74 65 78 74 20 69 6e 20 61 6e 20 53 51 4c  s text in an SQL
14450 20 73 74 61 74 65 6d 65 6e 74 20 61 73 20 66 6f   statement as fo
14460 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  llows:.**.** <bl
14470 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
14480 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20  *  char *zSQL = 
14490 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28  sqlite3_mprintf(
144a0 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62  "INSERT INTO tab
144b0 6c 65 20 56 41 4c 55 45 53 28 27 25 71 27 29 22  le VALUES('%q')"
144c0 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71  , zText);.**  sq
144d0 6c 69 74 65 33 5f 65 78 65 63 28 64 62 2c 20 7a  lite3_exec(db, z
144e0 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a  SQL, 0, 0, 0);.*
144f0 2a 20 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  *  sqlite3_free(
14500 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e  zSQL);.** </pre>
14510 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
14520 0a 2a 2a 20 42 65 63 61 75 73 65 20 74 68 65 20  .** Because the 
14530 25 71 20 66 6f 72 6d 61 74 20 73 74 72 69 6e 67  %q format string
14540 20 69 73 20 75 73 65 64 2c 20 74 68 65 20 27 5c   is used, the '\
14550 27 27 20 63 68 61 72 61 63 74 65 72 20 69 6e 20  '' character in 
14560 7a 54 65 78 74 0a 2a 2a 20 69 73 20 65 73 63 61  zText.** is esca
14570 70 65 64 20 61 6e 64 20 74 68 65 20 53 51 4c 20  ped and the SQL 
14580 67 65 6e 65 72 61 74 65 64 20 69 73 20 61 73 20  generated is as 
14590 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c  follows:.**.** <
145a0 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
145b0 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f  .**  INSERT INTO
145c0 20 74 61 62 6c 65 31 20 56 41 4c 55 45 53 28 27   table1 VALUES('
145d0 49 74 27 27 73 20 61 20 68 61 70 70 79 20 64 61  It''s a happy da
145e0 79 21 27 29 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  y!').** </pre></
145f0 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
14600 2a 20 54 68 69 73 20 69 73 20 63 6f 72 72 65 63  * This is correc
14610 74 2e 20 20 48 61 64 20 77 65 20 75 73 65 64 20  t.  Had we used 
14620 25 73 20 69 6e 73 74 65 61 64 20 6f 66 20 25 71  %s instead of %q
14630 2c 20 74 68 65 20 67 65 6e 65 72 61 74 65 64 20  , the generated 
14640 53 51 4c 0a 2a 2a 20 77 6f 75 6c 64 20 68 61 76  SQL.** would hav
14650 65 20 6c 6f 6f 6b 65 64 20 6c 69 6b 65 20 74 68  e looked like th
14660 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  is:.**.** <block
14670 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
14680 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c  INSERT INTO tabl
14690 65 31 20 56 41 4c 55 45 53 28 27 49 74 27 73 20  e1 VALUES('It's 
146a0 61 20 68 61 70 70 79 20 64 61 79 21 27 29 3b 0a  a happy day!');.
146b0 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
146c0 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69  quote>.**.** Thi
146d0 73 20 73 65 63 6f 6e 64 20 65 78 61 6d 70 6c 65  s second example
146e0 20 69 73 20 61 6e 20 53 51 4c 20 73 79 6e 74 61   is an SQL synta
146f0 78 20 65 72 72 6f 72 2e 20 20 41 73 20 61 20 67  x error.  As a g
14700 65 6e 65 72 61 6c 20 72 75 6c 65 20 79 6f 75 20  eneral rule you 
14710 73 68 6f 75 6c 64 0a 2a 2a 20 61 6c 77 61 79 73  should.** always
14720 20 75 73 65 20 25 71 20 69 6e 73 74 65 61 64 20   use %q instead 
14730 6f 66 20 25 73 20 77 68 65 6e 20 69 6e 73 65 72  of %s when inser
14740 74 69 6e 67 20 74 65 78 74 20 69 6e 74 6f 20 61  ting text into a
14750 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e   string literal.
14760 0a 2a 2a 0a 2a 2a 20 54 68 65 20 25 51 20 6f 70  .**.** The %Q op
14770 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20  tion works like 
14780 25 71 20 65 78 63 65 70 74 20 69 74 20 61 6c 73  %q except it als
14790 6f 20 61 64 64 73 20 73 69 6e 67 6c 65 20 71 75  o adds single qu
147a0 6f 74 65 73 20 61 72 6f 75 6e 64 0a 2a 2a 20 74  otes around.** t
147b0 68 65 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68  he outside of th
147c0 65 20 74 6f 74 61 6c 20 73 74 72 69 6e 67 2e 20  e total string. 
147d0 20 41 64 64 69 74 69 6f 6e 61 6c 6c 79 2c 20 69   Additionally, i
147e0 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  f the parameter 
147f0 69 6e 20 74 68 65 0a 2a 2a 20 61 72 67 75 6d 65  in the.** argume
14800 6e 74 20 6c 69 73 74 20 69 73 20 61 20 4e 55 4c  nt list is a NUL
14810 4c 20 70 6f 69 6e 74 65 72 2c 20 25 51 20 73 75  L pointer, %Q su
14820 62 73 74 69 74 75 74 65 73 20 74 68 65 20 74 65  bstitutes the te
14830 78 74 20 22 4e 55 4c 4c 22 20 28 77 69 74 68 6f  xt "NULL" (witho
14840 75 74 0a 2a 2a 20 73 69 6e 67 6c 65 20 71 75 6f  ut.** single quo
14850 74 65 73 29 20 69 6e 20 70 6c 61 63 65 20 6f 66  tes) in place of
14860 20 74 68 65 20 25 51 20 6f 70 74 69 6f 6e 2e 20   the %Q option. 
14870 20 53 6f 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65   So, for example
14880 2c 20 6f 6e 65 20 63 6f 75 6c 64 20 73 61 79 3a  , one could say:
14890 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
148a0 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61  te><pre>.**  cha
148b0 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65  r *zSQL = sqlite
148c0 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 45 52  3_mprintf("INSER
148d0 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c  T INTO table VAL
148e0 55 45 53 28 25 51 29 22 2c 20 7a 54 65 78 74 29  UES(%Q)", zText)
148f0 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 78  ;.**  sqlite3_ex
14900 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20  ec(db, zSQL, 0, 
14910 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74  0, 0);.**  sqlit
14920 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a  e3_free(zSQL);.*
14930 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
14940 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  uote>.**.** The 
14950 63 6f 64 65 20 61 62 6f 76 65 20 77 69 6c 6c 20  code above will 
14960 72 65 6e 64 65 72 20 61 20 63 6f 72 72 65 63 74  render a correct
14970 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69   SQL statement i
14980 6e 20 74 68 65 20 7a 53 51 4c 0a 2a 2a 20 76 61  n the zSQL.** va
14990 72 69 61 62 6c 65 20 65 76 65 6e 20 69 66 20 74  riable even if t
149a0 68 65 20 7a 54 65 78 74 20 76 61 72 69 61 62 6c  he zText variabl
149b0 65 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  e is a NULL poin
149c0 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 22  ter..**.** The "
149d0 25 7a 22 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f  %z" formatting o
149e0 70 74 69 6f 6e 20 77 6f 72 6b 73 20 65 78 61 63  ption works exac
149f0 74 6c 79 20 6c 69 6b 65 20 22 25 73 22 20 77 69  tly like "%s" wi
14a00 74 68 20 74 68 65 0a 2a 2a 20 61 64 64 69 74 69  th the.** additi
14a10 6f 6e 20 74 68 61 74 20 61 66 74 65 72 20 74 68  on that after th
14a20 65 20 73 74 72 69 6e 67 20 68 61 73 20 62 65 65  e string has bee
14a30 6e 20 72 65 61 64 20 61 6e 64 20 63 6f 70 69 65  n read and copie
14a40 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 72 65  d into.** the re
14a50 73 75 6c 74 2c 20 5b 73 71 6c 69 74 65 33 5f 66  sult, [sqlite3_f
14a60 72 65 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64  ree()] is called
14a70 20 6f 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74   on the input st
14a80 72 69 6e 67 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a  ring. {END}.**.*
14a90 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
14aa0 0a 2a 2a 20 7b 48 31 37 34 30 33 7d 20 20 54 68  .** {H17403}  Th
14ab0 65 20 5b 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e  e [sqlite3_mprin
14ac0 74 66 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  tf()] and [sqlit
14ad0 65 33 5f 76 6d 70 72 69 6e 74 66 28 29 5d 20 69  e3_vmprintf()] i
14ae0 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 20 20 20  nterfaces.**    
14af0 20 20 20 20 20 20 20 72 65 74 75 72 6e 20 65 69         return ei
14b00 74 68 65 72 20 70 6f 69 6e 74 65 72 73 20 74 6f  ther pointers to
14b10 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
14b20 20 55 54 46 2d 38 20 73 74 72 69 6e 67 73 20 68   UTF-8 strings h
14b30 65 6c 64 20 69 6e 0a 2a 2a 20 20 20 20 20 20 20  eld in.**       
14b40 20 20 20 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69      memory obtai
14b50 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ned from [sqlite
14b60 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 4e  3_malloc()] or N
14b70 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20 69 66 0a  ULL pointers if.
14b80 2a 2a 20 20 20 20 20 20 20 20 20 20 20 61 20 63  **           a c
14b90 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
14ba0 6d 61 6c 6c 6f 63 28 29 5d 20 66 61 69 6c 73 2e  malloc()] fails.
14bb0 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 34 30 36 7d 20  .**.** {H17406} 
14bc0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 6e   The [sqlite3_sn
14bd0 70 72 69 6e 74 66 28 29 5d 20 69 6e 74 65 72 66  printf()] interf
14be0 61 63 65 20 77 72 69 74 65 73 20 61 20 7a 65 72  ace writes a zer
14bf0 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20  o-terminated.** 
14c00 20 20 20 20 20 20 20 20 20 20 55 54 46 2d 38 20            UTF-8 
14c10 73 74 72 69 6e 67 20 69 6e 74 6f 20 74 68 65 20  string into the 
14c20 62 75 66 66 65 72 20 70 6f 69 6e 74 65 64 20 74  buffer pointed t
14c30 6f 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20  o by the second 
14c40 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 20 20 20  parameter.**    
14c50 20 20 20 20 20 20 20 70 72 6f 76 69 64 65 64 20         provided 
14c60 74 68 61 74 20 74 68 65 20 66 69 72 73 74 20 70  that the first p
14c70 61 72 61 6d 65 74 65 72 20 69 73 20 67 72 65 61  arameter is grea
14c80 74 65 72 20 74 68 61 6e 20 7a 65 72 6f 2e 0a 2a  ter than zero..*
14c90 2a 0a 2a 2a 20 7b 48 31 37 34 30 37 7d 20 20 54  *.** {H17407}  T
14ca0 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72  he [sqlite3_snpr
14cb0 69 6e 74 66 28 29 5d 20 69 6e 74 65 72 66 61 63  intf()] interfac
14cc0 65 20 64 6f 65 73 20 6e 6f 74 20 77 72 69 74 65  e does not write
14cd0 20 73 6c 6f 74 73 20 6f 66 0a 2a 2a 20 20 20 20   slots of.**    
14ce0 20 20 20 20 20 20 20 69 74 73 20 6f 75 74 70 75         its outpu
14cf0 74 20 62 75 66 66 65 72 20 28 74 68 65 20 73 65  t buffer (the se
14d00 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 29 20  cond parameter) 
14d10 6f 75 74 73 69 64 65 20 74 68 65 20 72 61 6e 67  outside the rang
14d20 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 6f  e.**           o
14d30 66 20 30 20 74 68 72 6f 75 67 68 20 4e 2d 31 20  f 0 through N-1 
14d40 28 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20  (where N is the 
14d50 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 29  first parameter)
14d60 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 72 65  .**           re
14d70 67 61 72 64 6c 65 73 73 20 6f 66 20 74 68 65 20  gardless of the 
14d80 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 73 74  length of the st
14d90 72 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20  ring.**         
14da0 20 20 72 65 71 75 65 73 74 65 64 20 62 79 20 74    requested by t
14db0 68 65 20 66 6f 72 6d 61 74 20 73 70 65 63 69 66  he format specif
14dc0 69 63 61 74 69 6f 6e 2e 0a 2a 2f 0a 63 68 61 72  ication..*/.char
14dd0 20 2a 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74   *sqlite3_mprint
14de0 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 2e 2e  f(const char*,..
14df0 2e 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65  .);.char *sqlite
14e00 33 5f 76 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74  3_vmprintf(const
14e10 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29   char*, va_list)
14e20 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  ;.char *sqlite3_
14e30 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 61  snprintf(int,cha
14e40 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20  r*,const char*, 
14e50 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ...);../*.** CAP
14e60 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c  I3REF: Memory Al
14e70 6c 6f 63 61 74 69 6f 6e 20 53 75 62 73 79 73 74  location Subsyst
14e80 65 6d 20 7b 48 31 37 33 30 30 7d 20 3c 53 32 30  em {H17300} <S20
14e90 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53  000>.**.** The S
14ea0 51 4c 69 74 65 20 63 6f 72 65 20 20 75 73 65 73  QLite core  uses
14eb0 20 74 68 65 73 65 20 74 68 72 65 65 20 72 6f 75   these three rou
14ec0 74 69 6e 65 73 20 66 6f 72 20 61 6c 6c 20 6f 66  tines for all of
14ed0 20 69 74 73 20 6f 77 6e 0a 2a 2a 20 69 6e 74 65   its own.** inte
14ee0 72 6e 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  rnal memory allo
14ef0 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 20 22 43  cation needs. "C
14f00 6f 72 65 22 20 69 6e 20 74 68 65 20 70 72 65 76  ore" in the prev
14f10 69 6f 75 73 20 73 65 6e 74 65 6e 63 65 0a 2a 2a  ious sentence.**
14f20 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64   does not includ
14f30 65 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 74  e operating-syst
14f40 65 6d 20 73 70 65 63 69 66 69 63 20 56 46 53 20  em specific VFS 
14f50 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20  implementation. 
14f60 20 54 68 65 0a 2a 2a 20 57 69 6e 64 6f 77 73 20   The.** Windows 
14f70 56 46 53 20 75 73 65 73 20 6e 61 74 69 76 65 20  VFS uses native 
14f80 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65  malloc() and fre
14f90 65 28 29 20 66 6f 72 20 73 6f 6d 65 20 6f 70 65  e() for some ope
14fa0 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54  rations..**.** T
14fb0 68 65 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  he sqlite3_mallo
14fc0 63 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75  c() routine retu
14fd0 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
14fe0 20 61 20 62 6c 6f 63 6b 0a 2a 2a 20 6f 66 20 6d   a block.** of m
14ff0 65 6d 6f 72 79 20 61 74 20 6c 65 61 73 74 20 4e  emory at least N
15000 20 62 79 74 65 73 20 69 6e 20 6c 65 6e 67 74 68   bytes in length
15010 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65  , where N is the
15020 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 49   parameter..** I
15030 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  f sqlite3_malloc
15040 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  () is unable to 
15050 6f 62 74 61 69 6e 20 73 75 66 66 69 63 69 65 6e  obtain sufficien
15060 74 20 66 72 65 65 0a 2a 2a 20 6d 65 6d 6f 72 79  t free.** memory
15070 2c 20 69 74 20 72 65 74 75 72 6e 73 20 61 20 4e  , it returns a N
15080 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 49 66  ULL pointer.  If
15090 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 4e   the parameter N
150a0 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d   to.** sqlite3_m
150b0 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f 20  alloc() is zero 
150c0 6f 72 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e  or negative then
150d0 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
150e0 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20 4e  ) returns.** a N
150f0 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a  ULL pointer..**.
15100 2a 2a 20 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74  ** Calling sqlit
15110 65 33 5f 66 72 65 65 28 29 20 77 69 74 68 20 61  e3_free() with a
15120 20 70 6f 69 6e 74 65 72 20 70 72 65 76 69 6f 75   pointer previou
15130 73 6c 79 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  sly returned.** 
15140 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  by sqlite3_mallo
15150 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72  c() or sqlite3_r
15160 65 61 6c 6c 6f 63 28 29 20 72 65 6c 65 61 73 65  ealloc() release
15170 73 20 74 68 61 74 20 6d 65 6d 6f 72 79 20 73 6f  s that memory so
15180 0a 2a 2a 20 74 68 61 74 20 69 74 20 6d 69 67 68  .** that it migh
15190 74 20 62 65 20 72 65 75 73 65 64 2e 20 20 54 68  t be reused.  Th
151a0 65 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29  e sqlite3_free()
151b0 20 72 6f 75 74 69 6e 65 20 69 73 0a 2a 2a 20 61   routine is.** a
151c0 20 6e 6f 2d 6f 70 20 69 66 20 69 73 20 63 61 6c   no-op if is cal
151d0 6c 65 64 20 77 69 74 68 20 61 20 4e 55 4c 4c 20  led with a NULL 
151e0 70 6f 69 6e 74 65 72 2e 20 20 50 61 73 73 69 6e  pointer.  Passin
151f0 67 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  g a NULL pointer
15200 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 66  .** to sqlite3_f
15210 72 65 65 28 29 20 69 73 20 68 61 72 6d 6c 65 73  ree() is harmles
15220 73 2e 20 20 41 66 74 65 72 20 62 65 69 6e 67 20  s.  After being 
15230 66 72 65 65 64 2c 20 6d 65 6d 6f 72 79 0a 2a 2a  freed, memory.**
15240 20 73 68 6f 75 6c 64 20 6e 65 69 74 68 65 72 20   should neither 
15250 62 65 20 72 65 61 64 20 6e 6f 72 20 77 72 69 74  be read nor writ
15260 74 65 6e 2e 20 20 45 76 65 6e 20 72 65 61 64 69  ten.  Even readi
15270 6e 67 20 70 72 65 76 69 6f 75 73 6c 79 20 66 72  ng previously fr
15280 65 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6d 69  eed.** memory mi
15290 67 68 74 20 72 65 73 75 6c 74 20 69 6e 20 61 20  ght result in a 
152a0 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75  segmentation fau
152b0 6c 74 20 6f 72 20 6f 74 68 65 72 20 73 65 76 65  lt or other seve
152c0 72 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 4d 65 6d  re error..** Mem
152d0 6f 72 79 20 63 6f 72 72 75 70 74 69 6f 6e 2c 20  ory corruption, 
152e0 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66  a segmentation f
152f0 61 75 6c 74 2c 20 6f 72 20 6f 74 68 65 72 20 73  ault, or other s
15300 65 76 65 72 65 20 65 72 72 6f 72 0a 2a 2a 20 6d  evere error.** m
15310 69 67 68 74 20 72 65 73 75 6c 74 20 69 66 20 73  ight result if s
15320 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69 73  qlite3_free() is
15330 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20 6e   called with a n
15340 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20  on-NULL pointer 
15350 74 68 61 74 0a 2a 2a 20 77 61 73 20 6e 6f 74 20  that.** was not 
15360 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 73 71  obtained from sq
15370 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f  lite3_malloc() o
15380 72 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29  r sqlite3_free()
15390 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
153a0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 69 6e  te3_realloc() in
153b0 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 73  terface attempts
153c0 20 74 6f 20 72 65 73 69 7a 65 20 61 0a 2a 2a 20   to resize a.** 
153d0 70 72 69 6f 72 20 6d 65 6d 6f 72 79 20 61 6c 6c  prior memory all
153e0 6f 63 61 74 69 6f 6e 20 74 6f 20 62 65 20 61 74  ocation to be at
153f0 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 2c 20   least N bytes, 
15400 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 0a 2a  where N is the.*
15410 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  * second paramet
15420 65 72 2e 20 20 54 68 65 20 6d 65 6d 6f 72 79 20  er.  The memory 
15430 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 62 65  allocation to be
15440 20 72 65 73 69 7a 65 64 20 69 73 20 74 68 65 20   resized is the 
15450 66 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74  first.** paramet
15460 65 72 2e 20 20 49 66 20 74 68 65 20 66 69 72 73  er.  If the firs
15470 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  t parameter to s
15480 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
15490 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  .** is a NULL po
154a0 69 6e 74 65 72 20 74 68 65 6e 20 69 74 73 20 62  inter then its b
154b0 65 68 61 76 69 6f 72 20 69 73 20 69 64 65 6e 74  ehavior is ident
154c0 69 63 61 6c 20 74 6f 20 63 61 6c 6c 69 6e 67 0a  ical to calling.
154d0 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  ** sqlite3_mallo
154e0 63 28 4e 29 20 77 68 65 72 65 20 4e 20 69 73 20  c(N) where N is 
154f0 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  the second param
15500 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
15510 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 49 66  realloc()..** If
15520 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   the second para
15530 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
15540 5f 72 65 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65  _realloc() is ze
15550 72 6f 20 6f 72 0a 2a 2a 20 6e 65 67 61 74 69 76  ro or.** negativ
15560 65 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76  e then the behav
15570 69 6f 72 20 69 73 20 65 78 61 63 74 6c 79 20 74  ior is exactly t
15580 68 65 20 73 61 6d 65 20 61 73 20 63 61 6c 6c 69  he same as calli
15590 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66 72  ng.** sqlite3_fr
155a0 65 65 28 50 29 20 77 68 65 72 65 20 50 20 69 73  ee(P) where P is
155b0 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   the first param
155c0 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
155d0 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 73 71  realloc()..** sq
155e0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20  lite3_realloc() 
155f0 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
15600 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20 61 6c  r to a memory al
15610 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 61  location.** of a
15620 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20  t least N bytes 
15630 69 6e 20 73 69 7a 65 20 6f 72 20 4e 55 4c 4c 20  in size or NULL 
15640 69 66 20 73 75 66 66 69 63 69 65 6e 74 20 6d 65  if sufficient me
15650 6d 6f 72 79 20 69 73 20 75 6e 61 76 61 69 6c 61  mory is unavaila
15660 62 6c 65 2e 0a 2a 2a 20 49 66 20 4d 20 69 73 20  ble..** If M is 
15670 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  the size of the 
15680 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e  prior allocation
15690 2c 20 74 68 65 6e 20 6d 69 6e 28 4e 2c 4d 29 20  , then min(N,M) 
156a0 62 79 74 65 73 0a 2a 2a 20 6f 66 20 74 68 65 20  bytes.** of the 
156b0 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e  prior allocation
156c0 20 61 72 65 20 63 6f 70 69 65 64 20 69 6e 74 6f   are copied into
156d0 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f   the beginning o
156e0 66 20 62 75 66 66 65 72 20 72 65 74 75 72 6e 65  f buffer returne
156f0 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f  d.** by sqlite3_
15700 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64 20 74 68  realloc() and th
15710 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69  e prior allocati
15720 6f 6e 20 69 73 20 66 72 65 65 64 2e 0a 2a 2a 20  on is freed..** 
15730 49 66 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  If sqlite3_reall
15740 6f 63 28 29 20 72 65 74 75 72 6e 73 20 4e 55 4c  oc() returns NUL
15750 4c 2c 20 74 68 65 6e 20 74 68 65 20 70 72 69 6f  L, then the prio
15760 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20  r allocation.** 
15770 69 73 20 6e 6f 74 20 66 72 65 65 64 2e 0a 2a 2a  is not freed..**
15780 0a 2a 2a 20 54 68 65 20 6d 65 6d 6f 72 79 20 72  .** The memory r
15790 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
157a0 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20  e3_malloc() and 
157b0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
157c0 29 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61  ).** is always a
157d0 6c 69 67 6e 65 64 20 74 6f 20 61 74 20 6c 65 61  ligned to at lea
157e0 73 74 20 61 6e 20 38 20 62 79 74 65 20 62 6f 75  st an 8 byte bou
157f0 6e 64 61 72 79 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a  ndary. {END}.**.
15800 2a 2a 20 54 68 65 20 64 65 66 61 75 6c 74 20 69  ** The default i
15810 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
15820 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f   the memory allo
15830 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d  cation subsystem
15840 20 75 73 65 73 0a 2a 2a 20 74 68 65 20 6d 61 6c   uses.** the mal
15850 6c 6f 63 28 29 2c 20 72 65 61 6c 6c 6f 63 28 29  loc(), realloc()
15860 20 61 6e 64 20 66 72 65 65 28 29 20 70 72 6f 76   and free() prov
15870 69 64 65 64 20 62 79 20 74 68 65 20 73 74 61 6e  ided by the stan
15880 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a  dard C library..
15890 2a 2a 20 7b 48 31 37 33 38 32 7d 20 48 6f 77 65  ** {H17382} Howe
158a0 76 65 72 2c 20 69 66 20 53 51 4c 69 74 65 20 69  ver, if SQLite i
158b0 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20  s compiled with 
158c0 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 4d 45  the.** SQLITE_ME
158d0 4d 4f 52 59 5f 53 49 5a 45 3d 3c 69 3e 4e 4e 4e  MORY_SIZE=<i>NNN
158e0 3c 2f 69 3e 20 43 20 70 72 65 70 72 6f 63 65 73  </i> C preproces
158f0 73 6f 72 20 6d 61 63 72 6f 20 28 77 68 65 72 65  sor macro (where
15900 20 3c 69 3e 4e 4e 4e 3c 2f 69 3e 0a 2a 2a 20 69   <i>NNN</i>.** i
15910 73 20 61 6e 20 69 6e 74 65 67 65 72 29 2c 20 74  s an integer), t
15920 68 65 6e 20 53 51 4c 69 74 65 20 63 72 65 61 74  hen SQLite creat
15930 65 20 61 20 73 74 61 74 69 63 20 61 72 72 61 79  e a static array
15940 20 6f 66 20 61 74 20 6c 65 61 73 74 0a 2a 2a 20   of at least.** 
15950 3c 69 3e 4e 4e 4e 3c 2f 69 3e 20 62 79 74 65 73  <i>NNN</i> bytes
15960 20 69 6e 20 73 69 7a 65 20 61 6e 64 20 75 73 65   in size and use
15970 73 20 74 68 61 74 20 61 72 72 61 79 20 66 6f 72  s that array for
15980 20 61 6c 6c 20 6f 66 20 69 74 73 20 64 79 6e 61   all of its dyna
15990 6d 69 63 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c  mic.** memory al
159a0 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 20  location needs. 
159b0 7b 45 4e 44 7d 20 20 41 64 64 69 74 69 6f 6e 61  {END}  Additiona
159c0 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  l memory allocat
159d0 6f 72 20 6f 70 74 69 6f 6e 73 0a 2a 2a 20 6d 61  or options.** ma
159e0 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75  y be added in fu
159f0 74 75 72 65 20 72 65 6c 65 61 73 65 73 2e 0a 2a  ture releases..*
15a00 2a 0a 2a 2a 20 49 6e 20 53 51 4c 69 74 65 20 76  *.** In SQLite v
15a10 65 72 73 69 6f 6e 20 33 2e 35 2e 30 20 61 6e 64  ersion 3.5.0 and
15a20 20 33 2e 35 2e 31 2c 20 69 74 20 77 61 73 20 70   3.5.1, it was p
15a30 6f 73 73 69 62 6c 65 20 74 6f 20 64 65 66 69 6e  ossible to defin
15a40 65 0a 2a 2a 20 74 68 65 20 53 51 4c 49 54 45 5f  e.** the SQLITE_
15a50 4f 4d 49 54 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f  OMIT_MEMORY_ALLO
15a60 43 41 54 49 4f 4e 20 77 68 69 63 68 20 77 6f 75  CATION which wou
15a70 6c 64 20 63 61 75 73 65 20 74 68 65 20 62 75 69  ld cause the bui
15a80 6c 74 2d 69 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65  lt-in.** impleme
15a90 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 73 65  ntation of these
15aa0 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20   routines to be 
15ab0 6f 6d 69 74 74 65 64 2e 20 20 54 68 61 74 20 63  omitted.  That c
15ac0 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20  apability.** is 
15ad0 6e 6f 20 6c 6f 6e 67 65 72 20 70 72 6f 76 69 64  no longer provid
15ae0 65 64 2e 20 20 4f 6e 6c 79 20 62 75 69 6c 74 2d  ed.  Only built-
15af0 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  in memory alloca
15b00 74 6f 72 73 20 63 61 6e 20 62 65 20 75 73 65 64  tors can be used
15b10 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 57 69 6e 64  ..**.** The Wind
15b20 6f 77 73 20 4f 53 20 69 6e 74 65 72 66 61 63 65  ows OS interface
15b30 20 6c 61 79 65 72 20 63 61 6c 6c 73 0a 2a 2a 20   layer calls.** 
15b40 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f  the system mallo
15b50 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 64  c() and free() d
15b60 69 72 65 63 74 6c 79 20 77 68 65 6e 20 63 6f 6e  irectly when con
15b70 76 65 72 74 69 6e 67 0a 2a 2a 20 66 69 6c 65 6e  verting.** filen
15b80 61 6d 65 73 20 62 65 74 77 65 65 6e 20 74 68 65  ames between the
15b90 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20   UTF-8 encoding 
15ba0 75 73 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a  used by SQLite.*
15bb0 2a 20 61 6e 64 20 77 68 61 74 65 76 65 72 20 66  * and whatever f
15bc0 69 6c 65 6e 61 6d 65 20 65 6e 63 6f 64 69 6e 67  ilename encoding
15bd0 20 69 73 20 75 73 65 64 20 62 79 20 74 68 65 20   is used by the 
15be0 70 61 72 74 69 63 75 6c 61 72 20 57 69 6e 64 6f  particular Windo
15bf0 77 73 0a 2a 2a 20 69 6e 73 74 61 6c 6c 61 74 69  ws.** installati
15c00 6f 6e 2e 20 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f  on.  Memory allo
15c10 63 61 74 69 6f 6e 20 65 72 72 6f 72 73 20 61 72  cation errors ar
15c20 65 20 64 65 74 65 63 74 65 64 2c 20 62 75 74 0a  e detected, but.
15c30 2a 2a 20 74 68 65 79 20 61 72 65 20 72 65 70 6f  ** they are repo
15c40 72 74 65 64 20 62 61 63 6b 20 61 73 20 5b 53 51  rted back as [SQ
15c50 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 6f  LITE_CANTOPEN] o
15c60 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f 45  r.** [SQLITE_IOE
15c70 52 52 5d 20 72 61 74 68 65 72 20 74 68 61 6e 20  RR] rather than 
15c80 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a  [SQLITE_NOMEM]..
15c90 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
15ca0 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33 30 33 7d  :.**.** {H17303}
15cb0 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d    The [sqlite3_m
15cc0 61 6c 6c 6f 63 28 4e 29 5d 20 69 6e 74 65 72 66  alloc(N)] interf
15cd0 61 63 65 20 72 65 74 75 72 6e 73 20 65 69 74 68  ace returns eith
15ce0 65 72 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 0a  er a pointer to.
15cf0 2a 2a 20 20 20 20 20 20 20 20 20 20 20 61 20 6e  **           a n
15d00 65 77 6c 79 20 63 68 65 63 6b 65 64 2d 6f 75 74  ewly checked-out
15d10 20 62 6c 6f 63 6b 20 6f 66 20 61 74 20 6c 65 61   block of at lea
15d20 73 74 20 4e 20 62 79 74 65 73 20 6f 66 20 6d 65  st N bytes of me
15d30 6d 6f 72 79 0a 2a 2a 20 20 20 20 20 20 20 20 20  mory.**         
15d40 20 20 74 68 61 74 20 69 73 20 38 2d 62 79 74 65    that is 8-byte
15d50 20 61 6c 69 67 6e 65 64 2c 20 6f 72 20 69 74 20   aligned, or it 
15d60 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20 69 66 20  returns NULL if 
15d70 69 74 20 69 73 20 75 6e 61 62 6c 65 0a 2a 2a 20  it is unable.** 
15d80 20 20 20 20 20 20 20 20 20 20 74 6f 20 66 75 6c            to ful
15d90 66 69 6c 6c 20 74 68 65 20 72 65 71 75 65 73 74  fill the request
15da0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33 30 34 7d  ..**.** {H17304}
15db0 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d    The [sqlite3_m
15dc0 61 6c 6c 6f 63 28 4e 29 5d 20 69 6e 74 65 72 66  alloc(N)] interf
15dd0 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 4e 55  ace returns a NU
15de0 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 0a 2a 2a  LL pointer if.**
15df0 20 20 20 20 20 20 20 20 20 20 20 4e 20 69 73 20             N is 
15e00 6c 65 73 73 20 74 68 61 6e 20 6f 72 20 65 71 75  less than or equ
15e10 61 6c 20 74 6f 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a  al to zero..**.*
15e20 2a 20 7b 48 31 37 33 30 35 7d 20 20 54 68 65 20  * {H17305}  The 
15e30 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 50 29  [sqlite3_free(P)
15e40 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 6c 65  ] interface rele
15e50 61 73 65 73 20 6d 65 6d 6f 72 79 20 70 72 65 76  ases memory prev
15e60 69 6f 75 73 6c 79 0a 2a 2a 20 20 20 20 20 20 20  iously.**       
15e70 20 20 20 20 72 65 74 75 72 6e 65 64 20 66 72 6f      returned fro
15e80 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  m [sqlite3_mallo
15e90 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  c()] or [sqlite3
15ea0 5f 72 65 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20  _realloc()],.** 
15eb0 20 20 20 20 20 20 20 20 20 20 6d 61 6b 69 6e 67            making
15ec0 20 69 74 20 61 76 61 69 6c 61 62 6c 65 20 66 6f   it available fo
15ed0 72 20 72 65 75 73 65 2e 0a 2a 2a 0a 2a 2a 20 7b  r reuse..**.** {
15ee0 48 31 37 33 30 36 7d 20 20 41 20 63 61 6c 6c 20  H17306}  A call 
15ef0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  to [sqlite3_free
15f00 28 4e 55 4c 4c 29 5d 20 69 73 20 61 20 68 61 72  (NULL)] is a har
15f10 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2a 0a  mless no-op..**.
15f20 2a 2a 20 7b 48 31 37 33 31 30 7d 20 20 41 20 63  ** {H17310}  A c
15f30 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
15f40 72 65 61 6c 6c 6f 63 28 30 2c 4e 29 5d 20 69 73  realloc(0,N)] is
15f50 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 61   equivalent to a
15f60 20 63 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20   call.**        
15f70 20 20 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d     to [sqlite3_m
15f80 61 6c 6c 6f 63 28 4e 29 5d 2e 0a 2a 2a 0a 2a 2a  alloc(N)]..**.**
15f90 20 7b 48 31 37 33 31 32 7d 20 20 41 20 63 61 6c   {H17312}  A cal
15fa0 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65  l to [sqlite3_re
15fb0 61 6c 6c 6f 63 28 50 2c 30 29 5d 20 69 73 20 65  alloc(P,0)] is e
15fc0 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 61 20 63  quivalent to a c
15fd0 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  all.**          
15fe0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65   to [sqlite3_fre
15ff0 65 28 50 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  e(P)]..**.** {H1
16000 37 33 31 35 7d 20 20 54 68 65 20 53 51 4c 69 74  7315}  The SQLit
16010 65 20 63 6f 72 65 20 75 73 65 73 20 5b 73 71 6c  e core uses [sql
16020 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20  ite3_malloc()], 
16030 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  [sqlite3_realloc
16040 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  ()],.**         
16050 20 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 66    and [sqlite3_f
16060 72 65 65 28 29 5d 20 66 6f 72 20 61 6c 6c 20 6f  ree()] for all o
16070 66 20 69 74 73 20 6d 65 6d 6f 72 79 20 61 6c 6c  f its memory all
16080 6f 63 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 20  ocation and.**  
16090 20 20 20 20 20 20 20 20 20 64 65 61 6c 6c 6f 63           dealloc
160a0 61 74 69 6f 6e 20 6e 65 65 64 73 2e 0a 2a 2a 0a  ation needs..**.
160b0 2a 2a 20 7b 48 31 37 33 31 38 7d 20 20 54 68 65  ** {H17318}  The
160c0 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   [sqlite3_reallo
160d0 63 28 50 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63  c(P,N)] interfac
160e0 65 20 72 65 74 75 72 6e 73 20 65 69 74 68 65 72  e returns either
160f0 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 20 20   a pointer.**   
16100 20 20 20 20 20 20 20 20 74 6f 20 61 20 62 6c 6f          to a blo
16110 63 6b 20 6f 66 20 63 68 65 63 6b 65 64 2d 6f 75  ck of checked-ou
16120 74 20 6d 65 6d 6f 72 79 20 6f 66 20 61 74 20 6c  t memory of at l
16130 65 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20  east N bytes in 
16140 73 69 7a 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  size.**         
16150 20 20 74 68 61 74 20 69 73 20 38 2d 62 79 74 65    that is 8-byte
16160 20 61 6c 69 67 6e 65 64 2c 20 6f 72 20 61 20 4e   aligned, or a N
16170 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a  ULL pointer..**.
16180 2a 2a 20 7b 48 31 37 33 32 31 7d 20 20 57 68 65  ** {H17321}  Whe
16190 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  n [sqlite3_reall
161a0 6f 63 28 50 2c 4e 29 5d 20 72 65 74 75 72 6e 73  oc(P,N)] returns
161b0 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e   a non-NULL poin
161c0 74 65 72 2c 20 69 74 20 66 69 72 73 74 0a 2a 2a  ter, it first.**
161d0 20 20 20 20 20 20 20 20 20 20 20 63 6f 70 69 65             copie
161e0 73 20 74 68 65 20 66 69 72 73 74 20 4b 20 62 79  s the first K by
161f0 74 65 73 20 6f 66 20 63 6f 6e 74 65 6e 74 20 66  tes of content f
16200 72 6f 6d 20 50 20 69 6e 74 6f 20 74 68 65 20 6e  rom P into the n
16210 65 77 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20 20  ewly.**         
16220 20 20 61 6c 6c 6f 63 61 74 65 64 20 62 6c 6f 63    allocated bloc
16230 6b 2c 20 77 68 65 72 65 20 4b 20 69 73 20 74 68  k, where K is th
16240 65 20 6c 65 73 73 65 72 20 6f 66 20 4e 20 61 6e  e lesser of N an
16250 64 20 74 68 65 20 73 69 7a 65 20 6f 66 0a 2a 2a  d the size of.**
16260 20 20 20 20 20 20 20 20 20 20 20 74 68 65 20 62             the b
16270 75 66 66 65 72 20 50 2e 0a 2a 2a 0a 2a 2a 20 7b  uffer P..**.** {
16280 48 31 37 33 32 32 7d 20 20 57 68 65 6e 20 5b 73  H17322}  When [s
16290 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 50  qlite3_realloc(P
162a0 2c 4e 29 5d 20 72 65 74 75 72 6e 73 20 61 20 6e  ,N)] returns a n
162b0 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c  on-NULL pointer,
162c0 20 69 74 20 66 69 72 73 74 0a 2a 2a 20 20 20 20   it first.**    
162d0 20 20 20 20 20 20 20 72 65 6c 65 61 73 65 73 20         releases 
162e0 74 68 65 20 62 75 66 66 65 72 20 50 2e 0a 2a 2a  the buffer P..**
162f0 0a 2a 2a 20 7b 48 31 37 33 32 33 7d 20 20 57 68  .** {H17323}  Wh
16300 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c  en [sqlite3_real
16310 6c 6f 63 28 50 2c 4e 29 5d 20 72 65 74 75 72 6e  loc(P,N)] return
16320 73 20 4e 55 4c 4c 2c 20 74 68 65 20 62 75 66 66  s NULL, the buff
16330 65 72 20 50 20 69 73 0a 2a 2a 20 20 20 20 20 20  er P is.**      
16340 20 20 20 20 20 6e 6f 74 20 6d 6f 64 69 66 69 65       not modifie
16350 64 20 6f 72 20 72 65 6c 65 61 73 65 64 2e 0a 2a  d or released..*
16360 2a 0a 2a 2a 20 41 53 53 55 4d 50 54 49 4f 4e 53  *.** ASSUMPTIONS
16370 3a 0a 2a 2a 0a 2a 2a 20 7b 41 31 37 33 35 30 7d  :.**.** {A17350}
16380 20 20 54 68 65 20 70 6f 69 6e 74 65 72 20 61 72    The pointer ar
16390 67 75 6d 65 6e 74 73 20 74 6f 20 5b 73 71 6c 69  guments to [sqli
163a0 74 65 33 5f 66 72 65 65 28 29 5d 20 61 6e 64 20  te3_free()] and 
163b0 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  [sqlite3_realloc
163c0 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ()].**          
163d0 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 20   must be either 
163e0 4e 55 4c 4c 20 6f 72 20 65 6c 73 65 20 70 6f 69  NULL or else poi
163f0 6e 74 65 72 73 20 6f 62 74 61 69 6e 65 64 20 66  nters obtained f
16400 72 6f 6d 20 61 20 70 72 69 6f 72 0a 2a 2a 20 20  rom a prior.**  
16410 20 20 20 20 20 20 20 20 20 69 6e 76 6f 63 61 74           invocat
16420 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f  ion of [sqlite3_
16430 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 73 71  malloc()] or [sq
16440 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d  lite3_realloc()]
16450 20 74 68 61 74 20 68 61 76 65 0a 2a 2a 20 20 20   that have.**   
16460 20 20 20 20 20 20 20 20 6e 6f 74 20 79 65 74 20          not yet 
16470 62 65 65 6e 20 72 65 6c 65 61 73 65 64 2e 0a 2a  been released..*
16480 2a 0a 2a 2a 20 7b 41 31 37 33 35 31 7d 20 20 54  *.** {A17351}  T
16490 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  he application m
164a0 75 73 74 20 6e 6f 74 20 72 65 61 64 20 6f 72 20  ust not read or 
164b0 77 72 69 74 65 20 61 6e 79 20 70 61 72 74 20 6f  write any part o
164c0 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 61  f.**           a
164d0 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72 79   block of memory
164e0 20 61 66 74 65 72 20 69 74 20 68 61 73 20 62 65   after it has be
164f0 65 6e 20 72 65 6c 65 61 73 65 64 20 75 73 69 6e  en released usin
16500 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 5b  g.**           [
16510 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20  sqlite3_free()] 
16520 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c  or [sqlite3_real
16530 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 76 6f 69 64 20  loc()]..*/.void 
16540 2a 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  *sqlite3_malloc(
16550 69 6e 74 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69  int);.void *sqli
16560 74 65 33 5f 72 65 61 6c 6c 6f 63 28 76 6f 69 64  te3_realloc(void
16570 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71  *, int);.void sq
16580 6c 69 74 65 33 5f 66 72 65 65 28 76 6f 69 64 2a  lite3_free(void*
16590 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
165a0 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63  EF: Memory Alloc
165b0 61 74 6f 72 20 53 74 61 74 69 73 74 69 63 73 20  ator Statistics 
165c0 7b 48 31 37 33 37 30 7d 20 3c 53 33 30 32 31 30  {H17370} <S30210
165d0 3e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 70  >.**.** SQLite p
165e0 72 6f 76 69 64 65 73 20 74 68 65 73 65 20 74 77  rovides these tw
165f0 6f 20 69 6e 74 65 72 66 61 63 65 73 20 66 6f 72  o interfaces for
16600 20 72 65 70 6f 72 74 69 6e 67 20 6f 6e 20 74 68   reporting on th
16610 65 20 73 74 61 74 75 73 0a 2a 2a 20 6f 66 20 74  e status.** of t
16620 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  he [sqlite3_mall
16630 6f 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  oc()], [sqlite3_
16640 66 72 65 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71  free()], and [sq
16650 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d  lite3_realloc()]
16660 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 2c 20 77 68  .** routines, wh
16670 69 63 68 20 66 6f 72 6d 20 74 68 65 20 62 75 69  ich form the bui
16680 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c  lt-in memory all
16690 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65  ocation subsyste
166a0 6d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  m..**.** INVARIA
166b0 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33  NTS:.**.** {H173
166c0 37 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  71} The [sqlite3
166d0 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20  _memory_used()] 
166e0 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
166f0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
16700 74 65 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  tes.**          
16710 6f 66 20 6d 65 6d 6f 72 79 20 63 75 72 72 65 6e  of memory curren
16720 74 6c 79 20 6f 75 74 73 74 61 6e 64 69 6e 67 20  tly outstanding 
16730 28 6d 61 6c 6c 6f 63 65 64 20 62 75 74 20 6e 6f  (malloced but no
16740 74 20 66 72 65 65 64 29 2e 0a 2a 2a 0a 2a 2a 20  t freed)..**.** 
16750 7b 48 31 37 33 37 33 7d 20 54 68 65 20 5b 73 71  {H17373} The [sq
16760 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67  lite3_memory_hig
16770 68 77 61 74 65 72 28 29 5d 20 72 6f 75 74 69 6e  hwater()] routin
16780 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6d 61  e returns the ma
16790 78 69 6d 75 6d 0a 2a 2a 20 20 20 20 20 20 20 20  ximum.**        
167a0 20 20 76 61 6c 75 65 20 6f 66 20 5b 73 71 6c 69    value of [sqli
167b0 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28  te3_memory_used(
167c0 29 5d 20 73 69 6e 63 65 20 74 68 65 20 68 69 67  )] since the hig
167d0 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20  h-water mark.** 
167e0 20 20 20 20 20 20 20 20 20 77 61 73 20 6c 61 73           was las
167f0 74 20 72 65 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 7b  t reset..**.** {
16800 48 31 37 33 37 34 7d 20 54 68 65 20 76 61 6c 75  H17374} The valu
16810 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b  es returned by [
16820 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75  sqlite3_memory_u
16830 73 65 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 20 20  sed()] and.**   
16840 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
16850 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72  memory_highwater
16860 28 29 5d 20 69 6e 63 6c 75 64 65 20 61 6e 79 20  ()] include any 
16870 6f 76 65 72 68 65 61 64 0a 2a 2a 20 20 20 20 20  overhead.**     
16880 20 20 20 20 20 61 64 64 65 64 20 62 79 20 53 51       added by SQ
16890 4c 69 74 65 20 69 6e 20 69 74 73 20 69 6d 70 6c  Lite in its impl
168a0 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 73  ementation of [s
168b0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
168c0 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 75  ,.**          bu
168d0 74 20 6e 6f 74 20 6f 76 65 72 68 65 61 64 20 61  t not overhead a
168e0 64 64 65 64 20 62 79 20 74 68 65 20 61 6e 79 20  dded by the any 
168f0 75 6e 64 65 72 6c 79 69 6e 67 20 73 79 73 74 65  underlying syste
16900 6d 20 6c 69 62 72 61 72 79 0a 2a 2a 20 20 20 20  m library.**    
16910 20 20 20 20 20 20 72 6f 75 74 69 6e 65 73 20 74        routines t
16920 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  hat [sqlite3_mal
16930 6c 6f 63 28 29 5d 20 6d 61 79 20 63 61 6c 6c 2e  loc()] may call.
16940 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33 37 35 7d 20  .**.** {H17375} 
16950 54 68 65 20 6d 65 6d 6f 72 79 20 68 69 67 68 2d  The memory high-
16960 77 61 74 65 72 20 6d 61 72 6b 20 69 73 20 72 65  water mark is re
16970 73 65 74 20 74 6f 20 74 68 65 20 63 75 72 72 65  set to the curre
16980 6e 74 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 20  nt value of.**  
16990 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
169a0 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20  _memory_used()] 
169b0 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74  if and only if t
169c0 68 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  he parameter to.
169d0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
169e0 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68  ite3_memory_high
169f0 77 61 74 65 72 28 29 5d 20 69 73 20 74 72 75 65  water()] is true
16a00 2e 20 20 54 68 65 20 76 61 6c 75 65 20 72 65 74  .  The value ret
16a10 75 72 6e 65 64 0a 2a 2a 20 20 20 20 20 20 20 20  urned.**        
16a20 20 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65    by [sqlite3_me
16a30 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 31  mory_highwater(1
16a40 29 5d 20 69 73 20 74 68 65 20 68 69 67 68 2d 77  )] is the high-w
16a50 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 20 20 20  ater mark.**    
16a60 20 20 20 20 20 20 70 72 69 6f 72 20 74 6f 20 74        prior to t
16a70 68 65 20 72 65 73 65 74 2e 0a 2a 2f 0a 73 71 6c  he reset..*/.sql
16a80 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74  ite3_int64 sqlit
16a90 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 76  e3_memory_used(v
16aa0 6f 69 64 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e  oid);.sqlite3_in
16ab0 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  t64 sqlite3_memo
16ac0 72 79 5f 68 69 67 68 77 61 74 65 72 28 69 6e 74  ry_highwater(int
16ad0 20 72 65 73 65 74 46 6c 61 67 29 3b 0a 0a 2f 2a   resetFlag);../*
16ae0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 50 73  .** CAPI3REF: Ps
16af0 65 75 64 6f 2d 52 61 6e 64 6f 6d 20 4e 75 6d 62  eudo-Random Numb
16b00 65 72 20 47 65 6e 65 72 61 74 6f 72 20 7b 48 31  er Generator {H1
16b10 37 33 39 30 7d 20 3c 53 32 30 30 30 30 3e 0a 2a  7390} <S20000>.*
16b20 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63 6f 6e 74  *.** SQLite cont
16b30 61 69 6e 73 20 61 20 68 69 67 68 2d 71 75 61 6c  ains a high-qual
16b40 69 74 79 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f  ity pseudo-rando
16b50 6d 20 6e 75 6d 62 65 72 20 67 65 6e 65 72 61 74  m number generat
16b60 6f 72 20 28 50 52 4e 47 29 20 75 73 65 64 20 74  or (PRNG) used t
16b70 6f 0a 2a 2a 20 73 65 6c 65 63 74 20 72 61 6e 64  o.** select rand
16b80 6f 6d 20 52 4f 57 49 44 73 20 77 68 65 6e 20 69  om ROWIDs when i
16b90 6e 73 65 72 74 69 6e 67 20 6e 65 77 20 72 65 63  nserting new rec
16ba0 6f 72 64 73 20 69 6e 74 6f 20 61 20 74 61 62 6c  ords into a tabl
16bb0 65 20 74 68 61 74 0a 2a 2a 20 61 6c 72 65 61 64  e that.** alread
16bc0 79 20 75 73 65 73 20 74 68 65 20 6c 61 72 67 65  y uses the large
16bd0 73 74 20 70 6f 73 73 69 62 6c 65 20 52 4f 57 49  st possible ROWI
16be0 44 2e 20 20 54 68 65 20 50 52 4e 47 20 69 73 20  D.  The PRNG is 
16bf0 61 6c 73 6f 20 75 73 65 64 20 66 6f 72 0a 2a 2a  also used for.**
16c00 20 74 68 65 20 62 75 69 6c 64 2d 69 6e 20 72 61   the build-in ra
16c10 6e 64 6f 6d 28 29 20 61 6e 64 20 72 61 6e 64 6f  ndom() and rando
16c20 6d 62 6c 6f 62 28 29 20 53 51 4c 20 66 75 6e 63  mblob() SQL func
16c30 74 69 6f 6e 73 2e 20 20 54 68 69 73 20 69 6e 74  tions.  This int
16c40 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 0a 2a 2a  erface allows.**
16c50 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 6f   applications to
16c60 20 61 63 63 65 73 73 20 74 68 65 20 73 61 6d 65   access the same
16c70 20 50 52 4e 47 20 66 6f 72 20 6f 74 68 65 72 20   PRNG for other 
16c80 70 75 72 70 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a 20  purposes..**.** 
16c90 41 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20 72  A call to this r
16ca0 6f 75 74 69 6e 65 20 73 74 6f 72 65 73 20 4e 20  outine stores N 
16cb0 62 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e  bytes of randomn
16cc0 65 73 73 20 69 6e 74 6f 20 62 75 66 66 65 72 20  ess into buffer 
16cd0 50 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72  P..**.** The fir
16ce0 73 74 20 74 69 6d 65 20 74 68 69 73 20 72 6f 75  st time this rou
16cf0 74 69 6e 65 20 69 73 20 69 6e 76 6f 6b 65 64 20  tine is invoked 
16d00 28 65 69 74 68 65 72 20 69 6e 74 65 72 6e 61 6c  (either internal
16d10 6c 79 20 6f 72 20 62 79 0a 2a 2a 20 74 68 65 20  ly or by.** the 
16d20 61 70 70 6c 69 63 61 74 69 6f 6e 29 20 74 68 65  application) the
16d30 20 50 52 4e 47 20 69 73 20 73 65 65 64 65 64 20   PRNG is seeded 
16d40 75 73 69 6e 67 20 72 61 6e 64 6f 6d 6e 65 73 73  using randomness
16d50 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f   obtained.** fro
16d60 6d 20 74 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73  m the xRandomnes
16d70 73 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20  s method of the 
16d80 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33  default [sqlite3
16d90 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a  _vfs] object..**
16da0 20 4f 6e 20 61 6c 6c 20 73 75 62 73 65 71 75 65   On all subseque
16db0 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e 73 2c 20  nt invocations, 
16dc0 74 68 65 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f  the pseudo-rando
16dd0 6d 6e 65 73 73 20 69 73 20 67 65 6e 65 72 61 74  mness is generat
16de0 65 64 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 6c 79  ed.** internally
16df0 20 61 6e 64 20 77 69 74 68 6f 75 74 20 72 65 63   and without rec
16e00 6f 75 72 73 65 20 74 6f 20 74 68 65 20 5b 73 71  ourse to the [sq
16e10 6c 69 74 65 33 5f 76 66 73 5d 20 78 52 61 6e 64  lite3_vfs] xRand
16e20 6f 6d 6e 65 73 73 0a 2a 2a 20 6d 65 74 68 6f 64  omness.** method
16e30 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  ..**.** INVARIAN
16e40 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33 39  TS:.**.** {H1739
16e50 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  2} The [sqlite3_
16e60 72 61 6e 64 6f 6d 6e 65 73 73 28 4e 2c 50 29 5d  randomness(N,P)]
16e70 20 69 6e 74 65 72 66 61 63 65 20 77 72 69 74 65   interface write
16e80 73 20 4e 20 62 79 74 65 73 20 6f 66 0a 2a 2a 20  s N bytes of.** 
16e90 20 20 20 20 20 20 20 20 20 68 69 67 68 2d 71 75           high-qu
16ea0 61 6c 69 74 79 20 70 73 65 75 64 6f 2d 72 61 6e  ality pseudo-ran
16eb0 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 62 75 66  domness into buf
16ec0 66 65 72 20 50 2e 0a 2a 2f 0a 76 6f 69 64 20 73  fer P..*/.void s
16ed0 71 6c 69 74 65 33 5f 72 61 6e 64 6f 6d 6e 65 73  qlite3_randomnes
16ee0 73 28 69 6e 74 20 4e 2c 20 76 6f 69 64 20 2a 50  s(int N, void *P
16ef0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
16f00 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d 65  EF: Compile-Time
16f10 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 43   Authorization C
16f20 61 6c 6c 62 61 63 6b 73 20 7b 48 31 32 35 30 30  allbacks {H12500
16f30 7d 20 3c 53 37 30 31 30 30 3e 0a 2a 2a 0a 2a 2a  } <S70100>.**.**
16f40 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65   This routine re
16f50 67 69 73 74 65 72 73 20 61 20 61 75 74 68 6f 72  gisters a author
16f60 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 77 69  izer callback wi
16f70 74 68 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a  th a particular.
16f80 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
16f90 6e 65 63 74 69 6f 6e 5d 2c 20 73 75 70 70 6c 69  nection], suppli
16fa0 65 64 20 69 6e 20 74 68 65 20 66 69 72 73 74 20  ed in the first 
16fb0 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65  argument..** The
16fc0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
16fd0 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20  back is invoked 
16fe0 61 73 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  as SQL statement
16ff0 73 20 61 72 65 20 62 65 69 6e 67 20 63 6f 6d 70  s are being comp
17000 69 6c 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69  iled.** by [sqli
17010 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f  te3_prepare()] o
17020 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 20 5b  r its variants [
17030 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
17040 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  v2()],.** [sqlit
17050 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20  e3_prepare16()] 
17060 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  and [sqlite3_pre
17070 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 20 20 41  pare16_v2()].  A
17080 74 20 76 61 72 69 6f 75 73 0a 2a 2a 20 70 6f 69  t various.** poi
17090 6e 74 73 20 64 75 72 69 6e 67 20 74 68 65 20 63  nts during the c
170a0 6f 6d 70 69 6c 61 74 69 6f 6e 20 70 72 6f 63 65  ompilation proce
170b0 73 73 2c 20 61 73 20 6c 6f 67 69 63 20 69 73 20  ss, as logic is 
170c0 62 65 69 6e 67 20 63 72 65 61 74 65 64 0a 2a 2a  being created.**
170d0 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69   to perform vari
170e0 6f 75 73 20 61 63 74 69 6f 6e 73 2c 20 74 68 65  ous actions, the
170f0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
17100 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20  back is invoked 
17110 74 6f 0a 2a 2a 20 73 65 65 20 69 66 20 74 68 6f  to.** see if tho
17120 73 65 20 61 63 74 69 6f 6e 73 20 61 72 65 20 61  se actions are a
17130 6c 6c 6f 77 65 64 2e 20 20 54 68 65 20 61 75 74  llowed.  The aut
17140 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
17150 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72   should.** retur
17160 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 74 6f  n [SQLITE_OK] to
17170 20 61 6c 6c 6f 77 20 74 68 65 20 61 63 74 69 6f   allow the actio
17180 6e 2c 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52  n, [SQLITE_IGNOR
17190 45 5d 20 74 6f 20 64 69 73 61 6c 6c 6f 77 20 74  E] to disallow t
171a0 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 61  he.** specific a
171b0 63 74 69 6f 6e 20 62 75 74 20 61 6c 6c 6f 77 20  ction but allow 
171c0 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
171d0 74 20 74 6f 20 63 6f 6e 74 69 6e 75 65 20 74 6f  t to continue to
171e0 20 62 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 2c   be.** compiled,
171f0 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59   or [SQLITE_DENY
17200 5d 20 74 6f 20 63 61 75 73 65 20 74 68 65 20 65  ] to cause the e
17210 6e 74 69 72 65 20 53 51 4c 20 73 74 61 74 65 6d  ntire SQL statem
17220 65 6e 74 20 74 6f 20 62 65 0a 2a 2a 20 72 65 6a  ent to be.** rej
17230 65 63 74 65 64 20 77 69 74 68 20 61 6e 20 65 72  ected with an er
17240 72 6f 72 2e 20 20 49 66 20 74 68 65 20 61 75 74  ror.  If the aut
17250 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
17260 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20   returns.** any 
17270 76 61 6c 75 65 20 6f 74 68 65 72 20 74 68 61 6e  value other than
17280 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d   [SQLITE_IGNORE]
17290 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 6f  , [SQLITE_OK], o
172a0 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 0a  r [SQLITE_DENY].
172b0 2a 2a 20 74 68 65 6e 20 74 68 65 20 5b 73 71 6c  ** then the [sql
172c0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
172d0 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74  )] or equivalent
172e0 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67   call that trigg
172f0 65 72 65 64 0a 2a 2a 20 74 68 65 20 61 75 74 68  ered.** the auth
17300 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c  orizer will fail
17310 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 6d   with an error m
17320 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 57 68  essage..**.** Wh
17330 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  en the callback 
17340 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
17350 4f 4b 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73 20  OK], that means 
17360 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a  the operation.**
17370 20 72 65 71 75 65 73 74 65 64 20 69 73 20 6f 6b   requested is ok
17380 2e 20 20 57 68 65 6e 20 74 68 65 20 63 61 6c 6c  .  When the call
17390 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51  back returns [SQ
173a0 4c 49 54 45 5f 44 45 4e 59 5d 2c 20 74 68 65 0a  LITE_DENY], the.
173b0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
173c0 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75  are_v2()] or equ
173d0 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61  ivalent call tha
173e0 74 20 74 72 69 67 67 65 72 65 64 20 74 68 65 0a  t triggered the.
173f0 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 77 69  ** authorizer wi
17400 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20  ll fail with an 
17410 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 65 78  error message ex
17420 70 6c 61 69 6e 69 6e 67 20 74 68 61 74 0a 2a 2a  plaining that.**
17430 20 61 63 63 65 73 73 20 69 73 20 64 65 6e 69 65   access is denie
17440 64 2e 20 20 49 66 20 74 68 65 20 61 75 74 68 6f  d.  If the autho
17450 72 69 7a 65 72 20 63 6f 64 65 20 69 73 20 5b 53  rizer code is [S
17460 51 4c 49 54 45 5f 52 45 41 44 5d 0a 2a 2a 20 61  QLITE_READ].** a
17470 6e 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  nd the callback 
17480 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
17490 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65  IGNORE] then the
174a0 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
174b0 61 74 65 6d 65 6e 74 5d 20 73 74 61 74 65 6d 65  atement] stateme
174c0 6e 74 20 69 73 20 63 6f 6e 73 74 72 75 63 74 65  nt is constructe
174d0 64 20 74 6f 20 73 75 62 73 74 69 74 75 74 65 0a  d to substitute.
174e0 2a 2a 20 61 20 4e 55 4c 4c 20 76 61 6c 75 65 20  ** a NULL value 
174f0 69 6e 20 70 6c 61 63 65 20 6f 66 20 74 68 65 20  in place of the 
17500 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61  table column tha
17510 74 20 77 6f 75 6c 64 20 68 61 76 65 0a 2a 2a 20  t would have.** 
17520 62 65 65 6e 20 72 65 61 64 20 69 66 20 5b 53 51  been read if [SQ
17530 4c 49 54 45 5f 4f 4b 5d 20 68 61 64 20 62 65 65  LITE_OK] had bee
17540 6e 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65  n returned.  The
17550 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d   [SQLITE_IGNORE]
17560 0a 2a 2a 20 72 65 74 75 72 6e 20 63 61 6e 20 62  .** return can b
17570 65 20 75 73 65 64 20 74 6f 20 64 65 6e 79 20 61  e used to deny a
17580 6e 20 75 6e 74 72 75 73 74 65 64 20 75 73 65 72  n untrusted user
17590 20 61 63 63 65 73 73 20 74 6f 20 69 6e 64 69 76   access to indiv
175a0 69 64 75 61 6c 0a 2a 2a 20 63 6f 6c 75 6d 6e 73  idual.** columns
175b0 20 6f 66 20 61 20 74 61 62 6c 65 2e 0a 2a 2a 0a   of a table..**.
175c0 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 61 72  ** The first par
175d0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 75  ameter to the au
175e0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
175f0 6b 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74  k is a copy of t
17600 68 65 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 61  he third.** para
17610 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c  meter to the sql
17620 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
17630 7a 65 72 28 29 20 69 6e 74 65 72 66 61 63 65 2e  zer() interface.
17640 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   The second para
17650 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20  meter.** to the 
17660 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69  callback is an i
17670 6e 74 65 67 65 72 20 5b 53 51 4c 49 54 45 5f 43  nteger [SQLITE_C
17680 4f 50 59 20 7c 20 61 63 74 69 6f 6e 20 63 6f 64  OPY | action cod
17690 65 5d 20 74 68 61 74 20 73 70 65 63 69 66 69 65  e] that specifie
176a0 73 0a 2a 2a 20 74 68 65 20 70 61 72 74 69 63 75  s.** the particu
176b0 6c 61 72 20 61 63 74 69 6f 6e 20 74 6f 20 62 65  lar action to be
176c0 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 54 68 65   authorized. The
176d0 20 74 68 69 72 64 20 74 68 72 6f 75 67 68 20 73   third through s
176e0 69 78 74 68 20 70 61 72 61 6d 65 74 65 72 73 0a  ixth parameters.
176f0 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61  ** to the callba
17700 63 6b 20 61 72 65 20 7a 65 72 6f 2d 74 65 72 6d  ck are zero-term
17710 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20 74  inated strings t
17720 68 61 74 20 63 6f 6e 74 61 69 6e 20 61 64 64 69  hat contain addi
17730 74 69 6f 6e 61 6c 0a 2a 2a 20 64 65 74 61 69 6c  tional.** detail
17740 73 20 61 62 6f 75 74 20 74 68 65 20 61 63 74 69  s about the acti
17750 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69  on to be authori
17760 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75  zed..**.** An au
17770 74 68 6f 72 69 7a 65 72 20 69 73 20 75 73 65 64  thorizer is used
17780 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70   when [sqlite3_p
17790 72 65 70 61 72 65 20 7c 20 70 72 65 70 61 72 69  repare | prepari
177a0 6e 67 5d 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65  ng].** SQL state
177b0 6d 65 6e 74 73 20 66 72 6f 6d 20 61 6e 20 75 6e  ments from an un
177c0 74 72 75 73 74 65 64 20 73 6f 75 72 63 65 2c 20  trusted source, 
177d0 74 6f 20 65 6e 73 75 72 65 20 74 68 61 74 20 74  to ensure that t
177e0 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
177f0 73 0a 2a 2a 20 64 6f 20 6e 6f 74 20 74 72 79 20  s.** do not try 
17800 74 6f 20 61 63 63 65 73 73 20 64 61 74 61 20 74  to access data t
17810 68 65 79 20 61 72 65 20 6e 6f 74 20 61 6c 6c 6f  hey are not allo
17820 77 65 64 20 74 6f 20 73 65 65 2c 20 6f 72 20 74  wed to see, or t
17830 68 61 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a  hat they do not.
17840 2a 2a 20 74 72 79 20 74 6f 20 65 78 65 63 75 74  ** try to execut
17850 65 20 6d 61 6c 69 63 69 6f 75 73 20 73 74 61 74  e malicious stat
17860 65 6d 65 6e 74 73 20 74 68 61 74 20 64 61 6d 61  ements that dama
17870 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65 2e  ge the database.
17880 20 20 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65    For.** example
17890 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  , an application
178a0 20 6d 61 79 20 61 6c 6c 6f 77 20 61 20 75 73 65   may allow a use
178b0 72 20 74 6f 20 65 6e 74 65 72 20 61 72 62 69 74  r to enter arbit
178c0 72 61 72 79 0a 2a 2a 20 53 51 4c 20 71 75 65 72  rary.** SQL quer
178d0 69 65 73 20 66 6f 72 20 65 76 61 6c 75 61 74 69  ies for evaluati
178e0 6f 6e 20 62 79 20 61 20 64 61 74 61 62 61 73 65  on by a database
178f0 2e 20 20 42 75 74 20 74 68 65 20 61 70 70 6c 69  .  But the appli
17900 63 61 74 69 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e  cation does.** n
17910 6f 74 20 77 61 6e 74 20 74 68 65 20 75 73 65 72  ot want the user
17920 20 74 6f 20 62 65 20 61 62 6c 65 20 74 6f 20 6d   to be able to m
17930 61 6b 65 20 61 72 62 69 74 72 61 72 79 20 63 68  ake arbitrary ch
17940 61 6e 67 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20  anges to the.** 
17950 64 61 74 61 62 61 73 65 2e 20 20 41 6e 20 61 75  database.  An au
17960 74 68 6f 72 69 7a 65 72 20 63 6f 75 6c 64 20 74  thorizer could t
17970 68 65 6e 20 62 65 20 70 75 74 20 69 6e 20 70 6c  hen be put in pl
17980 61 63 65 20 77 68 69 6c 65 20 74 68 65 0a 2a 2a  ace while the.**
17990 20 75 73 65 72 2d 65 6e 74 65 72 65 64 20 53 51   user-entered SQ
179a0 4c 20 69 73 20 62 65 69 6e 67 20 5b 73 71 6c 69  L is being [sqli
179b0 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72  te3_prepare | pr
179c0 65 70 61 72 65 64 5d 20 74 68 61 74 0a 2a 2a 20  epared] that.** 
179d0 64 69 73 61 6c 6c 6f 77 73 20 65 76 65 72 79 74  disallows everyt
179e0 68 69 6e 67 20 65 78 63 65 70 74 20 5b 53 45 4c  hing except [SEL
179f0 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e  ECT] statements.
17a00 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69  .**.** Applicati
17a10 6f 6e 73 20 74 68 61 74 20 6e 65 65 64 20 74 6f  ons that need to
17a20 20 70 72 6f 63 65 73 73 20 53 51 4c 20 66 72 6f   process SQL fro
17a30 6d 20 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72  m untrusted sour
17a40 63 65 73 0a 2a 2a 20 6d 69 67 68 74 20 61 6c 73  ces.** might als
17a50 6f 20 63 6f 6e 73 69 64 65 72 20 6c 6f 77 65 72  o consider lower
17a60 69 6e 67 20 72 65 73 6f 75 72 63 65 20 6c 69 6d  ing resource lim
17a70 69 74 73 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  its using [sqlit
17a80 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 61  e3_limit()].** a
17a90 6e 64 20 6c 69 6d 69 74 69 6e 67 20 64 61 74 61  nd limiting data
17aa0 62 61 73 65 20 73 69 7a 65 20 75 73 69 6e 67 20  base size using 
17ab0 74 68 65 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f  the [max_page_co
17ac0 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 0a 2a 2a  unt] [PRAGMA].**
17ad0 20 69 6e 20 61 64 64 69 74 69 6f 6e 20 74 6f 20   in addition to 
17ae0 75 73 69 6e 67 20 61 6e 20 61 75 74 68 6f 72 69  using an authori
17af0 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 4f 6e 6c 79 20  zer..**.** Only 
17b00 61 20 73 69 6e 67 6c 65 20 61 75 74 68 6f 72 69  a single authori
17b10 7a 65 72 20 63 61 6e 20 62 65 20 69 6e 20 70 6c  zer can be in pl
17b20 61 63 65 20 6f 6e 20 61 20 64 61 74 61 62 61 73  ace on a databas
17b30 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20  e connection.** 
17b40 61 74 20 61 20 74 69 6d 65 2e 20 20 45 61 63 68  at a time.  Each
17b50 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
17b60 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20  _set_authorizer 
17b70 6f 76 65 72 72 69 64 65 73 20 74 68 65 0a 2a 2a  overrides the.**
17b80 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 2e 20   previous call. 
17b90 20 44 69 73 61 62 6c 65 20 74 68 65 20 61 75 74   Disable the aut
17ba0 68 6f 72 69 7a 65 72 20 62 79 20 69 6e 73 74 61  horizer by insta
17bb0 6c 6c 69 6e 67 20 61 20 4e 55 4c 4c 20 63 61 6c  lling a NULL cal
17bc0 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68 65 20 61 75  lback..** The au
17bd0 74 68 6f 72 69 7a 65 72 20 69 73 20 64 69 73 61  thorizer is disa
17be0 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e  bled by default.
17bf0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f  .**.** The autho
17c00 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d  rizer callback m
17c10 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68  ust not do anyth
17c20 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f  ing that will mo
17c30 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61  dify.** the data
17c40 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
17c50 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65  that invoked the
17c60 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
17c70 62 61 63 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68  back..** Note th
17c80 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  at [sqlite3_prep
17c90 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73  are_v2()] and [s
17ca0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62  qlite3_step()] b
17cb0 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72  oth modify their
17cc0 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e  .** database con
17cd0 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65  nections for the
17ce0 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64   meaning of "mod
17cf0 69 66 79 22 20 69 6e 20 74 68 69 73 20 70 61 72  ify" in this par
17d00 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 57 68  agraph..**.** Wh
17d10 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  en [sqlite3_prep
17d20 61 72 65 5f 76 32 28 29 5d 20 69 73 20 75 73 65  are_v2()] is use
17d30 64 20 74 6f 20 70 72 65 70 61 72 65 20 61 20 73  d to prepare a s
17d40 74 61 74 65 6d 65 6e 74 2c 20 74 68 65 0a 2a 2a  tatement, the.**
17d50 20 73 74 61 74 65 6d 65 6e 74 20 6d 69 67 68 74   statement might
17d60 20 62 65 20 72 65 70 72 65 70 61 72 65 64 20 64   be reprepared d
17d70 75 72 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73  uring [sqlite3_s
17d80 74 65 70 28 29 5d 20 64 75 65 20 74 6f 20 61 20  tep()] due to a 
17d90 0a 2a 2a 20 73 63 68 65 6d 61 20 63 68 61 6e 67  .** schema chang
17da0 65 2e 20 20 48 65 6e 63 65 2c 20 74 68 65 20 61  e.  Hence, the a
17db0 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c  pplication shoul
17dc0 64 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68  d ensure that th
17dd0 65 0a 2a 2a 20 63 6f 72 72 65 63 74 20 61 75 74  e.** correct aut
17de0 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
17df0 20 72 65 6d 61 69 6e 73 20 69 6e 20 70 6c 61 63   remains in plac
17e00 65 20 64 75 72 69 6e 67 20 74 68 65 20 5b 73 71  e during the [sq
17e10 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a  lite3_step()]..*
17e20 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 74  *.** Note that t
17e30 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
17e40 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
17e50 64 20 6f 6e 6c 79 20 64 75 72 69 6e 67 0a 2a 2a  d only during.**
17e60 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
17e70 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69  e()] or its vari
17e80 61 6e 74 73 2e 20 20 41 75 74 68 6f 72 69 7a 61  ants.  Authoriza
17e90 74 69 6f 6e 20 69 73 20 6e 6f 74 0a 2a 2a 20 70  tion is not.** p
17ea0 65 72 66 6f 72 6d 65 64 20 64 75 72 69 6e 67 20  erformed during 
17eb0 73 74 61 74 65 6d 65 6e 74 20 65 76 61 6c 75 61  statement evalua
17ec0 74 69 6f 6e 20 69 6e 20 5b 73 71 6c 69 74 65 33  tion in [sqlite3
17ed0 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  _step()]..**.** 
17ee0 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
17ef0 2a 20 7b 48 31 32 35 30 31 7d 20 54 68 65 20 5b  * {H12501} The [
17f00 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
17f10 6f 72 69 7a 65 72 28 44 2c 2e 2e 2e 29 5d 20 69  orizer(D,...)] i
17f20 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65  nterface registe
17f30 72 73 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 20  rs a.**         
17f40 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
17f50 62 61 63 6b 20 77 69 74 68 20 64 61 74 61 62 61  back with databa
17f60 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e  se connection D.
17f70 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 30 32 7d 20  .**.** {H12502} 
17f80 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  The authorizer c
17f90 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
17fa0 65 64 20 61 73 20 53 51 4c 20 73 74 61 74 65 6d  ed as SQL statem
17fb0 65 6e 74 73 20 61 72 65 0a 2a 2a 20 20 20 20 20  ents are.**     
17fc0 20 20 20 20 20 62 65 69 6e 67 20 70 61 72 73 65       being parse
17fd0 65 64 20 61 6e 64 20 63 6f 6d 70 69 6c 65 64 2e  ed and compiled.
17fe0 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 30 33 7d 20  .**.** {H12503} 
17ff0 49 66 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  If the authorize
18000 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  r callback retur
18010 6e 73 20 61 6e 79 20 76 61 6c 75 65 20 6f 74 68  ns any value oth
18020 65 72 20 74 68 61 6e 0a 2a 2a 20 20 20 20 20 20  er than.**      
18030 20 20 20 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f      [SQLITE_IGNO
18040 52 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  RE], [SQLITE_OK]
18050 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e  , or [SQLITE_DEN
18060 59 5d 2c 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20  Y], then.**     
18070 20 20 20 20 20 74 68 65 20 61 70 70 6c 69 63 61       the applica
18080 74 69 6f 6e 20 69 6e 74 65 72 66 61 63 65 20 63  tion interface c
18090 61 6c 6c 20 74 68 61 74 20 63 61 75 73 65 64 0a  all that caused.
180a0 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
180b0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
180c0 61 63 6b 20 74 6f 20 72 75 6e 20 73 68 61 6c 6c  ack to run shall
180d0 20 66 61 69 6c 20 77 69 74 68 20 61 6e 0a 2a 2a   fail with an.**
180e0 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54            [SQLIT
180f0 45 5f 45 52 52 4f 52 5d 20 65 72 72 6f 72 20 63  E_ERROR] error c
18100 6f 64 65 20 61 6e 64 20 61 6e 20 61 70 70 72 6f  ode and an appro
18110 70 72 69 61 74 65 20 65 72 72 6f 72 20 6d 65 73  priate error mes
18120 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  sage..**.** {H12
18130 35 30 34 7d 20 57 68 65 6e 20 74 68 65 20 61 75  504} When the au
18140 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
18150 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  k returns [SQLIT
18160 45 5f 4f 4b 5d 2c 20 74 68 65 20 6f 70 65 72 61  E_OK], the opera
18170 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  tion.**         
18180 20 64 65 73 63 72 69 62 65 64 20 69 73 20 70 72   described is pr
18190 6f 63 65 73 73 65 64 20 6e 6f 72 6d 61 6c 6c 79  ocessed normally
181a0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 30 35 7d  ..**.** {H12505}
181b0 20 57 68 65 6e 20 74 68 65 20 61 75 74 68 6f 72   When the author
181c0 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65  izer callback re
181d0 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 44 45  turns [SQLITE_DE
181e0 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20 20 20 20 20  NY], the.**     
181f0 20 20 20 20 20 61 70 70 6c 69 63 61 74 69 6f 6e       application
18200 20 69 6e 74 65 72 66 61 63 65 20 63 61 6c 6c 20   interface call 
18210 74 68 61 74 20 63 61 75 73 65 64 20 74 68 65 0a  that caused the.
18220 2a 2a 20 20 20 20 20 20 20 20 20 20 61 75 74 68  **          auth
18230 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
18240 74 6f 20 72 75 6e 20 73 68 61 6c 6c 20 66 61 69  to run shall fai
18250 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 69  l.**          wi
18260 74 68 20 61 6e 20 5b 53 51 4c 49 54 45 5f 45 52  th an [SQLITE_ER
18270 52 4f 52 5d 20 65 72 72 6f 72 20 63 6f 64 65 20  ROR] error code 
18280 61 6e 64 20 61 6e 20 65 72 72 6f 72 20 6d 65 73  and an error mes
18290 73 61 67 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  sage.**         
182a0 20 65 78 70 6c 61 69 6e 69 6e 67 20 74 68 61 74   explaining that
182b0 20 61 63 63 65 73 73 20 69 73 20 64 65 6e 69 65   access is denie
182c0 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 30 36  d..**.** {H12506
182d0 7d 20 49 66 20 74 68 65 20 61 75 74 68 6f 72 69  } If the authori
182e0 7a 65 72 20 63 6f 64 65 20 28 74 68 65 20 32 6e  zer code (the 2n
182f0 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  d parameter to t
18300 68 65 20 61 75 74 68 6f 72 69 7a 65 72 0a 2a 2a  he authorizer.**
18310 20 20 20 20 20 20 20 20 20 20 63 61 6c 6c 62 61            callba
18320 63 6b 29 20 69 73 20 5b 53 51 4c 49 54 45 5f 52  ck) is [SQLITE_R
18330 45 41 44 5d 20 61 6e 64 20 74 68 65 20 61 75 74  EAD] and the aut
18340 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
18350 20 72 65 74 75 72 6e 73 0a 2a 2a 20 20 20 20 20   returns.**     
18360 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 49 47 4e       [SQLITE_IGN
18370 4f 52 45 5d 2c 20 74 68 65 6e 20 74 68 65 20 70  ORE], then the p
18380 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
18390 74 20 69 73 20 63 6f 6e 73 74 72 75 63 74 65 64  t is constructed
183a0 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   to.**          
183b0 69 6e 73 65 72 74 20 61 20 4e 55 4c 4c 20 76 61  insert a NULL va
183c0 6c 75 65 20 69 6e 20 70 6c 61 63 65 20 6f 66 20  lue in place of 
183d0 74 68 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e  the table column
183e0 20 74 68 61 74 20 77 6f 75 6c 64 20 68 61 76 65   that would have
183f0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 65 65  .**          bee
18400 6e 20 72 65 61 64 20 69 66 20 5b 53 51 4c 49 54  n read if [SQLIT
18410 45 5f 4f 4b 5d 20 68 61 64 20 62 65 65 6e 20 72  E_OK] had been r
18420 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b  eturned..**.** {
18430 48 31 32 35 30 37 7d 20 49 66 20 74 68 65 20 61  H12507} If the a
18440 75 74 68 6f 72 69 7a 65 72 20 63 6f 64 65 20 28  uthorizer code (
18450 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65  the 2nd paramete
18460 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69  r to the authori
18470 7a 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  zer.**          
18480 63 61 6c 6c 62 61 63 6b 29 20 69 73 20 61 6e 79  callback) is any
18490 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61 6e  thing other than
184a0 20 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d 2c 20   [SQLITE_READ], 
184b0 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  then.**         
184c0 20 61 20 72 65 74 75 72 6e 20 6f 66 20 5b 53 51   a return of [SQ
184d0 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 68 61 73  LITE_IGNORE] has
184e0 20 74 68 65 20 73 61 6d 65 20 65 66 66 65 63 74   the same effect
184f0 20 61 73 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59   as [SQLITE_DENY
18500 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 31 30  ]..**.** {H12510
18510 7d 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61  } The first para
18520 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 75 74  meter to the aut
18530 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
18540 20 69 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a   is a copy of.**
18550 20 20 20 20 20 20 20 20 20 20 74 68 65 20 74 68            the th
18560 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ird parameter to
18570 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65   the [sqlite3_se
18580 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 20  t_authorizer()] 
18590 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a  interface..**.**
185a0 20 7b 48 31 32 35 31 31 7d 20 54 68 65 20 73 65   {H12511} The se
185b0 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74  cond parameter t
185c0 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69  o the callback i
185d0 73 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20  s an integer.** 
185e0 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45           [SQLITE
185f0 5f 43 4f 50 59 20 7c 20 61 63 74 69 6f 6e 20 63  _COPY | action c
18600 6f 64 65 5d 20 74 68 61 74 20 73 70 65 63 69 66  ode] that specif
18610 69 65 73 20 74 68 65 20 70 61 72 74 69 63 75 6c  ies the particul
18620 61 72 20 61 63 74 69 6f 6e 0a 2a 2a 20 20 20 20  ar action.**    
18630 20 20 20 20 20 20 74 6f 20 62 65 20 61 75 74 68        to be auth
18640 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48  orized..**.** {H
18650 31 32 35 31 32 7d 20 54 68 65 20 74 68 69 72 64  12512} The third
18660 20 74 68 72 6f 75 67 68 20 73 69 78 74 68 20 70   through sixth p
18670 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68 65  arameters to the
18680 20 63 61 6c 6c 62 61 63 6b 20 61 72 65 0a 2a 2a   callback are.**
18690 20 20 20 20 20 20 20 20 20 20 7a 65 72 6f 2d 74            zero-t
186a0 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67  erminated string
186b0 73 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 0a 2a  s that contain.*
186c0 2a 20 20 20 20 20 20 20 20 20 20 61 64 64 69 74  *          addit
186d0 69 6f 6e 61 6c 20 64 65 74 61 69 6c 73 20 61 62  ional details ab
186e0 6f 75 74 20 74 68 65 20 61 63 74 69 6f 6e 20 74  out the action t
186f0 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e  o be authorized.
18700 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 32 30 7d 20  .**.** {H12520} 
18710 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 5b 73 71  Each call to [sq
18720 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
18730 69 7a 65 72 28 29 5d 20 6f 76 65 72 72 69 64 65  izer()] override
18740 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6e  s.**          an
18750 79 20 70 72 65 76 69 6f 75 73 6c 79 20 69 6e 73  y previously ins
18760 74 61 6c 6c 65 64 20 61 75 74 68 6f 72 69 7a 65  talled authorize
18770 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 32 31  r..**.** {H12521
18780 7d 20 41 20 4e 55 4c 4c 20 61 75 74 68 6f 72 69  } A NULL authori
18790 7a 65 72 20 6d 65 61 6e 73 20 74 68 61 74 20 6e  zer means that n
187a0 6f 20 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e 0a  o authorization.
187b0 2a 2a 20 20 20 20 20 20 20 20 20 20 63 61 6c 6c  **          call
187c0 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2e  back is invoked.
187d0 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 32 32 7d 20  .**.** {H12522} 
187e0 54 68 65 20 64 65 66 61 75 6c 74 20 61 75 74 68  The default auth
187f0 6f 72 69 7a 65 72 20 69 73 20 4e 55 4c 4c 2e 0a  orizer is NULL..
18800 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73  */.int sqlite3_s
18810 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 0a 20  et_authorizer(. 
18820 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20 69 6e 74   sqlite3*,.  int
18830 20 28 2a 78 41 75 74 68 29 28 76 6f 69 64 2a 2c   (*xAuth)(void*,
18840 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c  int,const char*,
18850 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73  const char*,cons
18860 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68  t char*,const ch
18870 61 72 2a 29 2c 0a 20 20 76 6f 69 64 20 2a 70 55  ar*),.  void *pU
18880 73 65 72 44 61 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a  serData.);../*.*
18890 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75 74 68  * CAPI3REF: Auth
188a0 6f 72 69 7a 65 72 20 52 65 74 75 72 6e 20 43 6f  orizer Return Co
188b0 64 65 73 20 7b 48 31 32 35 39 30 7d 20 3c 48 31  des {H12590} <H1
188c0 32 35 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  2500>.**.** The 
188d0 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74  [sqlite3_set_aut
188e0 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72  horizer | author
188f0 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75  izer callback fu
18900 6e 63 74 69 6f 6e 5d 20 6d 75 73 74 0a 2a 2a 20  nction] must.** 
18910 72 65 74 75 72 6e 20 65 69 74 68 65 72 20 5b 53  return either [S
18920 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 6f 6e 65  QLITE_OK] or one
18930 20 6f 66 20 74 68 65 73 65 20 74 77 6f 20 63 6f   of these two co
18940 6e 73 74 61 6e 74 73 20 69 6e 20 6f 72 64 65 72  nstants in order
18950 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c 20 53 51  .** to signal SQ
18960 4c 69 74 65 20 77 68 65 74 68 65 72 20 6f 72 20  Lite whether or 
18970 6e 6f 74 20 74 68 65 20 61 63 74 69 6f 6e 20 69  not the action i
18980 73 20 70 65 72 6d 69 74 74 65 64 2e 20 20 53 65  s permitted.  Se
18990 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  e the.** [sqlite
189a0 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
189b0 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 64 6f   | authorizer do
189c0 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72  cumentation] for
189d0 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69   additional.** i
189e0 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 23  nformation..*/.#
189f0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45  define SQLITE_DE
18a00 4e 59 20 20 20 31 20 20 20 2f 2a 20 41 62 6f 72  NY   1   /* Abor
18a10 74 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  t the SQL statem
18a20 65 6e 74 20 77 69 74 68 20 61 6e 20 65 72 72 6f  ent with an erro
18a30 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  r */.#define SQL
18a40 49 54 45 5f 49 47 4e 4f 52 45 20 32 20 20 20 2f  ITE_IGNORE 2   /
18a50 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f 77 20 61 63  * Don't allow ac
18a60 63 65 73 73 2c 20 62 75 74 20 64 6f 6e 27 74 20  cess, but don't 
18a70 67 65 6e 65 72 61 74 65 20 61 6e 20 65 72 72 6f  generate an erro
18a80 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  r */../*.** CAPI
18a90 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72  3REF: Authorizer
18aa0 20 41 63 74 69 6f 6e 20 43 6f 64 65 73 20 7b 48   Action Codes {H
18ab0 31 32 35 35 30 7d 20 3c 48 31 32 35 30 30 3e 0a  12550} <H12500>.
18ac0 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74  **.** The [sqlit
18ad0 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
18ae0 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  r()] interface r
18af0 65 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62  egisters a callb
18b00 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20  ack function.** 
18b10 74 68 61 74 20 69 73 20 69 6e 76 6f 6b 65 64 20  that is invoked 
18b20 74 6f 20 61 75 74 68 6f 72 69 7a 65 20 63 65 72  to authorize cer
18b30 74 61 69 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  tain SQL stateme
18b40 6e 74 20 61 63 74 69 6f 6e 73 2e 20 20 54 68 65  nt actions.  The
18b50 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  .** second param
18b60 65 74 65 72 20 74 6f 20 74 68 65 20 63 61 6c 6c  eter to the call
18b70 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67  back is an integ
18b80 65 72 20 63 6f 64 65 20 74 68 61 74 20 73 70 65  er code that spe
18b90 63 69 66 69 65 73 0a 2a 2a 20 77 68 61 74 20 61  cifies.** what a
18ba0 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 61  ction is being a
18bb0 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 73  uthorized.  Thes
18bc0 65 20 61 72 65 20 74 68 65 20 69 6e 74 65 67 65  e are the intege
18bd0 72 20 61 63 74 69 6f 6e 20 63 6f 64 65 73 20 74  r action codes t
18be0 68 61 74 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f  hat.** the autho
18bf0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d  rizer callback m
18c00 61 79 20 62 65 20 70 61 73 73 65 64 2e 0a 2a 2a  ay be passed..**
18c10 0a 2a 2a 20 54 68 65 73 65 20 61 63 74 69 6f 6e  .** These action
18c20 20 63 6f 64 65 20 76 61 6c 75 65 73 20 73 69 67   code values sig
18c30 6e 69 66 79 20 77 68 61 74 20 6b 69 6e 64 20 6f  nify what kind o
18c40 66 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 74  f operation is t
18c50 6f 20 62 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a  o be.** authoriz
18c60 65 64 2e 20 20 54 68 65 20 33 72 64 20 61 6e 64  ed.  The 3rd and
18c70 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 73 20   4th parameters 
18c80 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 61  to the authoriza
18c90 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b  tion.** callback
18ca0 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 62   function will b
18cb0 65 20 70 61 72 61 6d 65 74 65 72 73 20 6f 72 20  e parameters or 
18cc0 4e 55 4c 4c 20 64 65 70 65 6e 64 69 6e 67 20 6f  NULL depending o
18cd0 6e 20 77 68 69 63 68 20 6f 66 20 74 68 65 73 65  n which of these
18ce0 0a 2a 2a 20 63 6f 64 65 73 20 69 73 20 75 73 65  .** codes is use
18cf0 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20  d as the second 
18d00 70 61 72 61 6d 65 74 65 72 2e 20 20 54 68 65 20  parameter.  The 
18d10 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  5th parameter to
18d20 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a   the.** authoriz
18d30 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74  er callback is t
18d40 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64  he name of the d
18d50 61 74 61 62 61 73 65 20 28 22 6d 61 69 6e 22 2c  atabase ("main",
18d60 20 22 74 65 6d 70 22 2c 0a 2a 2a 20 65 74 63 2e   "temp",.** etc.
18d70 29 20 69 66 20 61 70 70 6c 69 63 61 62 6c 65 2e  ) if applicable.
18d80 20 20 54 68 65 20 36 74 68 20 70 61 72 61 6d 65    The 6th parame
18d90 74 65 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f  ter to the autho
18da0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 0a 2a  rizer callback.*
18db0 2a 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  * is the name of
18dc0 20 74 68 65 20 69 6e 6e 65 72 2d 6d 6f 73 74 20   the inner-most 
18dd0 74 72 69 67 67 65 72 20 6f 72 20 76 69 65 77 20  trigger or view 
18de0 74 68 61 74 20 69 73 20 72 65 73 70 6f 6e 73 69  that is responsi
18df0 62 6c 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61  ble for.** the a
18e00 63 63 65 73 73 20 61 74 74 65 6d 70 74 20 6f 72  ccess attempt or
18e10 20 4e 55 4c 4c 20 69 66 20 74 68 69 73 20 61 63   NULL if this ac
18e20 63 65 73 73 20 61 74 74 65 6d 70 74 20 69 73 20  cess attempt is 
18e30 64 69 72 65 63 74 6c 79 20 66 72 6f 6d 0a 2a 2a  directly from.**
18e40 20 74 6f 70 2d 6c 65 76 65 6c 20 53 51 4c 20 63   top-level SQL c
18e50 6f 64 65 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  ode..**.** INVAR
18e60 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31  IANTS:.**.** {H1
18e70 32 35 35 31 7d 20 54 68 65 20 73 65 63 6f 6e 64  2551} The second
18e80 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 61 6e   parameter to an
18e90 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
18ea0 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
18eb0 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65  izer | authorize
18ec0 72 20 63 61 6c 6c 62 61 63 6b 5d 20 73 68 61 6c  r callback] shal
18ed0 6c 20 62 65 20 61 6e 20 69 6e 74 65 67 65 72 0a  l be an integer.
18ee0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c  **          [SQL
18ef0 49 54 45 5f 43 4f 50 59 20 7c 20 61 75 74 68 6f  ITE_COPY | autho
18f00 72 69 7a 65 72 20 63 6f 64 65 5d 20 74 68 61 74  rizer code] that
18f10 20 73 70 65 63 69 66 69 65 73 20 77 68 61 74 20   specifies what 
18f20 61 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20  action.**       
18f30 20 20 20 69 73 20 62 65 69 6e 67 20 61 75 74 68     is being auth
18f40 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48  orized..**.** {H
18f50 31 32 35 35 32 7d 20 54 68 65 20 33 72 64 20 61  12552} The 3rd a
18f60 6e 64 20 34 74 68 20 70 61 72 61 6d 65 74 65 72  nd 4th parameter
18f70 73 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20  s to the.**     
18f80 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 73 65       [sqlite3_se
18f90 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61  t_authorizer | a
18fa0 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 63 61 6c  uthorization cal
18fb0 6c 62 61 63 6b 5d 0a 2a 2a 20 20 20 20 20 20 20  lback].**       
18fc0 20 20 20 73 68 61 6c 6c 20 62 65 20 70 61 72 61     shall be para
18fd0 6d 65 74 65 72 73 20 6f 72 20 4e 55 4c 4c 20 64  meters or NULL d
18fe0 65 70 65 6e 64 69 6e 67 20 6f 6e 20 77 68 69 63  epending on whic
18ff0 68 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53  h.**          [S
19000 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20 61 75 74  QLITE_COPY | aut
19010 68 6f 72 69 7a 65 72 20 63 6f 64 65 5d 20 69 73  horizer code] is
19020 20 75 73 65 64 20 61 73 20 74 68 65 20 73 65 63   used as the sec
19030 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  ond parameter..*
19040 2a 0a 2a 2a 20 7b 48 31 32 35 35 33 7d 20 54 68  *.** {H12553} Th
19050 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 5th parameter 
19060 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  to the.**       
19070 20 20 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f     [sqlite3_set_
19080 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74  authorizer | aut
19090 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
190a0 5d 20 73 68 61 6c 6c 20 62 65 20 74 68 65 20 6e  ] shall be the n
190b0 61 6d 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ame.**          
190c0 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  of the database 
190d0 28 65 78 61 6d 70 6c 65 3a 20 22 6d 61 69 6e 22  (example: "main"
190e0 2c 20 22 74 65 6d 70 22 2c 20 65 74 63 2e 29 20  , "temp", etc.) 
190f0 69 66 20 61 70 70 6c 69 63 61 62 6c 65 2e 0a 2a  if applicable..*
19100 2a 0a 2a 2a 20 7b 48 31 32 35 35 34 7d 20 54 68  *.** {H12554} Th
19110 65 20 36 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 6th parameter 
19120 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  to the.**       
19130 20 20 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f     [sqlite3_set_
19140 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74  authorizer | aut
19150 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
19160 5d 20 73 68 61 6c 6c 20 62 65 20 74 68 65 20 6e  ] shall be the n
19170 61 6d 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ame.**          
19180 6f 66 20 74 68 65 20 69 6e 6e 65 72 2d 6d 6f 73  of the inner-mos
19190 74 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 65  t trigger or vie
191a0 77 20 74 68 61 74 20 69 73 20 72 65 73 70 6f 6e  w that is respon
191b0 73 69 62 6c 65 20 66 6f 72 0a 2a 2a 20 20 20 20  sible for.**    
191c0 20 20 20 20 20 20 74 68 65 20 61 63 63 65 73 73        the access
191d0 20 61 74 74 65 6d 70 74 20 6f 72 20 4e 55 4c 4c   attempt or NULL
191e0 20 69 66 20 74 68 69 73 20 61 63 63 65 73 73 20   if this access 
191f0 61 74 74 65 6d 70 74 20 69 73 20 64 69 72 65 63  attempt is direc
19200 74 6c 79 20 66 72 6f 6d 0a 2a 2a 20 20 20 20 20  tly from.**     
19210 20 20 20 20 20 74 6f 70 2d 6c 65 76 65 6c 20 53       top-level S
19220 51 4c 20 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a  QL code..*/./***
19230 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
19240 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
19250 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72 64 20 2a 2a 2a  ******** 3rd ***
19260 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74 68 20 2a 2a  ********* 4th **
19270 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 69  *********/.#defi
19280 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
19290 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20  _INDEX          
192a0 31 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d  1   /* Index Nam
192b0 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  e      Table Nam
192c0 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
192d0 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
192e0 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 32  TABLE          2
192f0 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
19300 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
19310 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
19320 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54   SQLITE_CREATE_T
19330 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 33 20  EMP_INDEX     3 
19340 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20    /* Index Name 
19350 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20       Table Name 
19360 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
19370 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45  SQLITE_CREATE_TE
19380 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 34 20 20  MP_TABLE     4  
19390 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
193a0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
193b0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
193c0 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d  QLITE_CREATE_TEM
193d0 50 5f 54 52 49 47 47 45 52 20 20 20 35 20 20 20  P_TRIGGER   5   
193e0 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20  /* Trigger Name 
193f0 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
19400 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
19410 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50  LITE_CREATE_TEMP
19420 5f 56 49 45 57 20 20 20 20 20 20 36 20 20 20 2f  _VIEW      6   /
19430 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20  * View Name     
19440 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
19450 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
19460 49 54 45 5f 43 52 45 41 54 45 5f 54 52 49 47 47  ITE_CREATE_TRIGG
19470 45 52 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a  ER        7   /*
19480 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20   Trigger Name   
19490 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
194a0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
194b0 54 45 5f 43 52 45 41 54 45 5f 56 49 45 57 20 20  TE_CREATE_VIEW  
194c0 20 20 20 20 20 20 20 20 20 38 20 20 20 2f 2a 20           8   /* 
194d0 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20  View Name       
194e0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
194f0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
19500 45 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 20  E_DELETE        
19510 20 20 20 20 20 20 20 20 39 20 20 20 2f 2a 20 54          9   /* T
19520 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
19530 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
19540 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
19550 5f 44 52 4f 50 5f 49 4e 44 45 58 20 20 20 20 20  _DROP_INDEX     
19560 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20 49 6e        10   /* In
19570 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61  dex Name      Ta
19580 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
19590 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
195a0 44 52 4f 50 5f 54 41 42 4c 45 20 20 20 20 20 20  DROP_TABLE      
195b0 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54 61 62       11   /* Tab
195c0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
195d0 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
195e0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
195f0 52 4f 50 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20  ROP_TEMP_INDEX  
19600 20 20 20 20 31 32 20 20 20 2f 2a 20 49 6e 64 65      12   /* Inde
19610 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c  x Name      Tabl
19620 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
19630 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
19640 4f 50 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20  OP_TEMP_TABLE   
19650 20 20 20 31 33 20 20 20 2f 2a 20 54 61 62 6c 65     13   /* Table
19660 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
19670 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
19680 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
19690 50 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20  P_TEMP_TRIGGER  
196a0 20 20 31 34 20 20 20 2f 2a 20 54 72 69 67 67 65    14   /* Trigge
196b0 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20  r Name    Table 
196c0 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
196d0 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
196e0 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20  _TEMP_VIEW      
196f0 20 31 35 20 20 20 2f 2a 20 56 69 65 77 20 4e 61   15   /* View Na
19700 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  me       NULL   
19710 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
19720 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
19730 54 52 49 47 47 45 52 20 20 20 20 20 20 20 20 20  TRIGGER         
19740 31 36 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20  16   /* Trigger 
19750 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61  Name    Table Na
19760 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
19770 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56  ne SQLITE_DROP_V
19780 49 45 57 20 20 20 20 20 20 20 20 20 20 20 20 31  IEW            1
19790 37 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65  7   /* View Name
197a0 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
197b0 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
197c0 65 20 53 51 4c 49 54 45 5f 49 4e 53 45 52 54 20  e SQLITE_INSERT 
197d0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 38                18
197e0 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
197f0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
19800 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
19810 20 53 51 4c 49 54 45 5f 50 52 41 47 4d 41 20 20   SQLITE_PRAGMA  
19820 20 20 20 20 20 20 20 20 20 20 20 20 20 31 39 20               19 
19830 20 20 2f 2a 20 50 72 61 67 6d 61 20 4e 61 6d 65    /* Pragma Name
19840 20 20 20 20 20 31 73 74 20 61 72 67 20 6f 72 20       1st arg or 
19850 4e 55 4c 4c 20 2a 2f 0a 23 64 65 66 69 6e 65 20  NULL */.#define 
19860 53 51 4c 49 54 45 5f 52 45 41 44 20 20 20 20 20  SQLITE_READ     
19870 20 20 20 20 20 20 20 20 20 20 20 20 32 30 20 20              20  
19880 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
19890 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20      Column Name 
198a0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
198b0 51 4c 49 54 45 5f 53 45 4c 45 43 54 20 20 20 20  QLITE_SELECT    
198c0 20 20 20 20 20 20 20 20 20 20 20 32 31 20 20 20             21   
198d0 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20  /* NULL         
198e0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
198f0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
19900 4c 49 54 45 5f 54 52 41 4e 53 41 43 54 49 4f 4e  LITE_TRANSACTION
19910 20 20 20 20 20 20 20 20 20 20 32 32 20 20 20 2f            22   /
19920 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20  * NULL          
19930 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
19940 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
19950 49 54 45 5f 55 50 44 41 54 45 20 20 20 20 20 20  ITE_UPDATE      
19960 20 20 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a           23   /*
19970 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
19980 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20   Column Name    
19990 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
199a0 54 45 5f 41 54 54 41 43 48 20 20 20 20 20 20 20  TE_ATTACH       
199b0 20 20 20 20 20 20 20 20 32 34 20 20 20 2f 2a 20          24   /* 
199c0 46 69 6c 65 6e 61 6d 65 20 20 20 20 20 20 20 20  Filename        
199d0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
199e0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
199f0 45 5f 44 45 54 41 43 48 20 20 20 20 20 20 20 20  E_DETACH        
19a00 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20 44         25   /* D
19a10 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20 4e  atabase Name   N
19a20 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
19a30 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
19a40 5f 41 4c 54 45 52 5f 54 41 42 4c 45 20 20 20 20  _ALTER_TABLE    
19a50 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20 44 61        26   /* Da
19a60 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20 54 61  tabase Name   Ta
19a70 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
19a80 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
19a90 52 45 49 4e 44 45 58 20 20 20 20 20 20 20 20 20  REINDEX         
19aa0 20 20 20 20 20 32 37 20 20 20 2f 2a 20 49 6e 64       27   /* Ind
19ab0 65 78 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  ex Name      NUL
19ac0 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
19ad0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
19ae0 4e 41 4c 59 5a 45 20 20 20 20 20 20 20 20 20 20  NALYZE          
19af0 20 20 20 20 32 38 20 20 20 2f 2a 20 54 61 62 6c      28   /* Tabl
19b00 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
19b10 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
19b20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
19b30 45 41 54 45 5f 56 54 41 42 4c 45 20 20 20 20 20  EATE_VTABLE     
19b40 20 20 20 32 39 20 20 20 2f 2a 20 54 61 62 6c 65     29   /* Table
19b50 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c   Name      Modul
19b60 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64  e Name     */.#d
19b70 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
19b80 50 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20 20  P_VTABLE        
19b90 20 20 33 30 20 20 20 2f 2a 20 54 61 62 6c 65 20    30   /* Table 
19ba0 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65  Name      Module
19bb0 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65   Name     */.#de
19bc0 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 4e 43  fine SQLITE_FUNC
19bd0 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20 20 20  TION            
19be0 20 33 31 20 20 20 2f 2a 20 46 75 6e 63 74 69 6f   31   /* Functio
19bf0 6e 20 4e 61 6d 65 20 20 20 4e 55 4c 4c 20 20 20  n Name   NULL   
19c00 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
19c10 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 50 59 20  ine SQLITE_COPY 
19c20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
19c30 20 30 20 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65   0   /* No longe
19c40 72 20 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a  r used */../*.**
19c50 20 43 41 50 49 33 52 45 46 3a 20 54 72 61 63 69   CAPI3REF: Traci
19c60 6e 67 20 41 6e 64 20 50 72 6f 66 69 6c 69 6e 67  ng And Profiling
19c70 20 46 75 6e 63 74 69 6f 6e 73 20 7b 48 31 32 32   Functions {H122
19c80 38 30 7d 20 3c 53 36 30 34 30 30 3e 0a 2a 2a 20  80} <S60400>.** 
19c90 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a  EXPERIMENTAL.**.
19ca0 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
19cb0 73 20 72 65 67 69 73 74 65 72 20 63 61 6c 6c 62  s register callb
19cc0 61 63 6b 20 66 75 6e 63 74 69 6f 6e 73 20 74 68  ack functions th
19cd0 61 74 20 63 61 6e 20 62 65 20 75 73 65 64 20 66  at can be used f
19ce0 6f 72 0a 2a 2a 20 74 72 61 63 69 6e 67 20 61 6e  or.** tracing an
19cf0 64 20 70 72 6f 66 69 6c 69 6e 67 20 74 68 65 20  d profiling the 
19d00 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 53 51 4c  execution of SQL
19d10 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a   statements..**.
19d20 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20  ** The callback 
19d30 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65  function registe
19d40 72 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 74  red by sqlite3_t
19d50 72 61 63 65 28 29 20 69 73 20 69 6e 76 6f 6b 65  race() is invoke
19d60 64 20 61 74 0a 2a 2a 20 76 61 72 69 6f 75 73 20  d at.** various 
19d70 74 69 6d 65 73 20 77 68 65 6e 20 61 6e 20 53 51  times when an SQ
19d80 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 62  L statement is b
19d90 65 69 6e 67 20 72 75 6e 20 62 79 20 5b 73 71 6c  eing run by [sql
19da0 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a  ite3_step()]..**
19db0 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65   The callback re
19dc0 74 75 72 6e 73 20 61 20 55 54 46 2d 38 20 72 65  turns a UTF-8 re
19dd0 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 53  ndering of the S
19de0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78  QL statement tex
19df0 74 0a 2a 2a 20 61 73 20 74 68 65 20 73 74 61 74  t.** as the stat
19e00 65 6d 65 6e 74 20 66 69 72 73 74 20 62 65 67 69  ement first begi
19e10 6e 73 20 65 78 65 63 75 74 69 6e 67 2e 20 20 41  ns executing.  A
19e20 64 64 69 74 69 6f 6e 61 6c 20 63 61 6c 6c 62 61  dditional callba
19e30 63 6b 73 20 6f 63 63 75 72 0a 2a 2a 20 61 73 20  cks occur.** as 
19e40 65 61 63 68 20 74 72 69 67 67 65 72 65 64 20 73  each triggered s
19e50 75 62 70 72 6f 67 72 61 6d 20 69 73 20 65 6e 74  ubprogram is ent
19e60 65 72 65 64 2e 20 20 54 68 65 20 63 61 6c 6c 62  ered.  The callb
19e70 61 63 6b 73 20 66 6f 72 20 74 72 69 67 67 65 72  acks for trigger
19e80 73 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 61 20 55  s.** contain a U
19e90 54 46 2d 38 20 53 51 4c 20 63 6f 6d 6d 65 6e 74  TF-8 SQL comment
19ea0 20 74 68 61 74 20 69 64 65 6e 74 69 66 69 65 73   that identifies
19eb0 20 74 68 65 20 74 72 69 67 67 65 72 2e 0a 2a 2a   the trigger..**
19ec0 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61 63 6b  .** The callback
19ed0 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74   function regist
19ee0 65 72 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  ered by sqlite3_
19ef0 70 72 6f 66 69 6c 65 28 29 20 69 73 20 69 6e 76  profile() is inv
19f00 6f 6b 65 64 0a 2a 2a 20 61 73 20 65 61 63 68 20  oked.** as each 
19f10 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 66 69  SQL statement fi
19f20 6e 69 73 68 65 73 2e 20 20 54 68 65 20 70 72 6f  nishes.  The pro
19f30 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f  file callback co
19f40 6e 74 61 69 6e 73 0a 2a 2a 20 74 68 65 20 6f 72  ntains.** the or
19f50 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74  iginal statement
19f60 20 74 65 78 74 20 61 6e 64 20 61 6e 20 65 73 74   text and an est
19f70 69 6d 61 74 65 20 6f 66 20 77 61 6c 6c 2d 63 6c  imate of wall-cl
19f80 6f 63 6b 20 74 69 6d 65 0a 2a 2a 20 6f 66 20 68  ock time.** of h
19f90 6f 77 20 6c 6f 6e 67 20 74 68 61 74 20 73 74 61  ow long that sta
19fa0 74 65 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f 20 72  tement took to r
19fb0 75 6e 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  un..**.** INVARI
19fc0 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  ANTS:.**.** {H12
19fd0 32 38 31 7d 20 54 68 65 20 63 61 6c 6c 62 61 63  281} The callbac
19fe0 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73  k function regis
19ff0 74 65 72 65 64 20 62 79 20 5b 73 71 6c 69 74 65  tered by [sqlite
1a000 33 5f 74 72 61 63 65 28 29 5d 20 0a 2a 2a 20 20  3_trace()] .**  
1a010 20 20 20 20 20 20 20 20 73 68 61 6c 6c 20 62 65          shall be
1a020 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 20 20 20 20   invoked.**     
1a030 20 20 20 20 20 77 68 65 6e 65 76 65 72 20 61 6e       whenever an
1a040 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 66   SQL statement f
1a050 69 72 73 74 20 62 65 67 69 6e 73 20 74 6f 20 65  irst begins to e
1a060 78 65 63 75 74 65 20 61 6e 64 0a 2a 2a 20 20 20  xecute and.**   
1a070 20 20 20 20 20 20 20 77 68 65 6e 65 76 65 72 20         whenever 
1a080 61 20 74 72 69 67 67 65 72 20 73 75 62 70 72 6f  a trigger subpro
1a090 67 72 61 6d 20 66 69 72 73 74 20 62 65 67 69 6e  gram first begin
1a0a0 73 20 74 6f 20 72 75 6e 2e 0a 2a 2a 0a 2a 2a 20  s to run..**.** 
1a0b0 7b 48 31 32 32 38 32 7d 20 45 61 63 68 20 63 61  {H12282} Each ca
1a0c0 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 74  ll to [sqlite3_t
1a0d0 72 61 63 65 28 29 5d 20 73 68 61 6c 6c 20 6f 76  race()] shall ov
1a0e0 65 72 72 69 64 65 20 74 68 65 20 70 72 65 76 69  erride the previ
1a0f0 6f 75 73 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20  ously.**        
1a100 20 20 72 65 67 69 73 74 65 72 65 64 20 74 72 61    registered tra
1a110 63 65 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a  ce callback..**.
1a120 2a 2a 20 7b 48 31 32 32 38 33 7d 20 41 20 4e 55  ** {H12283} A NU
1a130 4c 4c 20 74 72 61 63 65 20 63 61 6c 6c 62 61 63  LL trace callbac
1a140 6b 20 73 68 61 6c 6c 20 64 69 73 61 62 6c 65 20  k shall disable 
1a150 74 72 61 63 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b  tracing..**.** {
1a160 48 31 32 32 38 34 7d 20 54 68 65 20 66 69 72 73  H12284} The firs
1a170 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  t argument to th
1a180 65 20 74 72 61 63 65 20 63 61 6c 6c 62 61 63 6b  e trace callback
1a190 20 73 68 61 6c 6c 20 62 65 20 61 20 63 6f 70 79   shall be a copy
1a1a0 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   of.**          
1a1b0 74 68 65 20 70 6f 69 6e 74 65 72 20 77 68 69 63  the pointer whic
1a1c0 68 20 77 61 73 20 74 68 65 20 33 72 64 20 61 72  h was the 3rd ar
1a1d0 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74  gument to [sqlit
1a1e0 65 33 5f 74 72 61 63 65 28 29 5d 2e 0a 2a 2a 0a  e3_trace()]..**.
1a1f0 2a 2a 20 7b 48 31 32 32 38 35 7d 20 54 68 65 20  ** {H12285} The 
1a200 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
1a210 74 6f 20 74 68 65 20 74 72 61 63 65 20 63 61 6c  to the trace cal
1a220 6c 62 61 63 6b 20 69 73 20 61 0a 2a 2a 20 20 20  lback is a.**   
1a230 20 20 20 20 20 20 20 7a 65 72 6f 2d 74 65 72 6d         zero-term
1a240 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72  inated UTF-8 str
1a250 69 6e 67 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74  ing containing t
1a260 68 65 20 6f 72 69 67 69 6e 61 6c 20 74 65 78 74  he original text
1a270 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20  .**          of 
1a280 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
1a290 74 20 61 73 20 69 74 20 77 61 73 20 70 61 73 73  t as it was pass
1a2a0 65 64 20 69 6e 74 6f 20 5b 73 71 6c 69 74 65 33  ed into [sqlite3
1a2b0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 0a 2a  _prepare_v2()].*
1a2c0 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 74 68  *          or th
1a2d0 65 20 65 71 75 69 76 61 6c 65 6e 74 2c 20 6f 72  e equivalent, or
1a2e0 20 61 6e 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 20   an SQL comment 
1a2f0 69 6e 64 69 63 61 74 69 6e 67 20 74 68 65 20 62  indicating the b
1a300 65 67 69 6e 6e 69 6e 67 0a 2a 2a 20 20 20 20 20  eginning.**     
1a310 20 20 20 20 20 6f 66 20 61 20 74 72 69 67 67 65       of a trigge
1a320 72 20 73 75 62 70 72 6f 67 72 61 6d 2e 0a 2a 2a  r subprogram..**
1a330 0a 2a 2a 20 7b 48 31 32 32 38 37 7d 20 54 68 65  .** {H12287} The
1a340 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
1a350 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 62 79  on registered by
1a360 20 5b 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c   [sqlite3_profil
1a370 65 28 29 5d 20 69 73 20 69 6e 76 6f 6b 65 64 0a  e()] is invoked.
1a380 2a 2a 20 20 20 20 20 20 20 20 20 20 61 73 20 65  **          as e
1a390 61 63 68 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ach SQL statemen
1a3a0 74 20 66 69 6e 69 73 68 65 73 2e 0a 2a 2a 0a 2a  t finishes..**.*
1a3b0 2a 20 7b 48 31 32 32 38 38 7d 20 54 68 65 20 66  * {H12288} The f
1a3c0 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74  irst parameter t
1a3d0 6f 20 74 68 65 20 70 72 6f 66 69 6c 65 20 63 61  o the profile ca
1a3e0 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79  llback is a copy
1a3f0 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   of.**          
1a400 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65  the 3rd paramete
1a410 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72  r to [sqlite3_pr
1a420 6f 66 69 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  ofile()]..**.** 
1a430 7b 48 31 32 32 38 39 7d 20 54 68 65 20 73 65 63  {H12289} The sec
1a440 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ond parameter to
1a450 20 74 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c   the profile cal
1a460 6c 62 61 63 6b 20 69 73 20 61 0a 2a 2a 20 20 20  lback is a.**   
1a470 20 20 20 20 20 20 20 7a 65 72 6f 2d 74 65 72 6d         zero-term
1a480 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72  inated UTF-8 str
1a490 69 6e 67 20 74 68 61 74 20 63 6f 6e 74 61 69 6e  ing that contain
1a4a0 73 20 74 68 65 20 63 6f 6d 70 6c 65 74 65 20 74  s the complete t
1a4b0 65 78 74 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20  ext of.**       
1a4c0 20 20 20 74 68 65 20 53 51 4c 20 73 74 61 74 65     the SQL state
1a4d0 6d 65 6e 74 20 61 73 20 69 74 20 77 61 73 20 70  ment as it was p
1a4e0 72 6f 63 65 73 73 65 64 20 62 79 20 5b 73 71 6c  rocessed by [sql
1a4f0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
1a500 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  )].**          o
1a510 72 20 74 68 65 20 65 71 75 69 76 61 6c 65 6e 74  r the equivalent
1a520 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 39 30 7d  ..**.** {H12290}
1a530 20 54 68 65 20 74 68 69 72 64 20 70 61 72 61 6d   The third param
1a540 65 74 65 72 20 74 6f 20 74 68 65 20 70 72 6f 66  eter to the prof
1a550 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  ile callback is 
1a560 61 6e 20 65 73 74 69 6d 61 74 65 0a 2a 2a 20 20  an estimate.**  
1a570 20 20 20 20 20 20 20 20 6f 66 20 74 68 65 20 6e          of the n
1a580 75 6d 62 65 72 20 6f 66 20 6e 61 6e 6f 73 65 63  umber of nanosec
1a590 6f 6e 64 73 20 6f 66 20 77 61 6c 6c 2d 63 6c 6f  onds of wall-clo
1a5a0 63 6b 20 74 69 6d 65 20 72 65 71 75 69 72 65 64  ck time required
1a5b0 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   to.**          
1a5c0 72 75 6e 20 74 68 65 20 53 51 4c 20 73 74 61 74  run the SQL stat
1a5d0 65 6d 65 6e 74 20 66 72 6f 6d 20 73 74 61 72 74  ement from start
1a5e0 20 74 6f 20 66 69 6e 69 73 68 2e 0a 2a 2f 0a 53   to finish..*/.S
1a5f0 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54  QLITE_EXPERIMENT
1a600 41 4c 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  AL void *sqlite3
1a610 5f 74 72 61 63 65 28 73 71 6c 69 74 65 33 2a 2c  _trace(sqlite3*,
1a620 20 76 6f 69 64 28 2a 78 54 72 61 63 65 29 28 76   void(*xTrace)(v
1a630 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  oid*,const char*
1a640 29 2c 20 76 6f 69 64 2a 29 3b 0a 53 51 4c 49 54  ), void*);.SQLIT
1a650 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 76  E_EXPERIMENTAL v
1a660 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 70 72 6f  oid *sqlite3_pro
1a670 66 69 6c 65 28 73 71 6c 69 74 65 33 2a 2c 0a 20  file(sqlite3*,. 
1a680 20 20 76 6f 69 64 28 2a 78 50 72 6f 66 69 6c 65    void(*xProfile
1a690 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68  )(void*,const ch
1a6a0 61 72 2a 2c 73 71 6c 69 74 65 33 5f 75 69 6e 74  ar*,sqlite3_uint
1a6b0 36 34 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a  64), void*);../*
1a6c0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 51 75  .** CAPI3REF: Qu
1a6d0 65 72 79 20 50 72 6f 67 72 65 73 73 20 43 61 6c  ery Progress Cal
1a6e0 6c 62 61 63 6b 73 20 7b 48 31 32 39 31 30 7d 20  lbacks {H12910} 
1a6f0 3c 53 36 30 34 30 30 3e 0a 2a 2a 0a 2a 2a 20 54  <S60400>.**.** T
1a700 68 69 73 20 72 6f 75 74 69 6e 65 20 63 6f 6e 66  his routine conf
1a710 69 67 75 72 65 73 20 61 20 63 61 6c 6c 62 61 63  igures a callbac
1a720 6b 20 66 75 6e 63 74 69 6f 6e 20 2d 20 74 68 65  k function - the
1a730 0a 2a 2a 20 70 72 6f 67 72 65 73 73 20 63 61 6c  .** progress cal
1a740 6c 62 61 63 6b 20 2d 20 74 68 61 74 20 69 73 20  lback - that is 
1a750 69 6e 76 6f 6b 65 64 20 70 65 72 69 6f 64 69 63  invoked periodic
1a760 61 6c 6c 79 20 64 75 72 69 6e 67 20 6c 6f 6e 67  ally during long
1a770 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 63 61 6c 6c  .** running call
1a780 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 78  s to [sqlite3_ex
1a790 65 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  ec()], [sqlite3_
1a7a0 73 74 65 70 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b  step()] and.** [
1a7b0 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
1a7c0 65 28 29 5d 2e 20 20 41 6e 20 65 78 61 6d 70 6c  e()].  An exampl
1a7d0 65 20 75 73 65 20 66 6f 72 20 74 68 69 73 0a 2a  e use for this.*
1a7e0 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74  * interface is t
1a7f0 6f 20 6b 65 65 70 20 61 20 47 55 49 20 75 70 64  o keep a GUI upd
1a800 61 74 65 64 20 64 75 72 69 6e 67 20 61 20 6c 61  ated during a la
1a810 72 67 65 20 71 75 65 72 79 2e 0a 2a 2a 0a 2a 2a  rge query..**.**
1a820 20 49 66 20 74 68 65 20 70 72 6f 67 72 65 73 73   If the progress
1a830 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
1a840 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20  s non-zero, the 
1a850 6f 70 65 72 61 74 69 6f 6e 20 69 73 0a 2a 2a 20  operation is.** 
1a860 69 6e 74 65 72 72 75 70 74 65 64 2e 20 20 54 68  interrupted.  Th
1a870 69 73 20 66 65 61 74 75 72 65 20 63 61 6e 20 62  is feature can b
1a880 65 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d  e used to implem
1a890 65 6e 74 20 61 0a 2a 2a 20 22 43 61 6e 63 65 6c  ent a.** "Cancel
1a8a0 22 20 62 75 74 74 6f 6e 20 6f 6e 20 61 20 47 55  " button on a GU
1a8b0 49 20 70 72 6f 67 72 65 73 73 20 64 69 61 6c 6f  I progress dialo
1a8c0 67 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  g box..**.** The
1a8d0 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65   progress handle
1a8e0 72 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e  r must not do an
1a8f0 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c  ything that will
1a900 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64   modify.** the d
1a910 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1a920 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20  on that invoked 
1a930 74 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e  the progress han
1a940 64 6c 65 72 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68  dler..** Note th
1a950 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  at [sqlite3_prep
1a960 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73  are_v2()] and [s
1a970 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62  qlite3_step()] b
1a980 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72  oth modify their
1a990 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e  .** database con
1a9a0 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65  nections for the
1a9b0 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64   meaning of "mod
1a9c0 69 66 79 22 20 69 6e 20 74 68 69 73 20 70 61 72  ify" in this par
1a9d0 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 49 4e  agraph..**.** IN
1a9e0 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
1a9f0 7b 48 31 32 39 31 31 7d 20 54 68 65 20 63 61 6c  {H12911} The cal
1aa00 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72  lback function r
1aa10 65 67 69 73 74 65 72 65 64 20 62 79 20 73 71 6c  egistered by sql
1aa20 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61  ite3_progress_ha
1aa30 6e 64 6c 65 72 28 29 0a 2a 2a 20 20 20 20 20 20  ndler().**      
1aa40 20 20 20 20 69 73 20 69 6e 76 6f 6b 65 64 20 70      is invoked p
1aa50 65 72 69 6f 64 69 63 61 6c 6c 79 20 64 75 72 69  eriodically duri
1aa60 6e 67 20 6c 6f 6e 67 20 72 75 6e 6e 69 6e 67 20  ng long running 
1aa70 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 20 20 20 20  calls to.**     
1aa80 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 73 74       [sqlite3_st
1aa90 65 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  ep()]..**.** {H1
1aaa0 32 39 31 32 7d 20 54 68 65 20 70 72 6f 67 72 65  2912} The progre
1aab0 73 73 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  ss callback is i
1aac0 6e 76 6f 6b 65 64 20 6f 6e 63 65 20 66 6f 72 20  nvoked once for 
1aad0 65 76 65 72 79 20 4e 20 76 69 72 74 75 61 6c 0a  every N virtual.
1aae0 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 61 63 68  **          mach
1aaf0 69 6e 65 20 6f 70 63 6f 64 65 73 2c 20 77 68 65  ine opcodes, whe
1ab00 72 65 20 4e 20 69 73 20 74 68 65 20 73 65 63 6f  re N is the seco
1ab10 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a  nd argument to.*
1ab20 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 5b  *          the [
1ab30 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73  sqlite3_progress
1ab40 5f 68 61 6e 64 6c 65 72 28 29 5d 20 63 61 6c 6c  _handler()] call
1ab50 20 74 68 61 74 20 72 65 67 69 73 74 65 72 65 64   that registered
1ab60 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
1ab70 20 63 61 6c 6c 62 61 63 6b 2e 20 20 49 66 20 4e   callback.  If N
1ab80 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 31 2c   is less than 1,
1ab90 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73   sqlite3_progres
1aba0 73 5f 68 61 6e 64 6c 65 72 28 29 0a 2a 2a 20 20  s_handler().**  
1abb0 20 20 20 20 20 20 20 20 61 63 74 73 20 61 73 20          acts as 
1abc0 69 66 20 61 20 4e 55 4c 4c 20 70 72 6f 67 72 65  if a NULL progre
1abd0 73 73 20 68 61 6e 64 6c 65 72 20 68 61 64 20 62  ss handler had b
1abe0 65 65 6e 20 73 70 65 63 69 66 69 65 64 2e 0a 2a  een specified..*
1abf0 2a 0a 2a 2a 20 7b 48 31 32 39 31 33 7d 20 54 68  *.** {H12913} Th
1ac00 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62  e progress callb
1ac10 61 63 6b 20 69 74 73 65 6c 66 20 69 73 20 69 64  ack itself is id
1ac20 65 6e 74 69 66 69 65 64 20 62 79 20 74 68 65 20  entified by the 
1ac30 74 68 69 72 64 0a 2a 2a 20 20 20 20 20 20 20 20  third.**        
1ac40 20 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71    argument to sq
1ac50 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68  lite3_progress_h
1ac60 61 6e 64 6c 65 72 28 29 2e 0a 2a 2a 0a 2a 2a 20  andler()..**.** 
1ac70 7b 48 31 32 39 31 34 7d 20 54 68 65 20 66 6f 75  {H12914} The fou
1ac80 72 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rth argument to 
1ac90 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73  sqlite3_progress
1aca0 5f 68 61 6e 64 6c 65 72 28 29 20 69 73 20 61 0a  _handler() is a.
1acb0 2a 2a 20 20 20 20 20 20 20 20 20 20 76 6f 69 64  **          void
1acc0 20 70 6f 69 6e 74 65 72 20 70 61 73 73 65 64 20   pointer passed 
1acd0 74 6f 20 74 68 65 20 70 72 6f 67 72 65 73 73 20  to the progress 
1ace0 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 20 20 20 20  callback.**     
1acf0 20 20 20 20 20 66 75 6e 63 74 69 6f 6e 20 65 61       function ea
1ad00 63 68 20 74 69 6d 65 20 69 74 20 69 73 20 69 6e  ch time it is in
1ad10 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  voked..**.** {H1
1ad20 32 39 31 35 7d 20 49 66 20 61 20 63 61 6c 6c 20  2915} If a call 
1ad30 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  to [sqlite3_step
1ad40 28 29 5d 20 72 65 73 75 6c 74 73 20 69 6e 20 66  ()] results in f
1ad50 65 77 65 72 20 74 68 61 6e 20 4e 20 6f 70 63 6f  ewer than N opco
1ad60 64 65 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  des.**          
1ad70 62 65 69 6e 67 20 65 78 65 63 75 74 65 64 2c 20  being executed, 
1ad80 74 68 65 6e 20 74 68 65 20 70 72 6f 67 72 65 73  then the progres
1ad90 73 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 6e 65  s callback is ne
1ada0 76 65 72 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a  ver invoked..**.
1adb0 2a 2a 20 7b 48 31 32 39 31 36 7d 20 45 76 65 72  ** {H12916} Ever
1adc0 79 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  y call to [sqlit
1add0 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64  e3_progress_hand
1ade0 6c 65 72 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20  ler()].**       
1adf0 20 20 20 6f 76 65 72 77 72 69 74 65 73 20 61 6e     overwrites an
1ae00 79 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 67  y previously reg
1ae10 69 73 74 65 72 65 64 20 70 72 6f 67 72 65 73 73  istered progress
1ae20 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20   handler..**.** 
1ae30 7b 48 31 32 39 31 37 7d 20 49 66 20 74 68 65 20  {H12917} If the 
1ae40 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72  progress handler
1ae50 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c   callback is NUL
1ae60 4c 20 74 68 65 6e 20 6e 6f 20 70 72 6f 67 72 65  L then no progre
1ae70 73 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 68  ss.**          h
1ae80 61 6e 64 6c 65 72 20 69 73 20 69 6e 76 6f 6b 65  andler is invoke
1ae90 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 31 38  d..**.** {H12918
1aea0 7d 20 49 66 20 74 68 65 20 70 72 6f 67 72 65 73  } If the progres
1aeb0 73 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  s callback retur
1aec0 6e 73 20 61 20 72 65 73 75 6c 74 20 6f 74 68 65  ns a result othe
1aed0 72 20 74 68 61 6e 20 30 2c 20 74 68 65 6e 0a 2a  r than 0, then.*
1aee0 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 62  *          the b
1aef0 65 68 61 76 69 6f 72 20 69 73 20 61 20 69 66 20  ehavior is a if 
1af00 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75  [sqlite3_interru
1af10 70 74 28 29 5d 20 68 61 64 20 62 65 65 6e 20 63  pt()] had been c
1af20 61 6c 6c 65 64 2e 0a 2a 2a 20 20 20 20 20 20 20  alled..**       
1af30 20 20 20 3c 53 33 30 35 30 30 3e 0a 2a 2f 0a 76     <S30500>.*/.v
1af40 6f 69 64 20 73 71 6c 69 74 65 33 5f 70 72 6f 67  oid sqlite3_prog
1af50 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 73 71 6c  ress_handler(sql
1af60 69 74 65 33 2a 2c 20 69 6e 74 2c 20 69 6e 74 28  ite3*, int, int(
1af70 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a  *)(void*), void*
1af80 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1af90 45 46 3a 20 4f 70 65 6e 69 6e 67 20 41 20 4e 65  EF: Opening A Ne
1afa0 77 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65  w Database Conne
1afb0 63 74 69 6f 6e 20 7b 48 31 32 37 30 30 7d 20 3c  ction {H12700} <
1afc0 53 34 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68  S40200>.**.** Th
1afd0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 70 65  ese routines ope
1afe0 6e 20 61 6e 20 53 51 4c 69 74 65 20 64 61 74 61  n an SQLite data
1aff0 62 61 73 65 20 66 69 6c 65 20 77 68 6f 73 65 20  base file whose 
1b000 6e 61 6d 65 20 69 73 20 67 69 76 65 6e 20 62 79  name is given by
1b010 20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65   the.** filename
1b020 20 61 72 67 75 6d 65 6e 74 2e 20 54 68 65 20 66   argument. The f
1b030 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74  ilename argument
1b040 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20   is interpreted 
1b050 61 73 20 55 54 46 2d 38 20 66 6f 72 0a 2a 2a 20  as UTF-8 for.** 
1b060 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61  sqlite3_open() a
1b070 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  nd sqlite3_open_
1b080 76 32 28 29 20 61 6e 64 20 61 73 20 55 54 46 2d  v2() and as UTF-
1b090 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65  16 in the native
1b0a0 20 62 79 74 65 0a 2a 2a 20 6f 72 64 65 72 20 66   byte.** order f
1b0b0 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  or sqlite3_open1
1b0c0 36 28 29 2e 20 41 20 5b 64 61 74 61 62 61 73 65  6(). A [database
1b0d0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e   connection] han
1b0e0 64 6c 65 20 69 73 20 75 73 75 61 6c 6c 79 0a 2a  dle is usually.*
1b0f0 2a 20 72 65 74 75 72 6e 65 64 20 69 6e 20 2a 70  * returned in *p
1b100 70 44 62 2c 20 65 76 65 6e 20 69 66 20 61 6e 20  pDb, even if an 
1b110 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 20 20 54  error occurs.  T
1b120 68 65 20 6f 6e 6c 79 20 65 78 63 65 70 74 69 6f  he only exceptio
1b130 6e 20 69 73 20 74 68 61 74 0a 2a 2a 20 69 66 20  n is that.** if 
1b140 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65  SQLite is unable
1b150 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d   to allocate mem
1b160 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20  ory to hold the 
1b170 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74  [sqlite3] object
1b180 2c 0a 2a 2a 20 61 20 4e 55 4c 4c 20 77 69 6c 6c  ,.** a NULL will
1b190 20 62 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f   be written into
1b1a0 20 2a 70 70 44 62 20 69 6e 73 74 65 61 64 20 6f   *ppDb instead o
1b1b0 66 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  f a pointer to t
1b1c0 68 65 20 5b 73 71 6c 69 74 65 33 5d 0a 2a 2a 20  he [sqlite3].** 
1b1d0 6f 62 6a 65 63 74 2e 20 49 66 20 74 68 65 20 64  object. If the d
1b1e0 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65  atabase is opene
1b1f0 64 20 28 61 6e 64 2f 6f 72 20 63 72 65 61 74 65  d (and/or create
1b200 64 29 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2c  d) successfully,
1b210 20 74 68 65 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45   then.** [SQLITE
1b220 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e 65 64  _OK] is returned
1b230 2e 20 20 4f 74 68 65 72 77 69 73 65 20 61 6e 20  .  Otherwise an 
1b240 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20  [error code] is 
1b250 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 0a 2a  returned.  The.*
1b260 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  * [sqlite3_errms
1b270 67 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  g()] or [sqlite3
1b280 5f 65 72 72 6d 73 67 31 36 28 29 5d 20 72 6f 75  _errmsg16()] rou
1b290 74 69 6e 65 73 20 63 61 6e 20 62 65 20 75 73 65  tines can be use
1b2a0 64 20 74 6f 20 6f 62 74 61 69 6e 0a 2a 2a 20 61  d to obtain.** a
1b2b0 6e 20 45 6e 67 6c 69 73 68 20 6c 61 6e 67 75 61  n English langua
1b2c0 67 65 20 64 65 73 63 72 69 70 74 69 6f 6e 20 6f  ge description o
1b2d0 66 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a 0a  f the error..**.
1b2e0 2a 2a 20 54 68 65 20 64 65 66 61 75 6c 74 20 65  ** The default e
1b2f0 6e 63 6f 64 69 6e 67 20 66 6f 72 20 74 68 65 20  ncoding for the 
1b300 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65  database will be
1b310 20 55 54 46 2d 38 20 69 66 0a 2a 2a 20 73 71 6c   UTF-8 if.** sql
1b320 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73  ite3_open() or s
1b330 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
1b340 20 69 73 20 63 61 6c 6c 65 64 20 61 6e 64 0a 2a   is called and.*
1b350 2a 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20  * UTF-16 in the 
1b360 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
1b370 72 20 69 66 20 73 71 6c 69 74 65 33 5f 6f 70 65  r if sqlite3_ope
1b380 6e 31 36 28 29 20 69 73 20 75 73 65 64 2e 0a 2a  n16() is used..*
1b390 2a 0a 2a 2a 20 57 68 65 74 68 65 72 20 6f 72 20  *.** Whether or 
1b3a0 6e 6f 74 20 61 6e 20 65 72 72 6f 72 20 6f 63 63  not an error occ
1b3b0 75 72 73 20 77 68 65 6e 20 69 74 20 69 73 20 6f  urs when it is o
1b3c0 70 65 6e 65 64 2c 20 72 65 73 6f 75 72 63 65 73  pened, resources
1b3d0 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77  .** associated w
1b3e0 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 73  ith the [databas
1b3f0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61  e connection] ha
1b400 6e 64 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 72  ndle should be r
1b410 65 6c 65 61 73 65 64 20 62 79 0a 2a 2a 20 70 61  eleased by.** pa
1b420 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c  ssing it to [sql
1b430 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20 77 68  ite3_close()] wh
1b440 65 6e 20 69 74 20 69 73 20 6e 6f 20 6c 6f 6e 67  en it is no long
1b450 65 72 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a  er required..**.
1b460 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f  ** The sqlite3_o
1b470 70 65 6e 5f 76 32 28 29 20 69 6e 74 65 72 66 61  pen_v2() interfa
1b480 63 65 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71  ce works like sq
1b490 6c 69 74 65 33 5f 6f 70 65 6e 28 29 0a 2a 2a 20  lite3_open().** 
1b4a0 65 78 63 65 70 74 20 74 68 61 74 20 69 74 20 61  except that it a
1b4b0 63 63 65 70 74 73 20 74 77 6f 20 61 64 64 69 74  ccepts two addit
1b4c0 69 6f 6e 61 6c 20 70 61 72 61 6d 65 74 65 72 73  ional parameters
1b4d0 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20   for additional 
1b4e0 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f 76 65 72 20  control.** over 
1b4f0 74 68 65 20 6e 65 77 20 64 61 74 61 62 61 73 65  the new database
1b500 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 54 68   connection.  Th
1b510 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65  e flags paramete
1b520 72 20 63 61 6e 20 74 61 6b 65 20 6f 6e 65 20 6f  r can take one o
1b530 66 0a 2a 2a 20 74 68 65 20 66 6f 6c 6c 6f 77 69  f.** the followi
1b540 6e 67 20 74 68 72 65 65 20 76 61 6c 75 65 73 2c  ng three values,
1b550 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62   optionally comb
1b560 69 6e 65 64 20 77 69 74 68 20 74 68 65 20 0a 2a  ined with the .*
1b570 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e  * [SQLITE_OPEN_N
1b580 4f 4d 55 54 45 58 5d 20 6f 72 20 5b 53 51 4c 49  OMUTEX] or [SQLI
1b590 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45  TE_OPEN_FULLMUTE
1b5a0 58 5d 20 66 6c 61 67 73 3a 0a 2a 2a 0a 2a 2a 20  X] flags:.**.** 
1b5b0 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 5b 53 51 4c  <dl>.** <dt>[SQL
1b5c0 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c  ITE_OPEN_READONL
1b5d0 59 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  Y]</dt>.** <dd>T
1b5e0 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f  he database is o
1b5f0 70 65 6e 65 64 20 69 6e 20 72 65 61 64 2d 6f 6e  pened in read-on
1b600 6c 79 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65  ly mode.  If the
1b610 20 64 61 74 61 62 61 73 65 20 64 6f 65 73 20 6e   database does n
1b620 6f 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20 65 78  ot.** already ex
1b630 69 73 74 2c 20 61 6e 20 65 72 72 6f 72 20 69 73  ist, an error is
1b640 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 0a   returned.</dd>.
1b650 2a 2a 0a 2a 2a 20 3c 64 74 3e 5b 53 51 4c 49 54  **.** <dt>[SQLIT
1b660 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45  E_OPEN_READWRITE
1b670 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  ]</dt>.** <dd>Th
1b680 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70  e database is op
1b690 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e 67  ened for reading
1b6a0 20 61 6e 64 20 77 72 69 74 69 6e 67 20 69 66 20   and writing if 
1b6b0 70 6f 73 73 69 62 6c 65 2c 20 6f 72 20 72 65 61  possible, or rea
1b6c0 64 69 6e 67 0a 2a 2a 20 6f 6e 6c 79 20 69 66 20  ding.** only if 
1b6d0 74 68 65 20 66 69 6c 65 20 69 73 20 77 72 69 74  the file is writ
1b6e0 65 20 70 72 6f 74 65 63 74 65 64 20 62 79 20 74  e protected by t
1b6f0 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73  he operating sys
1b700 74 65 6d 2e 20 20 49 6e 20 65 69 74 68 65 72 0a  tem.  In either.
1b710 2a 2a 20 63 61 73 65 20 74 68 65 20 64 61 74 61  ** case the data
1b720 62 61 73 65 20 6d 75 73 74 20 61 6c 72 65 61 64  base must alread
1b730 79 20 65 78 69 73 74 2c 20 6f 74 68 65 72 77 69  y exist, otherwi
1b740 73 65 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72  se an error is r
1b750 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 0a 2a 2a  eturned.</dd>.**
1b760 0a 2a 2a 20 3c 64 74 3e 5b 53 51 4c 49 54 45 5f  .** <dt>[SQLITE_
1b770 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20  OPEN_READWRITE] 
1b780 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43  | [SQLITE_OPEN_C
1b790 52 45 41 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c  REATE]</dt>.** <
1b7a0 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 20  dd>The database 
1b7b0 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65  is opened for re
1b7c0 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e  ading and writin
1b7d0 67 2c 20 61 6e 64 20 69 73 20 63 72 65 61 74 65  g, and is create
1b7e0 73 20 69 74 20 69 66 0a 2a 2a 20 69 74 20 64 6f  s it if.** it do
1b7f0 65 73 20 6e 6f 74 20 61 6c 72 65 61 64 79 20 65  es not already e
1b800 78 69 73 74 2e 20 54 68 69 73 20 69 73 20 74 68  xist. This is th
1b810 65 20 62 65 68 61 76 69 6f 72 20 74 68 61 74 20  e behavior that 
1b820 69 73 20 61 6c 77 61 79 73 20 75 73 65 64 20 66  is always used f
1b830 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70  or.** sqlite3_op
1b840 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  en() and sqlite3
1b850 5f 6f 70 65 6e 31 36 28 29 2e 3c 2f 64 64 3e 0a  _open16().</dd>.
1b860 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20 49  ** </dl>.**.** I
1b870 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65  f the 3rd parame
1b880 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f  ter to sqlite3_o
1b890 70 65 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74 20  pen_v2() is not 
1b8a0 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 63 6f  one of the.** co
1b8b0 6d 62 69 6e 61 74 69 6f 6e 73 20 73 68 6f 77 6e  mbinations shown
1b8c0 20 61 62 6f 76 65 20 6f 72 20 6f 6e 65 20 6f 66   above or one of
1b8d0 20 74 68 65 20 63 6f 6d 62 69 6e 61 74 69 6f 6e   the combination
1b8e0 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 63 6f  s shown above co
1b8f0 6d 62 69 6e 65 64 0a 2a 2a 20 77 69 74 68 20 74  mbined.** with t
1b900 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
1b910 4e 4f 4d 55 54 45 58 5d 20 6f 72 20 5b 53 51 4c  NOMUTEX] or [SQL
1b920 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54  ITE_OPEN_FULLMUT
1b930 45 58 5d 20 66 6c 61 67 73 2c 0a 2a 2a 20 74 68  EX] flags,.** th
1b940 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  en the behavior 
1b950 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  is undefined..**
1b960 0a 2a 2a 20 49 66 20 74 68 65 20 5b 53 51 4c 49  .** If the [SQLI
1b970 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d  TE_OPEN_NOMUTEX]
1b980 20 66 6c 61 67 20 69 73 20 73 65 74 2c 20 74 68   flag is set, th
1b990 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
1b9a0 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 70  connection.** op
1b9b0 65 6e 73 20 69 6e 20 74 68 65 20 6d 75 6c 74 69  ens in the multi
1b9c0 2d 74 68 72 65 61 64 20 5b 74 68 72 65 61 64 69  -thread [threadi
1b9d0 6e 67 20 6d 6f 64 65 5d 20 61 73 20 6c 6f 6e 67  ng mode] as long
1b9e0 20 61 73 20 74 68 65 20 73 69 6e 67 6c 65 2d 74   as the single-t
1b9f0 68 72 65 61 64 0a 2a 2a 20 6d 6f 64 65 20 68 61  hread.** mode ha
1ba00 73 20 6e 6f 74 20 62 65 65 6e 20 73 65 74 20 61  s not been set a
1ba10 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  t compile-time o
1ba20 72 20 73 74 61 72 74 2d 74 69 6d 65 2e 20 20 49  r start-time.  I
1ba30 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  f the.** [SQLITE
1ba40 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d  _OPEN_FULLMUTEX]
1ba50 20 66 6c 61 67 20 69 73 20 73 65 74 20 74 68 65   flag is set the
1ba60 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  n the database c
1ba70 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 73 0a  onnection opens.
1ba80 2a 2a 20 69 6e 20 74 68 65 20 73 65 72 69 61 6c  ** in the serial
1ba90 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20  ized [threading 
1baa0 6d 6f 64 65 5d 20 75 6e 6c 65 73 73 20 73 69 6e  mode] unless sin
1bab0 67 6c 65 2d 74 68 72 65 61 64 20 77 61 73 0a 2a  gle-thread was.*
1bac0 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65 6c  * previously sel
1bad0 65 63 74 65 64 20 61 74 20 63 6f 6d 70 69 6c 65  ected at compile
1bae0 2d 74 69 6d 65 20 6f 72 20 73 74 61 72 74 2d 74  -time or start-t
1baf0 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  ime..**.** If th
1bb00 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 22 3a  e filename is ":
1bb10 6d 65 6d 6f 72 79 3a 22 2c 20 74 68 65 6e 20 61  memory:", then a
1bb20 20 70 72 69 76 61 74 65 2c 20 74 65 6d 70 6f 72   private, tempor
1bb30 61 72 79 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61  ary in-memory da
1bb40 74 61 62 61 73 65 0a 2a 2a 20 69 73 20 63 72 65  tabase.** is cre
1bb50 61 74 65 64 20 66 6f 72 20 74 68 65 20 63 6f 6e  ated for the con
1bb60 6e 65 63 74 69 6f 6e 2e 20 20 54 68 69 73 20 69  nection.  This i
1bb70 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73  n-memory databas
1bb80 65 20 77 69 6c 6c 20 76 61 6e 69 73 68 20 77 68  e will vanish wh
1bb90 65 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61  en.** the databa
1bba0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
1bbb0 20 63 6c 6f 73 65 64 2e 20 20 46 75 74 75 72 65   closed.  Future
1bbc0 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
1bbd0 69 74 65 20 6d 69 67 68 74 0a 2a 2a 20 6d 61 6b  ite might.** mak
1bbe0 65 20 75 73 65 20 6f 66 20 61 64 64 69 74 69 6f  e use of additio
1bbf0 6e 61 6c 20 73 70 65 63 69 61 6c 20 66 69 6c 65  nal special file
1bc00 6e 61 6d 65 73 20 74 68 61 74 20 62 65 67 69 6e  names that begin
1bc10 20 77 69 74 68 20 74 68 65 20 22 3a 22 20 63 68   with the ":" ch
1bc20 61 72 61 63 74 65 72 2e 0a 2a 2a 20 49 74 20 69  aracter..** It i
1bc30 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68  s recommended th
1bc40 61 74 20 77 68 65 6e 20 61 20 64 61 74 61 62 61  at when a databa
1bc50 73 65 20 66 69 6c 65 6e 61 6d 65 20 61 63 74 75  se filename actu
1bc60 61 6c 6c 79 20 64 6f 65 73 20 62 65 67 69 6e 20  ally does begin 
1bc70 77 69 74 68 0a 2a 2a 20 61 20 22 3a 22 20 63 68  with.** a ":" ch
1bc80 61 72 61 63 74 65 72 20 79 6f 75 20 73 68 6f 75  aracter you shou
1bc90 6c 64 20 70 72 65 66 69 78 20 74 68 65 20 66 69  ld prefix the fi
1bca0 6c 65 6e 61 6d 65 20 77 69 74 68 20 61 20 70 61  lename with a pa
1bcb0 74 68 6e 61 6d 65 20 73 75 63 68 20 61 73 0a 2a  thname such as.*
1bcc0 2a 20 22 2e 2f 22 20 74 6f 20 61 76 6f 69 64 20  * "./" to avoid 
1bcd0 61 6d 62 69 67 75 69 74 79 2e 0a 2a 2a 0a 2a 2a  ambiguity..**.**
1bce0 20 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65   If the filename
1bcf0 20 69 73 20 61 6e 20 65 6d 70 74 79 20 73 74 72   is an empty str
1bd00 69 6e 67 2c 20 74 68 65 6e 20 61 20 70 72 69 76  ing, then a priv
1bd10 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 0a 2a  ate, temporary.*
1bd20 2a 20 6f 6e 2d 64 69 73 6b 20 64 61 74 61 62 61  * on-disk databa
1bd30 73 65 20 77 69 6c 6c 20 62 65 20 63 72 65 61 74  se will be creat
1bd40 65 64 2e 20 20 54 68 69 73 20 70 72 69 76 61 74  ed.  This privat
1bd50 65 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20  e database will 
1bd60 62 65 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61  be.** automatica
1bd70 6c 6c 79 20 64 65 6c 65 74 65 64 20 61 73 20 73  lly deleted as s
1bd80 6f 6f 6e 20 61 73 20 74 68 65 20 64 61 74 61 62  oon as the datab
1bd90 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
1bda0 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20  s closed..**.** 
1bdb0 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  The fourth param
1bdc0 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
1bdd0 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 74 68 65  open_v2() is the
1bde0 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20   name of the.** 
1bdf0 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62  [sqlite3_vfs] ob
1be00 6a 65 63 74 20 74 68 61 74 20 64 65 66 69 6e 65  ject that define
1be10 73 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20  s the operating 
1be20 73 79 73 74 65 6d 20 69 6e 74 65 72 66 61 63 65  system interface
1be30 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e 65 77   that.** the new
1be40 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1be50 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 2e  tion should use.
1be60 20 20 49 66 20 74 68 65 20 66 6f 75 72 74 68 20    If the fourth 
1be70 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20  parameter is.** 
1be80 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74  a NULL pointer t
1be90 68 65 6e 20 74 68 65 20 64 65 66 61 75 6c 74 20  hen the default 
1bea0 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62  [sqlite3_vfs] ob
1beb0 6a 65 63 74 20 69 73 20 75 73 65 64 2e 0a 2a 2a  ject is used..**
1bec0 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57  .** <b>Note to W
1bed0 69 6e 64 6f 77 73 20 75 73 65 72 73 3a 3c 2f 62  indows users:</b
1bee0 3e 20 20 54 68 65 20 65 6e 63 6f 64 69 6e 67 20  >  The encoding 
1bef0 75 73 65 64 20 66 6f 72 20 74 68 65 20 66 69 6c  used for the fil
1bf00 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a  ename argument.*
1bf10 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 70 65  * of sqlite3_ope
1bf20 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  n() and sqlite3_
1bf30 6f 70 65 6e 5f 76 32 28 29 20 6d 75 73 74 20 62  open_v2() must b
1bf40 65 20 55 54 46 2d 38 2c 20 6e 6f 74 20 77 68 61  e UTF-8, not wha
1bf50 74 65 76 65 72 0a 2a 2a 20 63 6f 64 65 70 61 67  tever.** codepag
1bf60 65 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 64  e is currently d
1bf70 65 66 69 6e 65 64 2e 20 20 46 69 6c 65 6e 61 6d  efined.  Filenam
1bf80 65 73 20 63 6f 6e 74 61 69 6e 69 6e 67 20 69 6e  es containing in
1bf90 74 65 72 6e 61 74 69 6f 6e 61 6c 0a 2a 2a 20 63  ternational.** c
1bfa0 68 61 72 61 63 74 65 72 73 20 6d 75 73 74 20 62  haracters must b
1bfb0 65 20 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 55  e converted to U
1bfc0 54 46 2d 38 20 70 72 69 6f 72 20 74 6f 20 70 61  TF-8 prior to pa
1bfd0 73 73 69 6e 67 20 74 68 65 6d 20 69 6e 74 6f 0a  ssing them into.
1bfe0 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  ** sqlite3_open(
1bff0 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65  ) or sqlite3_ope
1c000 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 49 4e  n_v2()..**.** IN
1c010 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
1c020 7b 48 31 32 37 30 31 7d 20 54 68 65 20 5b 73 71  {H12701} The [sq
1c030 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b  lite3_open()], [
1c040 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
1c050 5d 2c 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20  ], and.**       
1c060 20 20 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e     [sqlite3_open
1c070 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65  _v2()] interface
1c080 73 20 63 72 65 61 74 65 20 61 20 6e 65 77 0a 2a  s create a new.*
1c090 2a 20 20 20 20 20 20 20 20 20 20 5b 64 61 74 61  *          [data
1c0a0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
1c0b0 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
1c0c0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
1c0d0 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 67   database file g
1c0e0 69 76 65 6e 20 69 6e 20 74 68 65 69 72 20 66 69  iven in their fi
1c0f0 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  rst parameter..*
1c100 2a 0a 2a 2a 20 7b 48 31 32 37 30 32 7d 20 54 68  *.** {H12702} Th
1c110 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d  e filename argum
1c120 65 6e 74 20 69 73 20 69 6e 74 65 72 70 72 65 74  ent is interpret
1c130 65 64 20 61 73 20 55 54 46 2d 38 0a 2a 2a 20 20  ed as UTF-8.**  
1c140 20 20 20 20 20 20 20 20 66 6f 72 20 5b 73 71 6c          for [sql
1c150 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 61 6e 64  ite3_open()] and
1c160 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
1c170 32 28 29 5d 20 61 6e 64 20 61 73 20 55 54 46 2d  2()] and as UTF-
1c180 31 36 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  16.**          i
1c190 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74  n the native byt
1c1a0 65 20 6f 72 64 65 72 20 66 6f 72 20 5b 73 71 6c  e order for [sql
1c1b0 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 0a  ite3_open16()]..
1c1c0 2a 2a 0a 2a 2a 20 7b 48 31 32 37 30 33 7d 20 41  **.** {H12703} A
1c1d0 20 73 75 63 63 65 73 73 66 75 6c 20 69 6e 76 6f   successful invo
1c1e0 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74  cation of [sqlit
1c1f0 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c  e3_open()], [sql
1c200 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 0a  ite3_open16()],.
1c210 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 5b  **          or [
1c220 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
1c230 29 5d 20 77 72 69 74 65 73 20 61 20 70 6f 69 6e  )] writes a poin
1c240 74 65 72 20 74 6f 20 61 20 6e 65 77 0a 2a 2a 20  ter to a new.** 
1c250 20 20 20 20 20 20 20 20 20 5b 64 61 74 61 62 61           [databa
1c260 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69  se connection] i
1c270 6e 74 6f 20 2a 70 70 44 62 2e 0a 2a 2a 0a 2a 2a  nto *ppDb..**.**
1c280 20 7b 48 31 32 37 30 34 7d 20 54 68 65 20 5b 73   {H12704} The [s
1c290 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20  qlite3_open()], 
1c2a0 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28  [sqlite3_open16(
1c2b0 29 5d 2c 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20  )], and.**      
1c2c0 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65      [sqlite3_ope
1c2d0 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63  n_v2()] interfac
1c2e0 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  es return [SQLIT
1c2f0 45 5f 4f 4b 5d 20 75 70 6f 6e 20 73 75 63 63 65  E_OK] upon succe
1c300 73 73 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ss,.**          
1c310 6f 72 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74  or an appropriat
1c320 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f  e [error code] o
1c330 6e 20 66 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a  n failure..**.**
1c340 20 7b 48 31 32 37 30 36 7d 20 54 68 65 20 64 65   {H12706} The de
1c350 66 61 75 6c 74 20 74 65 78 74 20 65 6e 63 6f 64  fault text encod
1c360 69 6e 67 20 66 6f 72 20 61 20 6e 65 77 20 64 61  ing for a new da
1c370 74 61 62 61 73 65 20 63 72 65 61 74 65 64 20 75  tabase created u
1c380 73 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20  sing.**         
1c390 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
1c3a0 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ] or [sqlite3_op
1c3b0 65 6e 5f 76 32 28 29 5d 20 77 69 6c 6c 20 62 65  en_v2()] will be
1c3c0 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 7b 48   UTF-8..**.** {H
1c3d0 31 32 37 30 37 7d 20 54 68 65 20 64 65 66 61 75  12707} The defau
1c3e0 6c 74 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67  lt text encoding
1c3f0 20 66 6f 72 20 61 20 6e 65 77 20 64 61 74 61 62   for a new datab
1c400 61 73 65 20 63 72 65 61 74 65 64 20 75 73 69 6e  ase created usin
1c410 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  g.**          [s
1c420 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d  qlite3_open16()]
1c430 20 77 69 6c 6c 20 62 65 20 55 54 46 2d 31 36 2e   will be UTF-16.
1c440 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 30 39 7d 20  .**.** {H12709} 
1c450 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  The [sqlite3_ope
1c460 6e 28 46 2c 44 29 5d 20 69 6e 74 65 72 66 61 63  n(F,D)] interfac
1c470 65 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20  e is equivalent 
1c480 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  to.**          [
1c490 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
1c4a0 46 2c 44 2c 47 2c 30 29 5d 20 77 68 65 72 65 20  F,D,G,0)] where 
1c4b0 74 68 65 20 47 20 70 61 72 61 6d 65 74 65 72 20  the G parameter 
1c4c0 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  is.**          [
1c4d0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
1c4e0 57 52 49 54 45 5d 7c 5b 53 51 4c 49 54 45 5f 4f  WRITE]|[SQLITE_O
1c4f0 50 45 4e 5f 43 52 45 41 54 45 5d 2e 0a 2a 2a 0a  PEN_CREATE]..**.
1c500 2a 2a 20 7b 48 31 32 37 31 31 7d 20 49 66 20 74  ** {H12711} If t
1c510 68 65 20 47 20 70 61 72 61 6d 65 74 65 72 20 74  he G parameter t
1c520 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  o [sqlite3_open_
1c530 76 32 28 46 2c 44 2c 47 2c 56 29 5d 20 63 6f 6e  v2(F,D,G,V)] con
1c540 74 61 69 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20  tains the.**    
1c550 20 20 20 20 20 20 62 69 74 20 76 61 6c 75 65 20        bit value 
1c560 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
1c570 44 4f 4e 4c 59 5d 20 74 68 65 6e 20 74 68 65 20  DONLY] then the 
1c580 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e  database is open
1c590 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66  ed.**          f
1c5a0 6f 72 20 72 65 61 64 69 6e 67 20 6f 6e 6c 79 2e  or reading only.
1c5b0 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 31 32 7d 20  .**.** {H12712} 
1c5c0 49 66 20 74 68 65 20 47 20 70 61 72 61 6d 65 74  If the G paramet
1c5d0 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f  er to [sqlite3_o
1c5e0 70 65 6e 5f 76 32 28 46 2c 44 2c 47 2c 56 29 5d  pen_v2(F,D,G,V)]
1c5f0 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 0a 2a 2a   contains the.**
1c600 20 20 20 20 20 20 20 20 20 20 62 69 74 20 76 61            bit va
1c610 6c 75 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  lue [SQLITE_OPEN
1c620 5f 52 45 41 44 57 52 49 54 45 5d 20 74 68 65 6e  _READWRITE] then
1c630 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73   the database is
1c640 20 6f 70 65 6e 65 64 0a 2a 2a 20 20 20 20 20 20   opened.**      
1c650 20 20 20 20 72 65 61 64 69 6e 67 20 61 6e 64 20      reading and 
1c660 77 72 69 74 69 6e 67 20 69 66 20 70 6f 73 73 69  writing if possi
1c670 62 6c 65 2c 20 6f 72 20 66 6f 72 20 72 65 61 64  ble, or for read
1c680 69 6e 67 20 6f 6e 6c 79 20 69 66 20 74 68 65 0a  ing only if the.
1c690 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c 65  **          file
1c6a0 20 69 73 20 77 72 69 74 65 20 70 72 6f 74 65 63   is write protec
1c6b0 74 65 64 20 62 79 20 74 68 65 20 6f 70 65 72 61  ted by the opera
1c6c0 74 69 6e 67 20 73 79 73 74 65 6d 2e 0a 2a 2a 0a  ting system..**.
1c6d0 2a 2a 20 7b 48 31 32 37 31 33 7d 20 49 66 20 74  ** {H12713} If t
1c6e0 68 65 20 47 20 70 61 72 61 6d 65 74 65 72 20 74  he G parameter t
1c6f0 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  o [sqlite3_open_
1c700 76 32 28 46 2c 44 2c 47 2c 56 29 5d 20 6f 6d 69  v2(F,D,G,V)] omi
1c710 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  ts the.**       
1c720 20 20 20 62 69 74 20 76 61 6c 75 65 20 5b 53 51     bit value [SQ
1c730 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45  LITE_OPEN_CREATE
1c740 5d 20 61 6e 64 20 74 68 65 20 64 61 74 61 62 61  ] and the databa
1c750 73 65 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 20  se does not.**  
1c760 20 20 20 20 20 20 20 20 70 72 65 76 69 6f 75 73          previous
1c770 6c 79 20 65 78 69 73 74 2c 20 61 6e 20 65 72 72  ly exist, an err
1c780 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  or is returned..
1c790 2a 2a 0a 2a 2a 20 7b 48 31 32 37 31 34 7d 20 49  **.** {H12714} I
1c7a0 66 20 74 68 65 20 47 20 70 61 72 61 6d 65 74 65  f the G paramete
1c7b0 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70  r to [sqlite3_op
1c7c0 65 6e 5f 76 32 28 46 2c 44 2c 47 2c 56 29 5d 20  en_v2(F,D,G,V)] 
1c7d0 63 6f 6e 74 61 69 6e 73 20 74 68 65 0a 2a 2a 20  contains the.** 
1c7e0 20 20 20 20 20 20 20 20 20 62 69 74 20 76 61 6c           bit val
1c7f0 75 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ue [SQLITE_OPEN_
1c800 43 52 45 41 54 45 5d 20 61 6e 64 20 74 68 65 20  CREATE] and the 
1c810 64 61 74 61 62 61 73 65 20 64 6f 65 73 20 6e 6f  database does no
1c820 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70 72  t.**          pr
1c830 65 76 69 6f 75 73 6c 79 20 65 78 69 73 74 2c 20  eviously exist, 
1c840 74 68 65 6e 20 61 6e 20 61 74 74 65 6d 70 74 20  then an attempt 
1c850 69 73 20 6d 61 64 65 20 74 6f 20 63 72 65 61 74  is made to creat
1c860 65 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20  e and.**        
1c870 20 20 69 6e 69 74 69 61 6c 69 7a 65 20 74 68 65    initialize the
1c880 20 64 61 74 61 62 61 73 65 2e 0a 2a 2a 0a 2a 2a   database..**.**
1c890 20 7b 48 31 32 37 31 37 7d 20 49 66 20 74 68 65   {H12717} If the
1c8a0 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65   filename argume
1c8b0 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f  nt to [sqlite3_o
1c8c0 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  pen()], [sqlite3
1c8d0 5f 6f 70 65 6e 31 36 28 29 5d 2c 0a 2a 2a 20 20  _open16()],.**  
1c8e0 20 20 20 20 20 20 20 20 6f 72 20 5b 73 71 6c 69          or [sqli
1c8f0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69  te3_open_v2()] i
1c900 73 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20 74 68  s ":memory:", th
1c910 65 6e 20 61 6e 20 70 72 69 76 61 74 65 2c 0a 2a  en an private,.*
1c920 2a 20 20 20 20 20 20 20 20 20 20 65 70 68 65 6d  *          ephem
1c930 65 72 61 6c 2c 20 69 6e 2d 6d 65 6d 6f 72 79 20  eral, in-memory 
1c940 64 61 74 61 62 61 73 65 20 69 73 20 63 72 65 61  database is crea
1c950 74 65 64 20 66 6f 72 20 74 68 65 20 63 6f 6e 6e  ted for the conn
1c960 65 63 74 69 6f 6e 2e 0a 2a 2a 20 20 20 20 20 20  ection..**      
1c970 20 20 20 20 3c 74 6f 64 6f 3e 49 73 20 53 51 4c      <todo>Is SQL
1c980 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 7c  ITE_OPEN_CREATE|
1c990 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
1c9a0 57 52 49 54 45 20 72 65 71 75 69 72 65 64 0a 2a  WRITE required.*
1c9b0 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20 73 71  *          in sq
1c9c0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 3f  lite3_open_v2()?
1c9d0 3c 2f 74 6f 64 6f 3e 0a 2a 2a 0a 2a 2a 20 7b 48  </todo>.**.** {H
1c9e0 31 32 37 31 39 7d 20 49 66 20 74 68 65 20 66 69  12719} If the fi
1c9f0 6c 65 6e 61 6d 65 20 69 73 20 4e 55 4c 4c 20 6f  lename is NULL o
1ca00 72 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e  r an empty strin
1ca10 67 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61 74  g, then a privat
1ca20 65 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 65  e,.**          e
1ca30 70 68 65 6d 65 72 61 6c 20 6f 6e 2d 64 69 73 6b  phemeral on-disk
1ca40 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62   database will b
1ca50 65 20 63 72 65 61 74 65 64 2e 0a 2a 2a 20 20 20  e created..**   
1ca60 20 20 20 20 20 20 20 3c 74 6f 64 6f 3e 49 73 20         <todo>Is 
1ca70 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41  SQLITE_OPEN_CREA
1ca80 54 45 7c 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  TE|SQLITE_OPEN_R
1ca90 45 41 44 57 52 49 54 45 20 72 65 71 75 69 72 65  EADWRITE require
1caa0 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e  d.**          in
1cab0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
1cac0 28 29 3f 3c 2f 74 6f 64 6f 3e 0a 2a 2a 0a 2a 2a  ()?</todo>.**.**
1cad0 20 7b 48 31 32 37 32 31 7d 20 54 68 65 20 5b 64   {H12721} The [d
1cae0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1caf0 6f 6e 5d 20 63 72 65 61 74 65 64 20 62 79 20 5b  on] created by [
1cb00 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
1cb10 46 2c 44 2c 47 2c 56 29 5d 0a 2a 2a 20 20 20 20  F,D,G,V)].**    
1cb20 20 20 20 20 20 20 77 69 6c 6c 20 75 73 65 20 74        will use t
1cb30 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  he [sqlite3_vfs]
1cb40 20 6f 62 6a 65 63 74 20 69 64 65 6e 74 69 66 69   object identifi
1cb50 65 64 20 62 79 20 74 68 65 20 56 20 70 61 72 61  ed by the V para
1cb60 6d 65 74 65 72 2c 0a 2a 2a 20 20 20 20 20 20 20  meter,.**       
1cb70 20 20 20 6f 72 20 74 68 65 20 64 65 66 61 75 6c     or the defaul
1cb80 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  t [sqlite3_vfs] 
1cb90 6f 62 6a 65 63 74 20 69 66 20 56 20 69 73 20 61  object if V is a
1cba0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a   NULL pointer..*
1cbb0 2a 0a 2a 2a 20 7b 48 31 32 37 32 33 7d 20 54 77  *.** {H12723} Tw
1cbc0 6f 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  o [database conn
1cbd0 65 63 74 69 6f 6e 73 5d 20 77 69 6c 6c 20 73 68  ections] will sh
1cbe0 61 72 65 20 61 20 63 6f 6d 6d 6f 6e 20 63 61 63  are a common cac
1cbf0 68 65 20 69 66 20 62 6f 74 68 20 77 65 72 65 0a  he if both were.
1cc00 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 70 65 6e  **          open
1cc10 65 64 20 77 69 74 68 20 74 68 65 20 73 61 6d 65  ed with the same
1cc20 20 56 46 53 20 77 68 69 6c 65 20 5b 73 68 61 72   VFS while [shar
1cc30 65 64 20 63 61 63 68 65 20 6d 6f 64 65 5d 20 77  ed cache mode] w
1cc40 61 73 20 65 6e 61 62 6c 65 64 20 61 6e 64 0a 2a  as enabled and.*
1cc50 2a 20 20 20 20 20 20 20 20 20 20 69 66 20 62 6f  *          if bo
1cc60 74 68 20 66 69 6c 65 6e 61 6d 65 73 20 63 6f 6d  th filenames com
1cc70 70 61 72 65 20 65 71 75 61 6c 20 75 73 69 6e 67  pare equal using
1cc80 20 6d 65 6d 63 6d 70 28 29 20 61 66 74 65 72 20   memcmp() after 
1cc90 68 61 76 69 6e 67 20 62 65 65 6e 0a 2a 2a 20 20  having been.**  
1cca0 20 20 20 20 20 20 20 20 70 72 6f 63 65 73 73 65          processe
1ccb0 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65  d by the [sqlite
1ccc0 33 5f 76 66 73 20 7c 20 78 46 75 6c 6c 50 61 74  3_vfs | xFullPat
1ccd0 68 6e 61 6d 65 5d 20 6d 65 74 68 6f 64 20 6f 66  hname] method of
1cce0 20 74 68 65 20 56 46 53 2e 0a 2a 2f 0a 69 6e 74   the VFS..*/.int
1ccf0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 0a 20   sqlite3_open(. 
1cd00 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 6c   const char *fil
1cd10 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61  ename,   /* Data
1cd20 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55  base filename (U
1cd30 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74  TF-8) */.  sqlit
1cd40 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20 20  e3 **ppDb       
1cd50 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74     /* OUT: SQLit
1cd60 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29  e db handle */.)
1cd70 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70  ;.int sqlite3_op
1cd80 65 6e 31 36 28 0a 20 20 63 6f 6e 73 74 20 76 6f  en16(.  const vo
1cd90 69 64 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20  id *filename,   
1cda0 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65  /* Database file
1cdb0 6e 61 6d 65 20 28 55 54 46 2d 31 36 29 20 2a 2f  name (UTF-16) */
1cdc0 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44  .  sqlite3 **ppD
1cdd0 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55  b          /* OU
1cde0 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e  T: SQLite db han
1cdf0 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71  dle */.);.int sq
1ce00 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 0a 20  lite3_open_v2(. 
1ce10 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 6c   const char *fil
1ce20 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61  ename,   /* Data
1ce30 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55  base filename (U
1ce40 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74  TF-8) */.  sqlit
1ce50 65 33 20 2a 2a 70 70 44 62 2c 20 20 20 20 20 20  e3 **ppDb,      
1ce60 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74     /* OUT: SQLit
1ce70 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  e db handle */. 
1ce80 20 69 6e 74 20 66 6c 61 67 73 2c 20 20 20 20 20   int flags,     
1ce90 20 20 20 20 20 20 20 20 20 2f 2a 20 46 6c 61 67           /* Flag
1cea0 73 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  s */.  const cha
1ceb0 72 20 2a 7a 56 66 73 20 20 20 20 20 20 20 20 2f  r *zVfs        /
1cec0 2a 20 4e 61 6d 65 20 6f 66 20 56 46 53 20 6d 6f  * Name of VFS mo
1ced0 64 75 6c 65 20 74 6f 20 75 73 65 20 2a 2f 0a 29  dule to use */.)
1cee0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1cef0 46 3a 20 45 72 72 6f 72 20 43 6f 64 65 73 20 41  F: Error Codes A
1cf00 6e 64 20 4d 65 73 73 61 67 65 73 20 7b 48 31 32  nd Messages {H12
1cf10 38 30 30 7d 20 3c 53 36 30 32 30 30 3e 0a 2a 2a  800} <S60200>.**
1cf20 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
1cf30 65 72 72 63 6f 64 65 28 29 20 69 6e 74 65 72 66  errcode() interf
1cf40 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ace returns the 
1cf50 6e 75 6d 65 72 69 63 20 5b 72 65 73 75 6c 74 20  numeric [result 
1cf60 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74  code] or.** [ext
1cf70 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
1cf80 65 5d 20 66 6f 72 20 74 68 65 20 6d 6f 73 74 20  e] for the most 
1cf90 72 65 63 65 6e 74 20 66 61 69 6c 65 64 20 73 71  recent failed sq
1cfa0 6c 69 74 65 33 5f 2a 20 41 50 49 20 63 61 6c 6c  lite3_* API call
1cfb0 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77  .** associated w
1cfc0 69 74 68 20 61 20 5b 64 61 74 61 62 61 73 65 20  ith a [database 
1cfd0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 49 66 20  connection]. If 
1cfe0 61 20 70 72 69 6f 72 20 41 50 49 20 63 61 6c 6c  a prior API call
1cff0 20 66 61 69 6c 65 64 0a 2a 2a 20 62 75 74 20 74   failed.** but t
1d000 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 41  he most recent A
1d010 50 49 20 63 61 6c 6c 20 73 75 63 63 65 65 64 65  PI call succeede
1d020 64 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  d, the return va
1d030 6c 75 65 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69  lue from.** sqli
1d040 74 65 33 5f 65 72 72 63 6f 64 65 28 29 20 69 73  te3_errcode() is
1d050 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
1d060 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72  * The sqlite3_er
1d070 72 6d 73 67 28 29 20 61 6e 64 20 73 71 6c 69 74  rmsg() and sqlit
1d080 65 33 5f 65 72 72 6d 73 67 31 36 28 29 20 72 65  e3_errmsg16() re
1d090 74 75 72 6e 20 45 6e 67 6c 69 73 68 2d 6c 61 6e  turn English-lan
1d0a0 67 75 61 67 65 0a 2a 2a 20 74 65 78 74 20 74 68  guage.** text th
1d0b0 61 74 20 64 65 73 63 72 69 62 65 73 20 74 68 65  at describes the
1d0c0 20 65 72 72 6f 72 2c 20 61 73 20 65 69 74 68 65   error, as eithe
1d0d0 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31  r UTF-8 or UTF-1
1d0e0 36 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a  6 respectively..
1d0f0 2a 2a 20 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c  ** Memory to hol
1d100 64 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73  d the error mess
1d110 61 67 65 20 73 74 72 69 6e 67 20 69 73 20 6d 61  age string is ma
1d120 6e 61 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79  naged internally
1d130 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  ..** The applica
1d140 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 6e 65  tion does not ne
1d150 65 64 20 74 6f 20 77 6f 72 72 79 20 61 62 6f 75  ed to worry abou
1d160 74 20 66 72 65 65 69 6e 67 20 74 68 65 20 72 65  t freeing the re
1d170 73 75 6c 74 2e 0a 2a 2a 20 48 6f 77 65 76 65 72  sult..** However
1d180 2c 20 74 68 65 20 65 72 72 6f 72 20 73 74 72 69  , the error stri
1d190 6e 67 20 6d 69 67 68 74 20 62 65 20 6f 76 65 72  ng might be over
1d1a0 77 72 69 74 74 65 6e 20 6f 72 20 64 65 61 6c 6c  written or deall
1d1b0 6f 63 61 74 65 64 20 62 79 0a 2a 2a 20 73 75 62  ocated by.** sub
1d1c0 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f  sequent calls to
1d1d0 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e   other SQLite in
1d1e0 74 65 72 66 61 63 65 20 66 75 6e 63 74 69 6f 6e  terface function
1d1f0 73 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 69  s..**.** If an i
1d200 6e 74 65 72 66 61 63 65 20 66 61 69 6c 73 20 77  nterface fails w
1d210 69 74 68 20 53 51 4c 49 54 45 5f 4d 49 53 55 53  ith SQLITE_MISUS
1d220 45 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68  E, that means th
1d230 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 77  e interface.** w
1d240 61 73 20 69 6e 76 6f 6b 65 64 20 69 6e 63 6f 72  as invoked incor
1d250 72 65 63 74 6c 79 20 62 79 20 74 68 65 20 61 70  rectly by the ap
1d260 70 6c 69 63 61 74 69 6f 6e 2e 20 20 49 6e 20 74  plication.  In t
1d270 68 61 74 20 63 61 73 65 2c 20 74 68 65 0a 2a 2a  hat case, the.**
1d280 20 65 72 72 6f 72 20 63 6f 64 65 20 61 6e 64 20   error code and 
1d290 6d 65 73 73 61 67 65 20 6d 61 79 20 6f 72 20 6d  message may or m
1d2a0 61 79 20 6e 6f 74 20 62 65 20 73 65 74 2e 0a 2a  ay not be set..*
1d2b0 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
1d2c0 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 38 30 31 7d 20  .**.** {H12801} 
1d2d0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 65 72 72  The [sqlite3_err
1d2e0 63 6f 64 65 28 44 29 5d 20 69 6e 74 65 72 66 61  code(D)] interfa
1d2f0 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  ce returns the n
1d300 75 6d 65 72 69 63 0a 2a 2a 20 20 20 20 20 20 20  umeric.**       
1d310 20 20 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d     [result code]
1d320 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 20 72 65   or [extended re
1d330 73 75 6c 74 20 63 6f 64 65 5d 20 66 6f 72 20 74  sult code] for t
1d340 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79  he most recently
1d350 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 61 69  .**          fai
1d360 6c 65 64 20 69 6e 74 65 72 66 61 63 65 20 63 61  led interface ca
1d370 6c 6c 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ll associated wi
1d380 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  th the [database
1d390 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2e 0a   connection] D..
1d3a0 2a 2a 0a 2a 2a 20 7b 48 31 32 38 30 33 7d 20 54  **.** {H12803} T
1d3b0 68 65 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d  he [sqlite3_errm
1d3c0 73 67 28 44 29 5d 20 61 6e 64 20 5b 73 71 6c 69  sg(D)] and [sqli
1d3d0 74 65 33 5f 65 72 72 6d 73 67 31 36 28 44 29 5d  te3_errmsg16(D)]
1d3e0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74  .**          int
1d3f0 65 72 66 61 63 65 73 20 72 65 74 75 72 6e 20 45  erfaces return E
1d400 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65 20  nglish-language 
1d410 74 65 78 74 20 74 68 61 74 20 64 65 73 63 72 69  text that descri
1d420 62 65 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  bes.**          
1d430 74 68 65 20 65 72 72 6f 72 20 69 6e 20 74 68 65  the error in the
1d440 20 6d 6f 73 74 6c 79 20 72 65 63 65 6e 74 6c 79   mostly recently
1d450 20 66 61 69 6c 65 64 20 69 6e 74 65 72 66 61 63   failed interfac
1d460 65 20 63 61 6c 6c 2c 0a 2a 2a 20 20 20 20 20 20  e call,.**      
1d470 20 20 20 20 65 6e 63 6f 64 65 64 20 61 73 20 65      encoded as e
1d480 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55  ither UTF-8 or U
1d490 54 46 2d 31 36 20 72 65 73 70 65 63 74 69 76 65  TF-16 respective
1d4a0 6c 79 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 38 30  ly..**.** {H1280
1d4b0 37 7d 20 54 68 65 20 73 74 72 69 6e 67 73 20 72  7} The strings r
1d4c0 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69  eturned by [sqli
1d4d0 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 20 61 6e  te3_errmsg()] an
1d4e0 64 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  d [sqlite3_errms
1d4f0 67 31 36 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20  g16()].**       
1d500 20 20 20 61 72 65 20 76 61 6c 69 64 20 75 6e 74     are valid unt
1d510 69 6c 20 74 68 65 20 6e 65 78 74 20 53 51 4c 69  il the next SQLi
1d520 74 65 20 69 6e 74 65 72 66 61 63 65 20 63 61 6c  te interface cal
1d530 6c 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 38 30 38  l..**.** {H12808
1d540 7d 20 43 61 6c 6c 73 20 74 6f 20 41 50 49 20 72  } Calls to API r
1d550 6f 75 74 69 6e 65 73 20 74 68 61 74 20 64 6f 20  outines that do 
1d560 6e 6f 74 20 72 65 74 75 72 6e 20 61 6e 20 65 72  not return an er
1d570 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 20 20 20 20  ror code.**     
1d580 20 20 20 20 20 28 65 78 61 6d 70 6c 65 3a 20 5b       (example: [
1d590 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75  sqlite3_data_cou
1d5a0 6e 74 28 29 5d 29 20 64 6f 20 6e 6f 74 0a 2a 2a  nt()]) do not.**
1d5b0 20 20 20 20 20 20 20 20 20 20 63 68 61 6e 67 65            change
1d5c0 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 20   the error code 
1d5d0 6f 72 20 6d 65 73 73 61 67 65 20 72 65 74 75 72  or message retur
1d5e0 6e 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 20  ned by.**       
1d5f0 20 20 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63     [sqlite3_errc
1d600 6f 64 65 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  ode()], [sqlite3
1d610 5f 65 72 72 6d 73 67 28 29 5d 2c 20 6f 72 20 5b  _errmsg()], or [
1d620 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36  sqlite3_errmsg16
1d630 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 38  ()]..**.** {H128
1d640 30 39 7d 20 49 6e 74 65 72 66 61 63 65 73 20 74  09} Interfaces t
1d650 68 61 74 20 61 72 65 20 6e 6f 74 20 61 73 73 6f  hat are not asso
1d660 63 69 61 74 65 64 20 77 69 74 68 20 61 20 73 70  ciated with a sp
1d670 65 63 69 66 69 63 0a 2a 2a 20 20 20 20 20 20 20  ecific.**       
1d680 20 20 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e     [database con
1d690 6e 65 63 74 69 6f 6e 5d 20 28 65 78 61 6d 70 6c  nection] (exampl
1d6a0 65 73 3a 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  es:.**          
1d6b0 5b 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66  [sqlite3_mprintf
1d6c0 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
1d6d0 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 61  enable_shared_ca
1d6e0 63 68 65 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20  che()].**       
1d6f0 20 20 20 64 6f 20 6e 6f 74 20 63 68 61 6e 67 65     do not change
1d700 20 74 68 65 20 76 61 6c 75 65 73 20 72 65 74 75   the values retu
1d710 72 6e 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 20  rned by.**      
1d720 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 65 72 72      [sqlite3_err
1d730 63 6f 64 65 28 29 5d 2c 20 5b 73 71 6c 69 74 65  code()], [sqlite
1d740 33 5f 65 72 72 6d 73 67 28 29 5d 2c 20 6f 72 20  3_errmsg()], or 
1d750 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31  [sqlite3_errmsg1
1d760 36 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  6()]..*/.int sql
1d770 69 74 65 33 5f 65 72 72 63 6f 64 65 28 73 71 6c  ite3_errcode(sql
1d780 69 74 65 33 20 2a 64 62 29 3b 0a 63 6f 6e 73 74  ite3 *db);.const
1d790 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 65   char *sqlite3_e
1d7a0 72 72 6d 73 67 28 73 71 6c 69 74 65 33 2a 29 3b  rrmsg(sqlite3*);
1d7b0 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
1d7c0 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 73 71  ite3_errmsg16(sq
1d7d0 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  lite3*);../*.** 
1d7e0 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20 53 74  CAPI3REF: SQL St
1d7f0 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 20 7b  atement Object {
1d800 48 31 33 30 30 30 7d 20 3c 48 31 33 30 31 30 3e  H13000} <H13010>
1d810 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70  .** KEYWORDS: {p
1d820 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
1d830 74 7d 20 7b 70 72 65 70 61 72 65 64 20 73 74 61  t} {prepared sta
1d840 74 65 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20 41  tements}.**.** A
1d850 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
1d860 69 73 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73  is object repres
1d870 65 6e 74 73 20 61 20 73 69 6e 67 6c 65 20 53 51  ents a single SQ
1d880 4c 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20  L statement..** 
1d890 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 76  This object is v
1d8a0 61 72 69 6f 75 73 6c 79 20 6b 6e 6f 77 6e 20 61  ariously known a
1d8b0 73 20 61 20 22 70 72 65 70 61 72 65 64 20 73 74  s a "prepared st
1d8c0 61 74 65 6d 65 6e 74 22 20 6f 72 20 61 0a 2a 2a  atement" or a.**
1d8d0 20 22 63 6f 6d 70 69 6c 65 64 20 53 51 4c 20 73   "compiled SQL s
1d8e0 74 61 74 65 6d 65 6e 74 22 20 6f 72 20 73 69 6d  tatement" or sim
1d8f0 70 6c 79 20 61 73 20 61 20 22 73 74 61 74 65 6d  ply as a "statem
1d900 65 6e 74 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ent"..**.** The 
1d910 6c 69 66 65 20 6f 66 20 61 20 73 74 61 74 65 6d  life of a statem
1d920 65 6e 74 20 6f 62 6a 65 63 74 20 67 6f 65 73 20  ent object goes 
1d930 73 6f 6d 65 74 68 69 6e 67 20 6c 69 6b 65 20 74  something like t
1d940 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a  his:.**.** <ol>.
1d950 2a 2a 20 3c 6c 69 3e 20 43 72 65 61 74 65 20 74  ** <li> Create t
1d960 68 65 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20  he object using 
1d970 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1d980 5f 76 32 28 29 5d 20 6f 72 20 61 20 72 65 6c 61  _v2()] or a rela
1d990 74 65 64 0a 2a 2a 20 20 20 20 20 20 66 75 6e 63  ted.**      func
1d9a0 74 69 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e 20 42 69  tion..** <li> Bi
1d9b0 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 5b 68 6f  nd values to [ho
1d9c0 73 74 20 70 61 72 61 6d 65 74 65 72 73 5d 20 75  st parameters] u
1d9d0 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33  sing the sqlite3
1d9e0 5f 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20 20 20 20  _bind_*().**    
1d9f0 20 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a    interfaces..**
1da00 20 3c 6c 69 3e 20 52 75 6e 20 74 68 65 20 53 51   <li> Run the SQ
1da10 4c 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71  L by calling [sq
1da20 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 6e  lite3_step()] on
1da30 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e  e or more times.
1da40 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73 65 74 20 74  .** <li> Reset t
1da50 68 65 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69  he statement usi
1da60 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ng [sqlite3_rese
1da70 74 28 29 5d 20 74 68 65 6e 20 67 6f 20 62 61 63  t()] then go bac
1da80 6b 0a 2a 2a 20 20 20 20 20 20 74 6f 20 73 74 65  k.**      to ste
1da90 70 20 32 2e 20 20 44 6f 20 74 68 69 73 20 7a 65  p 2.  Do this ze
1daa0 72 6f 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73  ro or more times
1dab0 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73 74 72 6f  ..** <li> Destro
1dac0 79 20 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69  y the object usi
1dad0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  ng [sqlite3_fina
1dae0 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c  lize()]..** </ol
1daf0 3e 0a 2a 2a 0a 2a 2a 20 52 65 66 65 72 20 74 6f  >.**.** Refer to
1db00 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 6f   documentation o
1db10 6e 20 69 6e 64 69 76 69 64 75 61 6c 20 6d 65 74  n individual met
1db20 68 6f 64 73 20 61 62 6f 76 65 20 66 6f 72 20 61  hods above for a
1db30 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66  dditional.** inf
1db40 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70  ormation..*/.typ
1db50 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
1db60 74 65 33 5f 73 74 6d 74 20 73 71 6c 69 74 65 33  te3_stmt sqlite3
1db70 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  _stmt;../*.** CA
1db80 50 49 33 52 45 46 3a 20 52 75 6e 2d 74 69 6d 65  PI3REF: Run-time
1db90 20 4c 69 6d 69 74 73 20 7b 48 31 32 37 36 30 7d   Limits {H12760}
1dba0 20 3c 53 32 30 36 30 30 3e 0a 2a 2a 0a 2a 2a 20   <S20600>.**.** 
1dbb0 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 61  This interface a
1dbc0 6c 6c 6f 77 73 20 74 68 65 20 73 69 7a 65 20 6f  llows the size o
1dbd0 66 20 76 61 72 69 6f 75 73 20 63 6f 6e 73 74 72  f various constr
1dbe0 75 63 74 73 20 74 6f 20 62 65 20 6c 69 6d 69 74  ucts to be limit
1dbf0 65 64 0a 2a 2a 20 6f 6e 20 61 20 63 6f 6e 6e 65  ed.** on a conne
1dc00 63 74 69 6f 6e 20 62 79 20 63 6f 6e 6e 65 63 74  ction by connect
1dc10 69 6f 6e 20 62 61 73 69 73 2e 20 20 54 68 65 20  ion basis.  The 
1dc20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
1dc30 69 73 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62  is the.** [datab
1dc40 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
1dc50 77 68 6f 73 65 20 6c 69 6d 69 74 20 69 73 20 74  whose limit is t
1dc60 6f 20 62 65 20 73 65 74 20 6f 72 20 71 75 65 72  o be set or quer
1dc70 69 65 64 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63  ied.  The.** sec
1dc80 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ond parameter is
1dc90 20 6f 6e 65 20 6f 66 20 74 68 65 20 5b 6c 69 6d   one of the [lim
1dca0 69 74 20 63 61 74 65 67 6f 72 69 65 73 5d 20 74  it categories] t
1dcb0 68 61 74 20 64 65 66 69 6e 65 20 61 0a 2a 2a 20  hat define a.** 
1dcc0 63 6c 61 73 73 20 6f 66 20 63 6f 6e 73 74 72 75  class of constru
1dcd0 63 74 73 20 74 6f 20 62 65 20 73 69 7a 65 20 6c  cts to be size l
1dce0 69 6d 69 74 65 64 2e 20 20 54 68 65 20 74 68 69  imited.  The thi
1dcf0 72 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  rd parameter is 
1dd00 74 68 65 0a 2a 2a 20 6e 65 77 20 6c 69 6d 69 74  the.** new limit
1dd10 20 66 6f 72 20 74 68 61 74 20 63 6f 6e 73 74 72   for that constr
1dd20 75 63 74 2e 20 20 54 68 65 20 66 75 6e 63 74 69  uct.  The functi
1dd30 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6f  on returns the o
1dd40 6c 64 20 6c 69 6d 69 74 2e 0a 2a 2a 0a 2a 2a 20  ld limit..**.** 
1dd50 49 66 20 74 68 65 20 6e 65 77 20 6c 69 6d 69 74  If the new limit
1dd60 20 69 73 20 61 20 6e 65 67 61 74 69 76 65 20 6e   is a negative n
1dd70 75 6d 62 65 72 2c 20 74 68 65 20 6c 69 6d 69 74  umber, the limit
1dd80 20 69 73 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a   is unchanged..*
1dd90 2a 20 46 6f 72 20 74 68 65 20 6c 69 6d 69 74 20  * For the limit 
1dda0 63 61 74 65 67 6f 72 79 20 6f 66 20 53 51 4c 49  category of SQLI
1ddb0 54 45 5f 4c 49 4d 49 54 5f 58 59 5a 20 74 68 65  TE_LIMIT_XYZ the
1ddc0 72 65 20 69 73 20 61 20 68 61 72 64 20 75 70 70  re is a hard upp
1ddd0 65 72 0a 2a 2a 20 62 6f 75 6e 64 20 73 65 74 20  er.** bound set 
1dde0 62 79 20 61 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  by a compile-tim
1ddf0 65 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72  e C preprocessor
1de00 20 6d 61 63 72 6f 20 6e 61 6d 65 64 20 53 51 4c   macro named SQL
1de10 49 54 45 5f 4d 41 58 5f 58 59 5a 2e 0a 2a 2a 20  ITE_MAX_XYZ..** 
1de20 28 54 68 65 20 22 5f 4c 49 4d 49 54 5f 22 20 69  (The "_LIMIT_" i
1de30 6e 20 74 68 65 20 6e 61 6d 65 20 69 73 20 63 68  n the name is ch
1de40 61 6e 67 65 64 20 74 6f 20 22 5f 4d 41 58 5f 22  anged to "_MAX_"
1de50 2e 29 0a 2a 2a 20 41 74 74 65 6d 70 74 73 20 74  .).** Attempts t
1de60 6f 20 69 6e 63 72 65 61 73 65 20 61 20 6c 69 6d  o increase a lim
1de70 69 74 20 61 62 6f 76 65 20 69 74 73 20 68 61 72  it above its har
1de80 64 20 75 70 70 65 72 20 62 6f 75 6e 64 20 61 72  d upper bound ar
1de90 65 0a 2a 2a 20 73 69 6c 65 6e 74 6c 79 20 74 72  e.** silently tr
1dea0 75 6e 63 61 74 65 64 20 74 6f 20 74 68 65 20 68  uncated to the h
1deb0 61 72 64 20 75 70 70 65 72 20 6c 69 6d 69 74 2e  ard upper limit.
1dec0 0a 2a 2a 0a 2a 2a 20 52 75 6e 20 74 69 6d 65 20  .**.** Run time 
1ded0 6c 69 6d 69 74 73 20 61 72 65 20 69 6e 74 65 6e  limits are inten
1dee0 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e 20 61  ded for use in a
1def0 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74  pplications that
1df00 20 6d 61 6e 61 67 65 0a 2a 2a 20 62 6f 74 68 20   manage.** both 
1df10 74 68 65 69 72 20 6f 77 6e 20 69 6e 74 65 72 6e  their own intern
1df20 61 6c 20 64 61 74 61 62 61 73 65 20 61 6e 64 20  al database and 
1df30 61 6c 73 6f 20 64 61 74 61 62 61 73 65 73 20 74  also databases t
1df40 68 61 74 20 61 72 65 20 63 6f 6e 74 72 6f 6c 6c  hat are controll
1df50 65 64 0a 2a 2a 20 62 79 20 75 6e 74 72 75 73 74  ed.** by untrust
1df60 65 64 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72  ed external sour
1df70 63 65 73 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65  ces.  An example
1df80 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 69 67   application mig
1df90 68 74 20 62 65 20 61 0a 2a 2a 20 77 65 62 62 72  ht be a.** webbr
1dfa0 6f 77 73 65 72 20 74 68 61 74 20 68 61 73 20 69  owser that has i
1dfb0 74 73 20 6f 77 6e 20 64 61 74 61 62 61 73 65 73  ts own databases
1dfc0 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 68 69 73   for storing his
1dfd0 74 6f 72 79 20 61 6e 64 0a 2a 2a 20 73 65 70 61  tory and.** sepa
1dfe0 72 61 74 65 20 64 61 74 61 62 61 73 65 73 20 63  rate databases c
1dff0 6f 6e 74 72 6f 6c 6c 65 64 20 62 79 20 4a 61 76  ontrolled by Jav
1e000 61 53 63 72 69 70 74 20 61 70 70 6c 69 63 61 74  aScript applicat
1e010 69 6f 6e 73 20 64 6f 77 6e 6c 6f 61 64 65 64 0a  ions downloaded.
1e020 2a 2a 20 6f 66 66 20 74 68 65 20 49 6e 74 65 72  ** off the Inter
1e030 6e 65 74 2e 20 20 54 68 65 20 69 6e 74 65 72 6e  net.  The intern
1e040 61 6c 20 64 61 74 61 62 61 73 65 73 20 63 61 6e  al databases can
1e050 20 62 65 20 67 69 76 65 6e 20 74 68 65 0a 2a 2a   be given the.**
1e060 20 6c 61 72 67 65 2c 20 64 65 66 61 75 6c 74 20   large, default 
1e070 6c 69 6d 69 74 73 2e 20 20 44 61 74 61 62 61 73  limits.  Databas
1e080 65 73 20 6d 61 6e 61 67 65 64 20 62 79 20 65 78  es managed by ex
1e090 74 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 20 63  ternal sources c
1e0a0 61 6e 0a 2a 2a 20 62 65 20 67 69 76 65 6e 20 6d  an.** be given m
1e0b0 75 63 68 20 73 6d 61 6c 6c 65 72 20 6c 69 6d 69  uch smaller limi
1e0c0 74 73 20 64 65 73 69 67 6e 65 64 20 74 6f 20 70  ts designed to p
1e0d0 72 65 76 65 6e 74 20 61 20 64 65 6e 69 61 6c 20  revent a denial 
1e0e0 6f 66 20 73 65 72 76 69 63 65 0a 2a 2a 20 61 74  of service.** at
1e0f0 74 61 63 6b 2e 20 20 44 65 76 65 6c 6f 70 65 72  tack.  Developer
1e100 73 20 6d 69 67 68 74 20 61 6c 73 6f 20 77 61 6e  s might also wan
1e110 74 20 74 6f 20 75 73 65 20 74 68 65 20 5b 73 71  t to use the [sq
1e120 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
1e130 69 7a 65 72 28 29 5d 0a 2a 2a 20 69 6e 74 65 72  izer()].** inter
1e140 66 61 63 65 20 74 6f 20 66 75 72 74 68 65 72 20  face to further 
1e150 63 6f 6e 74 72 6f 6c 20 75 6e 74 72 75 73 74 65  control untruste
1e160 64 20 53 51 4c 2e 20 20 54 68 65 20 73 69 7a 65  d SQL.  The size
1e170 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
1e180 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 79 20 61  .** created by a
1e190 6e 20 75 6e 74 72 75 73 74 65 64 20 73 63 72 69  n untrusted scri
1e1a0 70 74 20 63 61 6e 20 62 65 20 63 6f 6e 74 61 69  pt can be contai
1e1b0 6e 65 64 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a  ned using the.**
1e1c0 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74   [max_page_count
1e1d0 5d 20 5b 50 52 41 47 4d 41 5d 2e 0a 2a 2a 0a 2a  ] [PRAGMA]..**.*
1e1e0 2a 20 4e 65 77 20 72 75 6e 2d 74 69 6d 65 20 6c  * New run-time l
1e1f0 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 20  imit categories 
1e200 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20  may be added in 
1e210 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 2e  future releases.
1e220 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
1e230 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 36 32  S:.**.** {H12762
1e240 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 63  } A successful c
1e250 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
1e260 6c 69 6d 69 74 28 44 2c 43 2c 56 29 5d 20 77 68  limit(D,C,V)] wh
1e270 65 72 65 20 56 20 69 73 0a 2a 2a 20 20 20 20 20  ere V is.**     
1e280 20 20 20 20 20 70 6f 73 69 74 69 76 65 20 63 68       positive ch
1e290 61 6e 67 65 73 20 74 68 65 20 6c 69 6d 69 74 20  anges the limit 
1e2a0 6f 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 63  on the size of c
1e2b0 6f 6e 73 74 72 75 63 74 20 43 20 69 6e 20 74 68  onstruct C in th
1e2c0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 64  e.**          [d
1e2d0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1e2e0 6f 6e 5d 20 44 20 74 6f 20 74 68 65 20 6c 65 73  on] D to the les
1e2f0 73 65 72 20 6f 66 20 56 20 61 6e 64 20 74 68 65  ser of V and the
1e300 20 68 61 72 64 20 75 70 70 65 72 0a 2a 2a 20 20   hard upper.**  
1e310 20 20 20 20 20 20 20 20 62 6f 75 6e 64 20 6f 6e          bound on
1e320 20 74 68 65 20 73 69 7a 65 20 6f 66 20 43 20 74   the size of C t
1e330 68 61 74 20 69 73 20 73 65 74 20 61 74 20 63 6f  hat is set at co
1e340 6d 70 69 6c 65 2d 74 69 6d 65 2e 0a 2a 2a 0a 2a  mpile-time..**.*
1e350 2a 20 7b 48 31 32 37 36 36 7d 20 41 20 73 75 63  * {H12766} A suc
1e360 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20  cessful call to 
1e370 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 44  [sqlite3_limit(D
1e380 2c 43 2c 56 29 5d 20 77 68 65 72 65 20 56 20 69  ,C,V)] where V i
1e390 73 20 6e 65 67 61 74 69 76 65 0a 2a 2a 20 20 20  s negative.**   
1e3a0 20 20 20 20 20 20 20 6c 65 61 76 65 73 20 74 68         leaves th
1e3b0 65 20 73 74 61 74 65 20 6f 66 20 74 68 65 20 5b  e state of the [
1e3c0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1e3d0 69 6f 6e 5d 20 44 20 75 6e 63 68 61 6e 67 65 64  ion] D unchanged
1e3e0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 36 39 7d  ..**.** {H12769}
1e3f0 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 63 61   A successful ca
1e400 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6c  ll to [sqlite3_l
1e410 69 6d 69 74 28 44 2c 43 2c 56 29 5d 20 72 65 74  imit(D,C,V)] ret
1e420 75 72 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20 20  urns the.**     
1e430 20 20 20 20 20 76 61 6c 75 65 20 6f 66 20 74 68       value of th
1e440 65 20 6c 69 6d 69 74 20 6f 6e 20 74 68 65 20 73  e limit on the s
1e450 69 7a 65 20 6f 66 20 63 6f 6e 73 74 72 75 63 74  ize of construct
1e460 20 43 20 69 6e 20 74 68 65 0a 2a 2a 20 20 20 20   C in the.**    
1e470 20 20 20 20 20 20 5b 64 61 74 61 62 61 73 65 20        [database 
1e480 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 61 73  connection] D as
1e490 20 69 74 20 77 61 73 20 70 72 69 6f 72 20 74 6f   it was prior to
1e4a0 20 74 68 65 20 63 61 6c 6c 2e 0a 2a 2f 0a 69 6e   the call..*/.in
1e4b0 74 20 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28  t sqlite3_limit(
1e4c0 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 69 64  sqlite3*, int id
1e4d0 2c 20 69 6e 74 20 6e 65 77 56 61 6c 29 3b 0a 0a  , int newVal);..
1e4e0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1e4f0 52 75 6e 2d 54 69 6d 65 20 4c 69 6d 69 74 20 43  Run-Time Limit C
1e500 61 74 65 67 6f 72 69 65 73 20 7b 48 31 32 37 39  ategories {H1279
1e510 30 7d 20 3c 48 31 32 37 36 30 3e 0a 2a 2a 20 4b  0} <H12760>.** K
1e520 45 59 57 4f 52 44 53 3a 20 7b 6c 69 6d 69 74 20  EYWORDS: {limit 
1e530 63 61 74 65 67 6f 72 79 7d 20 7b 6c 69 6d 69 74  category} {limit
1e540 20 63 61 74 65 67 6f 72 69 65 73 7d 0a 2a 2a 0a   categories}.**.
1e550 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e  ** These constan
1e560 74 73 20 64 65 66 69 6e 65 20 76 61 72 69 6f 75  ts define variou
1e570 73 20 61 73 70 65 63 74 73 20 6f 66 20 61 20 5b  s aspects of a [
1e580 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1e590 69 6f 6e 5d 0a 2a 2a 20 74 68 61 74 20 63 61 6e  ion].** that can
1e5a0 20 62 65 20 6c 69 6d 69 74 65 64 20 69 6e 20 73   be limited in s
1e5b0 69 7a 65 20 62 79 20 63 61 6c 6c 73 20 74 6f 20  ize by calls to 
1e5c0 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29  [sqlite3_limit()
1e5d0 5d 2e 0a 2a 2a 20 54 68 65 20 6d 65 61 6e 69 6e  ]..** The meanin
1e5e0 67 73 20 6f 66 20 74 68 65 20 76 61 72 69 6f 75  gs of the variou
1e5f0 73 20 6c 69 6d 69 74 73 20 61 72 65 20 61 73 20  s limits are as 
1e600 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c  follows:.**.** <
1e610 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  dl>.** <dt>SQLIT
1e620 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 3c 2f  E_LIMIT_LENGTH</
1e630 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
1e640 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f 66 20 61  aximum size of a
1e650 6e 79 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f  ny string or BLO
1e660 42 20 6f 72 20 74 61 62 6c 65 20 72 6f 77 2e 3c  B or table row.<
1e670 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51  dd>.**.** <dt>SQ
1e680 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c  LITE_LIMIT_SQL_L
1e690 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ENGTH</dt>.** <d
1e6a0 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65  d>The maximum le
1e6b0 6e 67 74 68 20 6f 66 20 61 6e 20 53 51 4c 20 73  ngth of an SQL s
1e6c0 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e 0a 2a  tatement.</dd>.*
1e6d0 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
1e6e0 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 3c 2f 64 74  LIMIT_COLUMN</dt
1e6f0 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
1e700 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63  imum number of c
1e710 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 74 61 62 6c  olumns in a tabl
1e720 65 20 64 65 66 69 6e 69 74 69 6f 6e 20 6f 72 20  e definition or 
1e730 69 6e 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74  in the.** result
1e740 20 73 65 74 20 6f 66 20 61 20 53 45 4c 45 43 54   set of a SELECT
1e750 20 6f 72 20 74 68 65 20 6d 61 78 69 6d 75 6d 20   or the maximum 
1e760 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  number of column
1e770 73 20 69 6e 20 61 6e 20 69 6e 64 65 78 0a 2a 2a  s in an index.**
1e780 20 6f 72 20 69 6e 20 61 6e 20 4f 52 44 45 52 20   or in an ORDER 
1e790 42 59 20 6f 72 20 47 52 4f 55 50 20 42 59 20 63  BY or GROUP BY c
1e7a0 6c 61 75 73 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  lause.</dd>.**.*
1e7b0 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  * <dt>SQLITE_LIM
1e7c0 49 54 5f 45 58 50 52 5f 44 45 50 54 48 3c 2f 64  IT_EXPR_DEPTH</d
1e7d0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
1e7e0 78 69 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 74  ximum depth of t
1e7f0 68 65 20 70 61 72 73 65 20 74 72 65 65 20 6f 6e  he parse tree on
1e800 20 61 6e 79 20 65 78 70 72 65 73 73 69 6f 6e 2e   any expression.
1e810 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
1e820 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d  SQLITE_LIMIT_COM
1e830 50 4f 55 4e 44 5f 53 45 4c 45 43 54 3c 2f 64 74  POUND_SELECT</dt
1e840 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
1e850 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74  imum number of t
1e860 65 72 6d 73 20 69 6e 20 61 20 63 6f 6d 70 6f 75  erms in a compou
1e870 6e 64 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d  nd SELECT statem
1e880 65 6e 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ent.</dd>.**.** 
1e890 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
1e8a0 5f 56 44 42 45 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a  _VDBE_OP</dt>.**
1e8b0 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
1e8c0 20 6e 75 6d 62 65 72 20 6f 66 20 69 6e 73 74 72   number of instr
1e8d0 75 63 74 69 6f 6e 73 20 69 6e 20 61 20 76 69 72  uctions in a vir
1e8e0 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 70 72 6f  tual machine pro
1e8f0 67 72 61 6d 0a 2a 2a 20 75 73 65 64 20 74 6f 20  gram.** used to 
1e900 69 6d 70 6c 65 6d 65 6e 74 20 61 6e 20 53 51 4c  implement an SQL
1e910 20 73 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e   statement.</dd>
1e920 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
1e930 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e  E_LIMIT_FUNCTION
1e940 5f 41 52 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  _ARG</dt>.** <dd
1e950 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  >The maximum num
1e960 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73  ber of arguments
1e970 20 6f 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e 3c   on a function.<
1e980 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
1e990 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41  QLITE_LIMIT_ATTA
1e9a0 43 48 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  CHED</dt>.** <dd
1e9b0 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  >The maximum num
1e9c0 62 65 72 20 6f 66 20 61 74 74 61 63 68 65 64 20  ber of attached 
1e9d0 64 61 74 61 62 61 73 65 73 2e 3c 2f 64 64 3e 0a  databases.</dd>.
1e9e0 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
1e9f0 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54  _LIMIT_LIKE_PATT
1ea00 45 52 4e 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a  ERN_LENGTH</dt>.
1ea10 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
1ea20 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65  um length of the
1ea30 20 70 61 74 74 65 72 6e 20 61 72 67 75 6d 65 6e   pattern argumen
1ea40 74 20 74 6f 20 74 68 65 20 4c 49 4b 45 20 6f 72  t to the LIKE or
1ea50 0a 2a 2a 20 47 4c 4f 42 20 6f 70 65 72 61 74 6f  .** GLOB operato
1ea60 72 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  rs.</dd>.**.** <
1ea70 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
1ea80 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 3c  VARIABLE_NUMBER<
1ea90 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
1eaa0 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
1eab0 66 20 76 61 72 69 61 62 6c 65 73 20 69 6e 20 61  f variables in a
1eac0 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  n SQL statement 
1ead0 74 68 61 74 20 63 61 6e 0a 2a 2a 20 62 65 20 62  that can.** be b
1eae0 6f 75 6e 64 2e 3c 2f 64 64 3e 0a 2a 2a 20 3c 2f  ound.</dd>.** </
1eaf0 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  dl>.*/.#define S
1eb00 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47  QLITE_LIMIT_LENG
1eb10 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20  TH              
1eb20 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20        0.#define 
1eb30 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c  SQLITE_LIMIT_SQL
1eb40 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 20 20  _LENGTH         
1eb50 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65         1.#define
1eb60 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f   SQLITE_LIMIT_CO
1eb70 4c 55 4d 4e 20 20 20 20 20 20 20 20 20 20 20 20  LUMN            
1eb80 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e          2.#defin
1eb90 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45  e SQLITE_LIMIT_E
1eba0 58 50 52 5f 44 45 50 54 48 20 20 20 20 20 20 20  XPR_DEPTH       
1ebb0 20 20 20 20 20 20 20 20 20 33 0a 23 64 65 66 69           3.#defi
1ebc0 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
1ebd0 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 20  COMPOUND_SELECT 
1ebe0 20 20 20 20 20 20 20 20 20 20 34 0a 23 64 65 66            4.#def
1ebf0 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
1ec00 5f 56 44 42 45 5f 4f 50 20 20 20 20 20 20 20 20  _VDBE_OP        
1ec10 20 20 20 20 20 20 20 20 20 20 20 35 0a 23 64 65             5.#de
1ec20 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
1ec30 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 20 20  T_FUNCTION_ARG  
1ec40 20 20 20 20 20 20 20 20 20 20 20 20 36 0a 23 64              6.#d
1ec50 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
1ec60 49 54 5f 41 54 54 41 43 48 45 44 20 20 20 20 20  IT_ATTACHED     
1ec70 20 20 20 20 20 20 20 20 20 20 20 20 20 37 0a 23               7.#
1ec80 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
1ec90 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e  MIT_LIKE_PATTERN
1eca0 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 38 0a  _LENGTH       8.
1ecb0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
1ecc0 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55  IMIT_VARIABLE_NU
1ecd0 4d 42 45 52 20 20 20 20 20 20 20 20 20 20 20 39  MBER           9
1ece0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1ecf0 3a 20 43 6f 6d 70 69 6c 69 6e 67 20 41 6e 20 53  : Compiling An S
1ed00 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 7b 48 31  QL Statement {H1
1ed10 33 30 31 30 7d 20 3c 53 31 30 30 30 30 3e 0a 2a  3010} <S10000>.*
1ed20 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c  * KEYWORDS: {SQL
1ed30 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69   statement compi
1ed40 6c 65 72 7d 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78  ler}.**.** To ex
1ed50 65 63 75 74 65 20 61 6e 20 53 51 4c 20 71 75 65  ecute an SQL que
1ed60 72 79 2c 20 69 74 20 6d 75 73 74 20 66 69 72 73  ry, it must firs
1ed70 74 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 69 6e  t be compiled in
1ed80 74 6f 20 61 20 62 79 74 65 2d 63 6f 64 65 0a 2a  to a byte-code.*
1ed90 2a 20 70 72 6f 67 72 61 6d 20 75 73 69 6e 67 20  * program using 
1eda0 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75  one of these rou
1edb0 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  tines..**.** The
1edc0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2c   first argument,
1edd0 20 22 64 62 22 2c 20 69 73 20 61 20 5b 64 61 74   "db", is a [dat
1ede0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1edf0 5d 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  ] obtained from 
1ee00 61 0a 2a 2a 20 70 72 69 6f 72 20 63 61 6c 6c 20  a.** prior call 
1ee10 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  to [sqlite3_open
1ee20 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ()], [sqlite3_op
1ee30 65 6e 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c  en_v2()] or [sql
1ee40 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 0a  ite3_open16()]..
1ee50 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  **.** The second
1ee60 20 61 72 67 75 6d 65 6e 74 2c 20 22 7a 53 71 6c   argument, "zSql
1ee70 22 2c 20 69 73 20 74 68 65 20 73 74 61 74 65 6d  ", is the statem
1ee80 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c  ent to be compil
1ee90 65 64 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a 20 61  ed, encoded.** a
1eea0 73 20 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f  s either UTF-8 o
1eeb0 72 20 55 54 46 2d 31 36 2e 20 20 54 68 65 20 73  r UTF-16.  The s
1eec0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
1eed0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65   and sqlite3_pre
1eee0 70 61 72 65 5f 76 32 28 29 0a 2a 2a 20 69 6e 74  pare_v2().** int
1eef0 65 72 66 61 63 65 73 20 75 73 65 20 55 54 46 2d  erfaces use UTF-
1ef00 38 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70  8, and sqlite3_p
1ef10 72 65 70 61 72 65 31 36 28 29 20 61 6e 64 20 73  repare16() and s
1ef20 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
1ef30 5f 76 32 28 29 0a 2a 2a 20 75 73 65 20 55 54 46  _v2().** use UTF
1ef40 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  -16..**.** If th
1ef50 65 20 6e 42 79 74 65 20 61 72 67 75 6d 65 6e 74  e nByte argument
1ef60 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 7a 65   is less than ze
1ef70 72 6f 2c 20 74 68 65 6e 20 7a 53 71 6c 20 69 73  ro, then zSql is
1ef80 20 72 65 61 64 20 75 70 20 74 6f 20 74 68 65 0a   read up to the.
1ef90 2a 2a 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65  ** first zero te
1efa0 72 6d 69 6e 61 74 6f 72 2e 20 49 66 20 6e 42 79  rminator. If nBy
1efb0 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69  te is non-negati
1efc0 76 65 2c 20 74 68 65 6e 20 69 74 20 69 73 20 74  ve, then it is t
1efd0 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 6e 75  he maximum.** nu
1efe0 6d 62 65 72 20 6f 66 20 20 62 79 74 65 73 20 72  mber of  bytes r
1eff0 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c 2e 20 20  ead from zSql.  
1f000 57 68 65 6e 20 6e 42 79 74 65 20 69 73 20 6e 6f  When nByte is no
1f010 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65 0a  n-negative, the.
1f020 2a 2a 20 7a 53 71 6c 20 73 74 72 69 6e 67 20 65  ** zSql string e
1f030 6e 64 73 20 61 74 20 65 69 74 68 65 72 20 74 68  nds at either th
1f040 65 20 66 69 72 73 74 20 27 5c 30 30 30 27 20 6f  e first '\000' o
1f050 72 20 27 5c 75 30 30 30 30 27 20 63 68 61 72 61  r '\u0000' chara
1f060 63 74 65 72 20 6f 72 0a 2a 2a 20 74 68 65 20 6e  cter or.** the n
1f070 42 79 74 65 2d 74 68 20 62 79 74 65 2c 20 77 68  Byte-th byte, wh
1f080 69 63 68 65 76 65 72 20 63 6f 6d 65 73 20 66 69  ichever comes fi
1f090 72 73 74 2e 20 49 66 20 74 68 65 20 63 61 6c 6c  rst. If the call
1f0a0 65 72 20 6b 6e 6f 77 73 0a 2a 2a 20 74 68 61 74  er knows.** that
1f0b0 20 74 68 65 20 73 75 70 70 6c 69 65 64 20 73 74   the supplied st
1f0c0 72 69 6e 67 20 69 73 20 6e 75 6c 2d 74 65 72 6d  ring is nul-term
1f0d0 69 6e 61 74 65 64 2c 20 74 68 65 6e 20 74 68 65  inated, then the
1f0e0 72 65 20 69 73 20 61 20 73 6d 61 6c 6c 0a 2a 2a  re is a small.**
1f0f0 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 61 64 76   performance adv
1f100 61 6e 74 61 67 65 20 74 6f 20 62 65 20 67 61 69  antage to be gai
1f110 6e 65 64 20 62 79 20 70 61 73 73 69 6e 67 20 61  ned by passing a
1f120 6e 20 6e 42 79 74 65 20 70 61 72 61 6d 65 74 65  n nByte paramete
1f130 72 20 74 68 61 74 0a 2a 2a 20 69 73 20 65 71 75  r that.** is equ
1f140 61 6c 20 74 6f 20 74 68 65 20 6e 75 6d 62 65 72  al to the number
1f150 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65   of bytes in the
1f160 20 69 6e 70 75 74 20 73 74 72 69 6e 67 20 3c 69   input string <i
1f170 3e 69 6e 63 6c 75 64 69 6e 67 3c 2f 69 3e 0a 2a  >including</i>.*
1f180 2a 20 74 68 65 20 6e 75 6c 2d 74 65 72 6d 69 6e  * the nul-termin
1f190 61 74 6f 72 20 62 79 74 65 73 2e 0a 2a 2a 0a 2a  ator bytes..**.*
1f1a0 2a 20 2a 70 7a 54 61 69 6c 20 69 73 20 6d 61 64  * *pzTail is mad
1f1b0 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 74 68  e to point to th
1f1c0 65 20 66 69 72 73 74 20 62 79 74 65 20 70 61 73  e first byte pas
1f1d0 74 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65  t the end of the
1f1e0 0a 2a 2a 20 66 69 72 73 74 20 53 51 4c 20 73 74  .** first SQL st
1f1f0 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2e  atement in zSql.
1f200 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73    These routines
1f210 20 6f 6e 6c 79 20 63 6f 6d 70 69 6c 65 20 74 68   only compile th
1f220 65 20 66 69 72 73 74 0a 2a 2a 20 73 74 61 74 65  e first.** state
1f230 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2c 20 73 6f  ment in zSql, so
1f240 20 2a 70 7a 54 61 69 6c 20 69 73 20 6c 65 66 74   *pzTail is left
1f250 20 70 6f 69 6e 74 69 6e 67 20 74 6f 20 77 68 61   pointing to wha
1f260 74 20 72 65 6d 61 69 6e 73 0a 2a 2a 20 75 6e 63  t remains.** unc
1f270 6f 6d 70 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 2a  ompiled..**.** *
1f280 70 70 53 74 6d 74 20 69 73 20 6c 65 66 74 20 70  ppStmt is left p
1f290 6f 69 6e 74 69 6e 67 20 74 6f 20 61 20 63 6f 6d  ointing to a com
1f2a0 70 69 6c 65 64 20 5b 70 72 65 70 61 72 65 64 20  piled [prepared 
1f2b0 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20  statement] that 
1f2c0 63 61 6e 20 62 65 0a 2a 2a 20 65 78 65 63 75 74  can be.** execut
1f2d0 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ed using [sqlite
1f2e0 33 5f 73 74 65 70 28 29 5d 2e 20 20 49 66 20 74  3_step()].  If t
1f2f0 68 65 72 65 20 69 73 20 61 6e 20 65 72 72 6f 72  here is an error
1f300 2c 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74  , *ppStmt is set
1f310 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 20 20 49 66  .** to NULL.  If
1f320 20 74 68 65 20 69 6e 70 75 74 20 74 65 78 74 20   the input text 
1f330 63 6f 6e 74 61 69 6e 73 20 6e 6f 20 53 51 4c 20  contains no SQL 
1f340 28 69 66 20 74 68 65 20 69 6e 70 75 74 20 69 73  (if the input is
1f350 20 61 6e 20 65 6d 70 74 79 0a 2a 2a 20 73 74 72   an empty.** str
1f360 69 6e 67 20 6f 72 20 61 20 63 6f 6d 6d 65 6e 74  ing or a comment
1f370 29 20 74 68 65 6e 20 2a 70 70 53 74 6d 74 20 69  ) then *ppStmt i
1f380 73 20 73 65 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a  s set to NULL..*
1f390 2a 20 7b 41 31 33 30 31 38 7d 20 54 68 65 20 63  * {A13018} The c
1f3a0 61 6c 6c 69 6e 67 20 70 72 6f 63 65 64 75 72 65  alling procedure
1f3b0 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20   is responsible 
1f3c0 66 6f 72 20 64 65 6c 65 74 69 6e 67 20 74 68 65  for deleting the
1f3d0 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 53 51 4c   compiled.** SQL
1f3e0 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67   statement using
1f3f0 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
1f400 7a 65 28 29 5d 20 61 66 74 65 72 20 69 74 20 68  ze()] after it h
1f410 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68  as finished with
1f420 20 69 74 2e 0a 2a 2a 0a 2a 2a 20 4f 6e 20 73 75   it..**.** On su
1f430 63 63 65 73 73 2c 20 5b 53 51 4c 49 54 45 5f 4f  ccess, [SQLITE_O
1f440 4b 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2c 20  K] is returned, 
1f450 6f 74 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72  otherwise an [er
1f460 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74  ror code] is ret
1f470 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  urned..**.** The
1f480 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
1f490 5f 76 32 28 29 20 61 6e 64 20 73 71 6c 69 74 65  _v2() and sqlite
1f4a0 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
1f4b0 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 0a   interfaces are.
1f4c0 2a 2a 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66  ** recommended f
1f4d0 6f 72 20 61 6c 6c 20 6e 65 77 20 70 72 6f 67 72  or all new progr
1f4e0 61 6d 73 2e 20 54 68 65 20 74 77 6f 20 6f 6c 64  ams. The two old
1f4f0 65 72 20 69 6e 74 65 72 66 61 63 65 73 20 61 72  er interfaces ar
1f500 65 20 72 65 74 61 69 6e 65 64 0a 2a 2a 20 66 6f  e retained.** fo
1f510 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70  r backwards comp
1f520 61 74 69 62 69 6c 69 74 79 2c 20 62 75 74 20 74  atibility, but t
1f530 68 65 69 72 20 75 73 65 20 69 73 20 64 69 73 63  heir use is disc
1f540 6f 75 72 61 67 65 64 2e 0a 2a 2a 20 49 6e 20 74  ouraged..** In t
1f550 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  he "v2" interfac
1f560 65 73 2c 20 74 68 65 20 70 72 65 70 61 72 65 64  es, the prepared
1f570 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 68   statement.** th
1f580 61 74 20 69 73 20 72 65 74 75 72 6e 65 64 20 28  at is returned (
1f590 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d  the [sqlite3_stm
1f5a0 74 5d 20 6f 62 6a 65 63 74 29 20 63 6f 6e 74 61  t] object) conta
1f5b0 69 6e 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68  ins a copy of th
1f5c0 65 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 20 53 51  e.** original SQ
1f5d0 4c 20 74 65 78 74 2e 20 54 68 69 73 20 63 61 75  L text. This cau
1f5e0 73 65 73 20 74 68 65 20 5b 73 71 6c 69 74 65 33  ses the [sqlite3
1f5f0 5f 73 74 65 70 28 29 5d 20 69 6e 74 65 72 66 61  _step()] interfa
1f600 63 65 20 74 6f 0a 2a 2a 20 62 65 68 61 76 65 20  ce to.** behave 
1f610 61 20 64 69 66 66 65 72 65 6e 74 6c 79 20 69 6e  a differently in
1f620 20 74 77 6f 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a   two ways:.**.**
1f630 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a   <ol>.** <li>.**
1f640 20 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65   If the database
1f650 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 73 2c   schema changes,
1f660 20 69 6e 73 74 65 61 64 20 6f 66 20 72 65 74 75   instead of retu
1f670 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f 53 43  rning [SQLITE_SC
1f680 48 45 4d 41 5d 20 61 73 20 69 74 0a 2a 2a 20 61  HEMA] as it.** a
1f690 6c 77 61 79 73 20 75 73 65 64 20 74 6f 20 64 6f  lways used to do
1f6a0 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  , [sqlite3_step(
1f6b0 29 5d 20 77 69 6c 6c 20 61 75 74 6f 6d 61 74 69  )] will automati
1f6c0 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65 20  cally recompile 
1f6d0 74 68 65 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65  the SQL.** state
1f6e0 6d 65 6e 74 20 61 6e 64 20 74 72 79 20 74 6f 20  ment and try to 
1f6f0 72 75 6e 20 69 74 20 61 67 61 69 6e 2e 20 20 49  run it again.  I
1f700 66 20 74 68 65 20 73 63 68 65 6d 61 20 68 61 73  f the schema has
1f710 20 63 68 61 6e 67 65 64 20 69 6e 0a 2a 2a 20 61   changed in.** a
1f720 20 77 61 79 20 74 68 61 74 20 6d 61 6b 65 73 20   way that makes 
1f730 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 6e 6f  the statement no
1f740 20 6c 6f 6e 67 65 72 20 76 61 6c 69 64 2c 20 5b   longer valid, [
1f750 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
1f760 77 69 6c 6c 20 73 74 69 6c 6c 0a 2a 2a 20 72 65  will still.** re
1f770 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 53 43 48  turn [SQLITE_SCH
1f780 45 4d 41 5d 2e 20 20 42 75 74 20 75 6e 6c 69 6b  EMA].  But unlik
1f790 65 20 74 68 65 20 6c 65 67 61 63 79 20 62 65 68  e the legacy beh
1f7a0 61 76 69 6f 72 2c 20 5b 53 51 4c 49 54 45 5f 53  avior, [SQLITE_S
1f7b0 43 48 45 4d 41 5d 20 69 73 0a 2a 2a 20 6e 6f 77  CHEMA] is.** now
1f7c0 20 61 20 66 61 74 61 6c 20 65 72 72 6f 72 2e 20   a fatal error. 
1f7d0 20 43 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   Calling [sqlite
1f7e0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
1f7f0 61 67 61 69 6e 20 77 69 6c 6c 20 6e 6f 74 20 6d  again will not m
1f800 61 6b 65 20 74 68 65 0a 2a 2a 20 65 72 72 6f 72  ake the.** error
1f810 20 67 6f 20 61 77 61 79 2e 20 20 4e 6f 74 65 3a   go away.  Note:
1f820 20 75 73 65 20 5b 73 71 6c 69 74 65 33 5f 65 72   use [sqlite3_er
1f830 72 6d 73 67 28 29 5d 20 74 6f 20 66 69 6e 64 20  rmsg()] to find 
1f840 74 68 65 20 74 65 78 74 0a 2a 2a 20 6f 66 20 74  the text.** of t
1f850 68 65 20 70 61 72 73 69 6e 67 20 65 72 72 6f 72  he parsing error
1f860 20 74 68 61 74 20 72 65 73 75 6c 74 73 20 69 6e   that results in
1f870 20 61 6e 20 5b 53 51 4c 49 54 45 5f 53 43 48 45   an [SQLITE_SCHE
1f880 4d 41 5d 20 72 65 74 75 72 6e 2e 0a 2a 2a 20 3c  MA] return..** <
1f890 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a  /li>.**.** <li>.
1f8a0 2a 2a 20 57 68 65 6e 20 61 6e 20 65 72 72 6f 72  ** When an error
1f8b0 20 6f 63 63 75 72 73 2c 20 5b 73 71 6c 69 74 65   occurs, [sqlite
1f8c0 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 72  3_step()] will r
1f8d0 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 74 68 65  eturn one of the
1f8e0 20 64 65 74 61 69 6c 65 64 0a 2a 2a 20 5b 65 72   detailed.** [er
1f8f0 72 6f 72 20 63 6f 64 65 73 5d 20 6f 72 20 5b 65  ror codes] or [e
1f900 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f  xtended error co
1f910 64 65 73 5d 2e 20 20 54 68 65 20 6c 65 67 61 63  des].  The legac
1f920 79 20 62 65 68 61 76 69 6f 72 20 77 61 73 20 74  y behavior was t
1f930 68 61 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  hat.** [sqlite3_
1f940 73 74 65 70 28 29 5d 20 77 6f 75 6c 64 20 6f 6e  step()] would on
1f950 6c 79 20 72 65 74 75 72 6e 20 61 20 67 65 6e 65  ly return a gene
1f960 72 69 63 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  ric [SQLITE_ERRO
1f970 52 5d 20 72 65 73 75 6c 74 20 63 6f 64 65 0a 2a  R] result code.*
1f980 2a 20 61 6e 64 20 79 6f 75 20 77 6f 75 6c 64 20  * and you would 
1f990 68 61 76 65 20 74 6f 20 6d 61 6b 65 20 61 20 73  have to make a s
1f9a0 65 63 6f 6e 64 20 63 61 6c 6c 20 74 6f 20 5b 73  econd call to [s
1f9b0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
1f9c0 69 6e 20 6f 72 64 65 72 0a 2a 2a 20 74 6f 20 66  in order.** to f
1f9d0 69 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69  ind the underlyi
1f9e0 6e 67 20 63 61 75 73 65 20 6f 66 20 74 68 65 20  ng cause of the 
1f9f0 70 72 6f 62 6c 65 6d 2e 20 57 69 74 68 20 74 68  problem. With th
1fa00 65 20 22 76 32 22 20 70 72 65 70 61 72 65 0a 2a  e "v2" prepare.*
1fa10 2a 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68  * interfaces, th
1fa20 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 72 65 61  e underlying rea
1fa30 73 6f 6e 20 66 6f 72 20 74 68 65 20 65 72 72 6f  son for the erro
1fa40 72 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 6d  r is returned im
1fa50 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 20 3c 2f  mediately..** </
1fa60 6c 69 3e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a  li>.** </ol>.**.
1fa70 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
1fa80 2a 0a 2a 2a 20 7b 48 31 33 30 31 31 7d 20 54 68  *.** {H13011} Th
1fa90 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  e [sqlite3_prepa
1faa0 72 65 28 64 62 2c 7a 53 71 6c 2c 2e 2e 2e 29 5d  re(db,zSql,...)]
1fab0 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20   and.**         
1fac0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1fad0 65 5f 76 32 28 64 62 2c 7a 53 71 6c 2c 2e 2e 2e  e_v2(db,zSql,...
1fae0 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 69 6e  )] interfaces in
1faf0 74 65 72 70 72 65 74 20 74 68 65 0a 2a 2a 20 20  terpret the.**  
1fb00 20 20 20 20 20 20 20 20 74 65 78 74 20 69 6e 20          text in 
1fb10 74 68 65 69 72 20 7a 53 71 6c 20 70 61 72 61 6d  their zSql param
1fb20 65 74 65 72 20 61 73 20 55 54 46 2d 38 2e 0a 2a  eter as UTF-8..*
1fb30 2a 0a 2a 2a 20 7b 48 31 33 30 31 32 7d 20 54 68  *.** {H13012} Th
1fb40 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  e [sqlite3_prepa
1fb50 72 65 31 36 28 64 62 2c 7a 53 71 6c 2c 2e 2e 2e  re16(db,zSql,...
1fb60 29 5d 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20  )] and.**       
1fb70 20 20 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70     [sqlite3_prep
1fb80 61 72 65 31 36 5f 76 32 28 64 62 2c 7a 53 71 6c  are16_v2(db,zSql
1fb90 2c 2e 2e 2e 29 5d 20 69 6e 74 65 72 66 61 63 65  ,...)] interface
1fba0 73 20 69 6e 74 65 72 70 72 65 74 20 74 68 65 0a  s interpret the.
1fbb0 2a 2a 20 20 20 20 20 20 20 20 20 20 74 65 78 74  **          text
1fbc0 20 69 6e 20 74 68 65 69 72 20 7a 53 71 6c 20 70   in their zSql p
1fbd0 61 72 61 6d 65 74 65 72 20 61 73 20 55 54 46 2d  arameter as UTF-
1fbe0 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65  16 in the native
1fbf0 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 0a   byte order..**.
1fc00 2a 2a 20 7b 48 31 33 30 31 33 7d 20 49 66 20 74  ** {H13013} If t
1fc10 68 65 20 6e 42 79 74 65 20 61 72 67 75 6d 65 6e  he nByte argumen
1fc20 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72  t to [sqlite3_pr
1fc30 65 70 61 72 65 5f 76 32 28 64 62 2c 7a 53 71 6c  epare_v2(db,zSql
1fc40 2c 6e 42 79 74 65 2c 2e 2e 2e 29 5d 0a 2a 2a 20  ,nByte,...)].** 
1fc50 20 20 20 20 20 20 20 20 20 61 6e 64 20 69 74 73           and its
1fc60 20 76 61 72 69 61 6e 74 73 20 69 73 20 6c 65 73   variants is les
1fc70 73 20 74 68 61 6e 20 7a 65 72 6f 2c 20 74 68 65  s than zero, the
1fc80 20 53 51 4c 20 74 65 78 74 20 69 73 0a 2a 2a 20   SQL text is.** 
1fc90 20 20 20 20 20 20 20 20 20 72 65 61 64 20 66 72           read fr
1fca0 6f 6d 20 7a 53 71 6c 20 69 73 20 72 65 61 64 20  om zSql is read 
1fcb0 75 70 20 74 6f 20 74 68 65 20 66 69 72 73 74 20  up to the first 
1fcc0 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e  zero terminator.
1fcd0 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 30 31 34 7d 20  .**.** {H13014} 
1fce0 49 66 20 74 68 65 20 6e 42 79 74 65 20 61 72 67  If the nByte arg
1fcf0 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65  ument to [sqlite
1fd00 33 5f 70 72 65 70 61 72 65 5f 76 32 28 64 62 2c  3_prepare_v2(db,
1fd10 7a 53 71 6c 2c 6e 42 79 74 65 2c 2e 2e 2e 29 5d  zSql,nByte,...)]
1fd20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6e 64  .**          and
1fd30 20 69 74 73 20 76 61 72 69 61 6e 74 73 20 69 73   its variants is
1fd40 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74   non-negative, t
1fd50 68 65 6e 20 61 74 20 6d 6f 73 74 20 6e 42 79 74  hen at most nByt
1fd60 65 73 20 62 79 74 65 73 20 6f 66 0a 2a 2a 20 20  es bytes of.**  
1fd70 20 20 20 20 20 20 20 20 53 51 4c 20 74 65 78 74          SQL text
1fd80 20 69 73 20 72 65 61 64 20 66 72 6f 6d 20 7a 53   is read from zS
1fd90 71 6c 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 30 31  ql..**.** {H1301
1fda0 35 7d 20 49 6e 20 5b 73 71 6c 69 74 65 33 5f 70  5} In [sqlite3_p
1fdb0 72 65 70 61 72 65 5f 76 32 28 64 62 2c 7a 53 71  repare_v2(db,zSq
1fdc0 6c 2c 4e 2c 50 2c 70 7a 54 61 69 6c 29 5d 20 61  l,N,P,pzTail)] a
1fdd0 6e 64 20 69 74 73 20 76 61 72 69 61 6e 74 73 0a  nd its variants.
1fde0 2a 2a 20 20 20 20 20 20 20 20 20 20 69 66 20 74  **          if t
1fdf0 68 65 20 7a 53 71 6c 20 69 6e 70 75 74 20 74 65  he zSql input te
1fe00 78 74 20 63 6f 6e 74 61 69 6e 73 20 6d 6f 72 65  xt contains more
1fe10 20 74 68 61 6e 20 6f 6e 65 20 53 51 4c 20 73 74   than one SQL st
1fe20 61 74 65 6d 65 6e 74 0a 2a 2a 20 20 20 20 20 20  atement.**      
1fe30 20 20 20 20 61 6e 64 20 70 7a 54 61 69 6c 20 69      and pzTail i
1fe40 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e  s not NULL, then
1fe50 20 2a 70 7a 54 61 69 6c 20 69 73 20 6d 61 64 65   *pzTail is made
1fe60 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 74 68 65   to point to the
1fe70 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69 72  .**          fir
1fe80 73 74 20 62 79 74 65 20 70 61 73 74 20 74 68 65  st byte past the
1fe90 20 65 6e 64 20 6f 66 20 74 68 65 20 66 69 72 73   end of the firs
1fea0 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  t SQL statement 
1feb0 69 6e 20 7a 53 71 6c 2e 0a 2a 2a 20 20 20 20 20  in zSql..**     
1fec0 20 20 20 20 20 3c 74 6f 64 6f 3e 57 68 61 74 20       <todo>What 
1fed0 64 6f 65 73 20 2a 70 7a 54 61 69 6c 20 70 6f 69  does *pzTail poi
1fee0 6e 74 20 74 6f 20 69 66 20 74 68 65 72 65 20 69  nt to if there i
1fef0 73 20 6f 6e 65 20 73 74 61 74 65 6d 65 6e 74 3f  s one statement?
1ff00 3c 2f 74 6f 64 6f 3e 0a 2a 2a 0a 2a 2a 20 7b 48  </todo>.**.** {H
1ff10 31 33 30 31 36 7d 20 41 20 73 75 63 63 65 73 73  13016} A success
1ff20 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ful call to [sql
1ff30 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
1ff40 64 62 2c 7a 53 71 6c 2c 4e 2c 70 70 53 74 6d 74  db,zSql,N,ppStmt
1ff50 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20  ,...)].**       
1ff60 20 20 20 6f 72 20 6f 6e 65 20 6f 66 20 69 74 73     or one of its
1ff70 20 76 61 72 69 61 6e 74 73 20 77 72 69 74 65 73   variants writes
1ff80 20 69 6e 74 6f 20 2a 70 70 53 74 6d 74 20 61 20   into *ppStmt a 
1ff90 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6e 65 77  pointer to a new
1ffa0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72  .**          [pr
1ffb0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
1ffc0 5d 20 6f 72 20 61 20 70 6f 69 6e 74 65 72 20 74  ] or a pointer t
1ffd0 6f 20 4e 55 4c 4c 20 69 66 20 7a 53 71 6c 20 63  o NULL if zSql c
1ffe0 6f 6e 74 61 69 6e 73 0a 2a 2a 20 20 20 20 20 20  ontains.**      
1fff0 20 20 20 20 6e 6f 74 68 69 6e 67 20 6f 74 68 65      nothing othe
20000 72 20 74 68 61 6e 20 77 68 69 74 65 73 70 61 63  r than whitespac
20010 65 20 6f 72 20 63 6f 6d 6d 65 6e 74 73 2e 0a 2a  e or comments..*
20020 2a 0a 2a 2a 20 7b 48 31 33 30 31 39 7d 20 54 68  *.** {H13019} Th
20030 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  e [sqlite3_prepa
20040 72 65 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61  re_v2()] interfa
20050 63 65 20 61 6e 64 20 69 74 73 20 76 61 72 69 61  ce and its varia
20060 6e 74 73 20 72 65 74 75 72 6e 0a 2a 2a 20 20 20  nts return.**   
20070 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 4f         [SQLITE_O
20080 4b 5d 20 6f 72 20 61 6e 20 61 70 70 72 6f 70 72  K] or an appropr
20090 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65  iate [error code
200a0 5d 20 75 70 6f 6e 20 66 61 69 6c 75 72 65 2e 0a  ] upon failure..
200b0 2a 2a 0a 2a 2a 20 7b 48 31 33 30 32 31 7d 20 42  **.** {H13021} B
200c0 65 66 6f 72 65 20 5b 73 71 6c 69 74 65 33 5f 70  efore [sqlite3_p
200d0 72 65 70 61 72 65 28 64 62 2c 7a 53 71 6c 2c 6e  repare(db,zSql,n
200e0 42 79 74 65 2c 70 70 53 74 6d 74 2c 70 7a 54 61  Byte,ppStmt,pzTa
200f0 69 6c 29 5d 20 6f 72 20 69 74 73 0a 2a 2a 20 20  il)] or its.**  
20100 20 20 20 20 20 20 20 20 76 61 72 69 61 6e 74 73          variants
20110 20 72 65 74 75 72 6e 73 20 61 6e 20 65 72 72 6f   returns an erro
20120 72 20 28 61 6e 79 20 76 61 6c 75 65 20 6f 74 68  r (any value oth
20130 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
20140 4f 4b 5d 29 2c 0a 2a 2a 20 20 20 20 20 20 20 20  OK]),.**        
20150 20 20 74 68 65 79 20 66 69 72 73 74 20 73 65 74    they first set
20160 20 2a 70 70 53 74 6d 74 20 74 6f 20 4e 55 4c 4c   *ppStmt to NULL
20170 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
20180 5f 70 72 65 70 61 72 65 28 0a 20 20 73 71 6c 69  _prepare(.  sqli
20190 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
201a0 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20      /* Database 
201b0 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
201c0 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20  t char *zSql,   
201d0 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65      /* SQL state
201e0 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f  ment, UTF-8 enco
201f0 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79  ded */.  int nBy
20200 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  te,             
20210 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67   /* Maximum leng
20220 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79  th of zSql in by
20230 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65  tes. */.  sqlite
20240 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c  3_stmt **ppStmt,
20250 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d    /* OUT: Statem
20260 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ent handle */.  
20270 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54  const char **pzT
20280 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20  ail     /* OUT: 
20290 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65  Pointer to unuse
202a0 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71  d portion of zSq
202b0 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69  l */.);.int sqli
202c0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 0a  te3_prepare_v2(.
202d0 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
202e0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74            /* Dat
202f0 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a  abase handle */.
20300 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53    const char *zS
20310 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c  ql,       /* SQL
20320 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d   statement, UTF-
20330 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69  8 encoded */.  i
20340 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20  nt nByte,       
20350 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75         /* Maximu
20360 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c  m length of zSql
20370 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20   in bytes. */.  
20380 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70  sqlite3_stmt **p
20390 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20  pStmt,  /* OUT: 
203a0 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65  Statement handle
203b0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
203c0 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a   **pzTail     /*
203d0 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f   OUT: Pointer to
203e0 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20   unused portion 
203f0 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e  of zSql */.);.in
20400 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  t sqlite3_prepar
20410 65 31 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  e16(.  sqlite3 *
20420 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f  db,            /
20430 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c  * Database handl
20440 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69  e */.  const voi
20450 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f  d *zSql,       /
20460 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c  * SQL statement,
20470 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20   UTF-16 encoded 
20480 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20  */.  int nByte, 
20490 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
204a0 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  Maximum length o
204b0 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e  f zSql in bytes.
204c0 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74   */.  sqlite3_st
204d0 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a  mt **ppStmt,  /*
204e0 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20   OUT: Statement 
204f0 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
20500 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20  t void **pzTail 
20510 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e      /* OUT: Poin
20520 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f  ter to unused po
20530 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f  rtion of zSql */
20540 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
20550 70 72 65 70 61 72 65 31 36 5f 76 32 28 0a 20 20  prepare16_v2(.  
20560 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
20570 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62          /* Datab
20580 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ase handle */.  
20590 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c  const void *zSql
205a0 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73  ,       /* SQL s
205b0 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36  tatement, UTF-16
205c0 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e   encoded */.  in
205d0 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20  t nByte,        
205e0 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d        /* Maximum
205f0 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20   length of zSql 
20600 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73  in bytes. */.  s
20610 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70  qlite3_stmt **pp
20620 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53  Stmt,  /* OUT: S
20630 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20  tatement handle 
20640 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
20650 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20  **pzTail     /* 
20660 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20  OUT: Pointer to 
20670 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f  unused portion o
20680 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a  f zSql */.);../*
20690 0a 2a 2a 20 43 41 50 49 52 45 46 3a 20 52 65 74  .** CAPIREF: Ret
206a0 72 69 65 76 69 6e 67 20 53 74 61 74 65 6d 65 6e  rieving Statemen
206b0 74 20 53 51 4c 20 7b 48 31 33 31 30 30 7d 20 3c  t SQL {H13100} <
206c0 48 31 33 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68  H13000>.**.** Th
206d0 69 73 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e  is interface can
206e0 20 62 65 20 75 73 65 64 20 74 6f 20 72 65 74 72   be used to retr
206f0 69 65 76 65 20 61 20 73 61 76 65 64 20 63 6f 70  ieve a saved cop
20700 79 20 6f 66 20 74 68 65 20 6f 72 69 67 69 6e 61  y of the origina
20710 6c 0a 2a 2a 20 53 51 4c 20 74 65 78 74 20 75 73  l.** SQL text us
20720 65 64 20 74 6f 20 63 72 65 61 74 65 20 61 20 5b  ed to create a [
20730 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
20740 6e 74 5d 20 69 66 20 74 68 61 74 20 73 74 61 74  nt] if that stat
20750 65 6d 65 6e 74 20 77 61 73 0a 2a 2a 20 63 6f 6d  ement was.** com
20760 70 69 6c 65 64 20 75 73 69 6e 67 20 65 69 74 68  piled using eith
20770 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  er [sqlite3_prep
20780 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71  are_v2()] or [sq
20790 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
207a0 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56  v2()]..**.** INV
207b0 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
207c0 48 31 33 31 30 31 7d 20 49 66 20 74 68 65 20 5b  H13101} If the [
207d0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
207e0 6e 74 5d 20 70 61 73 73 65 64 20 61 73 20 74 68  nt] passed as th
207f0 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a  e argument to.**
20800 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
20810 65 33 5f 73 71 6c 28 29 5d 20 77 61 73 20 63 6f  e3_sql()] was co
20820 6d 70 69 6c 65 64 20 75 73 69 6e 67 20 65 69 74  mpiled using eit
20830 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  her [sqlite3_pre
20840 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a  pare_v2()] or.**
20850 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
20860 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
20870 29 5d 2c 20 74 68 65 6e 20 5b 73 71 6c 69 74 65  )], then [sqlite
20880 33 5f 73 71 6c 28 29 5d 20 72 65 74 75 72 6e 73  3_sql()] returns
20890 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20 70  .**          a p
208a0 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 6f  ointer to a zero
208b0 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69  -terminated stri
208c0 6e 67 20 63 6f 6e 74 61 69 6e 69 6e 67 20 61 20  ng containing a 
208d0 55 54 46 2d 38 20 72 65 6e 64 65 72 69 6e 67 0a  UTF-8 rendering.
208e0 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20 74  **          of t
208f0 68 65 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20  he original SQL 
20900 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a  statement..**.**
20910 20 7b 48 31 33 31 30 32 7d 20 49 66 20 74 68 65   {H13102} If the
20920 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
20930 6d 65 6e 74 5d 20 70 61 73 73 65 64 20 61 73 20  ment] passed as 
20940 74 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a  the argument to.
20950 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
20960 69 74 65 33 5f 73 71 6c 28 29 5d 20 77 61 73 20  ite3_sql()] was 
20970 63 6f 6d 70 69 6c 65 64 20 75 73 69 6e 67 20 65  compiled using e
20980 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70  ither [sqlite3_p
20990 72 65 70 61 72 65 28 29 5d 20 6f 72 0a 2a 2a 20  repare()] or.** 
209a0 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
209b0 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2c 20  3_prepare16()], 
209c0 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 73 71  then [sqlite3_sq
209d0 6c 28 29 5d 20 72 65 74 75 72 6e 73 20 61 20 4e  l()] returns a N
209e0 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a  ULL pointer..**.
209f0 2a 2a 20 7b 48 31 33 31 30 33 7d 20 54 68 65 20  ** {H13103} The 
20a00 73 74 72 69 6e 67 20 72 65 74 75 72 6e 65 64 20  string returned 
20a10 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 71 6c 28  by [sqlite3_sql(
20a20 53 29 5d 20 69 73 20 76 61 6c 69 64 20 75 6e 74  S)] is valid unt
20a30 69 6c 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  il the.**       
20a40 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61     [prepared sta
20a50 74 65 6d 65 6e 74 5d 20 53 20 69 73 20 64 65 6c  tement] S is del
20a60 65 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69  eted using [sqli
20a70 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 5d  te3_finalize(S)]
20a80 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20  ..*/.const char 
20a90 2a 73 71 6c 69 74 65 33 5f 73 71 6c 28 73 71 6c  *sqlite3_sql(sql
20aa0 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
20ab0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
20ac0 45 46 3a 20 44 79 6e 61 6d 69 63 61 6c 6c 79 20  EF: Dynamically 
20ad0 54 79 70 65 64 20 56 61 6c 75 65 20 4f 62 6a 65  Typed Value Obje
20ae0 63 74 20 7b 48 31 35 30 30 30 7d 20 3c 53 32 30  ct {H15000} <S20
20af0 32 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  200>.** KEYWORDS
20b00 3a 20 7b 70 72 6f 74 65 63 74 65 64 20 73 71 6c  : {protected sql
20b10 69 74 65 33 5f 76 61 6c 75 65 7d 20 7b 75 6e 70  ite3_value} {unp
20b20 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
20b30 5f 76 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 51  _value}.**.** SQ
20b40 4c 69 74 65 20 75 73 65 73 20 74 68 65 20 73 71  Lite uses the sq
20b50 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
20b60 63 74 20 74 6f 20 72 65 70 72 65 73 65 6e 74 20  ct to represent 
20b70 61 6c 6c 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68  all values.** th
20b80 61 74 20 63 61 6e 20 62 65 20 73 74 6f 72 65 64  at can be stored
20b90 20 69 6e 20 61 20 64 61 74 61 62 61 73 65 20 74   in a database t
20ba0 61 62 6c 65 2e 20 53 51 4c 69 74 65 20 75 73 65  able. SQLite use
20bb0 73 20 64 79 6e 61 6d 69 63 20 74 79 70 69 6e 67  s dynamic typing
20bc0 0a 2a 2a 20 66 6f 72 20 74 68 65 20 76 61 6c 75  .** for the valu
20bd0 65 73 20 69 74 20 73 74 6f 72 65 73 2e 20 56 61  es it stores. Va
20be0 6c 75 65 73 20 73 74 6f 72 65 64 20 69 6e 20 73  lues stored in s
20bf0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
20c00 65 63 74 73 0a 2a 2a 20 63 61 6e 20 62 65 20 69  ects.** can be i
20c10 6e 74 65 67 65 72 73 2c 20 66 6c 6f 61 74 69 6e  ntegers, floatin
20c20 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 73 2c 20  g point values, 
20c30 73 74 72 69 6e 67 73 2c 20 42 4c 4f 42 73 2c 20  strings, BLOBs, 
20c40 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41  or NULL..**.** A
20c50 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  n sqlite3_value 
20c60 6f 62 6a 65 63 74 20 6d 61 79 20 62 65 20 65 69  object may be ei
20c70 74 68 65 72 20 22 70 72 6f 74 65 63 74 65 64 22  ther "protected"
20c80 20 6f 72 20 22 75 6e 70 72 6f 74 65 63 74 65 64   or "unprotected
20c90 22 2e 0a 2a 2a 20 53 6f 6d 65 20 69 6e 74 65 72  "..** Some inter
20ca0 66 61 63 65 73 20 72 65 71 75 69 72 65 20 61 20  faces require a 
20cb0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
20cc0 33 5f 76 61 6c 75 65 2e 20 20 4f 74 68 65 72 20  3_value.  Other 
20cd0 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 77 69  interfaces.** wi
20ce0 6c 6c 20 61 63 63 65 70 74 20 65 69 74 68 65 72  ll accept either
20cf0 20 61 20 70 72 6f 74 65 63 74 65 64 20 6f 72 20   a protected or 
20d00 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73  an unprotected s
20d10 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a  qlite3_value..**
20d20 20 45 76 65 72 79 20 69 6e 74 65 72 66 61 63 65   Every interface
20d30 20 74 68 61 74 20 61 63 63 65 70 74 73 20 73 71   that accepts sq
20d40 6c 69 74 65 33 5f 76 61 6c 75 65 20 61 72 67 75  lite3_value argu
20d50 6d 65 6e 74 73 20 73 70 65 63 69 66 69 65 73 0a  ments specifies.
20d60 2a 2a 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  ** whether or no
20d70 74 20 69 74 20 72 65 71 75 69 72 65 73 20 61 20  t it requires a 
20d80 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
20d90 33 5f 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54  3_value..**.** T
20da0 68 65 20 74 65 72 6d 73 20 22 70 72 6f 74 65 63  he terms "protec
20db0 74 65 64 22 20 61 6e 64 20 22 75 6e 70 72 6f 74  ted" and "unprot
20dc0 65 63 74 65 64 22 20 72 65 66 65 72 20 74 6f 20  ected" refer to 
20dd0 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 0a 2a  whether or not.*
20de0 2a 20 61 20 6d 75 74 65 78 20 69 73 20 68 65 6c  * a mutex is hel
20df0 64 2e 20 20 41 20 69 6e 74 65 72 6e 61 6c 20 6d  d.  A internal m
20e00 75 74 65 78 20 69 73 20 68 65 6c 64 20 66 6f 72  utex is held for
20e10 20 61 20 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20   a protected.** 
20e20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
20e30 6a 65 63 74 20 62 75 74 20 6e 6f 20 6d 75 74 65  ject but no mute
20e40 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61 6e  x is held for an
20e50 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20   unprotected.** 
20e60 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
20e70 6a 65 63 74 2e 20 20 49 66 20 53 51 4c 69 74 65  ject.  If SQLite
20e80 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 74 6f 20   is compiled to 
20e90 62 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64  be single-thread
20ea0 65 64 0a 2a 2a 20 28 77 69 74 68 20 5b 53 51 4c  ed.** (with [SQL
20eb0 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30  ITE_THREADSAFE=0
20ec0 5d 20 61 6e 64 20 77 69 74 68 20 5b 73 71 6c 69  ] and with [sqli
20ed0 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 29  te3_threadsafe()
20ee0 5d 20 72 65 74 75 72 6e 69 6e 67 20 30 29 0a 2a  ] returning 0).*
20ef0 2a 20 6f 72 20 69 66 20 53 51 4c 69 74 65 20 69  * or if SQLite i
20f00 73 20 72 75 6e 20 69 6e 20 6f 6e 65 20 6f 66 20  s run in one of 
20f10 72 65 64 75 63 65 64 20 6d 75 74 65 78 20 6d 6f  reduced mutex mo
20f20 64 65 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  des .** [SQLITE_
20f30 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52  CONFIG_SINGLETHR
20f40 45 41 44 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  EAD] or [SQLITE_
20f50 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45  CONFIG_MULTITHRE
20f60 41 44 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 72  AD].** then ther
20f70 65 20 69 73 20 6e 6f 20 64 69 73 74 69 6e 63 74  e is no distinct
20f80 69 6f 6e 20 62 65 74 77 65 65 6e 20 70 72 6f 74  ion between prot
20f90 65 63 74 65 64 20 61 6e 64 20 75 6e 70 72 6f 74  ected and unprot
20fa0 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33  ected.** sqlite3
20fb0 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 61  _value objects a
20fc0 6e 64 20 74 68 65 79 20 63 61 6e 20 62 65 20 75  nd they can be u
20fd0 73 65 64 20 69 6e 74 65 72 63 68 61 6e 67 65 61  sed interchangea
20fe0 62 6c 79 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a  bly.  However,.*
20ff0 2a 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 63 6f  * for maximum co
21000 64 65 20 70 6f 72 74 61 62 69 6c 69 74 79 20 69  de portability i
21010 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64  t is recommended
21020 20 74 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f   that applicatio
21030 6e 73 0a 2a 2a 20 73 74 69 6c 6c 20 6d 61 6b 65  ns.** still make
21040 20 74 68 65 20 64 69 73 74 69 6e 63 74 69 6f 6e   the distinction
21050 20 62 65 74 77 65 65 6e 20 62 65 74 77 65 65 6e   between between
21060 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75   protected and u
21070 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71  nprotected.** sq
21080 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
21090 63 74 73 20 65 76 65 6e 20 77 68 65 6e 20 6e 6f  cts even when no
210a0 74 20 73 74 72 69 63 74 6c 79 20 72 65 71 75 69  t strictly requi
210b0 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  red..**.** The s
210c0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
210d0 65 63 74 73 20 74 68 61 74 20 61 72 65 20 70 61  ects that are pa
210e0 73 73 65 64 20 61 73 20 70 61 72 61 6d 65 74 65  ssed as paramete
210f0 72 73 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 69  rs into the.** i
21100 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
21110 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65   [application-de
21120 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
21130 6f 6e 73 5d 20 61 72 65 20 70 72 6f 74 65 63 74  ons] are protect
21140 65 64 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  ed..** The sqlit
21150 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20  e3_value object 
21160 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b  returned by.** [
21170 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76  sqlite3_column_v
21180 61 6c 75 65 28 29 5d 20 69 73 20 75 6e 70 72 6f  alue()] is unpro
21190 74 65 63 74 65 64 2e 0a 2a 2a 20 55 6e 70 72 6f  tected..** Unpro
211a0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
211b0 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 6d 61 79  alue objects may
211c0 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 77 69   only be used wi
211d0 74 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72  th.** [sqlite3_r
211e0 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 20 61  esult_value()] a
211f0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  nd [sqlite3_bind
21200 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 54 68  _value()]..** Th
21210 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
21220 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f  _blob | sqlite3_
21230 76 61 6c 75 65 5f 74 79 70 65 28 29 5d 20 66 61  value_type()] fa
21240 6d 69 6c 79 20 6f 66 0a 2a 2a 20 69 6e 74 65 72  mily of.** inter
21250 66 61 63 65 73 20 72 65 71 75 69 72 65 20 70 72  faces require pr
21260 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
21270 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 2e 0a 2a  value objects..*
21280 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
21290 20 4d 65 6d 20 73 71 6c 69 74 65 33 5f 76 61 6c   Mem sqlite3_val
212a0 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  ue;../*.** CAPI3
212b0 52 45 46 3a 20 53 51 4c 20 46 75 6e 63 74 69 6f  REF: SQL Functio
212c0 6e 20 43 6f 6e 74 65 78 74 20 4f 62 6a 65 63 74  n Context Object
212d0 20 7b 48 31 36 30 30 31 7d 20 3c 53 32 30 32 30   {H16001} <S2020
212e0 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 6e  0>.**.** The con
212f0 74 65 78 74 20 69 6e 20 77 68 69 63 68 20 61 6e  text in which an
21300 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 65 78   SQL function ex
21310 65 63 75 74 65 73 20 69 73 20 73 74 6f 72 65 64  ecutes is stored
21320 20 69 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65   in an.** sqlite
21330 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74  3_context object
21340 2e 20 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20  .  A pointer to 
21350 61 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  an sqlite3_conte
21360 78 74 20 6f 62 6a 65 63 74 0a 2a 2a 20 69 73 20  xt object.** is 
21370 61 6c 77 61 79 73 20 66 69 72 73 74 20 70 61 72  always first par
21380 61 6d 65 74 65 72 20 74 6f 20 5b 61 70 70 6c 69  ameter to [appli
21390 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53  cation-defined S
213a0 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a  QL functions]..*
213b0 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
213c0 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75  n-defined SQL fu
213d0 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74  nction implement
213e0 61 74 69 6f 6e 20 77 69 6c 6c 20 70 61 73 73 20  ation will pass 
213f0 74 68 69 73 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  this.** pointer 
21400 74 68 72 6f 75 67 68 20 69 6e 74 6f 20 63 61 6c  through into cal
21410 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72  ls to [sqlite3_r
21420 65 73 75 6c 74 5f 69 6e 74 20 7c 20 73 71 6c 69  esult_int | sqli
21430 74 65 33 5f 72 65 73 75 6c 74 28 29 5d 2c 0a 2a  te3_result()],.*
21440 2a 20 5b 73 71 6c 69 74 65 33 5f 61 67 67 72 65  * [sqlite3_aggre
21450 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 5d 2c  gate_context()],
21460 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64   [sqlite3_user_d
21470 61 74 61 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  ata()],.** [sqli
21480 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68  te3_context_db_h
21490 61 6e 64 6c 65 28 29 5d 2c 20 5b 73 71 6c 69 74  andle()], [sqlit
214a0 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29  e3_get_auxdata()
214b0 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b 73 71  ],.** and/or [sq
214c0 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74  lite3_set_auxdat
214d0 61 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  a()]..*/.typedef
214e0 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
214f0 63 6f 6e 74 65 78 74 20 73 71 6c 69 74 65 33 5f  context sqlite3_
21500 63 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20  context;../*.** 
21510 43 41 50 49 33 52 45 46 3a 20 42 69 6e 64 69 6e  CAPI3REF: Bindin
21520 67 20 56 61 6c 75 65 73 20 54 6f 20 50 72 65 70  g Values To Prep
21530 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 73 20  ared Statements 
21540 7b 48 31 33 35 30 30 7d 20 3c 53 37 30 33 30 30  {H13500} <S70300
21550 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  >.** KEYWORDS: {
21560 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 7d 20  host parameter} 
21570 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73  {host parameters
21580 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65  } {host paramete
21590 72 20 6e 61 6d 65 7d 0a 2a 2a 20 4b 45 59 57 4f  r name}.** KEYWO
215a0 52 44 53 3a 20 7b 53 51 4c 20 70 61 72 61 6d 65  RDS: {SQL parame
215b0 74 65 72 7d 20 7b 53 51 4c 20 70 61 72 61 6d 65  ter} {SQL parame
215c0 74 65 72 73 7d 20 7b 70 61 72 61 6d 65 74 65 72  ters} {parameter
215d0 20 62 69 6e 64 69 6e 67 7d 0a 2a 2a 0a 2a 2a 20   binding}.**.** 
215e0 49 6e 20 74 68 65 20 53 51 4c 20 73 74 72 69 6e  In the SQL strin
215f0 67 73 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c  gs input to [sql
21600 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
21610 29 5d 20 61 6e 64 20 69 74 73 20 76 61 72 69 61  )] and its varia
21620 6e 74 73 2c 0a 2a 2a 20 6c 69 74 65 72 61 6c 73  nts,.** literals
21630 20 6d 61 79 20 62 65 20 72 65 70 6c 61 63 65 64   may be replaced
21640 20 62 79 20 61 20 70 61 72 61 6d 65 74 65 72 20   by a parameter 
21650 69 6e 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20  in one of these 
21660 66 6f 72 6d 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  forms:.**.** <ul
21670 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 0a 2a 2a 20  >.** <li>  ?.** 
21680 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c  <li>  ?NNN.** <l
21690 69 3e 20 20 3a 56 56 56 0a 2a 2a 20 3c 6c 69 3e  i>  :VVV.** <li>
216a0 20 20 40 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20    @VVV.** <li>  
216b0 24 56 56 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  $VVV.** </ul>.**
216c0 0a 2a 2a 20 49 6e 20 74 68 65 20 70 61 72 61 6d  .** In the param
216d0 65 74 65 72 20 66 6f 72 6d 73 20 73 68 6f 77 6e  eter forms shown
216e0 20 61 62 6f 76 65 20 4e 4e 4e 20 69 73 20 61 6e   above NNN is an
216f0 20 69 6e 74 65 67 65 72 20 6c 69 74 65 72 61 6c   integer literal
21700 2c 0a 2a 2a 20 61 6e 64 20 56 56 56 20 69 73 20  ,.** and VVV is 
21710 61 6e 20 61 6c 70 68 61 2d 6e 75 6d 65 72 69 63  an alpha-numeric
21720 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 2e   parameter name.
21730 20 54 68 65 20 76 61 6c 75 65 73 20 6f 66 20 74   The values of t
21740 68 65 73 65 0a 2a 2a 20 70 61 72 61 6d 65 74 65  hese.** paramete
21750 72 73 20 28 61 6c 73 6f 20 63 61 6c 6c 65 64 20  rs (also called 
21760 22 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20  "host parameter 
21770 6e 61 6d 65 73 22 20 6f 72 20 22 53 51 4c 20 70  names" or "SQL p
21780 61 72 61 6d 65 74 65 72 73 22 29 0a 2a 2a 20 63  arameters").** c
21790 61 6e 20 62 65 20 73 65 74 20 75 73 69 6e 67 20  an be set using 
217a0 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  the sqlite3_bind
217b0 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 64 65  _*() routines de
217c0 66 69 6e 65 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a  fined here..**.*
217d0 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75  * The first argu
217e0 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69  ment to the sqli
217f0 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75  te3_bind_*() rou
21800 74 69 6e 65 73 20 69 73 20 61 6c 77 61 79 73 0a  tines is always.
21810 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ** a pointer to 
21820 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d  the [sqlite3_stm
21830 74 5d 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e  t] object return
21840 65 64 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69  ed from.** [sqli
21850 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
21860 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74  ] or its variant
21870 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63  s..**.** The sec
21880 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ond argument is 
21890 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65  the index of the
218a0 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 74   SQL parameter t
218b0 6f 20 62 65 20 73 65 74 2e 0a 2a 2a 20 54 68 65  o be set..** The
218c0 20 6c 65 66 74 6d 6f 73 74 20 53 51 4c 20 70 61   leftmost SQL pa
218d0 72 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69  rameter has an i
218e0 6e 64 65 78 20 6f 66 20 31 2e 20 20 57 68 65 6e  ndex of 1.  When
218f0 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 64 0a   the same named.
21900 2a 2a 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  ** SQL parameter
21910 20 69 73 20 75 73 65 64 20 6d 6f 72 65 20 74 68   is used more th
21920 61 6e 20 6f 6e 63 65 2c 20 73 65 63 6f 6e 64 20  an once, second 
21930 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74 0a 2a  and subsequent.*
21940 2a 20 6f 63 63 75 72 72 65 6e 63 65 73 20 68 61  * occurrences ha
21950 76 65 20 74 68 65 20 73 61 6d 65 20 69 6e 64 65  ve the same inde
21960 78 20 61 73 20 74 68 65 20 66 69 72 73 74 20 6f  x as the first o
21970 63 63 75 72 72 65 6e 63 65 2e 0a 2a 2a 20 54 68  ccurrence..** Th
21980 65 20 69 6e 64 65 78 20 66 6f 72 20 6e 61 6d 65  e index for name
21990 64 20 70 61 72 61 6d 65 74 65 72 73 20 63 61 6e  d parameters can
219a0 20 62 65 20 6c 6f 6f 6b 65 64 20 75 70 20 75 73   be looked up us
219b0 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69  ing the.** [sqli
219c0 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
219d0 65 72 5f 69 6e 64 65 78 28 29 5d 20 41 50 49 20  er_index()] API 
219e0 69 66 20 64 65 73 69 72 65 64 2e 20 20 54 68 65  if desired.  The
219f0 20 69 6e 64 65 78 0a 2a 2a 20 66 6f 72 20 22 3f   index.** for "?
21a00 4e 4e 4e 22 20 70 61 72 61 6d 65 74 65 72 73 20  NNN" parameters 
21a10 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  is the value of 
21a20 4e 4e 4e 2e 0a 2a 2a 20 54 68 65 20 4e 4e 4e 20  NNN..** The NNN 
21a30 76 61 6c 75 65 20 6d 75 73 74 20 62 65 20 62 65  value must be be
21a40 74 77 65 65 6e 20 31 20 61 6e 64 20 74 68 65 20  tween 1 and the 
21a50 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29  [sqlite3_limit()
21a60 5d 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 5b  ].** parameter [
21a70 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52  SQLITE_LIMIT_VAR
21a80 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 20 28 64  IABLE_NUMBER] (d
21a90 65 66 61 75 6c 74 20 76 61 6c 75 65 3a 20 39 39  efault value: 99
21aa0 39 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 68  9)..**.** The th
21ab0 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ird argument is 
21ac0 74 68 65 20 76 61 6c 75 65 20 74 6f 20 62 69 6e  the value to bin
21ad0 64 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74  d to the paramet
21ae0 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 6f  er..**.** In tho
21af0 73 65 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74  se routines that
21b00 20 68 61 76 65 20 61 20 66 6f 75 72 74 68 20 61   have a fourth a
21b10 72 67 75 6d 65 6e 74 2c 20 69 74 73 20 76 61 6c  rgument, its val
21b20 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d  ue is the.** num
21b30 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
21b40 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 20 20  the parameter.  
21b50 54 6f 20 62 65 20 63 6c 65 61 72 3a 20 74 68 65  To be clear: the
21b60 20 76 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a   value is the.**
21b70 20 6e 75 6d 62 65 72 20 6f 66 20 3c 75 3e 62 79   number of <u>by
21b80 74 65 73 3c 2f 75 3e 20 69 6e 20 74 68 65 20 76  tes</u> in the v
21b90 61 6c 75 65 2c 20 6e 6f 74 20 74 68 65 20 6e 75  alue, not the nu
21ba0 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65  mber of characte
21bb0 72 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20 66 6f  rs..** If the fo
21bc0 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  urth parameter i
21bd0 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 20  s negative, the 
21be0 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 73 74  length of the st
21bf0 72 69 6e 67 20 69 73 0a 2a 2a 20 74 68 65 20 6e  ring is.** the n
21c00 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 75  umber of bytes u
21c10 70 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 7a  p to the first z
21c20 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a  ero terminator..
21c30 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 66 74 68 20  **.** The fifth 
21c40 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69  argument to sqli
21c50 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 2c  te3_bind_blob(),
21c60 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
21c70 78 74 28 29 2c 20 61 6e 64 0a 2a 2a 20 73 71 6c  xt(), and.** sql
21c80 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36  ite3_bind_text16
21c90 28 29 20 69 73 20 61 20 64 65 73 74 72 75 63 74  () is a destruct
21ca0 6f 72 20 75 73 65 64 20 74 6f 20 64 69 73 70 6f  or used to dispo
21cb0 73 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f  se of the BLOB o
21cc0 72 0a 2a 2a 20 73 74 72 69 6e 67 20 61 66 74 65  r.** string afte
21cd0 72 20 53 51 4c 69 74 65 20 68 61 73 20 66 69 6e  r SQLite has fin
21ce0 69 73 68 65 64 20 77 69 74 68 20 69 74 2e 20 49  ished with it. I
21cf0 66 20 74 68 65 20 66 69 66 74 68 20 61 72 67 75  f the fifth argu
21d00 6d 65 6e 74 20 69 73 0a 2a 2a 20 74 68 65 20 73  ment is.** the s
21d10 70 65 63 69 61 6c 20 76 61 6c 75 65 20 5b 53 51  pecial value [SQ
21d20 4c 49 54 45 5f 53 54 41 54 49 43 5d 2c 20 74 68  LITE_STATIC], th
21d30 65 6e 20 53 51 4c 69 74 65 20 61 73 73 75 6d 65  en SQLite assume
21d40 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 69 6e  s that the.** in
21d50 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 69 6e 20  formation is in 
21d60 73 74 61 74 69 63 2c 20 75 6e 6d 61 6e 61 67 65  static, unmanage
21d70 64 20 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73  d space and does
21d80 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20   not need to be 
21d90 66 72 65 65 64 2e 0a 2a 2a 20 49 66 20 74 68 65  freed..** If the
21da0 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20   fifth argument 
21db0 68 61 73 20 74 68 65 20 76 61 6c 75 65 20 5b 53  has the value [S
21dc0 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d  QLITE_TRANSIENT]
21dd0 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65  , then.** SQLite
21de0 20 6d 61 6b 65 73 20 69 74 73 20 6f 77 6e 20 70   makes its own p
21df0 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74  rivate copy of t
21e00 68 65 20 64 61 74 61 20 69 6d 6d 65 64 69 61 74  he data immediat
21e10 65 6c 79 2c 20 62 65 66 6f 72 65 0a 2a 2a 20 74  ely, before.** t
21e20 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
21e30 2a 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75  *() routine retu
21e40 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  rns..**.** The s
21e50 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f  qlite3_bind_zero
21e60 62 6c 6f 62 28 29 20 72 6f 75 74 69 6e 65 20 62  blob() routine b
21e70 69 6e 64 73 20 61 20 42 4c 4f 42 20 6f 66 20 6c  inds a BLOB of l
21e80 65 6e 67 74 68 20 4e 20 74 68 61 74 0a 2a 2a 20  ength N that.** 
21e90 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 7a  is filled with z
21ea0 65 72 6f 65 73 2e 20 20 41 20 7a 65 72 6f 62 6c  eroes.  A zerobl
21eb0 6f 62 20 75 73 65 73 20 61 20 66 69 78 65 64 20  ob uses a fixed 
21ec0 61 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 79  amount of memory
21ed0 0a 2a 2a 20 28 6a 75 73 74 20 61 6e 20 69 6e 74  .** (just an int
21ee0 65 67 65 72 20 74 6f 20 68 6f 6c 64 20 69 74 73  eger to hold its
21ef0 20 73 69 7a 65 29 20 77 68 69 6c 65 20 69 74 20   size) while it 
21f00 69 73 20 62 65 69 6e 67 20 70 72 6f 63 65 73 73  is being process
21f10 65 64 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62 73  ed..** Zeroblobs
21f20 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 74 6f   are intended to
21f30 20 73 65 72 76 65 20 61 73 20 70 6c 61 63 65 68   serve as placeh
21f40 6f 6c 64 65 72 73 20 66 6f 72 20 42 4c 4f 42 73  olders for BLOBs
21f50 20 77 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65 6e   whose.** conten
21f60 74 20 69 73 20 6c 61 74 65 72 20 77 72 69 74 74  t is later writt
21f70 65 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c  en using.** [sql
21f80 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c  ite3_blob_open |
21f90 20 69 6e 63 72 65 6d 65 6e 74 61 6c 20 42 4c 4f   incremental BLO
21fa0 42 20 49 2f 4f 5d 20 72 6f 75 74 69 6e 65 73 2e  B I/O] routines.
21fb0 0a 2a 2a 20 41 20 6e 65 67 61 74 69 76 65 20 76  .** A negative v
21fc0 61 6c 75 65 20 66 6f 72 20 74 68 65 20 7a 65 72  alue for the zer
21fd0 6f 62 6c 6f 62 20 72 65 73 75 6c 74 73 20 69 6e  oblob results in
21fe0 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42   a zero-length B
21ff0 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  LOB..**.** The s
22000 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20  qlite3_bind_*() 
22010 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65  routines must be
22020 20 63 61 6c 6c 65 64 20 61 66 74 65 72 0a 2a 2a   called after.**
22030 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
22040 65 5f 76 32 28 29 5d 20 28 61 6e 64 20 69 74 73  e_v2()] (and its
22050 20 76 61 72 69 61 6e 74 73 29 20 6f 72 20 5b 73   variants) or [s
22060 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
22070 61 6e 64 0a 2a 2a 20 62 65 66 6f 72 65 20 5b 73  and.** before [s
22080 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a  qlite3_step()]..
22090 2a 2a 20 42 69 6e 64 69 6e 67 73 20 61 72 65 20  ** Bindings are 
220a0 6e 6f 74 20 63 6c 65 61 72 65 64 20 62 79 20 74  not cleared by t
220b0 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  he [sqlite3_rese
220c0 74 28 29 5d 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a  t()] routine..**
220d0 20 55 6e 62 6f 75 6e 64 20 70 61 72 61 6d 65 74   Unbound paramet
220e0 65 72 73 20 61 72 65 20 69 6e 74 65 72 70 72 65  ers are interpre
220f0 74 65 64 20 61 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a  ted as NULL..**.
22100 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
22110 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  s return [SQLITE
22120 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20  _OK] on success 
22130 6f 72 20 61 6e 20 65 72 72 6f 72 20 63 6f 64 65  or an error code
22140 20 69 66 0a 2a 2a 20 61 6e 79 74 68 69 6e 67 20   if.** anything 
22150 67 6f 65 73 20 77 72 6f 6e 67 2e 20 20 5b 53 51  goes wrong.  [SQ
22160 4c 49 54 45 5f 52 41 4e 47 45 5d 20 69 73 20 72  LITE_RANGE] is r
22170 65 74 75 72 6e 65 64 20 69 66 20 74 68 65 20 70  eturned if the p
22180 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69 6e 64 65  arameter.** inde
22190 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67  x is out of rang
221a0 65 2e 20 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45  e.  [SQLITE_NOME
221b0 4d 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 69  M] is returned i
221c0 66 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73  f malloc() fails
221d0 2e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53  ..** [SQLITE_MIS
221e0 55 53 45 5d 20 6d 69 67 68 74 20 62 65 20 72 65  USE] might be re
221f0 74 75 72 6e 65 64 20 69 66 20 74 68 65 73 65 20  turned if these 
22200 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c  routines are cal
22210 6c 65 64 20 6f 6e 20 61 0a 2a 2a 20 76 69 72 74  led on a.** virt
22220 75 61 6c 20 6d 61 63 68 69 6e 65 20 74 68 61 74  ual machine that
22230 20 69 73 20 74 68 65 20 77 72 6f 6e 67 20 73 74   is the wrong st
22240 61 74 65 20 6f 72 20 77 68 69 63 68 20 68 61 73  ate or which has
22250 20 61 6c 72 65 61 64 79 20 62 65 65 6e 20 66 69   already been fi
22260 6e 61 6c 69 7a 65 64 2e 0a 2a 2a 20 44 65 74 65  nalized..** Dete
22270 63 74 69 6f 6e 20 6f 66 20 6d 69 73 75 73 65 20  ction of misuse 
22280 69 73 20 75 6e 72 65 6c 69 61 62 6c 65 2e 20 20  is unreliable.  
22290 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f  Applications sho
222a0 75 6c 64 20 6e 6f 74 20 64 65 70 65 6e 64 0a 2a  uld not depend.*
222b0 2a 20 6f 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55  * on SQLITE_MISU
222c0 53 45 20 72 65 74 75 72 6e 73 2e 20 20 53 51 4c  SE returns.  SQL
222d0 49 54 45 5f 4d 49 53 55 53 45 20 69 73 20 69 6e  ITE_MISUSE is in
222e0 74 65 6e 64 65 64 20 74 6f 20 69 6e 64 69 63 61  tended to indica
222f0 74 65 20 61 0a 2a 2a 20 61 20 6c 6f 67 69 63 20  te a.** a logic 
22300 65 72 72 6f 72 20 69 6e 20 74 68 65 20 61 70 70  error in the app
22310 6c 69 63 61 74 69 6f 6e 2e 20 20 46 75 74 75 72  lication.  Futur
22320 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  e versions of SQ
22330 4c 69 74 65 20 6d 69 67 68 74 0a 2a 2a 20 70 61  Lite might.** pa
22340 6e 69 63 20 72 61 74 68 65 72 20 74 68 61 6e 20  nic rather than 
22350 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4d 49  return SQLITE_MI
22360 53 55 53 45 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  SUSE..**.** See 
22370 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62  also: [sqlite3_b
22380 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f  ind_parameter_co
22390 75 6e 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  unt()],.** [sqli
223a0 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
223b0 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 20  er_name()], and 
223c0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
223d0 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d  rameter_index()]
223e0 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  ..**.** INVARIAN
223f0 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 30  TS:.**.** {H1350
22400 36 7d 20 54 68 65 20 5b 53 51 4c 20 73 74 61 74  6} The [SQL stat
22410 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 72 5d 20  ement compiler] 
22420 72 65 63 6f 67 6e 69 7a 65 73 20 74 6f 6b 65 6e  recognizes token
22430 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 73 0a 2a  s of the forms.*
22440 2a 20 20 20 20 20 20 20 20 20 20 22 3f 22 2c 20  *          "?", 
22450 22 3f 4e 4e 4e 22 2c 20 22 24 56 56 56 22 2c 20  "?NNN", "$VVV", 
22460 22 3a 56 56 56 22 2c 20 61 6e 64 20 22 40 56 56  ":VVV", and "@VV
22470 56 22 20 61 73 20 53 51 4c 20 70 61 72 61 6d 65  V" as SQL parame
22480 74 65 72 73 2c 0a 2a 2a 20 20 20 20 20 20 20 20  ters,.**        
22490 20 20 77 68 65 72 65 20 4e 4e 4e 20 69 73 20 61    where NNN is a
224a0 6e 79 20 73 65 71 75 65 6e 63 65 20 6f 66 20 6f  ny sequence of o
224b0 6e 65 20 6f 72 20 6d 6f 72 65 20 64 69 67 69 74  ne or more digit
224c0 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6e  s.**          an
224d0 64 20 77 68 65 72 65 20 56 56 56 20 69 73 20 61  d where VVV is a
224e0 6e 79 20 73 65 71 75 65 6e 63 65 20 6f 66 20 6f  ny sequence of o
224f0 6e 65 20 6f 72 20 6d 6f 72 65 20 61 6c 70 68 61  ne or more alpha
22500 6e 75 6d 65 72 69 63 0a 2a 2a 20 20 20 20 20 20  numeric.**      
22510 20 20 20 20 63 68 61 72 61 63 74 65 72 73 20 6f      characters o
22520 72 20 22 3a 3a 22 20 6f 70 74 69 6f 6e 61 6c 6c  r "::" optionall
22530 79 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 61 20  y followed by a 
22540 73 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e 69 6e  string containin
22550 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 6f  g.**          no
22560 20 73 70 61 63 65 73 20 61 6e 64 20 63 6f 6e 74   spaces and cont
22570 61 69 6e 65 64 20 77 69 74 68 69 6e 20 70 61 72  ained within par
22580 65 6e 74 68 65 73 65 73 2e 0a 2a 2a 0a 2a 2a 20  entheses..**.** 
22590 7b 48 31 33 35 30 39 7d 20 54 68 65 20 69 6e 69  {H13509} The ini
225a0 74 69 61 6c 20 76 61 6c 75 65 20 6f 66 20 61 6e  tial value of an
225b0 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69   SQL parameter i
225c0 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 7b 48  s NULL..**.** {H
225d0 31 33 35 31 32 7d 20 54 68 65 20 69 6e 64 65 78  13512} The index
225e0 20 6f 66 20 61 6e 20 22 3f 22 20 53 51 4c 20 70   of an "?" SQL p
225f0 61 72 61 6d 65 74 65 72 20 69 73 20 6f 6e 65 20  arameter is one 
22600 6c 61 72 67 65 72 20 74 68 61 6e 20 74 68 65 0a  larger than the.
22610 2a 2a 20 20 20 20 20 20 20 20 20 20 6c 61 72 67  **          larg
22620 65 73 74 20 69 6e 64 65 78 20 6f 66 20 53 51 4c  est index of SQL
22630 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
22640 65 20 6c 65 66 74 2c 20 6f 72 20 31 20 69 66 0a  e left, or 1 if.
22650 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
22660 22 3f 22 20 69 73 20 74 68 65 20 6c 65 66 74 6d  "?" is the leftm
22670 6f 73 74 20 53 51 4c 20 70 61 72 61 6d 65 74 65  ost SQL paramete
22680 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 31 35  r..**.** {H13515
22690 7d 20 54 68 65 20 69 6e 64 65 78 20 6f 66 20 61  } The index of a
226a0 6e 20 22 3f 4e 4e 4e 22 20 53 51 4c 20 70 61 72  n "?NNN" SQL par
226b0 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 69 6e  ameter is the in
226c0 74 65 67 65 72 20 4e 4e 4e 2e 0a 2a 2a 0a 2a 2a  teger NNN..**.**
226d0 20 7b 48 31 33 35 31 38 7d 20 54 68 65 20 69 6e   {H13518} The in
226e0 64 65 78 20 6f 66 20 61 6e 20 22 3a 56 56 56 22  dex of an ":VVV"
226f0 2c 20 22 24 56 56 56 22 2c 20 6f 72 20 22 40 56  , "$VVV", or "@V
22700 56 56 22 20 53 51 4c 20 70 61 72 61 6d 65 74 65  VV" SQL paramete
22710 72 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  r is.**         
22720 20 74 68 65 20 73 61 6d 65 20 61 73 20 74 68 65   the same as the
22730 20 69 6e 64 65 78 20 6f 66 20 6c 65 66 74 6d 6f   index of leftmo
22740 73 74 20 6f 63 63 75 72 72 65 6e 63 65 73 20 6f  st occurrences o
22750 66 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 20 20  f the same.**   
22760 20 20 20 20 20 20 20 70 61 72 61 6d 65 74 65 72         parameter
22770 2c 20 6f 72 20 6f 6e 65 20 6d 6f 72 65 20 74 68  , or one more th
22780 61 6e 20 74 68 65 20 6c 61 72 67 65 73 74 20 69  an the largest i
22790 6e 64 65 78 20 6f 76 65 72 20 61 6c 6c 0a 2a 2a  ndex over all.**
227a0 20 20 20 20 20 20 20 20 20 20 70 61 72 61 6d 65            parame
227b0 74 65 72 73 20 74 6f 20 74 68 65 20 6c 65 66 74  ters to the left
227c0 20 69 66 20 74 68 69 73 20 69 73 20 74 68 65 20   if this is the 
227d0 66 69 72 73 74 20 6f 63 63 75 72 72 65 6e 63 65  first occurrence
227e0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20  .**          of 
227f0 74 68 69 73 20 70 61 72 61 6d 65 74 65 72 2c 20  this parameter, 
22800 6f 72 20 31 20 69 66 20 74 68 69 73 20 69 73 20  or 1 if this is 
22810 74 68 65 20 6c 65 66 74 6d 6f 73 74 20 70 61 72  the leftmost par
22820 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48  ameter..**.** {H
22830 31 33 35 32 31 7d 20 54 68 65 20 5b 53 51 4c 20  13521} The [SQL 
22840 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c  statement compil
22850 65 72 5d 20 66 61 69 6c 73 20 77 69 74 68 20 61  er] fails with a
22860 6e 20 5b 53 51 4c 49 54 45 5f 52 41 4e 47 45 5d  n [SQLITE_RANGE]
22870 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 65 72 72  .**          err
22880 6f 72 20 69 66 20 74 68 65 20 69 6e 64 65 78 20  or if the index 
22890 6f 66 20 61 6e 20 53 51 4c 20 70 61 72 61 6d 65  of an SQL parame
228a0 74 65 72 20 69 73 20 6c 65 73 73 20 74 68 61 6e  ter is less than
228b0 20 31 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f   1.**          o
228c0 72 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 74  r greater than t
228d0 68 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  he compile-time 
228e0 53 51 4c 49 54 45 5f 4d 41 58 5f 56 41 52 49 41  SQLITE_MAX_VARIA
228f0 42 4c 45 5f 4e 55 4d 42 45 52 0a 2a 2a 20 20 20  BLE_NUMBER.**   
22900 20 20 20 20 20 20 20 70 61 72 61 6d 65 74 65 72         parameter
22910 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 32 34 7d  ..**.** {H13524}
22920 20 43 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74   Calls to [sqlit
22930 65 33 5f 62 69 6e 64 5f 74 65 78 74 20 7c 20 73  e3_bind_text | s
22940 71 6c 69 74 65 33 5f 62 69 6e 64 28 53 2c 4e 2c  qlite3_bind(S,N,
22950 56 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20  V,...)].**      
22960 20 20 20 20 61 73 73 6f 63 69 61 74 65 20 74 68      associate th
22970 65 20 76 61 6c 75 65 20 56 20 77 69 74 68 20 61  e value V with a
22980 6c 6c 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  ll SQL parameter
22990 73 20 68 61 76 69 6e 67 20 61 6e 0a 2a 2a 20 20  s having an.**  
229a0 20 20 20 20 20 20 20 20 69 6e 64 65 78 20 6f 66          index of
229b0 20 4e 20 69 6e 20 74 68 65 20 5b 70 72 65 70 61   N in the [prepa
229c0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
229d0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 32 37 7d  ..**.** {H13527}
229e0 20 43 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74   Calls to [sqlit
229f0 65 33 5f 62 69 6e 64 5f 74 65 78 74 20 7c 20 73  e3_bind_text | s
22a00 71 6c 69 74 65 33 5f 62 69 6e 64 28 53 2c 4e 2c  qlite3_bind(S,N,
22a10 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20  ...)].**        
22a20 20 20 6f 76 65 72 72 69 64 65 20 70 72 69 6f 72    override prior
22a30 20 63 61 6c 6c 73 20 77 69 74 68 20 74 68 65 20   calls with the 
22a40 73 61 6d 65 20 76 61 6c 75 65 73 20 6f 66 20 53  same values of S
22a50 20 61 6e 64 20 4e 2e 0a 2a 2a 0a 2a 2a 20 7b 48   and N..**.** {H
22a60 31 33 35 33 30 7d 20 42 69 6e 64 69 6e 67 73 20  13530} Bindings 
22a70 65 73 74 61 62 6c 69 73 68 65 64 20 62 79 20 5b  established by [
22a80 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
22a90 74 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  t | sqlite3_bind
22aa0 28 53 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20  (S,...)].**     
22ab0 20 20 20 20 20 70 65 72 73 69 73 74 20 61 63 72       persist acr
22ac0 6f 73 73 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71  oss calls to [sq
22ad0 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 2e  lite3_reset(S)].
22ae0 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 33 33 7d 20  .**.** {H13533} 
22af0 49 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c  In calls to [sql
22b00 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 53  ite3_bind_blob(S
22b10 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c 0a 2a 2a 20 20  ,N,V,L,D)],.**  
22b20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
22b30 5f 62 69 6e 64 5f 74 65 78 74 28 53 2c 4e 2c 56  _bind_text(S,N,V
22b40 2c 4c 2c 44 29 5d 2c 20 6f 72 0a 2a 2a 20 20 20  ,L,D)], or.**   
22b50 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
22b60 62 69 6e 64 5f 74 65 78 74 31 36 28 53 2c 4e 2c  bind_text16(S,N,
22b70 56 2c 4c 2c 44 29 5d 20 53 51 4c 69 74 65 20 62  V,L,D)] SQLite b
22b80 69 6e 64 73 20 74 68 65 20 66 69 72 73 74 20 4c  inds the first L
22b90 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 79 74  .**          byt
22ba0 65 73 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f  es of the BLOB o
22bb0 72 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 64  r string pointed
22bc0 20 74 6f 20 62 79 20 56 2c 20 77 68 65 6e 20 4c   to by V, when L
22bd0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20  .**          is 
22be0 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2e 0a 2a 2a  non-negative..**
22bf0 0a 2a 2a 20 7b 48 31 33 35 33 36 7d 20 49 6e 20  .** {H13536} In 
22c00 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  calls to [sqlite
22c10 33 5f 62 69 6e 64 5f 74 65 78 74 28 53 2c 4e 2c  3_bind_text(S,N,
22c20 56 2c 4c 2c 44 29 5d 20 6f 72 0a 2a 2a 20 20 20  V,L,D)] or.**   
22c30 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
22c40 62 69 6e 64 5f 74 65 78 74 31 36 28 53 2c 4e 2c  bind_text16(S,N,
22c50 56 2c 4c 2c 44 29 5d 20 53 51 4c 69 74 65 20 62  V,L,D)] SQLite b
22c60 69 6e 64 73 20 63 68 61 72 61 63 74 65 72 73 0a  inds characters.
22c70 2a 2a 20 20 20 20 20 20 20 20 20 20 66 72 6f 6d  **          from
22c80 20 56 20 74 68 72 6f 75 67 68 20 74 68 65 20 66   V through the f
22c90 69 72 73 74 20 7a 65 72 6f 20 63 68 61 72 61 63  irst zero charac
22ca0 74 65 72 20 77 68 65 6e 20 4c 20 69 73 20 6e 65  ter when L is ne
22cb0 67 61 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48  gative..**.** {H
22cc0 31 33 35 33 39 7d 20 49 6e 20 63 61 6c 6c 73 20  13539} In calls 
22cd0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  to [sqlite3_bind
22ce0 5f 62 6c 6f 62 28 53 2c 4e 2c 56 2c 4c 2c 44 29  _blob(S,N,V,L,D)
22cf0 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  ],.**          [
22d00 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
22d10 74 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c 20 6f  t(S,N,V,L,D)], o
22d20 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  r.**          [s
22d30 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
22d40 31 36 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 20 77  16(S,N,V,L,D)] w
22d50 68 65 6e 20 44 20 69 73 20 74 68 65 20 73 70 65  hen D is the spe
22d60 63 69 61 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20  cial.**         
22d70 20 63 6f 6e 73 74 61 6e 74 20 5b 53 51 4c 49 54   constant [SQLIT
22d80 45 5f 53 54 41 54 49 43 5d 2c 20 53 51 4c 69 74  E_STATIC], SQLit
22d90 65 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74  e assumes that t
22da0 68 65 20 76 61 6c 75 65 20 56 0a 2a 2a 20 20 20  he value V.**   
22db0 20 20 20 20 20 20 20 69 73 20 68 65 6c 64 20 69         is held i
22dc0 6e 20 73 74 61 74 69 63 20 75 6e 6d 61 6e 61 67  n static unmanag
22dd0 65 64 20 73 70 61 63 65 20 74 68 61 74 20 77 69  ed space that wi
22de0 6c 6c 20 6e 6f 74 20 63 68 61 6e 67 65 0a 2a 2a  ll not change.**
22df0 20 20 20 20 20 20 20 20 20 20 64 75 72 69 6e 67            during
22e00 20 74 68 65 20 6c 69 66 65 74 69 6d 65 20 6f 66   the lifetime of
22e10 20 74 68 65 20 62 69 6e 64 69 6e 67 2e 0a 2a 2a   the binding..**
22e20 0a 2a 2a 20 7b 48 31 33 35 34 32 7d 20 49 6e 20  .** {H13542} In 
22e30 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  calls to [sqlite
22e40 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 53 2c 4e 2c  3_bind_blob(S,N,
22e50 56 2c 4c 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20  V,L,D)],.**     
22e60 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 69       [sqlite3_bi
22e70 6e 64 5f 74 65 78 74 28 53 2c 4e 2c 56 2c 4c 2c  nd_text(S,N,V,L,
22e80 44 29 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20  D)], or.**      
22e90 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e      [sqlite3_bin
22ea0 64 5f 74 65 78 74 31 36 28 53 2c 4e 2c 56 2c 4c  d_text16(S,N,V,L
22eb0 2c 44 29 5d 20 77 68 65 6e 20 44 20 69 73 20 74  ,D)] when D is t
22ec0 68 65 20 73 70 65 63 69 61 6c 0a 2a 2a 20 20 20  he special.**   
22ed0 20 20 20 20 20 20 20 63 6f 6e 73 74 61 6e 74 20         constant 
22ee0 5b 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e  [SQLITE_TRANSIEN
22ef0 54 5d 2c 20 74 68 65 20 72 6f 75 74 69 6e 65 20  T], the routine 
22f00 6d 61 6b 65 73 20 61 0a 2a 2a 20 20 20 20 20 20  makes a.**      
22f10 20 20 20 20 70 72 69 76 61 74 65 20 63 6f 70 79      private copy
22f20 20 6f 66 20 74 68 65 20 76 61 6c 75 65 20 56 20   of the value V 
22f30 62 65 66 6f 72 65 20 69 74 20 72 65 74 75 72 6e  before it return
22f40 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 34 35  s..**.** {H13545
22f50 7d 20 49 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73  } In calls to [s
22f60 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
22f70 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c 0a 2a 2a  (S,N,V,L,D)],.**
22f80 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
22f90 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 53 2c 4e  e3_bind_text(S,N
22fa0 2c 56 2c 4c 2c 44 29 5d 2c 20 6f 72 0a 2a 2a 20  ,V,L,D)], or.** 
22fb0 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
22fc0 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 53 2c  3_bind_text16(S,
22fd0 4e 2c 56 2c 4c 2c 44 29 5d 20 77 68 65 6e 20 44  N,V,L,D)] when D
22fe0 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
22ff0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20 66  .**          a f
23000 75 6e 63 74 69 6f 6e 2c 20 53 51 4c 69 74 65 20  unction, SQLite 
23010 69 6e 76 6f 6b 65 73 20 74 68 61 74 20 66 75 6e  invokes that fun
23020 63 74 69 6f 6e 20 74 6f 20 64 65 73 74 72 6f 79  ction to destroy
23030 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
23040 20 76 61 6c 75 65 20 56 20 61 66 74 65 72 20 69   value V after i
23050 74 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 75  t has finished u
23060 73 69 6e 67 20 74 68 65 20 76 61 6c 75 65 20 56  sing the value V
23070 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 34 38 7d  ..**.** {H13548}
23080 20 49 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71   In calls to [sq
23090 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62  lite3_bind_zerob
230a0 6c 6f 62 28 53 2c 4e 2c 56 2c 4c 29 5d 20 74 68  lob(S,N,V,L)] th
230b0 65 20 76 61 6c 75 65 20 62 6f 75 6e 64 0a 2a 2a  e value bound.**
230c0 20 20 20 20 20 20 20 20 20 20 69 73 20 61 20 42            is a B
230d0 4c 4f 42 20 6f 66 20 4c 20 62 79 74 65 73 2c 20  LOB of L bytes, 
230e0 6f 72 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68  or a zero-length
230f0 20 42 4c 4f 42 20 69 66 20 4c 20 69 73 20 6e 65   BLOB if L is ne
23100 67 61 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48  gative..**.** {H
23110 31 33 35 35 31 7d 20 49 6e 20 63 61 6c 6c 73 20  13551} In calls 
23120 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  to [sqlite3_bind
23130 5f 76 61 6c 75 65 28 53 2c 4e 2c 56 29 5d 20 74  _value(S,N,V)] t
23140 68 65 20 56 20 61 72 67 75 6d 65 6e 74 20 6d 61  he V argument ma
23150 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 65  y.**          be
23160 20 65 69 74 68 65 72 20 61 20 5b 70 72 6f 74 65   either a [prote
23170 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
23180 75 65 5d 20 6f 62 6a 65 63 74 20 6f 72 20 61 6e  ue] object or an
23190 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 75 6e  .**          [un
231a0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
231b0 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 2e  3_value] object.
231c0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
231d0 62 69 6e 64 5f 62 6c 6f 62 28 73 71 6c 69 74 65  bind_blob(sqlite
231e0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f  3_stmt*, int, co
231f0 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e  nst void*, int n
23200 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  , void(*)(void*)
23210 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
23220 69 6e 64 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74  ind_double(sqlit
23230 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 64  e3_stmt*, int, d
23240 6f 75 62 6c 65 29 3b 0a 69 6e 74 20 73 71 6c 69  ouble);.int sqli
23250 74 65 33 5f 62 69 6e 64 5f 69 6e 74 28 73 71 6c  te3_bind_int(sql
23260 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
23270 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74   int);.int sqlit
23280 65 33 5f 62 69 6e 64 5f 69 6e 74 36 34 28 73 71  e3_bind_int64(sq
23290 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
232a0 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29  , sqlite3_int64)
232b0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
232c0 6e 64 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f  nd_null(sqlite3_
232d0 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 69 6e 74  stmt*, int);.int
232e0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
232f0 78 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  xt(sqlite3_stmt*
23300 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 63 68 61  , int, const cha
23310 72 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28  r*, int n, void(
23320 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20  *)(void*));.int 
23330 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
23340 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  t16(sqlite3_stmt
23350 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f  *, int, const vo
23360 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a  id*, int, void(*
23370 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73  )(void*));.int s
23380 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75  qlite3_bind_valu
23390 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
233a0 20 69 6e 74 2c 20 63 6f 6e 73 74 20 73 71 6c 69   int, const sqli
233b0 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74  te3_value*);.int
233c0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65   sqlite3_bind_ze
233d0 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73  roblob(sqlite3_s
233e0 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 20 6e  tmt*, int, int n
233f0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
23400 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 53 51  EF: Number Of SQ
23410 4c 20 50 61 72 61 6d 65 74 65 72 73 20 7b 48 31  L Parameters {H1
23420 33 36 30 30 7d 20 3c 53 37 30 33 30 30 3e 0a 2a  3600} <S70300>.*
23430 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e  *.** This routin
23440 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  e can be used to
23450 20 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 65 72   find the number
23460 20 6f 66 20 5b 53 51 4c 20 70 61 72 61 6d 65 74   of [SQL paramet
23470 65 72 73 5d 0a 2a 2a 20 69 6e 20 61 20 5b 70 72  ers].** in a [pr
23480 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
23490 5d 2e 20 20 53 51 4c 20 70 61 72 61 6d 65 74 65  ].  SQL paramete
234a0 72 73 20 61 72 65 20 74 6f 6b 65 6e 73 20 6f 66  rs are tokens of
234b0 20 74 68 65 0a 2a 2a 20 66 6f 72 6d 20 22 3f 22   the.** form "?"
234c0 2c 20 22 3f 4e 4e 4e 22 2c 20 22 3a 41 41 41 22  , "?NNN", ":AAA"
234d0 2c 20 22 24 41 41 41 22 2c 20 6f 72 20 22 40 41  , "$AAA", or "@A
234e0 41 41 22 20 74 68 61 74 20 73 65 72 76 65 20 61  AA" that serve a
234f0 73 0a 2a 2a 20 70 6c 61 63 65 68 6f 6c 64 65 72  s.** placeholder
23500 73 20 66 6f 72 20 76 61 6c 75 65 73 20 74 68 61  s for values tha
23510 74 20 61 72 65 20 5b 73 71 6c 69 74 65 33 5f 62  t are [sqlite3_b
23520 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 6f 75 6e 64  ind_blob | bound
23530 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 70 61 72 61  ].** to the para
23540 6d 65 74 65 72 73 20 61 74 20 61 20 6c 61 74 65  meters at a late
23550 72 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  r time..**.** Th
23560 69 73 20 72 6f 75 74 69 6e 65 20 61 63 74 75 61  is routine actua
23570 6c 6c 79 20 72 65 74 75 72 6e 73 20 74 68 65 20  lly returns the 
23580 69 6e 64 65 78 20 6f 66 20 74 68 65 20 6c 61 72  index of the lar
23590 67 65 73 74 20 28 72 69 67 68 74 6d 6f 73 74 29  gest (rightmost)
235a0 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e 20 46  .** parameter. F
235b0 6f 72 20 61 6c 6c 20 66 6f 72 6d 73 20 65 78 63  or all forms exc
235c0 65 70 74 20 3f 4e 4e 4e 2c 20 74 68 69 73 20 77  ept ?NNN, this w
235d0 69 6c 6c 20 63 6f 72 72 65 73 70 6f 6e 64 20 74  ill correspond t
235e0 6f 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20  o the.** number 
235f0 6f 66 20 75 6e 69 71 75 65 20 70 61 72 61 6d 65  of unique parame
23600 74 65 72 73 2e 20 20 49 66 20 70 61 72 61 6d 65  ters.  If parame
23610 74 65 72 73 20 6f 66 20 74 68 65 20 3f 4e 4e 4e  ters of the ?NNN
23620 20 61 72 65 20 75 73 65 64 2c 0a 2a 2a 20 74 68   are used,.** th
23630 65 72 65 20 6d 61 79 20 62 65 20 67 61 70 73 20  ere may be gaps 
23640 69 6e 20 74 68 65 20 6c 69 73 74 2e 0a 2a 2a 0a  in the list..**.
23650 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
23660 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c  lite3_bind_blob|
23670 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c  sqlite3_bind()],
23680 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
23690 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65  d_parameter_name
236a0 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ()], and.** [sql
236b0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
236c0 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2a  ter_index()]..**
236d0 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
236e0 2a 2a 0a 2a 2a 20 7b 48 31 33 36 30 31 7d 20 54  **.** {H13601} T
236f0 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  he [sqlite3_bind
23700 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74  _parameter_count
23710 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  (S)] interface r
23720 65 74 75 72 6e 73 0a 2a 2a 20 20 20 20 20 20 20  eturns.**       
23730 20 20 20 74 68 65 20 6c 61 72 67 65 73 74 20 69     the largest i
23740 6e 64 65 78 20 6f 66 20 61 6c 6c 20 53 51 4c 20  ndex of all SQL 
23750 70 61 72 61 6d 65 74 65 72 73 20 69 6e 20 74 68  parameters in th
23760 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70  e.**          [p
23770 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
23780 74 5d 20 53 2c 20 6f 72 20 30 20 69 66 20 53 20  t] S, or 0 if S 
23790 63 6f 6e 74 61 69 6e 73 20 6e 6f 20 53 51 4c 20  contains no SQL 
237a0 70 61 72 61 6d 65 74 65 72 73 2e 0a 2a 2f 0a 69  parameters..*/.i
237b0 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
237c0 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28  parameter_count(
237d0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a  sqlite3_stmt*);.
237e0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
237f0 20 4e 61 6d 65 20 4f 66 20 41 20 48 6f 73 74 20   Name Of A Host 
23800 50 61 72 61 6d 65 74 65 72 20 7b 48 31 33 36 32  Parameter {H1362
23810 30 7d 20 3c 53 37 30 33 30 30 3e 0a 2a 2a 0a 2a  0} <S70300>.**.*
23820 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72  * This routine r
23830 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
23840 20 74 6f 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   to the name of 
23850 74 68 65 20 6e 2d 74 68 0a 2a 2a 20 5b 53 51 4c  the n-th.** [SQL
23860 20 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 61   parameter] in a
23870 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
23880 6d 65 6e 74 5d 2e 0a 2a 2a 20 53 51 4c 20 70 61  ment]..** SQL pa
23890 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20  rameters of the 
238a0 66 6f 72 6d 20 22 3f 4e 4e 4e 22 20 6f 72 20 22  form "?NNN" or "
238b0 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41 22 20  :AAA" or "@AAA" 
238c0 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 68 61 76  or "$AAA".** hav
238d0 65 20 61 20 6e 61 6d 65 20 77 68 69 63 68 20 69  e a name which i
238e0 73 20 74 68 65 20 73 74 72 69 6e 67 20 22 3f 4e  s the string "?N
238f0 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72  NN" or ":AAA" or
23900 20 22 40 41 41 41 22 20 6f 72 20 22 24 41 41 41   "@AAA" or "$AAA
23910 22 0a 2a 2a 20 72 65 73 70 65 63 74 69 76 65 6c  ".** respectivel
23920 79 2e 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77  y..** In other w
23930 6f 72 64 73 2c 20 74 68 65 20 69 6e 69 74 69 61  ords, the initia
23940 6c 20 22 3a 22 20 6f 72 20 22 24 22 20 6f 72 20  l ":" or "$" or 
23950 22 40 22 20 6f 72 20 22 3f 22 0a 2a 2a 20 69 73  "@" or "?".** is
23960 20 69 6e 63 6c 75 64 65 64 20 61 73 20 70 61 72   included as par
23970 74 20 6f 66 20 74 68 65 20 6e 61 6d 65 2e 0a 2a  t of the name..*
23980 2a 20 50 61 72 61 6d 65 74 65 72 73 20 6f 66 20  * Parameters of 
23990 74 68 65 20 66 6f 72 6d 20 22 3f 22 20 77 69 74  the form "?" wit
239a0 68 6f 75 74 20 61 20 66 6f 6c 6c 6f 77 69 6e 67  hout a following
239b0 20 69 6e 74 65 67 65 72 20 68 61 76 65 20 6e 6f   integer have no
239c0 20 6e 61 6d 65 0a 2a 2a 20 61 6e 64 20 61 72 65   name.** and are
239d0 20 61 6c 73 6f 20 72 65 66 65 72 72 65 64 20 74   also referred t
239e0 6f 20 61 73 20 22 61 6e 6f 6e 79 6d 6f 75 73 20  o as "anonymous 
239f0 70 61 72 61 6d 65 74 65 72 73 22 2e 0a 2a 2a 0a  parameters"..**.
23a00 2a 2a 20 54 68 65 20 66 69 72 73 74 20 68 6f 73  ** The first hos
23a10 74 20 70 61 72 61 6d 65 74 65 72 20 68 61 73 20  t parameter has 
23a20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2c 20 6e  an index of 1, n
23a30 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  ot 0..**.** If t
23a40 68 65 20 76 61 6c 75 65 20 6e 20 69 73 20 6f 75  he value n is ou
23a50 74 20 6f 66 20 72 61 6e 67 65 20 6f 72 20 69 66  t of range or if
23a60 20 74 68 65 20 6e 2d 74 68 20 70 61 72 61 6d 65   the n-th parame
23a70 74 65 72 20 69 73 0a 2a 2a 20 6e 61 6d 65 6c 65  ter is.** namele
23a80 73 73 2c 20 74 68 65 6e 20 4e 55 4c 4c 20 69 73  ss, then NULL is
23a90 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20   returned.  The 
23aa0 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20  returned string 
23ab0 69 73 0a 2a 2a 20 61 6c 77 61 79 73 20 69 6e 20  is.** always in 
23ac0 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 65  UTF-8 encoding e
23ad0 76 65 6e 20 69 66 20 74 68 65 20 6e 61 6d 65 64  ven if the named
23ae0 20 70 61 72 61 6d 65 74 65 72 20 77 61 73 0a 2a   parameter was.*
23af0 2a 20 6f 72 69 67 69 6e 61 6c 6c 79 20 73 70 65  * originally spe
23b00 63 69 66 69 65 64 20 61 73 20 55 54 46 2d 31 36  cified as UTF-16
23b10 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   in [sqlite3_pre
23b20 70 61 72 65 31 36 28 29 5d 20 6f 72 0a 2a 2a 20  pare16()] or.** 
23b30 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
23b40 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  16_v2()]..**.** 
23b50 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
23b60 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c  e3_bind_blob|sql
23b70 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a  ite3_bind()],.**
23b80 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
23b90 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29  arameter_count()
23ba0 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  ], and.** [sqlit
23bb0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
23bc0 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2a 0a 2a  r_index()]..**.*
23bd0 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
23be0 0a 2a 2a 20 7b 48 31 33 36 32 31 7d 20 54 68 65  .** {H13621} The
23bf0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
23c00 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 53 2c  arameter_name(S,
23c10 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  N)] interface re
23c20 74 75 72 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20  turns.**        
23c30 20 20 61 20 55 54 46 2d 38 20 72 65 6e 64 65 72    a UTF-8 render
23c40 69 6e 67 20 6f 66 20 74 68 65 20 6e 61 6d 65 20  ing of the name 
23c50 6f 66 20 74 68 65 20 53 51 4c 20 70 61 72 61 6d  of the SQL param
23c60 65 74 65 72 20 69 6e 0a 2a 2a 20 20 20 20 20 20  eter in.**      
23c70 20 20 20 20 74 68 65 20 5b 70 72 65 70 61 72 65      the [prepare
23c80 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 68  d statement] S h
23c90 61 76 69 6e 67 20 69 6e 64 65 78 20 4e 2c 20 6f  aving index N, o
23ca0 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 55  r.**          NU
23cb0 4c 4c 20 69 66 20 74 68 65 72 65 20 69 73 20 6e  LL if there is n
23cc0 6f 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20  o SQL parameter 
23cd0 77 69 74 68 20 69 6e 64 65 78 20 4e 20 6f 72 20  with index N or 
23ce0 69 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  if the.**       
23cf0 20 20 20 70 61 72 61 6d 65 74 65 72 20 77 69 74     parameter wit
23d00 68 20 69 6e 64 65 78 20 4e 20 69 73 20 61 6e 20  h index N is an 
23d10 61 6e 6f 6e 79 6d 6f 75 73 20 70 61 72 61 6d 65  anonymous parame
23d20 74 65 72 20 22 3f 22 2e 0a 2a 2f 0a 63 6f 6e 73  ter "?"..*/.cons
23d30 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
23d40 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e  bind_parameter_n
23d50 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ame(sqlite3_stmt
23d60 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *, int);../*.** 
23d70 43 41 50 49 33 52 45 46 3a 20 49 6e 64 65 78 20  CAPI3REF: Index 
23d80 4f 66 20 41 20 50 61 72 61 6d 65 74 65 72 20 57  Of A Parameter W
23d90 69 74 68 20 41 20 47 69 76 65 6e 20 4e 61 6d 65  ith A Given Name
23da0 20 7b 48 31 33 36 34 30 7d 20 3c 53 37 30 33 30   {H13640} <S7030
23db0 30 3e 0a 2a 2a 0a 2a 2a 20 52 65 74 75 72 6e 20  0>.**.** Return 
23dc0 74 68 65 20 69 6e 64 65 78 20 6f 66 20 61 6e 20  the index of an 
23dd0 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 67 69  SQL parameter gi
23de0 76 65 6e 20 69 74 73 20 6e 61 6d 65 2e 20 20 54  ven its name.  T
23df0 68 65 0a 2a 2a 20 69 6e 64 65 78 20 76 61 6c 75  he.** index valu
23e00 65 20 72 65 74 75 72 6e 65 64 20 69 73 20 73 75  e returned is su
23e10 69 74 61 62 6c 65 20 66 6f 72 20 75 73 65 20 61  itable for use a
23e20 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20  s the second.** 
23e30 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71  parameter to [sq
23e40 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c  lite3_bind_blob|
23e50 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2e  sqlite3_bind()].
23e60 20 20 41 20 7a 65 72 6f 0a 2a 2a 20 69 73 20 72    A zero.** is r
23e70 65 74 75 72 6e 65 64 20 69 66 20 6e 6f 20 6d 61  eturned if no ma
23e80 74 63 68 69 6e 67 20 70 61 72 61 6d 65 74 65 72  tching parameter
23e90 20 69 73 20 66 6f 75 6e 64 2e 20 20 54 68 65 20   is found.  The 
23ea0 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 6e 61 6d  parameter.** nam
23eb0 65 20 6d 75 73 74 20 62 65 20 67 69 76 65 6e 20  e must be given 
23ec0 69 6e 20 55 54 46 2d 38 20 65 76 65 6e 20 69 66  in UTF-8 even if
23ed0 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74   the original st
23ee0 61 74 65 6d 65 6e 74 0a 2a 2a 20 77 61 73 20 70  atement.** was p
23ef0 72 65 70 61 72 65 64 20 66 72 6f 6d 20 55 54 46  repared from UTF
23f00 2d 31 36 20 74 65 78 74 20 75 73 69 6e 67 20 5b  -16 text using [
23f10 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
23f20 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53  6_v2()]..**.** S
23f30 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
23f40 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69  3_bind_blob|sqli
23f50 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20  te3_bind()],.** 
23f60 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
23f70 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d  rameter_count()]
23f80 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  , and.** [sqlite
23f90 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
23fa0 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2a 0a 2a 2a  _index()]..**.**
23fb0 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
23fc0 2a 2a 20 7b 48 31 33 36 34 31 7d 20 54 68 65 20  ** {H13641} The 
23fd0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
23fe0 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 53 2c  rameter_index(S,
23ff0 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  N)] interface re
24000 74 75 72 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20  turns.**        
24010 20 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 53    the index of S
24020 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20  QL parameter in 
24030 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
24040 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 20 20 20 20  atement].**     
24050 20 20 20 20 20 53 20 77 68 6f 73 65 20 6e 61 6d       S whose nam
24060 65 20 6d 61 74 63 68 65 73 20 74 68 65 20 55 54  e matches the UT
24070 46 2d 38 20 73 74 72 69 6e 67 20 4e 2c 20 6f 72  F-8 string N, or
24080 20 30 20 69 66 20 74 68 65 72 65 20 69 73 0a 2a   0 if there is.*
24090 2a 20 20 20 20 20 20 20 20 20 20 6e 6f 20 6d 61  *          no ma
240a0 74 63 68 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  tch..*/.int sqli
240b0 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
240c0 65 72 5f 69 6e 64 65 78 28 73 71 6c 69 74 65 33  er_index(sqlite3
240d0 5f 73 74 6d 74 2a 2c 20 63 6f 6e 73 74 20 63 68  _stmt*, const ch
240e0 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a  ar *zName);../*.
240f0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73  ** CAPI3REF: Res
24100 65 74 20 41 6c 6c 20 42 69 6e 64 69 6e 67 73 20  et All Bindings 
24110 4f 6e 20 41 20 50 72 65 70 61 72 65 64 20 53 74  On A Prepared St
24120 61 74 65 6d 65 6e 74 20 7b 48 31 33 36 36 30 7d  atement {H13660}
24130 20 3c 53 37 30 33 30 30 3e 0a 2a 2a 0a 2a 2a 20   <S70300>.**.** 
24140 43 6f 6e 74 72 61 72 79 20 74 6f 20 74 68 65 20  Contrary to the 
24150 69 6e 74 75 69 74 69 6f 6e 20 6f 66 20 6d 61 6e  intuition of man
24160 79 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  y, [sqlite3_rese
24170 74 28 29 5d 20 64 6f 65 73 20 6e 6f 74 20 72 65  t()] does not re
24180 73 65 74 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69  set.** the [sqli
24190 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20  te3_bind_blob | 
241a0 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 61 20 5b  bindings] on a [
241b0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
241c0 6e 74 5d 2e 0a 2a 2a 20 55 73 65 20 74 68 69 73  nt]..** Use this
241d0 20 72 6f 75 74 69 6e 65 20 74 6f 20 72 65 73 65   routine to rese
241e0 74 20 61 6c 6c 20 68 6f 73 74 20 70 61 72 61 6d  t all host param
241f0 65 74 65 72 73 20 74 6f 20 4e 55 4c 4c 2e 0a 2a  eters to NULL..*
24200 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
24210 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 36 36 31 7d 20  .**.** {H13661} 
24220 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6c 65  The [sqlite3_cle
24230 61 72 5f 62 69 6e 64 69 6e 67 73 28 53 29 5d 20  ar_bindings(S)] 
24240 69 6e 74 65 72 66 61 63 65 20 72 65 73 65 74 73  interface resets
24250 20 61 6c 6c 20 53 51 4c 0a 2a 2a 20 20 20 20 20   all SQL.**     
24260 20 20 20 20 20 70 61 72 61 6d 65 74 65 72 20 62       parameter b
24270 69 6e 64 69 6e 67 73 20 69 6e 20 74 68 65 20 5b  indings in the [
24280 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
24290 6e 74 5d 20 53 20 62 61 63 6b 20 74 6f 20 4e 55  nt] S back to NU
242a0 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  LL..*/.int sqlit
242b0 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67  e3_clear_binding
242c0 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29  s(sqlite3_stmt*)
242d0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
242e0 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 43 6f 6c  F: Number Of Col
242f0 75 6d 6e 73 20 49 6e 20 41 20 52 65 73 75 6c 74  umns In A Result
24300 20 53 65 74 20 7b 48 31 33 37 31 30 7d 20 3c 53   Set {H13710} <S
24310 31 30 37 30 30 3e 0a 2a 2a 0a 2a 2a 20 52 65 74  10700>.**.** Ret
24320 75 72 6e 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  urn the number o
24330 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65  f columns in the
24340 20 72 65 73 75 6c 74 20 73 65 74 20 72 65 74 75   result set retu
24350 72 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b  rned by the.** [
24360 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
24370 6e 74 5d 2e 20 54 68 69 73 20 72 6f 75 74 69 6e  nt]. This routin
24380 65 20 72 65 74 75 72 6e 73 20 30 20 69 66 20 70  e returns 0 if p
24390 53 74 6d 74 20 69 73 20 61 6e 20 53 51 4c 0a 2a  Stmt is an SQL.*
243a0 2a 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74  * statement that
243b0 20 64 6f 65 73 20 6e 6f 74 20 72 65 74 75 72 6e   does not return
243c0 20 64 61 74 61 20 28 66 6f 72 20 65 78 61 6d 70   data (for examp
243d0 6c 65 20 61 6e 20 5b 55 50 44 41 54 45 5d 29 2e  le an [UPDATE]).
243e0 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
243f0 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 31 31  S:.**.** {H13711
24400 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  } The [sqlite3_c
24410 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 53 29 5d 20  olumn_count(S)] 
24420 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
24430 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a  s the number of.
24440 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6c 75  **          colu
24450 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c  mns in the resul
24460 74 20 73 65 74 20 67 65 6e 65 72 61 74 65 64 20  t set generated 
24470 62 79 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  by the [prepared
24480 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2c 0a 2a   statement] S,.*
24490 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 30 20  *          or 0 
244a0 69 66 20 53 20 64 6f 65 73 20 6e 6f 74 20 67 65  if S does not ge
244b0 6e 65 72 61 74 65 20 61 20 72 65 73 75 6c 74 20  nerate a result 
244c0 73 65 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  set..*/.int sqli
244d0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74  te3_column_count
244e0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70  (sqlite3_stmt *p
244f0 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Stmt);../*.** CA
24500 50 49 33 52 45 46 3a 20 43 6f 6c 75 6d 6e 20 4e  PI3REF: Column N
24510 61 6d 65 73 20 49 6e 20 41 20 52 65 73 75 6c 74  ames In A Result
24520 20 53 65 74 20 7b 48 31 33 37 32 30 7d 20 3c 53   Set {H13720} <S
24530 31 30 37 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  10700>.**.** The
24540 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  se routines retu
24550 72 6e 20 74 68 65 20 6e 61 6d 65 20 61 73 73 69  rn the name assi
24560 67 6e 65 64 20 74 6f 20 61 20 70 61 72 74 69 63  gned to a partic
24570 75 6c 61 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69  ular column.** i
24580 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  n the result set
24590 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 73   of a [SELECT] s
245a0 74 61 74 65 6d 65 6e 74 2e 20 20 54 68 65 20 73  tatement.  The s
245b0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
245c0 6d 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63  me().** interfac
245d0 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  e returns a poin
245e0 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65  ter to a zero-te
245f0 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73  rminated UTF-8 s
24600 74 72 69 6e 67 0a 2a 2a 20 61 6e 64 20 73 71 6c  tring.** and sql
24610 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
24620 31 36 28 29 20 72 65 74 75 72 6e 73 20 61 20 70  16() returns a p
24630 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 6f  ointer to a zero
24640 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55  -terminated.** U
24650 54 46 2d 31 36 20 73 74 72 69 6e 67 2e 20 20 54  TF-16 string.  T
24660 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
24670 65 72 20 69 73 20 74 68 65 20 5b 70 72 65 70 61  er is the [prepa
24680 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a  red statement].*
24690 2a 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74  * that implement
246a0 73 20 74 68 65 20 5b 53 45 4c 45 43 54 5d 20 73  s the [SELECT] s
246b0 74 61 74 65 6d 65 6e 74 2e 20 54 68 65 20 73 65  tatement. The se
246c0 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69  cond parameter i
246d0 73 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20  s the.** column 
246e0 6e 75 6d 62 65 72 2e 20 20 54 68 65 20 6c 65 66  number.  The lef
246f0 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20  tmost column is 
24700 6e 75 6d 62 65 72 20 30 2e 0a 2a 2a 0a 2a 2a 20  number 0..**.** 
24710 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72  The returned str
24720 69 6e 67 20 70 6f 69 6e 74 65 72 20 69 73 20 76  ing pointer is v
24730 61 6c 69 64 20 75 6e 74 69 6c 20 65 69 74 68 65  alid until eithe
24740 72 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  r the [prepared 
24750 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 69 73  statement].** is
24760 20 64 65 73 74 72 6f 79 65 64 20 62 79 20 5b 73   destroyed by [s
24770 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
24780 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20  )] or until the 
24790 6e 65 78 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20  next call to.** 
247a0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
247b0 61 6d 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33  ame() or sqlite3
247c0 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29  _column_name16()
247d0 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 63 6f 6c   on the same col
247e0 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 73 71  umn..**.** If sq
247f0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 66  lite3_malloc() f
24800 61 69 6c 73 20 64 75 72 69 6e 67 20 74 68 65 20  ails during the 
24810 70 72 6f 63 65 73 73 69 6e 67 20 6f 66 20 65 69  processing of ei
24820 74 68 65 72 20 72 6f 75 74 69 6e 65 0a 2a 2a 20  ther routine.** 
24830 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 64 75 72  (for example dur
24840 69 6e 67 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e  ing a conversion
24850 20 66 72 6f 6d 20 55 54 46 2d 38 20 74 6f 20 55   from UTF-8 to U
24860 54 46 2d 31 36 29 20 74 68 65 6e 20 61 0a 2a 2a  TF-16) then a.**
24870 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73   NULL pointer is
24880 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
24890 20 54 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 72   The name of a r
248a0 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 73 20  esult column is 
248b0 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65  the value of the
248c0 20 22 41 53 22 20 63 6c 61 75 73 65 20 66 6f 72   "AS" clause for
248d0 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 75 6d 6e 2c  .** that column,
248e0 20 69 66 20 74 68 65 72 65 20 69 73 20 61 6e 20   if there is an 
248f0 41 53 20 63 6c 61 75 73 65 2e 20 20 49 66 20 74  AS clause.  If t
24900 68 65 72 65 20 69 73 20 6e 6f 20 41 53 20 63 6c  here is no AS cl
24910 61 75 73 65 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ause.** then the
24920 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c   name of the col
24930 75 6d 6e 20 69 73 20 75 6e 73 70 65 63 69 66 69  umn is unspecifi
24940 65 64 20 61 6e 64 20 6d 61 79 20 63 68 61 6e 67  ed and may chang
24950 65 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 72 65  e from.** one re
24960 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 20  lease of SQLite 
24970 74 6f 20 74 68 65 20 6e 65 78 74 2e 0a 2a 2a 0a  to the next..**.
24980 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
24990 2a 0a 2a 2a 20 7b 48 31 33 37 32 31 7d 20 41 20  *.** {H13721} A 
249a0 73 75 63 63 65 73 73 66 75 6c 20 69 6e 76 6f 63  successful invoc
249b0 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 5b 73 71  ation of the [sq
249c0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
249d0 65 28 53 2c 4e 29 5d 0a 2a 2a 20 20 20 20 20 20  e(S,N)].**      
249e0 20 20 20 20 69 6e 74 65 72 66 61 63 65 20 72 65      interface re
249f0 74 75 72 6e 73 20 74 68 65 20 6e 61 6d 65 20 6f  turns the name o
24a00 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e  f the Nth column
24a10 20 28 77 68 65 72 65 20 30 20 69 73 0a 2a 2a 20   (where 0 is.** 
24a20 20 20 20 20 20 20 20 20 20 74 68 65 20 6c 65 66           the lef
24a30 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 29 20 66 6f  tmost column) fo
24a40 72 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  r the result set
24a50 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20   of the.**      
24a60 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74      [prepared st
24a70 61 74 65 6d 65 6e 74 5d 20 53 20 61 73 20 61 20  atement] S as a 
24a80 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
24a90 55 54 46 2d 38 20 73 74 72 69 6e 67 2e 0a 2a 2a  UTF-8 string..**
24aa0 0a 2a 2a 20 7b 48 31 33 37 32 33 7d 20 41 20 73  .** {H13723} A s
24ab0 75 63 63 65 73 73 66 75 6c 20 69 6e 76 6f 63 61  uccessful invoca
24ac0 74 69 6f 6e 20 6f 66 20 74 68 65 20 5b 73 71 6c  tion of the [sql
24ad0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
24ae0 31 36 28 53 2c 4e 29 5d 0a 2a 2a 20 20 20 20 20  16(S,N)].**     
24af0 20 20 20 20 20 69 6e 74 65 72 66 61 63 65 20 72       interface r
24b00 65 74 75 72 6e 73 20 74 68 65 20 6e 61 6d 65 20  eturns the name 
24b10 6f 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d  of the Nth colum
24b20 6e 20 28 77 68 65 72 65 20 30 20 69 73 0a 2a 2a  n (where 0 is.**
24b30 20 20 20 20 20 20 20 20 20 20 74 68 65 20 6c 65            the le
24b40 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 29 20 66  ftmost column) f
24b50 6f 72 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  or the result se
24b60 74 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 20  t of the.**     
24b70 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73       [prepared s
24b80 74 61 74 65 6d 65 6e 74 5d 20 53 20 61 73 20 61  tatement] S as a
24b90 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
24ba0 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 0a 2a   UTF-16 string.*
24bb0 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20 74 68  *          in th
24bc0 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  e native byte or
24bd0 64 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37  der..**.** {H137
24be0 32 34 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  24} The [sqlite3
24bf0 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 5d 20  _column_name()] 
24c00 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  and [sqlite3_col
24c10 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 5d 0a 2a 2a  umn_name16()].**
24c20 20 20 20 20 20 20 20 20 20 20 69 6e 74 65 72 66            interf
24c30 61 63 65 73 20 72 65 74 75 72 6e 20 61 20 4e 55  aces return a NU
24c40 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 20 74 68  LL pointer if th
24c50 65 79 20 61 72 65 20 75 6e 61 62 6c 65 20 74 6f  ey are unable to
24c60 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6c 6c  .**          all
24c70 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20  ocate memory to 
24c80 68 6f 6c 64 20 74 68 65 69 72 20 6e 6f 72 6d 61  hold their norma
24c90 6c 20 72 65 74 75 72 6e 20 73 74 72 69 6e 67 73  l return strings
24ca0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 32 35 7d  ..**.** {H13725}
24cb0 20 49 66 20 74 68 65 20 4e 20 70 61 72 61 6d 65   If the N parame
24cc0 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ter to [sqlite3_
24cd0 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 53 2c 4e 29  column_name(S,N)
24ce0 5d 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  ] or.**         
24cf0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
24d00 5f 6e 61 6d 65 31 36 28 53 2c 4e 29 5d 20 69 73  _name16(S,N)] is
24d10 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c 20 74   out of range, t
24d20 68 65 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  hen the.**      
24d30 20 20 20 20 69 6e 74 65 72 66 61 63 65 73 20 72      interfaces r
24d40 65 74 75 72 6e 20 61 20 4e 55 4c 4c 20 70 6f 69  eturn a NULL poi
24d50 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33  nter..**.** {H13
24d60 37 32 36 7d 20 54 68 65 20 73 74 72 69 6e 67 73  726} The strings
24d70 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71   returned by [sq
24d80 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
24d90 65 28 53 2c 4e 29 5d 20 61 6e 64 0a 2a 2a 20 20  e(S,N)] and.**  
24da0 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
24db0 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 53  _column_name16(S
24dc0 2c 4e 29 5d 20 61 72 65 20 76 61 6c 69 64 20 75  ,N)] are valid u
24dd0 6e 74 69 6c 20 74 68 65 20 6e 65 78 74 0a 2a 2a  ntil the next.**
24de0 20 20 20 20 20 20 20 20 20 20 63 61 6c 6c 20 74            call t
24df0 6f 20 65 69 74 68 65 72 20 72 6f 75 74 69 6e 65  o either routine
24e00 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 53   with the same S
24e10 20 61 6e 64 20 4e 20 70 61 72 61 6d 65 74 65 72   and N parameter
24e20 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72  s.**          or
24e30 20 75 6e 74 69 6c 20 5b 73 71 6c 69 74 65 33 5f   until [sqlite3_
24e40 66 69 6e 61 6c 69 7a 65 28 53 29 5d 20 69 73 20  finalize(S)] is 
24e50 63 61 6c 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48  called..**.** {H
24e60 31 33 37 32 37 7d 20 57 68 65 6e 20 61 20 72 65  13727} When a re
24e70 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 61  sult column of a
24e80 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d   [SELECT] statem
24e90 65 6e 74 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20  ent contains.** 
24ea0 20 20 20 20 20 20 20 20 20 61 6e 20 41 53 20 63           an AS c
24eb0 6c 61 75 73 65 2c 20 74 68 65 20 6e 61 6d 65 20  lause, the name 
24ec0 6f 66 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69  of that column i
24ed0 73 20 74 68 65 20 69 64 65 6e 74 69 66 69 65 72  s the identifier
24ee0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20  .**          to 
24ef0 74 68 65 20 72 69 67 68 74 20 6f 66 20 74 68 65  the right of the
24f00 20 41 53 20 6b 65 79 77 6f 72 64 2e 0a 2a 2f 0a   AS keyword..*/.
24f10 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
24f20 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28  te3_column_name(
24f30 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
24f40 6e 74 20 4e 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  nt N);.const voi
24f50 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
24f60 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33  n_name16(sqlite3
24f70 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a  _stmt*, int N);.
24f80 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
24f90 20 53 6f 75 72 63 65 20 4f 66 20 44 61 74 61 20   Source Of Data 
24fa0 49 6e 20 41 20 51 75 65 72 79 20 52 65 73 75 6c  In A Query Resul
24fb0 74 20 7b 48 31 33 37 34 30 7d 20 3c 53 31 30 37  t {H13740} <S107
24fc0 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  00>.**.** These 
24fd0 72 6f 75 74 69 6e 65 73 20 70 72 6f 76 69 64 65  routines provide
24fe0 20 61 20 6d 65 61 6e 73 20 74 6f 20 64 65 74 65   a means to dete
24ff0 72 6d 69 6e 65 20 77 68 61 74 20 63 6f 6c 75 6d  rmine what colum
25000 6e 20 6f 66 20 77 68 61 74 0a 2a 2a 20 74 61 62  n of what.** tab
25010 6c 65 20 69 6e 20 77 68 69 63 68 20 64 61 74 61  le in which data
25020 62 61 73 65 20 61 20 72 65 73 75 6c 74 20 6f 66  base a result of
25030 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74   a [SELECT] stat
25040 65 6d 65 6e 74 20 63 6f 6d 65 73 20 66 72 6f 6d  ement comes from
25050 2e 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66  ..** The name of
25060 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6f 72   the database or
25070 20 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e   table or column
25080 20 63 61 6e 20 62 65 20 72 65 74 75 72 6e 65 64   can be returned
25090 20 61 73 0a 2a 2a 20 65 69 74 68 65 72 20 61 20   as.** either a 
250a0 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20  UTF-8 or UTF-16 
250b0 73 74 72 69 6e 67 2e 20 20 54 68 65 20 5f 64 61  string.  The _da
250c0 74 61 62 61 73 65 5f 20 72 6f 75 74 69 6e 65 73  tabase_ routines
250d0 20 72 65 74 75 72 6e 0a 2a 2a 20 74 68 65 20 64   return.** the d
250e0 61 74 61 62 61 73 65 20 6e 61 6d 65 2c 20 74 68  atabase name, th
250f0 65 20 5f 74 61 62 6c 65 5f 20 72 6f 75 74 69 6e  e _table_ routin
25100 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 74 61  es return the ta
25110 62 6c 65 20 6e 61 6d 65 2c 20 61 6e 64 0a 2a 2a  ble name, and.**
25120 20 74 68 65 20 6f 72 69 67 69 6e 5f 20 72 6f 75   the origin_ rou
25130 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65  tines return the
25140 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a   column name..**
25150 20 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74   The returned st
25160 72 69 6e 67 20 69 73 20 76 61 6c 69 64 20 75 6e  ring is valid un
25170 74 69 6c 20 74 68 65 20 5b 70 72 65 70 61 72 65  til the [prepare
25180 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 73 20  d statement] is 
25190 64 65 73 74 72 6f 79 65 64 0a 2a 2a 20 75 73 69  destroyed.** usi
251a0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  ng [sqlite3_fina
251b0 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c  lize()] or until
251c0 20 74 68 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d   the same inform
251d0 61 74 69 6f 6e 20 69 73 20 72 65 71 75 65 73 74  ation is request
251e0 65 64 0a 2a 2a 20 61 67 61 69 6e 20 69 6e 20 61  ed.** again in a
251f0 20 64 69 66 66 65 72 65 6e 74 20 65 6e 63 6f 64   different encod
25200 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6e  ing..**.** The n
25210 61 6d 65 73 20 72 65 74 75 72 6e 65 64 20 61 72  ames returned ar
25220 65 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 75  e the original u
25230 6e 2d 61 6c 69 61 73 65 64 20 6e 61 6d 65 73 20  n-aliased names 
25240 6f 66 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61  of the.** databa
25250 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64 20 63  se, table, and c
25260 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  olumn..**.** The
25270 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
25280 74 6f 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  to the following
25290 20 63 61 6c 6c 73 20 69 73 20 61 20 5b 70 72 65   calls is a [pre
252a0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
252b0 2e 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74  ..** These funct
252c0 69 6f 6e 73 20 72 65 74 75 72 6e 20 69 6e 66 6f  ions return info
252d0 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 74 68  rmation about th
252e0 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 72 65 74  e Nth column ret
252f0 75 72 6e 65 64 20 62 79 0a 2a 2a 20 74 68 65 20  urned by.** the 
25300 73 74 61 74 65 6d 65 6e 74 2c 20 77 68 65 72 65  statement, where
25310 20 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64   N is the second
25320 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65   function argume
25330 6e 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  nt..**.** If the
25340 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75   Nth column retu
25350 72 6e 65 64 20 62 79 20 74 68 65 20 73 74 61 74  rned by the stat
25360 65 6d 65 6e 74 20 69 73 20 61 6e 20 65 78 70 72  ement is an expr
25370 65 73 73 69 6f 6e 20 6f 72 0a 2a 2a 20 73 75 62  ession or.** sub
25380 71 75 65 72 79 20 61 6e 64 20 69 73 20 6e 6f 74  query and is not
25390 20 61 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 2c   a column value,
253a0 20 74 68 65 6e 20 61 6c 6c 20 6f 66 20 74 68 65   then all of the
253b0 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74  se functions ret
253c0 75 72 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20 20 54 68  urn.** NULL.  Th
253d0 65 73 65 20 72 6f 75 74 69 6e 65 20 6d 69 67 68  ese routine migh
253e0 74 20 61 6c 73 6f 20 72 65 74 75 72 6e 20 4e 55  t also return NU
253f0 4c 4c 20 69 66 20 61 20 6d 65 6d 6f 72 79 20 61  LL if a memory a
25400 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 0a  llocation error.
25410 2a 2a 20 6f 63 63 75 72 73 2e 20 20 4f 74 68 65  ** occurs.  Othe
25420 72 77 69 73 65 2c 20 74 68 65 79 20 72 65 74 75  rwise, they retu
25430 72 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  rn the name of t
25440 68 65 20 61 74 74 61 63 68 65 64 20 64 61 74 61  he attached data
25450 62 61 73 65 2c 20 74 61 62 6c 65 0a 2a 2a 20 61  base, table.** a
25460 6e 64 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 71  nd column that q
25470 75 65 72 79 20 72 65 73 75 6c 74 20 63 6f 6c 75  uery result colu
25480 6d 6e 20 77 61 73 20 65 78 74 72 61 63 74 65 64  mn was extracted
25490 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 41 73 20   from..**.** As 
254a0 77 69 74 68 20 61 6c 6c 20 6f 74 68 65 72 20 53  with all other S
254b0 51 4c 69 74 65 20 41 50 49 73 2c 20 74 68 6f 73  QLite APIs, thos
254c0 65 20 70 6f 73 74 66 69 78 65 64 20 77 69 74 68  e postfixed with
254d0 20 22 31 36 22 20 72 65 74 75 72 6e 0a 2a 2a 20   "16" return.** 
254e0 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 73  UTF-16 encoded s
254f0 74 72 69 6e 67 73 2c 20 74 68 65 20 6f 74 68 65  trings, the othe
25500 72 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75  r functions retu
25510 72 6e 20 55 54 46 2d 38 2e 20 7b 45 4e 44 7d 0a  rn UTF-8. {END}.
25520 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 41 50 49 73  **.** These APIs
25530 20 61 72 65 20 6f 6e 6c 79 20 61 76 61 69 6c 61   are only availa
25540 62 6c 65 20 69 66 20 74 68 65 20 6c 69 62 72 61  ble if the libra
25550 72 79 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20  ry was compiled 
25560 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c  with the.** [SQL
25570 49 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d  ITE_ENABLE_COLUM
25580 4e 5f 4d 45 54 41 44 41 54 41 5d 20 43 2d 70 72  N_METADATA] C-pr
25590 65 70 72 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f  eprocessor symbo
255a0 6c 20 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  l defined..**.**
255b0 20 7b 41 31 33 37 35 31 7d 0a 2a 2a 20 49 66 20   {A13751}.** If 
255c0 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65  two or more thre
255d0 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20  ads call one or 
255e0 6d 6f 72 65 20 6f 66 20 74 68 65 73 65 20 72 6f  more of these ro
255f0 75 74 69 6e 65 73 20 61 67 61 69 6e 73 74 20 74  utines against t
25600 68 65 20 73 61 6d 65 0a 2a 2a 20 70 72 65 70 61  he same.** prepa
25610 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61 6e  red statement an
25620 64 20 63 6f 6c 75 6d 6e 20 61 74 20 74 68 65 20  d column at the 
25630 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74  same time then t
25640 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 0a 2a  he results are.*
25650 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  * undefined..**.
25660 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
25670 2a 0a 2a 2a 20 7b 48 31 33 37 34 31 7d 20 54 68  *.** {H13741} Th
25680 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  e [sqlite3_colum
25690 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 28  n_database_name(
256a0 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20  S,N)] interface 
256b0 72 65 74 75 72 6e 73 20 65 69 74 68 65 72 0a 2a  returns either.*
256c0 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 55  *          the U
256d0 54 46 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  TF-8 zero-termin
256e0 61 74 65 64 20 6e 61 6d 65 20 6f 66 20 74 68 65  ated name of the
256f0 20 64 61 74 61 62 61 73 65 20 66 72 6f 6d 20 77   database from w
25700 68 69 63 68 20 74 68 65 0a 2a 2a 20 20 20 20 20  hich the.**     
25710 20 20 20 20 20 4e 74 68 20 72 65 73 75 6c 74 20       Nth result 
25720 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 5b 70  column of the [p
25730 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
25740 74 5d 20 53 20 69 73 20 65 78 74 72 61 63 74 65  t] S is extracte
25750 64 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  d,.**          o
25760 72 20 4e 55 4c 4c 20 69 66 20 74 68 65 20 4e 74  r NULL if the Nt
25770 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 53 20 69 73  h column of S is
25780 20 61 20 67 65 6e 65 72 61 6c 20 65 78 70 72 65   a general expre
25790 73 73 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20  ssion.**        
257a0 20 20 6f 72 20 69 66 20 75 6e 61 62 6c 65 20 74    or if unable t
257b0 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72  o allocate memor
257c0 79 20 74 6f 20 73 74 6f 72 65 20 74 68 65 20 6e  y to store the n
257d0 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37  ame..**.** {H137
257e0 34 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  42} The [sqlite3
257f0 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65  _column_database
25800 5f 6e 61 6d 65 31 36 28 53 2c 4e 29 5d 20 69 6e  _name16(S,N)] in
25810 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
25820 65 69 74 68 65 72 0a 2a 2a 20 20 20 20 20 20 20  either.**       
25830 20 20 20 74 68 65 20 55 54 46 2d 31 36 20 6e 61     the UTF-16 na
25840 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20  tive byte order 
25850 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
25860 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61  name of the data
25870 62 61 73 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  base.**         
25880 20 66 72 6f 6d 20 77 68 69 63 68 20 74 68 65 20   from which the 
25890 4e 74 68 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  Nth result colum
258a0 6e 20 6f 66 20 74 68 65 20 5b 70 72 65 70 61 72  n of the [prepar
258b0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20  ed statement] S 
258c0 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 65  is.**          e
258d0 78 74 72 61 63 74 65 64 2c 20 6f 72 20 4e 55 4c  xtracted, or NUL
258e0 4c 20 69 66 20 74 68 65 20 4e 74 68 20 63 6f 6c  L if the Nth col
258f0 75 6d 6e 20 6f 66 20 53 20 69 73 20 61 20 67 65  umn of S is a ge
25900 6e 65 72 61 6c 20 65 78 70 72 65 73 73 69 6f 6e  neral expression
25910 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20  .**          or 
25920 69 66 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c  if unable to all
25930 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20  ocate memory to 
25940 73 74 6f 72 65 20 74 68 65 20 6e 61 6d 65 2e 0a  store the name..
25950 2a 2a 0a 2a 2a 20 7b 48 31 33 37 34 33 7d 20 54  **.** {H13743} T
25960 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  he [sqlite3_colu
25970 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 28 53 2c  mn_table_name(S,
25980 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  N)] interface re
25990 74 75 72 6e 73 20 65 69 74 68 65 72 0a 2a 2a 20  turns either.** 
259a0 20 20 20 20 20 20 20 20 20 74 68 65 20 55 54 46           the UTF
259b0 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  -8 zero-terminat
259c0 65 64 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 74  ed name of the t
259d0 61 62 6c 65 20 66 72 6f 6d 20 77 68 69 63 68 20  able from which 
259e0 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
259f0 4e 74 68 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  Nth result colum
25a00 6e 20 6f 66 20 74 68 65 20 5b 70 72 65 70 61 72  n of the [prepar
25a10 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20  ed statement] S 
25a20 69 73 20 65 78 74 72 61 63 74 65 64 2c 0a 2a 2a  is extracted,.**
25a30 20 20 20 20 20 20 20 20 20 20 6f 72 20 4e 55 4c            or NUL
25a40 4c 20 69 66 20 74 68 65 20 4e 74 68 20 63 6f 6c  L if the Nth col
25a50 75 6d 6e 20 6f 66 20 53 20 69 73 20 61 20 67 65  umn of S is a ge
25a60 6e 65 72 61 6c 20 65 78 70 72 65 73 73 69 6f 6e  neral expression
25a70 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20  .**          or 
25a80 69 66 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c  if unable to all
25a90 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20  ocate memory to 
25aa0 73 74 6f 72 65 20 74 68 65 20 6e 61 6d 65 2e 0a  store the name..
25ab0 2a 2a 0a 2a 2a 20 7b 48 31 33 37 34 34 7d 20 54  **.** {H13744} T
25ac0 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  he [sqlite3_colu
25ad0 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 31 36 28  mn_table_name16(
25ae0 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20  S,N)] interface 
25af0 72 65 74 75 72 6e 73 20 65 69 74 68 65 72 0a 2a  returns either.*
25b00 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 55  *          the U
25b10 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74  TF-16 native byt
25b20 65 20 6f 72 64 65 72 20 7a 65 72 6f 2d 74 65 72  e order zero-ter
25b30 6d 69 6e 61 74 65 64 20 6e 61 6d 65 20 6f 66 20  minated name of 
25b40 74 68 65 20 74 61 62 6c 65 0a 2a 2a 20 20 20 20  the table.**    
25b50 20 20 20 20 20 20 66 72 6f 6d 20 77 68 69 63 68        from which
25b60 20 74 68 65 20 4e 74 68 20 72 65 73 75 6c 74 20   the Nth result 
25b70 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 5b 70  column of the [p
25b80 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
25b90 74 5d 20 53 20 69 73 0a 2a 2a 20 20 20 20 20 20  t] S is.**      
25ba0 20 20 20 20 65 78 74 72 61 63 74 65 64 2c 20 6f      extracted, o
25bb0 72 20 4e 55 4c 4c 20 69 66 20 74 68 65 20 4e 74  r NULL if the Nt
25bc0 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 53 20 69 73  h column of S is
25bd0 20 61 20 67 65 6e 65 72 61 6c 20 65 78 70 72 65   a general expre
25be0 73 73 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20  ssion.**        
25bf0 20 20 6f 72 20 69 66 20 75 6e 61 62 6c 65 20 74    or if unable t
25c00 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72  o allocate memor
25c10 79 20 74 6f 20 73 74 6f 72 65 20 74 68 65 20 6e  y to store the n
25c20 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37  ame..**.** {H137
25c30 34 35 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  45} The [sqlite3
25c40 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e  _column_origin_n
25c50 61 6d 65 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66  ame(S,N)] interf
25c60 61 63 65 20 72 65 74 75 72 6e 73 20 65 69 74 68  ace returns eith
25c70 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  er.**          t
25c80 68 65 20 55 54 46 2d 38 20 7a 65 72 6f 2d 74 65  he UTF-8 zero-te
25c90 72 6d 69 6e 61 74 65 64 20 6e 61 6d 65 20 6f 66  rminated name of
25ca0 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d   the table colum
25cb0 6e 20 66 72 6f 6d 20 77 68 69 63 68 20 74 68 65  n from which the
25cc0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 74 68  .**          Nth
25cd0 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f   result column o
25ce0 66 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  f the [prepared 
25cf0 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 73 20  statement] S is 
25d00 65 78 74 72 61 63 74 65 64 2c 0a 2a 2a 20 20 20  extracted,.**   
25d10 20 20 20 20 20 20 20 6f 72 20 4e 55 4c 4c 20 69         or NULL i
25d20 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e  f the Nth column
25d30 20 6f 66 20 53 20 69 73 20 61 20 67 65 6e 65 72   of S is a gener
25d40 61 6c 20 65 78 70 72 65 73 73 69 6f 6e 0a 2a 2a  al expression.**
25d50 20 20 20 20 20 20 20 20 20 20 6f 72 20 69 66 20            or if 
25d60 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61  unable to alloca
25d70 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20 73 74 6f  te memory to sto
25d80 72 65 20 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a 0a  re the name..**.
25d90 2a 2a 20 7b 48 31 33 37 34 36 7d 20 54 68 65 20  ** {H13746} The 
25da0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
25db0 6f 72 69 67 69 6e 5f 6e 61 6d 65 31 36 28 53 2c  origin_name16(S,
25dc0 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  N)] interface re
25dd0 74 75 72 6e 73 20 65 69 74 68 65 72 0a 2a 2a 20  turns either.** 
25de0 20 20 20 20 20 20 20 20 20 74 68 65 20 55 54 46           the UTF
25df0 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74 65 20  -16 native byte 
25e00 6f 72 64 65 72 20 7a 65 72 6f 2d 74 65 72 6d 69  order zero-termi
25e10 6e 61 74 65 64 20 6e 61 6d 65 20 6f 66 20 74 68  nated name of th
25e20 65 20 74 61 62 6c 65 0a 2a 2a 20 20 20 20 20 20  e table.**      
25e30 20 20 20 20 63 6f 6c 75 6d 6e 20 66 72 6f 6d 20      column from 
25e40 77 68 69 63 68 20 74 68 65 20 4e 74 68 20 72 65  which the Nth re
25e50 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74  sult column of t
25e60 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  he.**          [
25e70 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
25e80 6e 74 5d 20 53 20 69 73 20 65 78 74 72 61 63 74  nt] S is extract
25e90 65 64 2c 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74  ed, or NULL if t
25ea0 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 0a 2a 2a  he Nth column.**
25eb0 20 20 20 20 20 20 20 20 20 20 6f 66 20 53 20 69            of S i
25ec0 73 20 61 20 67 65 6e 65 72 61 6c 20 65 78 70 72  s a general expr
25ed0 65 73 73 69 6f 6e 20 6f 72 20 69 66 20 75 6e 61  ession or if una
25ee0 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20  ble to allocate 
25ef0 6d 65 6d 6f 72 79 0a 2a 2a 20 20 20 20 20 20 20  memory.**       
25f00 20 20 20 74 6f 20 73 74 6f 72 65 20 74 68 65 20     to store the 
25f10 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33  name..**.** {H13
25f20 37 34 38 7d 20 54 68 65 20 72 65 74 75 72 6e 20  748} The return 
25f30 76 61 6c 75 65 73 20 66 72 6f 6d 0a 2a 2a 20 20  values from.**  
25f40 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
25f50 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65  _column_database
25f60 5f 6e 61 6d 65 20 7c 20 63 6f 6c 75 6d 6e 20 6d  _name | column m
25f70 65 74 61 64 61 74 61 20 69 6e 74 65 72 66 61 63  etadata interfac
25f80 65 73 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  es].**          
25f90 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20 74 68  are valid for th
25fa0 65 20 6c 69 66 65 74 69 6d 65 20 6f 66 20 74 68  e lifetime of th
25fb0 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
25fc0 65 6d 65 6e 74 5d 0a 2a 2a 20 20 20 20 20 20 20  ement].**       
25fd0 20 20 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20     or until the 
25fe0 65 6e 63 6f 64 69 6e 67 20 69 73 20 63 68 61 6e  encoding is chan
25ff0 67 65 64 20 62 79 20 61 6e 6f 74 68 65 72 20 6d  ged by another m
26000 65 74 61 64 61 74 61 0a 2a 2a 20 20 20 20 20 20  etadata.**      
26010 20 20 20 20 69 6e 74 65 72 66 61 63 65 20 63 61      interface ca
26020 6c 6c 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20  ll for the same 
26030 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
26040 6e 74 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a  nt and column..*
26050 2a 0a 2a 2a 20 41 53 53 55 4d 50 54 49 4f 4e 53  *.** ASSUMPTIONS
26060 3a 0a 2a 2a 0a 2a 2a 20 7b 41 31 33 37 35 31 7d  :.**.** {A13751}
26070 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20   If two or more 
26080 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65  threads call one
26090 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 20 20 20 20   or more.**     
260a0 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f       [sqlite3_co
260b0 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61  lumn_database_na
260c0 6d 65 20 7c 20 63 6f 6c 75 6d 6e 20 6d 65 74 61  me | column meta
260d0 64 61 74 61 20 69 6e 74 65 72 66 61 63 65 73 5d  data interfaces]
260e0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 6f 72  .**          for
260f0 20 74 68 65 20 73 61 6d 65 20 5b 70 72 65 70 61   the same [prepa
26100 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61  red statement] a
26110 6e 64 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  nd result column
26120 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 74 20  .**          at 
26130 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68  the same time th
26140 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61  en the results a
26150 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f  re undefined..*/
26160 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
26170 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61  ite3_column_data
26180 62 61 73 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65  base_name(sqlite
26190 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f  3_stmt*,int);.co
261a0 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
261b0 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73  3_column_databas
261c0 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33  e_name16(sqlite3
261d0 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e  _stmt*,int);.con
261e0 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
261f0 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61  _column_table_na
26200 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  me(sqlite3_stmt*
26210 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  ,int);.const voi
26220 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
26230 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 31 36 28 73  n_table_name16(s
26240 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
26250 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  );.const char *s
26260 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72  qlite3_column_or
26270 69 67 69 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65  igin_name(sqlite
26280 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f  3_stmt*,int);.co
26290 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
262a0 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f  3_column_origin_
262b0 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73  name16(sqlite3_s
262c0 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a  tmt*,int);../*.*
262d0 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 63 6c  * CAPI3REF: Decl
262e0 61 72 65 64 20 44 61 74 61 74 79 70 65 20 4f 66  ared Datatype Of
262f0 20 41 20 51 75 65 72 79 20 52 65 73 75 6c 74 20   A Query Result 
26300 7b 48 31 33 37 36 30 7d 20 3c 53 31 30 37 30 30  {H13760} <S10700
26310 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73  >.**.** The firs
26320 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  t parameter is a
26330 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
26340 6d 65 6e 74 5d 2e 0a 2a 2a 20 49 66 20 74 68 69  ment]..** If thi
26350 73 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61  s statement is a
26360 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d   [SELECT] statem
26370 65 6e 74 20 61 6e 64 20 74 68 65 20 4e 74 68 20  ent and the Nth 
26380 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 0a 2a 2a  column of the.**
26390 20 72 65 74 75 72 6e 65 64 20 72 65 73 75 6c 74   returned result
263a0 20 73 65 74 20 6f 66 20 74 68 61 74 20 5b 53 45   set of that [SE
263b0 4c 45 43 54 5d 20 69 73 20 61 20 74 61 62 6c 65  LECT] is a table
263c0 20 63 6f 6c 75 6d 6e 20 28 6e 6f 74 20 61 6e 0a   column (not an.
263d0 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72  ** expression or
263e0 20 73 75 62 71 75 65 72 79 29 20 74 68 65 6e 20   subquery) then 
263f0 74 68 65 20 64 65 63 6c 61 72 65 64 20 74 79 70  the declared typ
26400 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 0a 2a  e of the table.*
26410 2a 20 63 6f 6c 75 6d 6e 20 69 73 20 72 65 74 75  * column is retu
26420 72 6e 65 64 2e 20 20 49 66 20 74 68 65 20 4e 74  rned.  If the Nt
26430 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20  h column of the 
26440 72 65 73 75 6c 74 20 73 65 74 20 69 73 20 61 6e  result set is an
26450 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 6f  .** expression o
26460 72 20 73 75 62 71 75 65 72 79 2c 20 74 68 65 6e  r subquery, then
26470 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
26480 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20  is returned..** 
26490 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72  The returned str
264a0 69 6e 67 20 69 73 20 61 6c 77 61 79 73 20 55 54  ing is always UT
264b0 46 2d 38 20 65 6e 63 6f 64 65 64 2e 20 7b 45 4e  F-8 encoded. {EN
264c0 44 7d 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78 61  D}.**.** For exa
264d0 6d 70 6c 65 2c 20 67 69 76 65 6e 20 74 68 65 20  mple, given the 
264e0 64 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 3a  database schema:
264f0 0a 2a 2a 0a 2a 2a 20 43 52 45 41 54 45 20 54 41  .**.** CREATE TA
26500 42 4c 45 20 74 31 28 63 31 20 56 41 52 49 41 4e  BLE t1(c1 VARIAN
26510 54 29 3b 0a 2a 2a 0a 2a 2a 20 61 6e 64 20 74 68  T);.**.** and th
26520 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 61 74  e following stat
26530 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70  ement to be comp
26540 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c 45  iled:.**.** SELE
26550 43 54 20 63 31 20 2b 20 31 2c 20 63 31 20 46 52  CT c1 + 1, c1 FR
26560 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a 20 74 68 69  OM t1;.**.** thi
26570 73 20 72 6f 75 74 69 6e 65 20 77 6f 75 6c 64 20  s routine would 
26580 72 65 74 75 72 6e 20 74 68 65 20 73 74 72 69 6e  return the strin
26590 67 20 22 56 41 52 49 41 4e 54 22 20 66 6f 72 20  g "VARIANT" for 
265a0 74 68 65 20 73 65 63 6f 6e 64 20 72 65 73 75 6c  the second resul
265b0 74 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d  t.** column (i==
265c0 31 29 2c 20 61 6e 64 20 61 20 4e 55 4c 4c 20 70  1), and a NULL p
265d0 6f 69 6e 74 65 72 20 66 6f 72 20 74 68 65 20 66  ointer for the f
265e0 69 72 73 74 20 72 65 73 75 6c 74 20 63 6f 6c 75  irst result colu
265f0 6d 6e 20 28 69 3d 3d 30 29 2e 0a 2a 2a 0a 2a 2a  mn (i==0)..**.**
26600 20 53 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e   SQLite uses dyn
26610 61 6d 69 63 20 72 75 6e 2d 74 69 6d 65 20 74 79  amic run-time ty
26620 70 69 6e 67 2e 20 20 53 6f 20 6a 75 73 74 20 62  ping.  So just b
26630 65 63 61 75 73 65 20 61 20 63 6f 6c 75 6d 6e 0a  ecause a column.
26640 2a 2a 20 69 73 20 64 65 63 6c 61 72 65 64 20 74  ** is declared t
26650 6f 20 63 6f 6e 74 61 69 6e 20 61 20 70 61 72 74  o contain a part
26660 69 63 75 6c 61 72 20 74 79 70 65 20 64 6f 65 73  icular type does
26670 20 6e 6f 74 20 6d 65 61 6e 20 74 68 61 74 20 74   not mean that t
26680 68 65 0a 2a 2a 20 64 61 74 61 20 73 74 6f 72 65  he.** data store
26690 64 20 69 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e  d in that column
266a0 20 69 73 20 6f 66 20 74 68 65 20 64 65 63 6c 61   is of the decla
266b0 72 65 64 20 74 79 70 65 2e 20 20 53 51 4c 69 74  red type.  SQLit
266c0 65 20 69 73 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79  e is.** strongly
266d0 20 74 79 70 65 64 2c 20 62 75 74 20 74 68 65 20   typed, but the 
266e0 74 79 70 69 6e 67 20 69 73 20 64 79 6e 61 6d 69  typing is dynami
266f0 63 20 6e 6f 74 20 73 74 61 74 69 63 2e 20 20 54  c not static.  T
26700 79 70 65 0a 2a 2a 20 69 73 20 61 73 73 6f 63 69  ype.** is associ
26710 61 74 65 64 20 77 69 74 68 20 69 6e 64 69 76 69  ated with indivi
26720 64 75 61 6c 20 76 61 6c 75 65 73 2c 20 6e 6f 74  dual values, not
26730 20 77 69 74 68 20 74 68 65 20 63 6f 6e 74 61 69   with the contai
26740 6e 65 72 73 0a 2a 2a 20 75 73 65 64 20 74 6f 20  ners.** used to 
26750 68 6f 6c 64 20 74 68 6f 73 65 20 76 61 6c 75 65  hold those value
26760 73 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  s..**.** INVARIA
26770 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37  NTS:.**.** {H137
26780 36 31 7d 20 20 41 20 73 75 63 63 65 73 73 66 75  61}  A successfu
26790 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  l call to [sqlit
267a0 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79  e3_column_declty
267b0 70 65 28 53 2c 4e 29 5d 20 72 65 74 75 72 6e 73  pe(S,N)] returns
267c0 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20   a.**           
267d0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
267e0 55 54 46 2d 38 20 73 74 72 69 6e 67 20 63 6f 6e  UTF-8 string con
267f0 74 61 69 6e 69 6e 67 20 74 68 65 20 64 65 63 6c  taining the decl
26800 61 72 65 64 20 64 61 74 61 74 79 70 65 0a 2a 2a  ared datatype.**
26810 20 20 20 20 20 20 20 20 20 20 20 6f 66 20 74 68             of th
26820 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74  e table column t
26830 68 61 74 20 61 70 70 65 61 72 73 20 61 73 20 74  hat appears as t
26840 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 28 6e  he Nth column (n
26850 75 6d 62 65 72 65 64 0a 2a 2a 20 20 20 20 20 20  umbered.**      
26860 20 20 20 20 20 66 72 6f 6d 20 30 29 20 6f 66 20       from 0) of 
26870 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 74  the result set t
26880 6f 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  o the [prepared 
26890 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2a  statement] S..**
268a0 0a 2a 2a 20 7b 48 31 33 37 36 32 7d 20 20 41 20  .** {H13762}  A 
268b0 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20  successful call 
268c0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  to [sqlite3_colu
268d0 6d 6e 5f 64 65 63 6c 74 79 70 65 31 36 28 53 2c  mn_decltype16(S,
268e0 4e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  N)].**          
268f0 20 72 65 74 75 72 6e 73 20 61 20 7a 65 72 6f 2d   returns a zero-
26900 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 31  terminated UTF-1
26910 36 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  6 native byte or
26920 64 65 72 20 73 74 72 69 6e 67 0a 2a 2a 20 20 20  der string.**   
26930 20 20 20 20 20 20 20 20 63 6f 6e 74 61 69 6e 69          containi
26940 6e 67 20 74 68 65 20 64 65 63 6c 61 72 65 64 20  ng the declared 
26950 64 61 74 61 74 79 70 65 20 6f 66 20 74 68 65 20  datatype of the 
26960 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61  table column tha
26970 74 20 61 70 70 65 61 72 73 0a 2a 2a 20 20 20 20  t appears.**    
26980 20 20 20 20 20 20 20 61 73 20 74 68 65 20 4e 74         as the Nt
26990 68 20 63 6f 6c 75 6d 6e 20 28 6e 75 6d 62 65 72  h column (number
269a0 65 64 20 66 72 6f 6d 20 30 29 20 6f 66 20 74 68  ed from 0) of th
269b0 65 20 72 65 73 75 6c 74 20 73 65 74 20 74 6f 20  e result set to 
269c0 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
269d0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
269e0 6d 65 6e 74 5d 20 53 2e 0a 2a 2a 0a 2a 2a 20 7b  ment] S..**.** {
269f0 48 31 33 37 36 33 7d 20 20 49 66 20 4e 20 69 73  H13763}  If N is
26a00 20 6c 65 73 73 20 74 68 61 6e 20 30 20 6f 72 20   less than 0 or 
26a10 4e 20 69 73 20 67 72 65 61 74 65 72 20 74 68 61  N is greater tha
26a20 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f 0a 2a 2a  n or equal to.**
26a30 20 20 20 20 20 20 20 20 20 20 20 74 68 65 20 6e             the n
26a40 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
26a50 20 69 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65   in the [prepare
26a60 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2c 0a  d statement] S,.
26a70 2a 2a 20 20 20 20 20 20 20 20 20 20 20 6f 72 20  **           or 
26a80 69 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d  if the Nth colum
26a90 6e 20 6f 66 20 53 20 69 73 20 61 6e 20 65 78 70  n of S is an exp
26aa0 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75  ression or subqu
26ab0 65 72 79 20 72 61 74 68 65 72 0a 2a 2a 20 20 20  ery rather.**   
26ac0 20 20 20 20 20 20 20 20 74 68 61 6e 20 61 20 74          than a t
26ad0 61 62 6c 65 20 63 6f 6c 75 6d 6e 2c 20 6f 72 20  able column, or 
26ae0 69 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  if a memory allo
26af0 63 61 74 69 6f 6e 20 66 61 69 6c 75 72 65 0a 2a  cation failure.*
26b00 2a 20 20 20 20 20 20 20 20 20 20 20 6f 63 63 75  *           occu
26b10 72 73 20 64 75 72 69 6e 67 20 65 6e 63 6f 64 69  rs during encodi
26b20 6e 67 20 63 6f 6e 76 65 72 73 69 6f 6e 73 2c 20  ng conversions, 
26b30 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  then.**         
26b40 20 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69    calls to [sqli
26b50 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74  te3_column_declt
26b60 79 70 65 28 53 2c 4e 29 5d 20 6f 72 0a 2a 2a 20  ype(S,N)] or.** 
26b70 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
26b80 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79  e3_column_declty
26b90 70 65 31 36 28 53 2c 4e 29 5d 20 72 65 74 75 72  pe16(S,N)] retur
26ba0 6e 20 4e 55 4c 4c 2e 0a 2a 2f 0a 63 6f 6e 73 74  n NULL..*/.const
26bb0 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63   char *sqlite3_c
26bc0 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 28 73  olumn_decltype(s
26bd0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
26be0 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
26bf0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65  qlite3_column_de
26c00 63 6c 74 79 70 65 31 36 28 73 71 6c 69 74 65 33  cltype16(sqlite3
26c10 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a  _stmt*,int);../*
26c20 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 76  .** CAPI3REF: Ev
26c30 61 6c 75 61 74 65 20 41 6e 20 53 51 4c 20 53 74  aluate An SQL St
26c40 61 74 65 6d 65 6e 74 20 7b 48 31 33 32 30 30 7d  atement {H13200}
26c50 20 3c 53 31 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20   <S10000>.**.** 
26c60 41 66 74 65 72 20 61 20 5b 70 72 65 70 61 72 65  After a [prepare
26c70 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 68 61 73  d statement] has
26c80 20 62 65 65 6e 20 70 72 65 70 61 72 65 64 20 75   been prepared u
26c90 73 69 6e 67 20 65 69 74 68 65 72 0a 2a 2a 20 5b  sing either.** [
26ca0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
26cb0 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  v2()] or [sqlite
26cc0 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
26cd0 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 20  ] or one of the 
26ce0 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66  legacy.** interf
26cf0 61 63 65 73 20 5b 73 71 6c 69 74 65 33 5f 70 72  aces [sqlite3_pr
26d00 65 70 61 72 65 28 29 5d 20 6f 72 20 5b 73 71 6c  epare()] or [sql
26d10 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29  ite3_prepare16()
26d20 5d 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e  ], this function
26d30 0a 2a 2a 20 6d 75 73 74 20 62 65 20 63 61 6c 6c  .** must be call
26d40 65 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74  ed one or more t
26d50 69 6d 65 73 20 74 6f 20 65 76 61 6c 75 61 74 65  imes to evaluate
26d60 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 2e 0a   the statement..
26d70 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 74 61 69 6c  **.** The detail
26d80 73 20 6f 66 20 74 68 65 20 62 65 68 61 76 69 6f  s of the behavio
26d90 72 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33  r of the sqlite3
26da0 5f 73 74 65 70 28 29 20 69 6e 74 65 72 66 61 63  _step() interfac
26db0 65 20 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20 77  e depend.** on w
26dc0 68 65 74 68 65 72 20 74 68 65 20 73 74 61 74 65  hether the state
26dd0 6d 65 6e 74 20 77 61 73 20 70 72 65 70 61 72 65  ment was prepare
26de0 64 20 75 73 69 6e 67 20 74 68 65 20 6e 65 77 65  d using the newe
26df0 72 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65  r "v2" interface
26e00 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
26e10 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b  pare_v2()] and [
26e20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
26e30 36 5f 76 32 28 29 5d 20 6f 72 20 74 68 65 20 6f  6_v2()] or the o
26e40 6c 64 65 72 20 6c 65 67 61 63 79 0a 2a 2a 20 69  lder legacy.** i
26e50 6e 74 65 72 66 61 63 65 20 5b 73 71 6c 69 74 65  nterface [sqlite
26e60 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e 64  3_prepare()] and
26e70 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
26e80 65 31 36 28 29 5d 2e 20 20 54 68 65 20 75 73 65  e16()].  The use
26e90 20 6f 66 20 74 68 65 0a 2a 2a 20 6e 65 77 20 22   of the.** new "
26ea0 76 32 22 20 69 6e 74 65 72 66 61 63 65 20 69 73  v2" interface is
26eb0 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72   recommended for
26ec0 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e   new application
26ed0 73 20 62 75 74 20 74 68 65 20 6c 65 67 61 63 79  s but the legacy
26ee0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 77 69  .** interface wi
26ef0 6c 6c 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62  ll continue to b
26f00 65 20 73 75 70 70 6f 72 74 65 64 2e 0a 2a 2a 0a  e supported..**.
26f10 2a 2a 20 49 6e 20 74 68 65 20 6c 65 67 61 63 79  ** In the legacy
26f20 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20   interface, the 
26f30 72 65 74 75 72 6e 20 76 61 6c 75 65 20 77 69 6c  return value wil
26f40 6c 20 62 65 20 65 69 74 68 65 72 20 5b 53 51 4c  l be either [SQL
26f50 49 54 45 5f 42 55 53 59 5d 2c 0a 2a 2a 20 5b 53  ITE_BUSY],.** [S
26f60 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 20 5b 53 51  QLITE_DONE], [SQ
26f70 4c 49 54 45 5f 52 4f 57 5d 2c 20 5b 53 51 4c 49  LITE_ROW], [SQLI
26f80 54 45 5f 45 52 52 4f 52 5d 2c 20 6f 72 20 5b 53  TE_ERROR], or [S
26f90 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 0a 2a  QLITE_MISUSE]..*
26fa0 2a 20 57 69 74 68 20 74 68 65 20 22 76 32 22 20  * With the "v2" 
26fb0 69 6e 74 65 72 66 61 63 65 2c 20 61 6e 79 20 6f  interface, any o
26fc0 66 20 74 68 65 20 6f 74 68 65 72 20 5b 72 65 73  f the other [res
26fd0 75 6c 74 20 63 6f 64 65 73 5d 20 6f 72 0a 2a 2a  ult codes] or.**
26fe0 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c   [extended resul
26ff0 74 20 63 6f 64 65 73 5d 20 6d 69 67 68 74 20 62  t codes] might b
27000 65 20 72 65 74 75 72 6e 65 64 20 61 73 20 77 65  e returned as we
27010 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54  ll..**.** [SQLIT
27020 45 5f 42 55 53 59 5d 20 6d 65 61 6e 73 20 74 68  E_BUSY] means th
27030 61 74 20 74 68 65 20 64 61 74 61 62 61 73 65 20  at the database 
27040 65 6e 67 69 6e 65 20 77 61 73 20 75 6e 61 62 6c  engine was unabl
27050 65 20 74 6f 20 61 63 71 75 69 72 65 20 74 68 65  e to acquire the
27060 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 6c 6f 63  .** database loc
27070 6b 73 20 69 74 20 6e 65 65 64 73 20 74 6f 20 64  ks it needs to d
27080 6f 20 69 74 73 20 6a 6f 62 2e 20 20 49 66 20 74  o its job.  If t
27090 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  he statement is 
270a0 61 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 72  a [COMMIT].** or
270b0 20 6f 63 63 75 72 73 20 6f 75 74 73 69 64 65 20   occurs outside 
270c0 6f 66 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74  of an explicit t
270d0 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e  ransaction, then
270e0 20 79 6f 75 20 63 61 6e 20 72 65 74 72 79 20 74   you can retry t
270f0 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 2e  he.** statement.
27100 20 20 49 66 20 74 68 65 20 73 74 61 74 65 6d 65    If the stateme
27110 6e 74 20 69 73 20 6e 6f 74 20 61 20 5b 43 4f 4d  nt is not a [COM
27120 4d 49 54 5d 20 61 6e 64 20 6f 63 63 75 72 73 20  MIT] and occurs 
27130 77 69 74 68 69 6e 20 61 0a 2a 2a 20 65 78 70 6c  within a.** expl
27140 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e  icit transaction
27150 20 74 68 65 6e 20 79 6f 75 20 73 68 6f 75 6c 64   then you should
27160 20 72 6f 6c 6c 62 61 63 6b 20 74 68 65 20 74 72   rollback the tr
27170 61 6e 73 61 63 74 69 6f 6e 20 62 65 66 6f 72 65  ansaction before
27180 0a 2a 2a 20 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a  .** continuing..
27190 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f  **.** [SQLITE_DO
271a0 4e 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74  NE] means that t
271b0 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61 73  he statement has
271c0 20 66 69 6e 69 73 68 65 64 20 65 78 65 63 75 74   finished execut
271d0 69 6e 67 0a 2a 2a 20 73 75 63 63 65 73 73 66 75  ing.** successfu
271e0 6c 6c 79 2e 20 20 73 71 6c 69 74 65 33 5f 73 74  lly.  sqlite3_st
271f0 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20  ep() should not 
27200 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20  be called again 
27210 6f 6e 20 74 68 69 73 20 76 69 72 74 75 61 6c 0a  on this virtual.
27220 2a 2a 20 6d 61 63 68 69 6e 65 20 77 69 74 68 6f  ** machine witho
27230 75 74 20 66 69 72 73 74 20 63 61 6c 6c 69 6e 67  ut first calling
27240 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
27250 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65 20  )] to reset the 
27260 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69  virtual.** machi
27270 6e 65 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69  ne back to its i
27280 6e 69 74 69 61 6c 20 73 74 61 74 65 2e 0a 2a 2a  nitial state..**
27290 0a 2a 2a 20 49 66 20 74 68 65 20 53 51 4c 20 73  .** If the SQL s
272a0 74 61 74 65 6d 65 6e 74 20 62 65 69 6e 67 20 65  tatement being e
272b0 78 65 63 75 74 65 64 20 72 65 74 75 72 6e 73 20  xecuted returns 
272c0 61 6e 79 20 64 61 74 61 2c 20 74 68 65 6e 20 5b  any data, then [
272d0 53 51 4c 49 54 45 5f 52 4f 57 5d 0a 2a 2a 20 69  SQLITE_ROW].** i
272e0 73 20 72 65 74 75 72 6e 65 64 20 65 61 63 68 20  s returned each 
272f0 74 69 6d 65 20 61 20 6e 65 77 20 72 6f 77 20 6f  time a new row o
27300 66 20 64 61 74 61 20 69 73 20 72 65 61 64 79 20  f data is ready 
27310 66 6f 72 20 70 72 6f 63 65 73 73 69 6e 67 20 62  for processing b
27320 79 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 65 72 2e  y the.** caller.
27330 20 54 68 65 20 76 61 6c 75 65 73 20 6d 61 79 20   The values may 
27340 62 65 20 61 63 63 65 73 73 65 64 20 75 73 69 6e  be accessed usin
27350 67 20 74 68 65 20 5b 63 6f 6c 75 6d 6e 20 61 63  g the [column ac
27360 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 2e  cess functions].
27370 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70  .** sqlite3_step
27380 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61 67 61  () is called aga
27390 69 6e 20 74 6f 20 72 65 74 72 69 65 76 65 20 74  in to retrieve t
273a0 68 65 20 6e 65 78 74 20 72 6f 77 20 6f 66 20 64  he next row of d
273b0 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49  ata..**.** [SQLI
273c0 54 45 5f 45 52 52 4f 52 5d 20 6d 65 61 6e 73 20  TE_ERROR] means 
273d0 74 68 61 74 20 61 20 72 75 6e 2d 74 69 6d 65 20  that a run-time 
273e0 65 72 72 6f 72 20 28 73 75 63 68 20 61 73 20 61  error (such as a
273f0 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 76   constraint.** v
27400 69 6f 6c 61 74 69 6f 6e 29 20 68 61 73 20 6f 63  iolation) has oc
27410 63 75 72 72 65 64 2e 20 20 73 71 6c 69 74 65 33  curred.  sqlite3
27420 5f 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e  _step() should n
27430 6f 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61  ot be called aga
27440 69 6e 20 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e  in on.** the VM.
27450 20 4d 6f 72 65 20 69 6e 66 6f 72 6d 61 74 69 6f   More informatio
27460 6e 20 6d 61 79 20 62 65 20 66 6f 75 6e 64 20 62  n may be found b
27470 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74  y calling [sqlit
27480 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a  e3_errmsg()]..**
27490 20 57 69 74 68 20 74 68 65 20 6c 65 67 61 63 79   With the legacy
274a0 20 69 6e 74 65 72 66 61 63 65 2c 20 61 20 6d 6f   interface, a mo
274b0 72 65 20 73 70 65 63 69 66 69 63 20 65 72 72 6f  re specific erro
274c0 72 20 63 6f 64 65 20 28 66 6f 72 20 65 78 61 6d  r code (for exam
274d0 70 6c 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ple,.** [SQLITE_
274e0 49 4e 54 45 52 52 55 50 54 5d 2c 20 5b 53 51 4c  INTERRUPT], [SQL
274f0 49 54 45 5f 53 43 48 45 4d 41 5d 2c 20 5b 53 51  ITE_SCHEMA], [SQ
27500 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d 2c 20 61  LITE_CORRUPT], a
27510 6e 64 20 73 6f 20 66 6f 72 74 68 29 0a 2a 2a 20  nd so forth).** 
27520 63 61 6e 20 62 65 20 6f 62 74 61 69 6e 65 64 20  can be obtained 
27530 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  by calling [sqli
27540 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 6e 20  te3_reset()] on 
27550 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  the.** [prepared
27560 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 49 6e   statement].  In
27570 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66   the "v2" interf
27580 61 63 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72 65  ace,.** the more
27590 20 73 70 65 63 69 66 69 63 20 65 72 72 6f 72 20   specific error 
275a0 63 6f 64 65 20 69 73 20 72 65 74 75 72 6e 65 64  code is returned
275b0 20 64 69 72 65 63 74 6c 79 20 62 79 20 73 71 6c   directly by sql
275c0 69 74 65 33 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a  ite3_step()..**.
275d0 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53  ** [SQLITE_MISUS
275e0 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  E] means that th
275f0 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77  e this routine w
27600 61 73 20 63 61 6c 6c 65 64 20 69 6e 61 70 70 72  as called inappr
27610 6f 70 72 69 61 74 65 6c 79 2e 0a 2a 2a 20 50 65  opriately..** Pe
27620 72 68 61 70 73 20 69 74 20 77 61 73 20 63 61 6c  rhaps it was cal
27630 6c 65 64 20 6f 6e 20 61 20 5b 70 72 65 70 61 72  led on a [prepar
27640 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68  ed statement] th
27650 61 74 20 68 61 73 0a 2a 2a 20 61 6c 72 65 61 64  at has.** alread
27660 79 20 62 65 65 6e 20 5b 73 71 6c 69 74 65 33 5f  y been [sqlite3_
27670 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c  finalize | final
27680 69 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65 20  ized] or on one 
27690 74 68 61 74 20 68 61 64 0a 2a 2a 20 70 72 65 76  that had.** prev
276a0 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64 20  iously returned 
276b0 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6f  [SQLITE_ERROR] o
276c0 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e  r [SQLITE_DONE].
276d0 20 20 4f 72 20 69 74 20 63 6f 75 6c 64 0a 2a 2a    Or it could.**
276e0 20 62 65 20 74 68 65 20 63 61 73 65 20 74 68 61   be the case tha
276f0 74 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62  t the same datab
27700 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
27710 73 20 62 65 69 6e 67 20 75 73 65 64 20 62 79 20  s being used by 
27720 74 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74  two or.** more t
27730 68 72 65 61 64 73 20 61 74 20 74 68 65 20 73 61  hreads at the sa
27740 6d 65 20 6d 6f 6d 65 6e 74 20 69 6e 20 74 69 6d  me moment in tim
27750 65 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f 66  e..**.** <b>Goof
27760 79 20 49 6e 74 65 72 66 61 63 65 20 41 6c 65 72  y Interface Aler
27770 74 3a 3c 2f 62 3e 20 49 6e 20 74 68 65 20 6c 65  t:</b> In the le
27780 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20  gacy interface, 
27790 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70  the sqlite3_step
277a0 28 29 0a 2a 2a 20 41 50 49 20 61 6c 77 61 79 73  ().** API always
277b0 20 72 65 74 75 72 6e 73 20 61 20 67 65 6e 65 72   returns a gener
277c0 69 63 20 65 72 72 6f 72 20 63 6f 64 65 2c 20 5b  ic error code, [
277d0 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 66  SQLITE_ERROR], f
277e0 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 0a 2a 2a 20  ollowing any.** 
277f0 65 72 72 6f 72 20 6f 74 68 65 72 20 74 68 61 6e  error other than
27800 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 61   [SQLITE_BUSY] a
27810 6e 64 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53  nd [SQLITE_MISUS
27820 45 5d 2e 20 20 59 6f 75 20 6d 75 73 74 20 63 61  E].  You must ca
27830 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72  ll.** [sqlite3_r
27840 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69  eset()] or [sqli
27850 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
27860 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64  in order to find
27870 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 73   one of the.** s
27880 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20 63  pecific [error c
27890 6f 64 65 73 5d 20 74 68 61 74 20 62 65 74 74 65  odes] that bette
278a0 72 20 64 65 73 63 72 69 62 65 73 20 74 68 65 20  r describes the 
278b0 65 72 72 6f 72 2e 0a 2a 2a 20 57 65 20 61 64 6d  error..** We adm
278c0 69 74 20 74 68 61 74 20 74 68 69 73 20 69 73 20  it that this is 
278d0 61 20 67 6f 6f 66 79 20 64 65 73 69 67 6e 2e 20  a goofy design. 
278e0 20 54 68 65 20 70 72 6f 62 6c 65 6d 20 68 61 73   The problem has
278f0 20 62 65 65 6e 20 66 69 78 65 64 0a 2a 2a 20 77   been fixed.** w
27900 69 74 68 20 74 68 65 20 22 76 32 22 20 69 6e 74  ith the "v2" int
27910 65 72 66 61 63 65 2e 20 20 49 66 20 79 6f 75 20  erface.  If you 
27920 70 72 65 70 61 72 65 20 61 6c 6c 20 6f 66 20 79  prepare all of y
27930 6f 75 72 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  our SQL statemen
27940 74 73 0a 2a 2a 20 75 73 69 6e 67 20 65 69 74 68  ts.** using eith
27950 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  er [sqlite3_prep
27960 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71  are_v2()] or [sq
27970 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
27980 76 32 28 29 5d 20 69 6e 73 74 65 61 64 0a 2a 2a  v2()] instead.**
27990 20 6f 66 20 74 68 65 20 6c 65 67 61 63 79 20 5b   of the legacy [
279a0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
279b0 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
279c0 70 72 65 70 61 72 65 31 36 28 29 5d 20 69 6e 74  prepare16()] int
279d0 65 72 66 61 63 65 73 2c 0a 2a 2a 20 74 68 65 6e  erfaces,.** then
279e0 20 74 68 65 20 6d 6f 72 65 20 73 70 65 63 69 66   the more specif
279f0 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d  ic [error codes]
27a00 20 61 72 65 20 72 65 74 75 72 6e 65 64 20 64 69   are returned di
27a10 72 65 63 74 6c 79 0a 2a 2a 20 62 79 20 73 71 6c  rectly.** by sql
27a20 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20 54 68  ite3_step().  Th
27a30 65 20 75 73 65 20 6f 66 20 74 68 65 20 22 76 32  e use of the "v2
27a40 22 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 72  " interface is r
27a50 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2a 0a 2a  ecommended..**.*
27a60 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
27a70 0a 2a 2a 20 7b 48 31 33 32 30 32 7d 20 20 49 66  .** {H13202}  If
27a80 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
27a90 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 73 20 72  tatement] S is r
27aa0 65 61 64 79 20 74 6f 20 62 65 20 72 75 6e 2c 20  eady to be run, 
27ab0 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  then.**         
27ac0 20 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28    [sqlite3_step(
27ad0 53 29 5d 20 61 64 76 61 6e 63 65 73 20 74 68 61  S)] advances tha
27ae0 74 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  t prepared state
27af0 6d 65 6e 74 20 75 6e 74 69 6c 0a 2a 2a 20 20 20  ment until.**   
27b00 20 20 20 20 20 20 20 20 63 6f 6d 70 6c 65 74 69          completi
27b10 6f 6e 20 6f 72 20 75 6e 74 69 6c 20 69 74 20 69  on or until it i
27b20 73 20 72 65 61 64 79 20 74 6f 20 72 65 74 75 72  s ready to retur
27b30 6e 20 61 6e 6f 74 68 65 72 20 72 6f 77 20 6f 66  n another row of
27b40 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
27b50 20 20 72 65 73 75 6c 74 20 73 65 74 2c 20 6f 72    result set, or
27b60 20 75 6e 74 69 6c 20 61 6e 20 5b 73 71 6c 69 74   until an [sqlit
27b70 65 33 5f 69 6e 74 65 72 72 75 70 74 20 7c 20 69  e3_interrupt | i
27b80 6e 74 65 72 72 75 70 74 5d 0a 2a 2a 20 20 20 20  nterrupt].**    
27b90 20 20 20 20 20 20 20 6f 72 20 61 20 72 75 6e 2d         or a run-
27ba0 74 69 6d 65 20 65 72 72 6f 72 20 6f 63 63 75 72  time error occur
27bb0 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 33 30 34  s..**.** {H15304
27bc0 7d 20 20 57 68 65 6e 20 61 20 63 61 6c 6c 20 74  }  When a call t
27bd0 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  o [sqlite3_step(
27be0 53 29 5d 20 63 61 75 73 65 73 20 74 68 65 20 5b  S)] causes the [
27bf0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
27c00 6e 74 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  nt].**          
27c10 20 53 20 74 6f 20 72 75 6e 20 74 6f 20 63 6f 6d   S to run to com
27c20 70 6c 65 74 69 6f 6e 2c 20 74 68 65 20 66 75 6e  pletion, the fun
27c30 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 5b 53  ction returns [S
27c40 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 0a 2a 2a 0a  QLITE_DONE]..**.
27c50 2a 2a 20 7b 48 31 35 33 30 36 7d 20 20 57 68 65  ** {H15306}  Whe
27c60 6e 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  n a call to [sql
27c70 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 73 74  ite3_step(S)] st
27c80 6f 70 73 20 62 65 63 61 75 73 65 20 69 74 20 69  ops because it i
27c90 73 20 72 65 61 64 79 20 74 6f 0a 2a 2a 20 20 20  s ready to.**   
27ca0 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 20 61          return a
27cb0 6e 6f 74 68 65 72 20 72 6f 77 20 6f 66 20 74 68  nother row of th
27cc0 65 20 72 65 73 75 6c 74 20 73 65 74 2c 20 69 74  e result set, it
27cd0 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
27ce0 5f 52 4f 57 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  _ROW]..**.** {H1
27cf0 35 33 30 38 7d 20 20 49 66 20 61 20 63 61 6c 6c  5308}  If a call
27d00 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   to [sqlite3_ste
27d10 70 28 53 29 5d 20 65 6e 63 6f 75 6e 74 65 72 73  p(S)] encounters
27d20 20 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   an.**          
27d30 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72   [sqlite3_interr
27d40 75 70 74 20 7c 20 69 6e 74 65 72 72 75 70 74 5d  upt | interrupt]
27d50 20 6f 72 20 61 20 72 75 6e 2d 74 69 6d 65 20 65   or a run-time e
27d60 72 72 6f 72 2c 0a 2a 2a 20 20 20 20 20 20 20 20  rror,.**        
27d70 20 20 20 69 74 20 72 65 74 75 72 6e 73 20 61 6e     it returns an
27d80 20 61 70 70 72 6f 70 72 69 61 74 65 20 65 72 72   appropriate err
27d90 6f 72 20 63 6f 64 65 20 74 68 61 74 20 69 73 20  or code that is 
27da0 6e 6f 74 20 6f 6e 65 20 6f 66 0a 2a 2a 20 20 20  not one of.**   
27db0 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f          [SQLITE_
27dc0 4f 4b 5d 2c 20 5b 53 51 4c 49 54 45 5f 52 4f 57  OK], [SQLITE_ROW
27dd0 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f  ], or [SQLITE_DO
27de0 4e 45 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 33  NE]..**.** {H153
27df0 31 30 7d 20 20 49 66 20 61 6e 20 5b 73 71 6c 69  10}  If an [sqli
27e00 74 65 33 5f 69 6e 74 65 72 72 75 70 74 20 7c 20  te3_interrupt | 
27e10 69 6e 74 65 72 72 75 70 74 5d 20 6f 72 20 61 20  interrupt] or a 
27e20 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72 0a 2a  run-time error.*
27e30 2a 20 20 20 20 20 20 20 20 20 20 20 6f 63 63 75  *           occu
27e40 72 73 20 64 75 72 69 6e 67 20 61 20 63 61 6c 6c  rs during a call
27e50 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   to [sqlite3_ste
27e60 70 28 53 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20  p(S)].**        
27e70 20 20 20 66 6f 72 20 61 20 5b 70 72 65 70 61 72     for a [prepar
27e80 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20  ed statement] S 
27e90 63 72 65 61 74 65 64 20 75 73 69 6e 67 0a 2a 2a  created using.**
27ea0 20 20 20 20 20 20 20 20 20 20 20 6c 65 67 61 63             legac
27eb0 79 20 69 6e 74 65 72 66 61 63 65 73 20 5b 73 71  y interfaces [sq
27ec0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d  lite3_prepare()]
27ed0 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   or.**          
27ee0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
27ef0 65 31 36 28 29 5d 2c 20 74 68 65 6e 20 74 68 65  e16()], then the
27f00 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
27f10 73 20 65 69 74 68 65 72 0a 2a 2a 20 20 20 20 20  s either.**     
27f20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 45 52        [SQLITE_ER
27f30 52 4f 52 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 55  ROR], [SQLITE_BU
27f40 53 59 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  SY], or [SQLITE_
27f50 4d 49 53 55 53 45 5d 2e 0a 2a 2f 0a 69 6e 74 20  MISUSE]..*/.int 
27f60 73 71 6c 69 74 65 33 5f 73 74 65 70 28 73 71 6c  sqlite3_step(sql
27f70 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a  ite3_stmt*);../*
27f80 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75  .** CAPI3REF: Nu
27f90 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20  mber of columns 
27fa0 69 6e 20 61 20 72 65 73 75 6c 74 20 73 65 74 20  in a result set 
27fb0 7b 48 31 33 37 37 30 7d 20 3c 53 31 30 37 30 30  {H13770} <S10700
27fc0 3e 0a 2a 2a 0a 2a 2a 20 52 65 74 75 72 6e 73 20  >.**.** Returns 
27fd0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 76 61  the number of va
27fe0 6c 75 65 73 20 69 6e 20 74 68 65 20 63 75 72 72  lues in the curr
27ff0 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72  ent row of the r
28000 65 73 75 6c 74 20 73 65 74 2e 0a 2a 2a 0a 2a 2a  esult set..**.**
28010 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
28020 2a 2a 20 7b 48 31 33 37 37 31 7d 20 20 41 66 74  ** {H13771}  Aft
28030 65 72 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71  er a call to [sq
28040 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 74  lite3_step(S)] t
28050 68 61 74 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  hat returns [SQL
28060 49 54 45 5f 52 4f 57 5d 2c 0a 2a 2a 20 20 20 20  ITE_ROW],.**    
28070 20 20 20 20 20 20 20 74 68 65 20 5b 73 71 6c 69         the [sqli
28080 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 53  te3_data_count(S
28090 29 5d 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20  )] routine will 
280a0 72 65 74 75 72 6e 20 74 68 65 20 73 61 6d 65 20  return the same 
280b0 76 61 6c 75 65 0a 2a 2a 20 20 20 20 20 20 20 20  value.**        
280c0 20 20 20 61 73 20 74 68 65 20 5b 73 71 6c 69 74     as the [sqlit
280d0 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28  e3_column_count(
280e0 53 29 5d 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a  S)] function..**
280f0 0a 2a 2a 20 7b 48 31 33 37 37 32 7d 20 20 41 66  .** {H13772}  Af
28100 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  ter [sqlite3_ste
28110 70 28 53 29 5d 20 68 61 73 20 72 65 74 75 72 6e  p(S)] has return
28120 65 64 20 61 6e 79 20 76 61 6c 75 65 20 6f 74 68  ed any value oth
28130 65 72 20 74 68 61 6e 0a 2a 2a 20 20 20 20 20 20  er than.**      
28140 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 52 4f 57       [SQLITE_ROW
28150 5d 20 6f 72 20 62 65 66 6f 72 65 20 5b 73 71 6c  ] or before [sql
28160 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 68 61  ite3_step(S)] ha
28170 73 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 6f 6e  s been called on
28180 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
28190 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74    [prepared stat
281a0 65 6d 65 6e 74 5d 20 66 6f 72 20 74 68 65 20 66  ement] for the f
281b0 69 72 73 74 20 74 69 6d 65 20 73 69 6e 63 65 20  irst time since 
281c0 69 74 20 77 61 73 0a 2a 2a 20 20 20 20 20 20 20  it was.**       
281d0 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 70 72 65      [sqlite3_pre
281e0 70 61 72 65 20 7c 20 70 72 65 70 61 72 65 64 5d  pare | prepared]
281f0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73   or [sqlite3_res
28200 65 74 20 7c 20 72 65 73 65 74 5d 2c 0a 2a 2a 20  et | reset],.** 
28210 20 20 20 20 20 20 20 20 20 20 74 68 65 20 5b 73            the [s
28220 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e  qlite3_data_coun
28230 74 28 53 29 5d 20 72 6f 75 74 69 6e 65 20 72 65  t(S)] routine re
28240 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2f 0a 69  turns zero..*/.i
28250 6e 74 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f  nt sqlite3_data_
28260 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74  count(sqlite3_st
28270 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a  mt *pStmt);../*.
28280 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e  ** CAPI3REF: Fun
28290 64 61 6d 65 6e 74 61 6c 20 44 61 74 61 74 79 70  damental Datatyp
282a0 65 73 20 7b 48 31 30 32 36 35 7d 20 3c 53 31 30  es {H10265} <S10
282b0 31 31 30 3e 3c 53 31 30 31 32 30 3e 0a 2a 2a 20  110><S10120>.** 
282c0 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c 49 54 45  KEYWORDS: SQLITE
282d0 5f 54 45 58 54 0a 2a 2a 0a 2a 2a 20 7b 48 31 30  _TEXT.**.** {H10
282e0 32 36 36 7d 20 45 76 65 72 79 20 76 61 6c 75 65  266} Every value
282f0 20 69 6e 20 53 51 4c 69 74 65 20 68 61 73 20 6f   in SQLite has o
28300 6e 65 20 6f 66 20 66 69 76 65 20 66 75 6e 64 61  ne of five funda
28310 6d 65 6e 74 61 6c 20 64 61 74 61 74 79 70 65 73  mental datatypes
28320 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
28330 3c 6c 69 3e 20 36 34 2d 62 69 74 20 73 69 67 6e  <li> 64-bit sign
28340 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 6c  ed integer.** <l
28350 69 3e 20 36 34 2d 62 69 74 20 49 45 45 45 20 66  i> 64-bit IEEE f
28360 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75  loating point nu
28370 6d 62 65 72 0a 2a 2a 20 3c 6c 69 3e 20 73 74 72  mber.** <li> str
28380 69 6e 67 0a 2a 2a 20 3c 6c 69 3e 20 42 4c 4f 42  ing.** <li> BLOB
28390 0a 2a 2a 20 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a  .** <li> NULL.**
283a0 20 3c 2f 75 6c 3e 20 7b 45 4e 44 7d 0a 2a 2a 0a   </ul> {END}.**.
283b0 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e  ** These constan
283c0 74 73 20 61 72 65 20 63 6f 64 65 73 20 66 6f 72  ts are codes for
283d0 20 65 61 63 68 20 6f 66 20 74 68 6f 73 65 20 74   each of those t
283e0 79 70 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65  ypes..**.** Note
283f0 20 74 68 61 74 20 74 68 65 20 53 51 4c 49 54 45   that the SQLITE
28400 5f 54 45 58 54 20 63 6f 6e 73 74 61 6e 74 20 77  _TEXT constant w
28410 61 73 20 61 6c 73 6f 20 75 73 65 64 20 69 6e 20  as also used in 
28420 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32  SQLite version 2
28430 0a 2a 2a 20 66 6f 72 20 61 20 63 6f 6d 70 6c 65  .** for a comple
28440 74 65 6c 79 20 64 69 66 66 65 72 65 6e 74 20 6d  tely different m
28450 65 61 6e 69 6e 67 2e 20 20 53 6f 66 74 77 61 72  eaning.  Softwar
28460 65 20 74 68 61 74 20 6c 69 6e 6b 73 20 61 67 61  e that links aga
28470 69 6e 73 74 20 62 6f 74 68 0a 2a 2a 20 53 51 4c  inst both.** SQL
28480 69 74 65 20 76 65 72 73 69 6f 6e 20 32 20 61 6e  ite version 2 an
28490 64 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  d SQLite version
284a0 20 33 20 73 68 6f 75 6c 64 20 75 73 65 20 53 51   3 should use SQ
284b0 4c 49 54 45 33 5f 54 45 58 54 2c 20 6e 6f 74 0a  LITE3_TEXT, not.
284c0 2a 2a 20 53 51 4c 49 54 45 5f 54 45 58 54 2e 0a  ** SQLITE_TEXT..
284d0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
284e0 45 5f 49 4e 54 45 47 45 52 20 20 31 0a 23 64 65  E_INTEGER  1.#de
284f0 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 4c 4f 41  fine SQLITE_FLOA
28500 54 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53  T    2.#define S
28510 51 4c 49 54 45 5f 42 4c 4f 42 20 20 20 20 20 34  QLITE_BLOB     4
28520 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
28530 4e 55 4c 4c 20 20 20 20 20 35 0a 23 69 66 64 65  NULL     5.#ifde
28540 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 20  f SQLITE_TEXT.# 
28550 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58  undef SQLITE_TEX
28560 54 0a 23 65 6c 73 65 0a 23 20 64 65 66 69 6e 65  T.#else.# define
28570 20 53 51 4c 49 54 45 5f 54 45 58 54 20 20 20 20   SQLITE_TEXT    
28580 20 33 0a 23 65 6e 64 69 66 0a 23 64 65 66 69 6e   3.#endif.#defin
28590 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54 20 20  e SQLITE3_TEXT  
285a0 20 20 20 33 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49     3../*.** CAPI
285b0 33 52 45 46 3a 20 52 65 73 75 6c 74 20 56 61 6c  3REF: Result Val
285c0 75 65 73 20 46 72 6f 6d 20 41 20 51 75 65 72 79  ues From A Query
285d0 20 7b 48 31 33 38 30 30 7d 20 3c 53 31 30 37 30   {H13800} <S1070
285e0 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  0>.** KEYWORDS: 
285f0 7b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66  {column access f
28600 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20  unctions}.**.** 
28610 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 66  These routines f
28620 6f 72 6d 20 74 68 65 20 22 72 65 73 75 6c 74 20  orm the "result 
28630 73 65 74 20 71 75 65 72 79 22 20 69 6e 74 65 72  set query" inter
28640 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  face..**.** Thes
28650 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  e routines retur
28660 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62  n information ab
28670 6f 75 74 20 61 20 73 69 6e 67 6c 65 20 63 6f 6c  out a single col
28680 75 6d 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65  umn of the curre
28690 6e 74 0a 2a 2a 20 72 65 73 75 6c 74 20 72 6f 77  nt.** result row
286a0 20 6f 66 20 61 20 71 75 65 72 79 2e 20 20 49 6e   of a query.  In
286b0 20 65 76 65 72 79 20 63 61 73 65 20 74 68 65 20   every case the 
286c0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69  first argument i
286d0 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74  s a pointer.** t
286e0 6f 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  o the [prepared 
286f0 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20  statement] that 
28700 69 73 20 62 65 69 6e 67 20 65 76 61 6c 75 61 74  is being evaluat
28710 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33  ed (the [sqlite3
28720 5f 73 74 6d 74 2a 5d 0a 2a 2a 20 74 68 61 74 20  _stmt*].** that 
28730 77 61 73 20 72 65 74 75 72 6e 65 64 20 66 72 6f  was returned fro
28740 6d 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  m [sqlite3_prepa
28750 72 65 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20  re_v2()] or one 
28760 6f 66 20 69 74 73 20 76 61 72 69 61 6e 74 73 29  of its variants)
28770 0a 2a 2a 20 61 6e 64 20 74 68 65 20 73 65 63 6f  .** and the seco
28780 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  nd argument is t
28790 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20  he index of the 
287a0 63 6f 6c 75 6d 6e 20 66 6f 72 20 77 68 69 63 68  column for which
287b0 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20   information.** 
287c0 73 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e  should be return
287d0 65 64 2e 20 20 54 68 65 20 6c 65 66 74 6d 6f 73  ed.  The leftmos
287e0 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20  t column of the 
287f0 72 65 73 75 6c 74 20 73 65 74 20 68 61 73 20 74  result set has t
28800 68 65 20 69 6e 64 65 78 20 30 2e 0a 2a 2a 0a 2a  he index 0..**.*
28810 2a 20 49 66 20 74 68 65 20 53 51 4c 20 73 74 61  * If the SQL sta
28820 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20  tement does not 
28830 63 75 72 72 65 6e 74 6c 79 20 70 6f 69 6e 74 20  currently point 
28840 74 6f 20 61 20 76 61 6c 69 64 20 72 6f 77 2c 20  to a valid row, 
28850 6f 72 20 69 66 20 74 68 65 0a 2a 2a 20 63 6f 6c  or if the.** col
28860 75 6d 6e 20 69 6e 64 65 78 20 69 73 20 6f 75 74  umn index is out
28870 20 6f 66 20 72 61 6e 67 65 2c 20 74 68 65 20 72   of range, the r
28880 65 73 75 6c 74 20 69 73 20 75 6e 64 65 66 69 6e  esult is undefin
28890 65 64 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  ed..** These rou
288a0 74 69 6e 65 73 20 6d 61 79 20 6f 6e 6c 79 20 62  tines may only b
288b0 65 20 63 61 6c 6c 65 64 20 77 68 65 6e 20 74 68  e called when th
288c0 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61  e most recent ca
288d0 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ll to.** [sqlite
288e0 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72 65  3_step()] has re
288f0 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52  turned [SQLITE_R
28900 4f 57 5d 20 61 6e 64 20 6e 65 69 74 68 65 72 0a  OW] and neither.
28910 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ** [sqlite3_rese
28920 74 28 29 5d 20 6e 6f 72 20 5b 73 71 6c 69 74 65  t()] nor [sqlite
28930 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 68 61  3_finalize()] ha
28940 76 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 73  ve been called s
28950 75 62 73 65 71 75 65 6e 74 6c 79 2e 0a 2a 2a 20  ubsequently..** 
28960 49 66 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20  If any of these 
28970 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c  routines are cal
28980 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c 69 74  led after [sqlit
28990 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a  e3_reset()] or.*
289a0 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  * [sqlite3_final
289b0 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20  ize()] or after 
289c0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
289d0 20 68 61 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a   has returned.**
289e0 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65 72   something other
289f0 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f   than [SQLITE_RO
28a00 57 5d 2c 20 74 68 65 20 72 65 73 75 6c 74 73 20  W], the results 
28a10 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a  are undefined..*
28a20 2a 20 49 66 20 5b 73 71 6c 69 74 65 33 5f 73 74  * If [sqlite3_st
28a30 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  ep()] or [sqlite
28a40 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73  3_reset()] or [s
28a50 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
28a60 29 5d 0a 2a 2a 20 61 72 65 20 63 61 6c 6c 65 64  )].** are called
28a70 20 66 72 6f 6d 20 61 20 64 69 66 66 65 72 65 6e   from a differen
28a80 74 20 74 68 72 65 61 64 20 77 68 69 6c 65 20 61  t thread while a
28a90 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  ny of these rout
28aa0 69 6e 65 73 0a 2a 2a 20 61 72 65 20 70 65 6e 64  ines.** are pend
28ab0 69 6e 67 2c 20 74 68 65 6e 20 74 68 65 20 72 65  ing, then the re
28ac0 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69  sults are undefi
28ad0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ned..**.** The s
28ae0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79  qlite3_column_ty
28af0 70 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74  pe() routine ret
28b00 75 72 6e 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c  urns the.** [SQL
28b10 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61  ITE_INTEGER | da
28b20 74 61 74 79 70 65 20 63 6f 64 65 5d 20 66 6f 72  tatype code] for
28b30 20 74 68 65 20 69 6e 69 74 69 61 6c 20 64 61 74   the initial dat
28b40 61 20 74 79 70 65 0a 2a 2a 20 6f 66 20 74 68 65  a type.** of the
28b50 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 2e 20   result column. 
28b60 20 54 68 65 20 72 65 74 75 72 6e 65 64 20 76 61   The returned va
28b70 6c 75 65 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53  lue is one of [S
28b80 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c 0a  QLITE_INTEGER],.
28b90 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54  ** [SQLITE_FLOAT
28ba0 5d 2c 20 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d  ], [SQLITE_TEXT]
28bb0 2c 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 2c  , [SQLITE_BLOB],
28bc0 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c   or [SQLITE_NULL
28bd0 5d 2e 20 20 54 68 65 20 76 61 6c 75 65 0a 2a 2a  ].  The value.**
28be0 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c   returned by sql
28bf0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65  ite3_column_type
28c00 28 29 20 69 73 20 6f 6e 6c 79 20 6d 65 61 6e 69  () is only meani
28c10 6e 67 66 75 6c 20 69 66 20 6e 6f 20 74 79 70 65  ngful if no type
28c20 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20  .** conversions 
28c30 68 61 76 65 20 6f 63 63 75 72 72 65 64 20 61 73  have occurred as
28c40 20 64 65 73 63 72 69 62 65 64 20 62 65 6c 6f 77   described below
28c50 2e 20 20 41 66 74 65 72 20 61 20 74 79 70 65 20  .  After a type 
28c60 63 6f 6e 76 65 72 73 69 6f 6e 2c 0a 2a 2a 20 74  conversion,.** t
28c70 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
28c80 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c  d by sqlite3_col
28c90 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 75 6e  umn_type() is un
28ca0 64 65 66 69 6e 65 64 2e 20 20 46 75 74 75 72 65  defined.  Future
28cb0 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  .** versions of 
28cc0 53 51 4c 69 74 65 20 6d 61 79 20 63 68 61 6e 67  SQLite may chang
28cd0 65 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f  e the behavior o
28ce0 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  f sqlite3_column
28cf0 5f 74 79 70 65 28 29 0a 2a 2a 20 66 6f 6c 6c 6f  _type().** follo
28d00 77 69 6e 67 20 61 20 74 79 70 65 20 63 6f 6e 76  wing a type conv
28d10 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66  ersion..**.** If
28d20 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61   the result is a
28d30 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d 38 20 73   BLOB or UTF-8 s
28d40 74 72 69 6e 67 20 74 68 65 6e 20 74 68 65 20 73  tring then the s
28d50 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
28d60 74 65 73 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65  tes().** routine
28d70 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
28d80 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
28d90 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 72  that BLOB or str
28da0 69 6e 67 2e 0a 2a 2a 20 49 66 20 74 68 65 20 72  ing..** If the r
28db0 65 73 75 6c 74 20 69 73 20 61 20 55 54 46 2d 31  esult is a UTF-1
28dc0 36 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 73  6 string, then s
28dd0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
28de0 74 65 73 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a  tes() converts.*
28df0 2a 20 74 68 65 20 73 74 72 69 6e 67 20 74 6f 20  * the string to 
28e00 55 54 46 2d 38 20 61 6e 64 20 74 68 65 6e 20 72  UTF-8 and then r
28e10 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
28e20 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20 49  r of bytes..** I
28e30 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
28e40 61 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20  a numeric value 
28e50 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c  then sqlite3_col
28e60 75 6d 6e 5f 62 79 74 65 73 28 29 20 75 73 65 73  umn_bytes() uses
28e70 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70  .** [sqlite3_snp
28e80 72 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76  rintf()] to conv
28e90 65 72 74 20 74 68 61 74 20 76 61 6c 75 65 20 74  ert that value t
28ea0 6f 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67  o a UTF-8 string
28eb0 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20   and returns.** 
28ec0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
28ed0 74 65 73 20 69 6e 20 74 68 61 74 20 73 74 72 69  tes in that stri
28ee0 6e 67 2e 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65  ng..** The value
28ef0 20 72 65 74 75 72 6e 65 64 20 64 6f 65 73 20 6e   returned does n
28f00 6f 74 20 69 6e 63 6c 75 64 65 20 74 68 65 20 7a  ot include the z
28f10 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 61  ero terminator a
28f20 74 20 74 68 65 20 65 6e 64 0a 2a 2a 20 6f 66 20  t the end.** of 
28f30 74 68 65 20 73 74 72 69 6e 67 2e 20 20 46 6f 72  the string.  For
28f40 20 63 6c 61 72 69 74 79 3a 20 74 68 65 20 76 61   clarity: the va
28f50 6c 75 65 20 72 65 74 75 72 6e 65 64 20 69 73 20  lue returned is 
28f60 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a  the number of.**
28f70 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 73 74   bytes in the st
28f80 72 69 6e 67 2c 20 6e 6f 74 20 74 68 65 20 6e 75  ring, not the nu
28f90 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65  mber of characte
28fa0 72 73 2e 0a 2a 2a 0a 2a 2a 20 53 74 72 69 6e 67  rs..**.** String
28fb0 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71  s returned by sq
28fc0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
28fd0 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  t() and sqlite3_
28fe0 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 2c  column_text16(),
28ff0 0a 2a 2a 20 65 76 65 6e 20 65 6d 70 74 79 20 73  .** even empty s
29000 74 72 69 6e 67 73 2c 20 61 72 65 20 61 6c 77 61  trings, are alwa
29010 79 73 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74  ys zero terminat
29020 65 64 2e 20 20 54 68 65 20 72 65 74 75 72 6e 0a  ed.  The return.
29030 2a 2a 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71  ** value from sq
29040 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
29050 62 28 29 20 66 6f 72 20 61 20 7a 65 72 6f 2d 6c  b() for a zero-l
29060 65 6e 67 74 68 20 42 4c 4f 42 20 69 73 20 61 6e  ength BLOB is an
29070 20 61 72 62 69 74 72 61 72 79 0a 2a 2a 20 70 6f   arbitrary.** po
29080 69 6e 74 65 72 2c 20 70 6f 73 73 69 62 6c 79 20  inter, possibly 
29090 65 76 65 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  even a NULL poin
290a0 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ter..**.** The s
290b0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
290c0 74 65 73 31 36 28 29 20 72 6f 75 74 69 6e 65 20  tes16() routine 
290d0 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 20 73 71  is similar to sq
290e0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
290f0 65 73 28 29 0a 2a 2a 20 62 75 74 20 6c 65 61 76  es().** but leav
29100 65 73 20 74 68 65 20 72 65 73 75 6c 74 20 69 6e  es the result in
29110 20 55 54 46 2d 31 36 20 69 6e 20 6e 61 74 69 76   UTF-16 in nativ
29120 65 20 62 79 74 65 20 6f 72 64 65 72 20 69 6e 73  e byte order ins
29130 74 65 61 64 20 6f 66 20 55 54 46 2d 38 2e 0a 2a  tead of UTF-8..*
29140 2a 20 54 68 65 20 7a 65 72 6f 20 74 65 72 6d 69  * The zero termi
29150 6e 61 74 6f 72 20 69 73 20 6e 6f 74 20 69 6e 63  nator is not inc
29160 6c 75 64 65 64 20 69 6e 20 74 68 69 73 20 63 6f  luded in this co
29170 75 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6f  unt..**.** The o
29180 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 62  bject returned b
29190 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  y [sqlite3_colum
291a0 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 61 6e  n_value()] is an
291b0 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64  .** [unprotected
291c0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
291d0 6f 62 6a 65 63 74 2e 20 20 41 6e 20 75 6e 70 72  object.  An unpr
291e0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
291f0 76 61 6c 75 65 20 6f 62 6a 65 63 74 0a 2a 2a 20  value object.** 
29200 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64  may only be used
29210 20 77 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 62   with [sqlite3_b
29220 69 6e 64 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64  ind_value()] and
29230 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
29240 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 49 66  _value()]..** If
29250 20 74 68 65 20 5b 75 6e 70 72 6f 74 65 63 74 65   the [unprotecte
29260 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
29270 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64   object returned
29280 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   by.** [sqlite3_
29290 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20  column_value()] 
292a0 69 73 20 75 73 65 64 20 69 6e 20 61 6e 79 20 6f  is used in any o
292b0 74 68 65 72 20 77 61 79 2c 20 69 6e 63 6c 75 64  ther way, includ
292c0 69 6e 67 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20  ing calls.** to 
292d0 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73  routines like [s
292e0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74  qlite3_value_int
292f0 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61  ()], [sqlite3_va
29300 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20  lue_text()],.** 
29310 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  or [sqlite3_valu
29320 65 5f 62 79 74 65 73 28 29 5d 2c 20 74 68 65 6e  e_bytes()], then
29330 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73   the behavior is
29340 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
29350 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
29360 20 61 74 74 65 6d 70 74 20 74 6f 20 63 6f 6e 76   attempt to conv
29370 65 72 74 20 74 68 65 20 76 61 6c 75 65 20 77 68  ert the value wh
29380 65 72 65 20 61 70 70 72 6f 70 72 69 61 74 65 2e  ere appropriate.
29390 20 20 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65    For.** example
293a0 2c 20 69 66 20 74 68 65 20 69 6e 74 65 72 6e 61  , if the interna
293b0 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e  l representation
293c0 20 69 73 20 46 4c 4f 41 54 20 61 6e 64 20 61 20   is FLOAT and a 
293d0 74 65 78 74 20 72 65 73 75 6c 74 0a 2a 2a 20 69  text result.** i
293e0 73 20 72 65 71 75 65 73 74 65 64 2c 20 5b 73 71  s requested, [sq
293f0 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
29400 5d 20 69 73 20 75 73 65 64 20 69 6e 74 65 72 6e  ] is used intern
29410 61 6c 6c 79 20 74 6f 20 70 65 72 66 6f 72 6d 20  ally to perform 
29420 74 68 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f  the.** conversio
29430 6e 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e  n automatically.
29440 20 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20    The following 
29450 74 61 62 6c 65 20 64 65 74 61 69 6c 73 20 74 68  table details th
29460 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 0a 2a 2a  e conversions.**
29470 20 74 68 61 74 20 61 72 65 20 61 70 70 6c 69 65   that are applie
29480 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  d:.**.** <blockq
29490 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20  uote>.** <table 
294a0 62 6f 72 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c  border="1">.** <
294b0 74 72 3e 3c 74 68 3e 20 49 6e 74 65 72 6e 61 6c  tr><th> Internal
294c0 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 52 65  <br>Type <th> Re
294d0 71 75 65 73 74 65 64 3c 62 72 3e 54 79 70 65 20  quested<br>Type 
294e0 3c 74 68 3e 20 20 43 6f 6e 76 65 72 73 69 6f 6e  <th>  Conversion
294f0 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  .**.** <tr><td> 
29500 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 49 4e   NULL    <td> IN
29510 54 45 47 45 52 20 20 20 3c 74 64 3e 20 52 65 73  TEGER   <td> Res
29520 75 6c 74 20 69 73 20 30 0a 2a 2a 20 3c 74 72 3e  ult is 0.** <tr>
29530 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74  <td>  NULL    <t
29540 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64  d>  FLOAT    <td
29550 3e 20 52 65 73 75 6c 74 20 69 73 20 30 2e 30 0a  > Result is 0.0.
29560 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c  ** <tr><td>  NUL
29570 4c 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54  L    <td>   TEXT
29580 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20      <td> Result 
29590 69 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a  is NULL pointer.
295a0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c  ** <tr><td>  NUL
295b0 4c 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42  L    <td>   BLOB
295c0 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20      <td> Result 
295d0 69 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a  is NULL pointer.
295e0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45  ** <tr><td> INTE
295f0 47 45 52 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54  GER  <td>  FLOAT
29600 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74      <td> Convert
29610 20 66 72 6f 6d 20 69 6e 74 65 67 65 72 20 74 6f   from integer to
29620 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74   float.** <tr><t
29630 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e  d> INTEGER  <td>
29640 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20     TEXT    <td> 
29650 41 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67 20  ASCII rendering 
29660 6f 66 20 74 68 65 20 69 6e 74 65 67 65 72 0a 2a  of the integer.*
29670 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47  * <tr><td> INTEG
29680 45 52 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20  ER  <td>   BLOB 
29690 20 20 20 3c 74 64 3e 20 53 61 6d 65 20 61 73 20     <td> Same as 
296a0 49 4e 54 45 47 45 52 2d 3e 54 45 58 54 0a 2a 2a  INTEGER->TEXT.**
296b0 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54   <tr><td>  FLOAT
296c0 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20     <td> INTEGER 
296d0 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 66    <td> Convert f
296e0 72 6f 6d 20 66 6c 6f 61 74 20 74 6f 20 69 6e 74  rom float to int
296f0 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  eger.** <tr><td>
29700 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20    FLOAT   <td>  
29710 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53   TEXT    <td> AS
29720 43 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66  CII rendering of
29730 20 74 68 65 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74   the float.** <t
29740 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20  r><td>  FLOAT   
29750 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c  <td>   BLOB    <
29760 74 64 3e 20 53 61 6d 65 20 61 73 20 46 4c 4f 41  td> Same as FLOA
29770 54 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c  T->TEXT.** <tr><
29780 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64  td>  TEXT    <td
29790 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e  > INTEGER   <td>
297a0 20 55 73 65 20 61 74 6f 69 28 29 0a 2a 2a 20 3c   Use atoi().** <
297b0 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20  tr><td>  TEXT   
297c0 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20   <td>  FLOAT    
297d0 3c 74 64 3e 20 55 73 65 20 61 74 6f 66 28 29 0a  <td> Use atof().
297e0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58  ** <tr><td>  TEX
297f0 54 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42  T    <td>   BLOB
29800 20 20 20 20 3c 74 64 3e 20 4e 6f 20 63 68 61 6e      <td> No chan
29810 67 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  ge.** <tr><td>  
29820 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 49 4e 54  BLOB    <td> INT
29830 45 47 45 52 20 20 20 3c 74 64 3e 20 43 6f 6e 76  EGER   <td> Conv
29840 65 72 74 20 74 6f 20 54 45 58 54 20 74 68 65 6e  ert to TEXT then
29850 20 75 73 65 20 61 74 6f 69 28 29 0a 2a 2a 20 3c   use atoi().** <
29860 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20  tr><td>  BLOB   
29870 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20   <td>  FLOAT    
29880 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 74 6f 20  <td> Convert to 
29890 54 45 58 54 20 74 68 65 6e 20 75 73 65 20 61 74  TEXT then use at
298a0 6f 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  of().** <tr><td>
298b0 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20    BLOB    <td>  
298c0 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 64   TEXT    <td> Ad
298d0 64 20 61 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61  d a zero termina
298e0 74 6f 72 20 69 66 20 6e 65 65 64 65 64 0a 2a 2a  tor if needed.**
298f0 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62   </table>.** </b
29900 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
29910 20 54 68 65 20 74 61 62 6c 65 20 61 62 6f 76 65   The table above
29920 20 6d 61 6b 65 73 20 72 65 66 65 72 65 6e 63 65   makes reference
29930 20 74 6f 20 73 74 61 6e 64 61 72 64 20 43 20 6c   to standard C l
29940 69 62 72 61 72 79 20 66 75 6e 63 74 69 6f 6e 73  ibrary functions
29950 20 61 74 6f 69 28 29 0a 2a 2a 20 61 6e 64 20 61   atoi().** and a
29960 74 6f 66 28 29 2e 20 20 53 51 4c 69 74 65 20 64  tof().  SQLite d
29970 6f 65 73 20 6e 6f 74 20 72 65 61 6c 6c 79 20 75  oes not really u
29980 73 65 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f  se these functio
29990 6e 73 2e 20 20 49 74 20 68 61 73 20 69 74 73 0a  ns.  It has its.
299a0 2a 2a 20 6f 77 6e 20 65 71 75 69 76 61 6c 65 6e  ** own equivalen
299b0 74 20 69 6e 74 65 72 6e 61 6c 20 72 6f 75 74 69  t internal routi
299c0 6e 65 73 2e 20 20 54 68 65 20 61 74 6f 69 28 29  nes.  The atoi()
299d0 20 61 6e 64 20 61 74 6f 66 28 29 20 6e 61 6d 65   and atof() name
299e0 73 20 61 72 65 0a 2a 2a 20 75 73 65 64 20 69 6e  s are.** used in
299f0 20 74 68 65 20 74 61 62 6c 65 20 66 6f 72 20 62   the table for b
29a00 72 65 76 69 74 79 20 61 6e 64 20 62 65 63 61 75  revity and becau
29a10 73 65 20 74 68 65 79 20 61 72 65 20 66 61 6d 69  se they are fami
29a20 6c 69 61 72 20 74 6f 20 6d 6f 73 74 0a 2a 2a 20  liar to most.** 
29a30 43 20 70 72 6f 67 72 61 6d 6d 65 72 73 2e 0a 2a  C programmers..*
29a40 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 77  *.** Note that w
29a50 68 65 6e 20 74 79 70 65 20 63 6f 6e 76 65 72 73  hen type convers
29a60 69 6f 6e 73 20 6f 63 63 75 72 2c 20 70 6f 69 6e  ions occur, poin
29a70 74 65 72 73 20 72 65 74 75 72 6e 65 64 20 62 79  ters returned by
29a80 20 70 72 69 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20   prior.** calls 
29a90 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  to sqlite3_colum
29aa0 6e 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65  n_blob(), sqlite
29ab0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c  3_column_text(),
29ac0 20 61 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74   and/or.** sqlit
29ad0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
29ae0 28 29 20 6d 61 79 20 62 65 20 69 6e 76 61 6c 69  () may be invali
29af0 64 61 74 65 64 2e 0a 2a 2a 20 54 79 70 65 20 63  dated..** Type c
29b00 6f 6e 76 65 72 73 69 6f 6e 73 20 61 6e 64 20 70  onversions and p
29b10 6f 69 6e 74 65 72 20 69 6e 76 61 6c 69 64 61 74  ointer invalidat
29b20 69 6f 6e 73 20 6d 69 67 68 74 20 6f 63 63 75 72  ions might occur
29b30 0a 2a 2a 20 69 6e 20 74 68 65 20 66 6f 6c 6c 6f  .** in the follo
29b40 77 69 6e 67 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a  wing cases:.**.*
29b50 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54  * <ul>.** <li> T
29b60 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65  he initial conte
29b70 6e 74 20 69 73 20 61 20 42 4c 4f 42 20 61 6e 64  nt is a BLOB and
29b80 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
29b90 74 65 78 74 28 29 20 6f 72 0a 2a 2a 20 20 20 20  text() or.**    
29ba0 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e    sqlite3_column
29bb0 5f 74 65 78 74 31 36 28 29 20 69 73 20 63 61 6c  _text16() is cal
29bc0 6c 65 64 2e 20 20 41 20 7a 65 72 6f 2d 74 65 72  led.  A zero-ter
29bd0 6d 69 6e 61 74 6f 72 20 6d 69 67 68 74 0a 2a 2a  minator might.**
29be0 20 20 20 20 20 20 6e 65 65 64 20 74 6f 20 62 65        need to be
29bf0 20 61 64 64 65 64 20 74 6f 20 74 68 65 20 73 74   added to the st
29c00 72 69 6e 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c  ring.</li>.** <l
29c10 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63  i> The initial c
29c20 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 38 20  ontent is UTF-8 
29c30 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33  text and sqlite3
29c40 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
29c50 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c  ) or.**      sql
29c60 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
29c70 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20  16() is called. 
29c80 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73   The content mus
29c90 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a  t be converted.*
29ca0 2a 20 20 20 20 20 20 74 6f 20 55 54 46 2d 31 36  *      to UTF-16
29cb0 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54  .</li>.** <li> T
29cc0 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65  he initial conte
29cd0 6e 74 20 69 73 20 55 54 46 2d 31 36 20 74 65 78  nt is UTF-16 tex
29ce0 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f  t and sqlite3_co
29cf0 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a  lumn_bytes() or.
29d00 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f  **      sqlite3_
29d10 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 69 73  column_text() is
29d20 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f   called.  The co
29d30 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f  ntent must be co
29d40 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20  nverted.**      
29d50 74 6f 20 55 54 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a  to UTF-8.</li>.*
29d60 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 43 6f  * </ul>.**.** Co
29d70 6e 76 65 72 73 69 6f 6e 73 20 62 65 74 77 65 65  nversions betwee
29d80 6e 20 55 54 46 2d 31 36 62 65 20 61 6e 64 20 55  n UTF-16be and U
29d90 54 46 2d 31 36 6c 65 20 61 72 65 20 61 6c 77 61  TF-16le are alwa
29da0 79 73 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65  ys done in place
29db0 20 61 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69   and do.** not i
29dc0 6e 76 61 6c 69 64 61 74 65 20 61 20 70 72 69 6f  nvalidate a prio
29dd0 72 20 70 6f 69 6e 74 65 72 2c 20 74 68 6f 75 67  r pointer, thoug
29de0 68 20 6f 66 20 63 6f 75 72 73 65 20 74 68 65 20  h of course the 
29df0 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 62  content of the b
29e00 75 66 66 65 72 0a 2a 2a 20 74 68 61 74 20 74 68  uffer.** that th
29e10 65 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 20  e prior pointer 
29e20 70 6f 69 6e 74 73 20 74 6f 20 77 69 6c 6c 20 68  points to will h
29e30 61 76 65 20 62 65 65 6e 20 6d 6f 64 69 66 69 65  ave been modifie
29e40 64 2e 20 20 4f 74 68 65 72 20 6b 69 6e 64 73 0a  d.  Other kinds.
29e50 2a 2a 20 6f 66 20 63 6f 6e 76 65 72 73 69 6f 6e  ** of conversion
29e60 20 61 72 65 20 64 6f 6e 65 20 69 6e 20 70 6c 61   are done in pla
29e70 63 65 20 77 68 65 6e 20 69 74 20 69 73 20 70 6f  ce when it is po
29e80 73 73 69 62 6c 65 2c 20 62 75 74 20 73 6f 6d 65  ssible, but some
29e90 74 69 6d 65 73 20 74 68 65 79 0a 2a 2a 20 61 72  times they.** ar
29ea0 65 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 61  e not possible a
29eb0 6e 64 20 69 6e 20 74 68 6f 73 65 20 63 61 73 65  nd in those case
29ec0 73 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 73  s prior pointers
29ed0 20 61 72 65 20 69 6e 76 61 6c 69 64 61 74 65 64   are invalidated
29ee0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 61 66 65  ..**.** The safe
29ef0 73 74 20 61 6e 64 20 65 61 73 69 65 73 74 20 74  st and easiest t
29f00 6f 20 72 65 6d 65 6d 62 65 72 20 70 6f 6c 69 63  o remember polic
29f10 79 20 69 73 20 74 6f 20 69 6e 76 6f 6b 65 20 74  y is to invoke t
29f20 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a  hese routines.**
29f30 20 69 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 66   in one of the f
29f40 6f 6c 6c 6f 77 69 6e 67 20 77 61 79 73 3a 0a 2a  ollowing ways:.*
29f50 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c  *.** <ul>.**  <l
29f60 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  i>sqlite3_column
29f70 5f 74 65 78 74 28 29 20 66 6f 6c 6c 6f 77 65 64  _text() followed
29f80 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   by sqlite3_colu
29f90 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a  mn_bytes()</li>.
29fa0 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f  **  <li>sqlite3_
29fb0 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f  column_blob() fo
29fc0 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65  llowed by sqlite
29fd0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
29fe0 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71  </li>.**  <li>sq
29ff0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
2a000 74 31 36 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62  t16() followed b
2a010 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  y sqlite3_column
2a020 5f 62 79 74 65 73 31 36 28 29 3c 2f 6c 69 3e 0a  _bytes16()</li>.
2a030 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49  ** </ul>.**.** I
2a040 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 79  n other words, y
2a050 6f 75 20 73 68 6f 75 6c 64 20 63 61 6c 6c 20 73  ou should call s
2a060 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
2a070 78 74 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33  xt(),.** sqlite3
2a080 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20  _column_blob(), 
2a090 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  or sqlite3_colum
2a0a0 6e 5f 74 65 78 74 31 36 28 29 20 66 69 72 73 74  n_text16() first
2a0b0 20 74 6f 20 66 6f 72 63 65 20 74 68 65 20 72 65   to force the re
2a0c0 73 75 6c 74 0a 2a 2a 20 69 6e 74 6f 20 74 68 65  sult.** into the
2a0d0 20 64 65 73 69 72 65 64 20 66 6f 72 6d 61 74 2c   desired format,
2a0e0 20 74 68 65 6e 20 69 6e 76 6f 6b 65 20 73 71 6c   then invoke sql
2a0f0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2a100 73 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  s() or.** sqlite
2a110 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
2a120 28 29 20 74 6f 20 66 69 6e 64 20 74 68 65 20 73  () to find the s
2a130 69 7a 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c  ize of the resul
2a140 74 2e 20 20 44 6f 20 6e 6f 74 20 6d 69 78 20 63  t.  Do not mix c
2a150 61 6c 6c 73 0a 2a 2a 20 74 6f 20 73 71 6c 69 74  alls.** to sqlit
2a160 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
2a170 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   or sqlite3_colu
2a180 6d 6e 5f 62 6c 6f 62 28 29 20 77 69 74 68 20 63  mn_blob() with c
2a190 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74  alls to.** sqlit
2a1a0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
2a1b0 36 28 29 2c 20 61 6e 64 20 64 6f 20 6e 6f 74 20  6(), and do not 
2a1c0 6d 69 78 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c  mix calls to sql
2a1d0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
2a1e0 31 36 28 29 0a 2a 2a 20 77 69 74 68 20 63 61 6c  16().** with cal
2a1f0 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ls to sqlite3_co
2a200 6c 75 6d 6e 5f 62 79 74 65 73 28 29 2e 0a 2a 2a  lumn_bytes()..**
2a210 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74 65 72 73  .** The pointers
2a220 20 72 65 74 75 72 6e 65 64 20 61 72 65 20 76 61   returned are va
2a230 6c 69 64 20 75 6e 74 69 6c 20 61 20 74 79 70 65  lid until a type
2a240 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75   conversion occu
2a250 72 73 20 61 73 0a 2a 2a 20 64 65 73 63 72 69 62  rs as.** describ
2a260 65 64 20 61 62 6f 76 65 2c 20 6f 72 20 75 6e 74  ed above, or unt
2a270 69 6c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  il [sqlite3_step
2a280 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
2a290 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b  reset()] or.** [
2a2a0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
2a2b0 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 2e 20 20  ()] is called.  
2a2c0 54 68 65 20 6d 65 6d 6f 72 79 20 73 70 61 63 65  The memory space
2a2d0 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 73 74   used to hold st
2a2e0 72 69 6e 67 73 0a 2a 2a 20 61 6e 64 20 42 4c 4f  rings.** and BLO
2a2f0 42 73 20 69 73 20 66 72 65 65 64 20 61 75 74 6f  Bs is freed auto
2a300 6d 61 74 69 63 61 6c 6c 79 2e 20 20 44 6f 20 3c  matically.  Do <
2a310 62 3e 6e 6f 74 3c 2f 62 3e 20 70 61 73 73 20 74  b>not</b> pass t
2a320 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75  he pointers retu
2a330 72 6e 65 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  rned.** [sqlite3
2a340 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 5d 2c  _column_blob()],
2a350 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
2a360 5f 74 65 78 74 28 29 5d 2c 20 65 74 63 2e 20 69  _text()], etc. i
2a370 6e 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  nto.** [sqlite3_
2a380 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49  free()]..**.** I
2a390 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  f a memory alloc
2a3a0 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75  ation error occu
2a3b0 72 73 20 64 75 72 69 6e 67 20 74 68 65 20 65 76  rs during the ev
2a3c0 61 6c 75 61 74 69 6f 6e 20 6f 66 20 61 6e 79 0a  aluation of any.
2a3d0 2a 2a 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  ** of these rout
2a3e0 69 6e 65 73 2c 20 61 20 64 65 66 61 75 6c 74 20  ines, a default 
2a3f0 76 61 6c 75 65 20 69 73 20 72 65 74 75 72 6e 65  value is returne
2a400 64 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74 20  d.  The default 
2a410 76 61 6c 75 65 0a 2a 2a 20 69 73 20 65 69 74 68  value.** is eith
2a420 65 72 20 74 68 65 20 69 6e 74 65 67 65 72 20 30  er the integer 0
2a430 2c 20 74 68 65 20 66 6c 6f 61 74 69 6e 67 20 70  , the floating p
2a440 6f 69 6e 74 20 6e 75 6d 62 65 72 20 30 2e 30 2c  oint number 0.0,
2a450 20 6f 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f   or a NULL.** po
2a460 69 6e 74 65 72 2e 20 20 53 75 62 73 65 71 75 65  inter.  Subseque
2a470 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c  nt calls to [sql
2a480 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20  ite3_errcode()] 
2a490 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 5b  will return.** [
2a4a0 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a  SQLITE_NOMEM]..*
2a4b0 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
2a4c0 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 38 30 33 7d 20  .**.** {H13803} 
2a4d0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  The [sqlite3_col
2a4e0 75 6d 6e 5f 62 6c 6f 62 28 53 2c 4e 29 5d 20 69  umn_blob(S,N)] i
2a4f0 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74  nterface convert
2a500 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  s the.**        
2a510 20 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 69 6e 20    Nth column in 
2a520 74 68 65 20 63 75 72 72 65 6e 74 20 72 6f 77 20  the current row 
2a530 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  of the result se
2a540 74 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20  t for.**        
2a550 20 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20    the [prepared 
2a560 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 74  statement] S int
2a570 6f 20 61 20 42 4c 4f 42 20 61 6e 64 20 74 68 65  o a BLOB and the
2a580 6e 20 72 65 74 75 72 6e 73 20 61 0a 2a 2a 20 20  n returns a.**  
2a590 20 20 20 20 20 20 20 20 70 6f 69 6e 74 65 72 20          pointer 
2a5a0 74 6f 20 74 68 65 20 63 6f 6e 76 65 72 74 65 64  to the converted
2a5b0 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48   value..**.** {H
2a5c0 31 33 38 30 36 7d 20 54 68 65 20 5b 73 71 6c 69  13806} The [sqli
2a5d0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2a5e0 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65  (S,N)] interface
2a5f0 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20   returns the.** 
2a600 20 20 20 20 20 20 20 20 20 6e 75 6d 62 65 72 20           number 
2a610 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20  of bytes in the 
2a620 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 20 28  BLOB or string (
2a630 65 78 63 6c 75 73 69 76 65 20 6f 66 20 74 68 65  exclusive of the
2a640 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 7a 65 72  .**          zer
2a650 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 6f 6e 20  o terminator on 
2a660 74 68 65 20 73 74 72 69 6e 67 29 20 74 68 61 74  the string) that
2a670 20 77 61 73 20 72 65 74 75 72 6e 65 64 20 62 79   was returned by
2a680 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
2a690 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c   most recent cal
2a6a0 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f  l to [sqlite3_co
2a6b0 6c 75 6d 6e 5f 62 6c 6f 62 28 53 2c 4e 29 5d 20  lumn_blob(S,N)] 
2a6c0 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  or.**          [
2a6d0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2a6e0 65 78 74 28 53 2c 4e 29 5d 2e 0a 2a 2a 0a 2a 2a  ext(S,N)]..**.**
2a6f0 20 7b 48 31 33 38 30 39 7d 20 54 68 65 20 5b 73   {H13809} The [s
2a700 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2a710 74 65 73 31 36 28 53 2c 4e 29 5d 20 69 6e 74 65  tes16(S,N)] inte
2a720 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68  rface returns th
2a730 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 75  e.**          nu
2a740 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e  mber of bytes in
2a750 20 74 68 65 20 73 74 72 69 6e 67 20 28 65 78 63   the string (exc
2a760 6c 75 73 69 76 65 20 6f 66 20 74 68 65 0a 2a 2a  lusive of the.**
2a770 20 20 20 20 20 20 20 20 20 20 7a 65 72 6f 20 74            zero t
2a780 65 72 6d 69 6e 61 74 6f 72 20 6f 6e 20 74 68 65  erminator on the
2a790 20 73 74 72 69 6e 67 29 20 74 68 61 74 20 77 61   string) that wa
2a7a0 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  s returned by th
2a7b0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 6f  e.**          mo
2a7c0 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74  st recent call t
2a7d0 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  o [sqlite3_colum
2a7e0 6e 5f 74 65 78 74 31 36 28 53 2c 4e 29 5d 2e 0a  n_text16(S,N)]..
2a7f0 2a 2a 0a 2a 2a 20 7b 48 31 33 38 31 32 7d 20 54  **.** {H13812} T
2a800 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  he [sqlite3_colu
2a810 6d 6e 5f 64 6f 75 62 6c 65 28 53 2c 4e 29 5d 20  mn_double(S,N)] 
2a820 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72  interface conver
2a830 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  ts the.**       
2a840 20 20 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 69 6e     Nth column in
2a850 20 74 68 65 20 63 75 72 72 65 6e 74 20 72 6f 77   the current row
2a860 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73   of the result s
2a870 65 74 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20 20  et for the.**   
2a880 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65 64         [prepared
2a890 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e   statement] S in
2a8a0 74 6f 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f  to a floating po
2a8b0 69 6e 74 20 76 61 6c 75 65 20 61 6e 64 0a 2a 2a  int value and.**
2a8c0 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e            return
2a8d0 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 61 74  s a copy of that
2a8e0 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48   value..**.** {H
2a8f0 31 33 38 31 35 7d 20 54 68 65 20 5b 73 71 6c 69  13815} The [sqli
2a900 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 28 53  te3_column_int(S
2a910 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63  ,N)] interface c
2a920 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20  onverts the.**  
2a930 20 20 20 20 20 20 20 20 4e 74 68 20 63 6f 6c 75          Nth colu
2a940 6d 6e 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e  mn in the curren
2a950 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73  t row of the res
2a960 75 6c 74 20 73 65 74 20 66 6f 72 20 74 68 65 0a  ult set for the.
2a970 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 65  **          [pre
2a980 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2a990 20 53 20 69 6e 74 6f 20 61 20 36 34 2d 62 69 74   S into a 64-bit
2a9a0 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20   signed integer 
2a9b0 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  and.**          
2a9c0 72 65 74 75 72 6e 73 20 74 68 65 20 6c 6f 77 65  returns the lowe
2a9d0 72 20 33 32 20 62 69 74 73 20 6f 66 20 74 68 61  r 32 bits of tha
2a9e0 74 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a  t integer..**.**
2a9f0 20 7b 48 31 33 38 31 38 7d 20 54 68 65 20 5b 73   {H13818} The [s
2aa00 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e  qlite3_column_in
2aa10 74 36 34 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66  t64(S,N)] interf
2aa20 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65  ace converts the
2aa30 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 74 68  .**          Nth
2aa40 20 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 20 63   column in the c
2aa50 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68  urrent row of th
2aa60 65 20 72 65 73 75 6c 74 20 73 65 74 20 66 6f 72  e result set for
2aa70 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
2aa80 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2aa90 6d 65 6e 74 5d 20 53 20 69 6e 74 6f 20 61 20 36  ment] S into a 6
2aaa0 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74  4-bit signed int
2aab0 65 67 65 72 20 61 6e 64 0a 2a 2a 20 20 20 20 20  eger and.**     
2aac0 20 20 20 20 20 72 65 74 75 72 6e 73 20 61 20 63       returns a c
2aad0 6f 70 79 20 6f 66 20 74 68 61 74 20 69 6e 74 65  opy of that inte
2aae0 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 38  ger..**.** {H138
2aaf0 32 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  21} The [sqlite3
2ab00 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 53 2c 4e  _column_text(S,N
2ab10 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e  )] interface con
2ab20 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20  verts the.**    
2ab30 20 20 20 20 20 20 4e 74 68 20 63 6f 6c 75 6d 6e        Nth column
2ab40 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20   in the current 
2ab50 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c  row of the resul
2ab60 74 20 73 65 74 20 66 6f 72 0a 2a 2a 20 20 20 20  t set for.**    
2ab70 20 20 20 20 20 20 74 68 65 20 5b 70 72 65 70 61        the [prepa
2ab80 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
2ab90 20 69 6e 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72   into a zero-ter
2aba0 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 0a 2a 2a  minated UTF-8.**
2abb0 20 20 20 20 20 20 20 20 20 20 73 74 72 69 6e 67            string
2abc0 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70   and returns a p
2abd0 6f 69 6e 74 65 72 20 74 6f 20 74 68 61 74 20 73  ointer to that s
2abe0 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  tring..**.** {H1
2abf0 33 38 32 34 7d 20 54 68 65 20 5b 73 71 6c 69 74  3824} The [sqlit
2ac00 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
2ac10 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65  (S,N)] interface
2ac20 20 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a   converts the.**
2ac30 20 20 20 20 20 20 20 20 20 20 4e 74 68 20 63 6f            Nth co
2ac40 6c 75 6d 6e 20 69 6e 20 74 68 65 20 63 75 72 72  lumn in the curr
2ac50 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72  ent row of the r
2ac60 65 73 75 6c 74 20 73 65 74 20 66 6f 72 20 74 68  esult set for th
2ac70 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70  e.**          [p
2ac80 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2ac90 74 5d 20 53 20 69 6e 74 6f 20 61 20 7a 65 72 6f  t] S into a zero
2aca0 2d 74 65 72 6d 69 6e 61 74 65 64 20 32 2d 62 79  -terminated 2-by
2acb0 74 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  te.**          a
2acc0 6c 69 67 6e 65 64 20 55 54 46 2d 31 36 20 6e 61  ligned UTF-16 na
2acd0 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20  tive byte order 
2ace0 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72  string and retur
2acf0 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  ns.**          a
2ad00 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 61 74   pointer to that
2ad10 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b   string..**.** {
2ad20 48 31 33 38 32 37 7d 20 54 68 65 20 5b 73 71 6c  H13827} The [sql
2ad30 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65  ite3_column_type
2ad40 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65  (S,N)] interface
2ad50 20 72 65 74 75 72 6e 73 0a 2a 2a 20 20 20 20 20   returns.**     
2ad60 20 20 20 20 20 6f 6e 65 20 6f 66 20 5b 53 51 4c       one of [SQL
2ad70 49 54 45 5f 4e 55 4c 4c 5d 2c 20 5b 53 51 4c 49  ITE_NULL], [SQLI
2ad80 54 45 5f 49 4e 54 45 47 45 52 5d 2c 20 5b 53 51  TE_INTEGER], [SQ
2ad90 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c 0a 2a 2a 20  LITE_FLOAT],.** 
2ada0 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45           [SQLITE
2adb0 5f 54 45 58 54 5d 2c 20 6f 72 20 5b 53 51 4c 49  _TEXT], or [SQLI
2adc0 54 45 5f 42 4c 4f 42 5d 20 61 73 20 61 70 70 72  TE_BLOB] as appr
2add0 6f 70 72 69 61 74 65 20 66 6f 72 0a 2a 2a 20 20  opriate for.**  
2ade0 20 20 20 20 20 20 20 20 74 68 65 20 4e 74 68 20          the Nth 
2adf0 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 20 63 75  column in the cu
2ae00 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65  rrent row of the
2ae10 20 72 65 73 75 6c 74 20 73 65 74 20 66 6f 72 0a   result set for.
2ae20 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
2ae30 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2ae40 65 6e 74 5d 20 53 2e 0a 2a 2a 0a 2a 2a 20 7b 48  ent] S..**.** {H
2ae50 31 33 38 33 30 7d 20 54 68 65 20 5b 73 71 6c 69  13830} The [sqli
2ae60 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65  te3_column_value
2ae70 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65  (S,N)] interface
2ae80 20 72 65 74 75 72 6e 73 20 61 0a 2a 2a 20 20 20   returns a.**   
2ae90 20 20 20 20 20 20 20 70 6f 69 6e 74 65 72 20 74         pointer t
2aea0 6f 20 61 6e 20 5b 75 6e 70 72 6f 74 65 63 74 65  o an [unprotecte
2aeb0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
2aec0 20 6f 62 6a 65 63 74 20 66 6f 72 20 74 68 65 0a   object for the.
2aed0 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 74 68 20  **          Nth 
2aee0 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 20 63 75  column in the cu
2aef0 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65  rrent row of the
2af00 20 72 65 73 75 6c 74 20 73 65 74 20 66 6f 72 0a   result set for.
2af10 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
2af20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2af30 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 63 6f 6e 73 74  ent] S..*/.const
2af40 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
2af50 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 73 71 6c 69 74  olumn_blob(sqlit
2af60 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
2af70 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ol);.int sqlite3
2af80 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 73 71  _column_bytes(sq
2af90 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2afa0 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69   iCol);.int sqli
2afb0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2afc0 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
2afd0 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 64 6f 75  , int iCol);.dou
2afe0 62 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ble sqlite3_colu
2aff0 6d 6e 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65  mn_double(sqlite
2b000 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
2b010 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  l);.int sqlite3_
2b020 63 6f 6c 75 6d 6e 5f 69 6e 74 28 73 71 6c 69 74  column_int(sqlit
2b030 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
2b040 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74  ol);.sqlite3_int
2b050 36 34 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  64 sqlite3_colum
2b060 6e 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f  n_int64(sqlite3_
2b070 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
2b080 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64  ;.const unsigned
2b090 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63   char *sqlite3_c
2b0a0 6f 6c 75 6d 6e 5f 74 65 78 74 28 73 71 6c 69 74  olumn_text(sqlit
2b0b0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
2b0c0 6f 6c 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  ol);.const void 
2b0d0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
2b0e0 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73  text16(sqlite3_s
2b0f0 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
2b100 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c  .int sqlite3_col
2b110 75 6d 6e 5f 74 79 70 65 28 73 71 6c 69 74 65 33  umn_type(sqlite3
2b120 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
2b130 29 3b 0a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  );.sqlite3_value
2b140 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
2b150 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73  _value(sqlite3_s
2b160 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
2b170 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2b180 3a 20 44 65 73 74 72 6f 79 20 41 20 50 72 65 70  : Destroy A Prep
2b190 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f  ared Statement O
2b1a0 62 6a 65 63 74 20 7b 48 31 33 33 30 30 7d 20 3c  bject {H13300} <
2b1b0 53 37 30 33 30 30 3e 3c 53 33 30 31 30 30 3e 0a  S70300><S30100>.
2b1c0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
2b1d0 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 66 75 6e  3_finalize() fun
2b1e0 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20  ction is called 
2b1f0 74 6f 20 64 65 6c 65 74 65 20 61 20 5b 70 72 65  to delete a [pre
2b200 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2b210 2e 0a 2a 2a 20 49 66 20 74 68 65 20 73 74 61 74  ..** If the stat
2b220 65 6d 65 6e 74 20 77 61 73 20 65 78 65 63 75 74  ement was execut
2b230 65 64 20 73 75 63 63 65 73 73 66 75 6c 6c 79 20  ed successfully 
2b240 6f 72 20 6e 6f 74 20 65 78 65 63 75 74 65 64 20  or not executed 
2b250 61 74 20 61 6c 6c 2c 20 74 68 65 6e 0a 2a 2a 20  at all, then.** 
2b260 53 51 4c 49 54 45 5f 4f 4b 20 69 73 20 72 65 74  SQLITE_OK is ret
2b270 75 72 6e 65 64 2e 20 49 66 20 65 78 65 63 75 74  urned. If execut
2b280 69 6f 6e 20 6f 66 20 74 68 65 20 73 74 61 74 65  ion of the state
2b290 6d 65 6e 74 20 66 61 69 6c 65 64 20 74 68 65 6e  ment failed then
2b2a0 20 61 6e 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f   an.** [error co
2b2b0 64 65 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65 64  de] or [extended
2b2c0 20 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20   error code] is 
2b2d0 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
2b2e0 54 68 69 73 20 72 6f 75 74 69 6e 65 20 63 61 6e  This routine can
2b2f0 20 62 65 20 63 61 6c 6c 65 64 20 61 74 20 61 6e   be called at an
2b300 79 20 70 6f 69 6e 74 20 64 75 72 69 6e 67 20 74  y point during t
2b310 68 65 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20  he execution of 
2b320 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  the.** [prepared
2b330 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 49 66   statement].  If
2b340 20 74 68 65 20 76 69 72 74 75 61 6c 20 6d 61 63   the virtual mac
2b350 68 69 6e 65 20 68 61 73 20 6e 6f 74 0a 2a 2a 20  hine has not.** 
2b360 63 6f 6d 70 6c 65 74 65 64 20 65 78 65 63 75 74  completed execut
2b370 69 6f 6e 20 77 68 65 6e 20 74 68 69 73 20 72 6f  ion when this ro
2b380 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 2c  utine is called,
2b390 20 74 68 61 74 20 69 73 20 6c 69 6b 65 0a 2a 2a   that is like.**
2b3a0 20 65 6e 63 6f 75 6e 74 65 72 69 6e 67 20 61 6e   encountering an
2b3b0 20 65 72 72 6f 72 20 6f 72 20 61 6e 20 5b 73 71   error or an [sq
2b3c0 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 20  lite3_interrupt 
2b3d0 7c 20 69 6e 74 65 72 72 75 70 74 5d 2e 0a 2a 2a  | interrupt]..**
2b3e0 20 49 6e 63 6f 6d 70 6c 65 74 65 20 75 70 64 61   Incomplete upda
2b3f0 74 65 73 20 6d 61 79 20 62 65 20 72 6f 6c 6c 65  tes may be rolle
2b400 64 20 62 61 63 6b 20 61 6e 64 20 74 72 61 6e 73  d back and trans
2b410 61 63 74 69 6f 6e 73 20 63 61 6e 63 65 6c 65 64  actions canceled
2b420 2c 0a 2a 2a 20 64 65 70 65 6e 64 69 6e 67 20 6f  ,.** depending o
2b430 6e 20 74 68 65 20 63 69 72 63 75 6d 73 74 61 6e  n the circumstan
2b440 63 65 73 2c 20 61 6e 64 20 74 68 65 0a 2a 2a 20  ces, and the.** 
2b450 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 72 65 74  [error code] ret
2b460 75 72 6e 65 64 20 77 69 6c 6c 20 62 65 20 5b 53  urned will be [S
2b470 51 4c 49 54 45 5f 41 42 4f 52 54 5d 2e 0a 2a 2a  QLITE_ABORT]..**
2b480 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
2b490 2a 2a 0a 2a 2a 20 7b 48 31 31 33 30 32 7d 20 54  **.** {H11302} T
2b4a0 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  he [sqlite3_fina
2b4b0 6c 69 7a 65 28 53 29 5d 20 69 6e 74 65 72 66 61  lize(S)] interfa
2b4c0 63 65 20 64 65 73 74 72 6f 79 73 20 74 68 65 0a  ce destroys the.
2b4d0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 65  **          [pre
2b4e0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2b4f0 20 53 20 61 6e 64 20 72 65 6c 65 61 73 65 73 20   S and releases 
2b500 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  all.**          
2b510 6d 65 6d 6f 72 79 20 61 6e 64 20 66 69 6c 65 20  memory and file 
2b520 72 65 73 6f 75 72 63 65 73 20 68 65 6c 64 20 62  resources held b
2b530 79 20 74 68 61 74 20 6f 62 6a 65 63 74 2e 0a 2a  y that object..*
2b540 2a 0a 2a 2a 20 7b 48 31 31 33 30 34 7d 20 49 66  *.** {H11304} If
2b550 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
2b560 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
2b570 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 20 74  3_step(S)] for t
2b580 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  he.**          [
2b590 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2b5a0 6e 74 5d 20 53 20 72 65 74 75 72 6e 65 64 20 61  nt] S returned a
2b5b0 6e 20 65 72 72 6f 72 2c 0a 2a 2a 20 20 20 20 20  n error,.**     
2b5c0 20 20 20 20 20 74 68 65 6e 20 5b 73 71 6c 69 74       then [sqlit
2b5d0 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 5d 20  e3_finalize(S)] 
2b5e0 72 65 74 75 72 6e 73 20 74 68 61 74 20 73 61 6d  returns that sam
2b5f0 65 20 65 72 72 6f 72 2e 0a 2a 2f 0a 69 6e 74 20  e error..*/.int 
2b600 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
2b610 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70  (sqlite3_stmt *p
2b620 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Stmt);../*.** CA
2b630 50 49 33 52 45 46 3a 20 52 65 73 65 74 20 41 20  PI3REF: Reset A 
2b640 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65  Prepared Stateme
2b650 6e 74 20 4f 62 6a 65 63 74 20 7b 48 31 33 33 33  nt Object {H1333
2b660 30 7d 20 3c 53 37 30 33 30 30 3e 0a 2a 2a 0a 2a  0} <S70300>.**.*
2b670 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65  * The sqlite3_re
2b680 73 65 74 28 29 20 66 75 6e 63 74 69 6f 6e 20 69  set() function i
2b690 73 20 63 61 6c 6c 65 64 20 74 6f 20 72 65 73 65  s called to rese
2b6a0 74 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  t a [prepared st
2b6b0 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65  atement].** obje
2b6c0 63 74 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69  ct back to its i
2b6d0 6e 69 74 69 61 6c 20 73 74 61 74 65 2c 20 72 65  nitial state, re
2b6e0 61 64 79 20 74 6f 20 62 65 20 72 65 2d 65 78 65  ady to be re-exe
2b6f0 63 75 74 65 64 2e 0a 2a 2a 20 41 6e 79 20 53 51  cuted..** Any SQ
2b700 4c 20 73 74 61 74 65 6d 65 6e 74 20 76 61 72 69  L statement vari
2b710 61 62 6c 65 73 20 74 68 61 74 20 68 61 64 20 76  ables that had v
2b720 61 6c 75 65 73 20 62 6f 75 6e 64 20 74 6f 20 74  alues bound to t
2b730 68 65 6d 20 75 73 69 6e 67 0a 2a 2a 20 74 68 65  hem using.** the
2b740 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
2b750 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 62 69  lob | sqlite3_bi
2b760 6e 64 5f 2a 28 29 20 41 50 49 5d 20 72 65 74 61  nd_*() API] reta
2b770 69 6e 20 74 68 65 69 72 20 76 61 6c 75 65 73 2e  in their values.
2b780 0a 2a 2a 20 55 73 65 20 5b 73 71 6c 69 74 65 33  .** Use [sqlite3
2b790 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28  _clear_bindings(
2b7a0 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65 20  )] to reset the 
2b7b0 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20  bindings..**.** 
2b7c0 7b 48 31 31 33 33 32 7d 20 54 68 65 20 5b 73 71  {H11332} The [sq
2b7d0 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20  lite3_reset(S)] 
2b7e0 69 6e 74 65 72 66 61 63 65 20 72 65 73 65 74 73  interface resets
2b7f0 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
2b800 74 61 74 65 6d 65 6e 74 5d 20 53 0a 2a 2a 20 20  tatement] S.**  
2b810 20 20 20 20 20 20 20 20 62 61 63 6b 20 74 6f 20          back to 
2b820 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66  the beginning of
2b830 20 69 74 73 20 70 72 6f 67 72 61 6d 2e 0a 2a 2a   its program..**
2b840 0a 2a 2a 20 7b 48 31 31 33 33 34 7d 20 49 66 20  .** {H11334} If 
2b850 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
2b860 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
2b870 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68  _step(S)] for th
2b880 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70  e.**          [p
2b890 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2b8a0 74 5d 20 53 20 72 65 74 75 72 6e 65 64 20 5b 53  t] S returned [S
2b8b0 51 4c 49 54 45 5f 52 4f 57 5d 20 6f 72 20 5b 53  QLITE_ROW] or [S
2b8c0 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20  QLITE_DONE],.** 
2b8d0 20 20 20 20 20 20 20 20 20 6f 72 20 69 66 20 5b           or if [
2b8e0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d  sqlite3_step(S)]
2b8f0 20 68 61 73 20 6e 65 76 65 72 20 62 65 66 6f 72   has never befor
2b900 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 6f 6e  e been called on
2b910 20 53 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   S,.**          
2b920 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65  then [sqlite3_re
2b930 73 65 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20  set(S)] returns 
2b940 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a  [SQLITE_OK]..**.
2b950 2a 2a 20 7b 48 31 31 33 33 36 7d 20 49 66 20 74  ** {H11336} If t
2b960 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63  he most recent c
2b970 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
2b980 73 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68 65  step(S)] for the
2b990 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72  .**          [pr
2b9a0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2b9b0 5d 20 53 20 69 6e 64 69 63 61 74 65 64 20 61 6e  ] S indicated an
2b9c0 20 65 72 72 6f 72 2c 20 74 68 65 6e 0a 2a 2a 20   error, then.** 
2b9d0 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
2b9e0 33 5f 72 65 73 65 74 28 53 29 5d 20 72 65 74 75  3_reset(S)] retu
2b9f0 72 6e 73 20 61 6e 20 61 70 70 72 6f 70 72 69 61  rns an appropria
2ba00 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e  te [error code].
2ba10 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 33 33 38 7d 20  .**.** {H11338} 
2ba20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  The [sqlite3_res
2ba30 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65  et(S)] interface
2ba40 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65   does not change
2ba50 20 74 68 65 20 76 61 6c 75 65 73 0a 2a 2a 20 20   the values.**  
2ba60 20 20 20 20 20 20 20 20 6f 66 20 61 6e 79 20 5b          of any [
2ba70 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
2ba80 62 7c 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 74  b|bindings] on t
2ba90 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
2baa0 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 69 6e  tement] S..*/.in
2bab0 74 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28  t sqlite3_reset(
2bac0 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
2bad0 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
2bae0 49 33 52 45 46 3a 20 43 72 65 61 74 65 20 4f 72  I3REF: Create Or
2baf0 20 52 65 64 65 66 69 6e 65 20 53 51 4c 20 46 75   Redefine SQL Fu
2bb00 6e 63 74 69 6f 6e 73 20 7b 48 31 36 31 30 30 7d  nctions {H16100}
2bb10 20 3c 53 32 30 32 30 30 3e 0a 2a 2a 20 4b 45 59   <S20200>.** KEY
2bb20 57 4f 52 44 53 3a 20 7b 66 75 6e 63 74 69 6f 6e  WORDS: {function
2bb30 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e   creation routin
2bb40 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  es}.** KEYWORDS:
2bb50 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65   {application-de
2bb60 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
2bb70 6f 6e 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  on}.** KEYWORDS:
2bb80 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65   {application-de
2bb90 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
2bba0 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ons}.**.** These
2bbb0 20 74 77 6f 20 66 75 6e 63 74 69 6f 6e 73 20 28   two functions (
2bbc0 63 6f 6c 6c 65 63 74 69 76 65 6c 79 20 6b 6e 6f  collectively kno
2bbd0 77 6e 20 61 73 20 22 66 75 6e 63 74 69 6f 6e 20  wn as "function 
2bbe0 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65  creation routine
2bbf0 73 22 29 0a 2a 2a 20 61 72 65 20 75 73 65 64 20  s").** are used 
2bc00 74 6f 20 61 64 64 20 53 51 4c 20 66 75 6e 63 74  to add SQL funct
2bc10 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74  ions or aggregat
2bc20 65 73 20 6f 72 20 74 6f 20 72 65 64 65 66 69 6e  es or to redefin
2bc30 65 20 74 68 65 20 62 65 68 61 76 69 6f 72 0a 2a  e the behavior.*
2bc40 2a 20 6f 66 20 65 78 69 73 74 69 6e 67 20 53 51  * of existing SQ
2bc50 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61  L functions or a
2bc60 67 67 72 65 67 61 74 65 73 2e 20 20 54 68 65 20  ggregates.  The 
2bc70 6f 6e 6c 79 20 64 69 66 66 65 72 65 6e 63 65 20  only difference 
2bc80 62 65 74 77 65 65 6e 20 74 68 65 0a 2a 2a 20 74  between the.** t
2bc90 77 6f 20 69 73 20 74 68 61 74 20 74 68 65 20 73  wo is that the s
2bca0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2c  econd parameter,
2bcb0 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
2bcc0 20 28 73 63 61 6c 61 72 29 20 66 75 6e 63 74 69   (scalar) functi
2bcd0 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61  on or.** aggrega
2bce0 74 65 2c 20 69 73 20 65 6e 63 6f 64 65 64 20 69  te, is encoded i
2bcf0 6e 20 55 54 46 2d 38 20 66 6f 72 20 73 71 6c 69  n UTF-8 for sqli
2bd00 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
2bd10 69 6f 6e 28 29 20 61 6e 64 20 55 54 46 2d 31 36  ion() and UTF-16
2bd20 0a 2a 2a 20 66 6f 72 20 73 71 6c 69 74 65 33 5f  .** for sqlite3_
2bd30 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31  create_function1
2bd40 36 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  6()..**.** The f
2bd50 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69  irst parameter i
2bd60 73 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  s the [database 
2bd70 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 77  connection] to w
2bd80 68 69 63 68 20 74 68 65 20 53 51 4c 0a 2a 2a 20  hich the SQL.** 
2bd90 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 6f 20 62  function is to b
2bda0 65 20 61 64 64 65 64 2e 20 20 49 66 20 61 20 73  e added.  If a s
2bdb0 69 6e 67 6c 65 20 70 72 6f 67 72 61 6d 20 75 73  ingle program us
2bdc0 65 73 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65  es more than one
2bdd0 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e   database.** con
2bde0 6e 65 63 74 69 6f 6e 20 69 6e 74 65 72 6e 61 6c  nection internal
2bdf0 6c 79 2c 20 74 68 65 6e 20 53 51 4c 20 66 75 6e  ly, then SQL fun
2be00 63 74 69 6f 6e 73 20 6d 75 73 74 20 62 65 20 61  ctions must be a
2be10 64 64 65 64 20 69 6e 64 69 76 69 64 75 61 6c 6c  dded individuall
2be20 79 20 74 6f 0a 2a 2a 20 65 61 63 68 20 64 61 74  y to.** each dat
2be30 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2be40 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f  ..**.** The seco
2be50 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  nd parameter is 
2be60 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
2be70 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  SQL function to 
2be80 62 65 20 63 72 65 61 74 65 64 20 6f 72 0a 2a 2a  be created or.**
2be90 20 72 65 64 65 66 69 6e 65 64 2e 20 20 54 68 65   redefined.  The
2bea0 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 6e   length of the n
2beb0 61 6d 65 20 69 73 20 6c 69 6d 69 74 65 64 20 74  ame is limited t
2bec0 6f 20 32 35 35 20 62 79 74 65 73 2c 20 65 78 63  o 255 bytes, exc
2bed0 6c 75 73 69 76 65 20 6f 66 0a 2a 2a 20 74 68 65  lusive of.** the
2bee0 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72   zero-terminator
2bef0 2e 20 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65  .  Note that the
2bf00 20 6e 61 6d 65 20 6c 65 6e 67 74 68 20 6c 69 6d   name length lim
2bf10 69 74 20 69 73 20 69 6e 20 62 79 74 65 73 2c 20  it is in bytes, 
2bf20 6e 6f 74 0a 2a 2a 20 63 68 61 72 61 63 74 65 72  not.** character
2bf30 73 2e 20 20 41 6e 79 20 61 74 74 65 6d 70 74 20  s.  Any attempt 
2bf40 74 6f 20 63 72 65 61 74 65 20 61 20 66 75 6e 63  to create a func
2bf50 74 69 6f 6e 20 77 69 74 68 20 61 20 6c 6f 6e 67  tion with a long
2bf60 65 72 20 6e 61 6d 65 0a 2a 2a 20 77 69 6c 6c 20  er name.** will 
2bf70 72 65 73 75 6c 74 20 69 6e 20 5b 53 51 4c 49 54  result in [SQLIT
2bf80 45 5f 45 52 52 4f 52 5d 20 62 65 69 6e 67 20 72  E_ERROR] being r
2bf90 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  eturned..**.** T
2bfa0 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
2bfb0 65 72 20 28 6e 41 72 67 29 0a 2a 2a 20 69 73 20  er (nArg).** is 
2bfc0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 61 72  the number of ar
2bfd0 67 75 6d 65 6e 74 73 20 74 68 61 74 20 74 68 65  guments that the
2bfe0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72   SQL function or
2bff0 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20 74 61  .** aggregate ta
2c000 6b 65 73 2e 20 49 66 20 74 68 69 73 20 70 61 72  kes. If this par
2c010 61 6d 65 74 65 72 20 69 73 20 6e 65 67 61 74 69  ameter is negati
2c020 76 65 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c  ve, then the SQL
2c030 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20   function or.** 
2c040 61 67 67 72 65 67 61 74 65 20 6d 61 79 20 74 61  aggregate may ta
2c050 6b 65 20 61 6e 79 20 6e 75 6d 62 65 72 20 6f 66  ke any number of
2c060 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a   arguments..**.*
2c070 2a 20 54 68 65 20 66 6f 75 72 74 68 20 70 61 72  * The fourth par
2c080 61 6d 65 74 65 72 2c 20 65 54 65 78 74 52 65 70  ameter, eTextRep
2c090 2c 20 73 70 65 63 69 66 69 65 73 20 77 68 61 74  , specifies what
2c0a0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 38  .** [SQLITE_UTF8
2c0b0 20 7c 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67   | text encoding
2c0c0 5d 20 74 68 69 73 20 53 51 4c 20 66 75 6e 63 74  ] this SQL funct
2c0d0 69 6f 6e 20 70 72 65 66 65 72 73 20 66 6f 72 0a  ion prefers for.
2c0e0 2a 2a 20 69 74 73 20 70 61 72 61 6d 65 74 65 72  ** its parameter
2c0f0 73 2e 20 20 41 6e 79 20 53 51 4c 20 66 75 6e 63  s.  Any SQL func
2c100 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74  tion implementat
2c110 69 6f 6e 20 73 68 6f 75 6c 64 20 62 65 20 61 62  ion should be ab
2c120 6c 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77 6f  le to work.** wo
2c130 72 6b 20 77 69 74 68 20 55 54 46 2d 38 2c 20 55  rk with UTF-8, U
2c140 54 46 2d 31 36 6c 65 2c 20 6f 72 20 55 54 46 2d  TF-16le, or UTF-
2c150 31 36 62 65 2e 20 20 42 75 74 20 73 6f 6d 65 20  16be.  But some 
2c160 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
2c170 6d 61 79 20 62 65 0a 2a 2a 20 6d 6f 72 65 20 65  may be.** more e
2c180 66 66 69 63 69 65 6e 74 20 77 69 74 68 20 6f 6e  fficient with on
2c190 65 20 65 6e 63 6f 64 69 6e 67 20 74 68 61 6e 20  e encoding than 
2c1a0 61 6e 6f 74 68 65 72 2e 20 20 49 74 20 69 73 20  another.  It is 
2c1b0 61 6c 6c 6f 77 65 64 20 74 6f 0a 2a 2a 20 69 6e  allowed to.** in
2c1c0 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63 72 65  voke sqlite3_cre
2c1d0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 20 6f  ate_function() o
2c1e0 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  r sqlite3_create
2c1f0 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 20 6d 75  _function16() mu
2c200 6c 74 69 70 6c 65 0a 2a 2a 20 74 69 6d 65 73 20  ltiple.** times 
2c210 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 66 75  with the same fu
2c220 6e 63 74 69 6f 6e 20 62 75 74 20 77 69 74 68 20  nction but with 
2c230 64 69 66 66 65 72 65 6e 74 20 76 61 6c 75 65 73  different values
2c240 20 6f 66 20 65 54 65 78 74 52 65 70 2e 0a 2a 2a   of eTextRep..**
2c250 20 57 68 65 6e 20 6d 75 6c 74 69 70 6c 65 20 69   When multiple i
2c260 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f  mplementations o
2c270 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74  f the same funct
2c280 69 6f 6e 20 61 72 65 20 61 76 61 69 6c 61 62 6c  ion are availabl
2c290 65 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c  e, SQLite.** wil
2c2a0 6c 20 70 69 63 6b 20 74 68 65 20 6f 6e 65 20 74  l pick the one t
2c2b0 68 61 74 20 69 6e 76 6f 6c 76 65 73 20 74 68 65  hat involves the
2c2c0 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66   least amount of
2c2d0 20 64 61 74 61 20 63 6f 6e 76 65 72 73 69 6f 6e   data conversion
2c2e0 2e 0a 2a 2a 20 49 66 20 74 68 65 72 65 20 69 73  ..** If there is
2c2f0 20 6f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 69   only a single i
2c300 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 68  mplementation wh
2c310 69 63 68 20 64 6f 65 73 20 6e 6f 74 20 63 61 72  ich does not car
2c320 65 20 77 68 61 74 20 74 65 78 74 0a 2a 2a 20 65  e what text.** e
2c330 6e 63 6f 64 69 6e 67 20 69 73 20 75 73 65 64 2c  ncoding is used,
2c340 20 74 68 65 6e 20 74 68 65 20 66 6f 75 72 74 68   then the fourth
2c350 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64   argument should
2c360 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 4e 59 5d   be [SQLITE_ANY]
2c370 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 66 74  ..**.** The fift
2c380 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  h parameter is a
2c390 6e 20 61 72 62 69 74 72 61 72 79 20 70 6f 69 6e  n arbitrary poin
2c3a0 74 65 72 2e 20 20 54 68 65 20 69 6d 70 6c 65 6d  ter.  The implem
2c3b0 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 0a  entation of the.
2c3c0 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20  ** function can 
2c3d0 67 61 69 6e 20 61 63 63 65 73 73 20 74 6f 20 74  gain access to t
2c3e0 68 69 73 20 70 6f 69 6e 74 65 72 20 75 73 69 6e  his pointer usin
2c3f0 67 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f  g [sqlite3_user_
2c400 64 61 74 61 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54  data()]..**.** T
2c410 68 65 20 73 65 76 65 6e 74 68 2c 20 65 69 67 68  he seventh, eigh
2c420 74 68 20 61 6e 64 20 6e 69 6e 74 68 20 70 61 72  th and ninth par
2c430 61 6d 65 74 65 72 73 2c 20 78 46 75 6e 63 2c 20  ameters, xFunc, 
2c440 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61 6c  xStep and xFinal
2c450 2c 20 61 72 65 0a 2a 2a 20 70 6f 69 6e 74 65 72  , are.** pointer
2c460 73 20 74 6f 20 43 2d 6c 61 6e 67 75 61 67 65 20  s to C-language 
2c470 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 69  functions that i
2c480 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c  mplement the SQL
2c490 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20   function or.** 
2c4a0 61 67 67 72 65 67 61 74 65 2e 20 41 20 73 63 61  aggregate. A sca
2c4b0 6c 61 72 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  lar SQL function
2c4c0 20 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d 70   requires an imp
2c4d0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74  lementation of t
2c4e0 68 65 20 78 46 75 6e 63 0a 2a 2a 20 63 61 6c 6c  he xFunc.** call
2c4f0 62 61 63 6b 20 6f 6e 6c 79 2c 20 4e 55 4c 4c 20  back only, NULL 
2c500 70 6f 69 6e 74 65 72 73 20 73 68 6f 75 6c 64 20  pointers should 
2c510 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65  be passed as the
2c520 20 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61   xStep and xFina
2c530 6c 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 2e  l.** parameters.
2c540 20 41 6e 20 61 67 67 72 65 67 61 74 65 20 53 51   An aggregate SQ
2c550 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69  L function requi
2c560 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74  res an implement
2c570 61 74 69 6f 6e 20 6f 66 20 78 53 74 65 70 0a 2a  ation of xStep.*
2c580 2a 20 61 6e 64 20 78 46 69 6e 61 6c 20 61 6e 64  * and xFinal and
2c590 20 4e 55 4c 4c 20 73 68 6f 75 6c 64 20 62 65 20   NULL should be 
2c5a0 70 61 73 73 65 64 20 66 6f 72 20 78 46 75 6e 63  passed for xFunc
2c5b0 2e 20 54 6f 20 64 65 6c 65 74 65 20 61 6e 20 65  . To delete an e
2c5c0 78 69 73 74 69 6e 67 0a 2a 2a 20 53 51 4c 20 66  xisting.** SQL f
2c5d0 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65  unction or aggre
2c5e0 67 61 74 65 2c 20 70 61 73 73 20 4e 55 4c 4c 20  gate, pass NULL 
2c5f0 66 6f 72 20 61 6c 6c 20 74 68 72 65 65 20 66 75  for all three fu
2c600 6e 63 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 73  nction callbacks
2c610 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73 20 70 65  ..**.** It is pe
2c620 72 6d 69 74 74 65 64 20 74 6f 20 72 65 67 69 73  rmitted to regis
2c630 74 65 72 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70  ter multiple imp
2c640 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20  lementations of 
2c650 74 68 65 20 73 61 6d 65 0a 2a 2a 20 66 75 6e 63  the same.** func
2c660 74 69 6f 6e 73 20 77 69 74 68 20 74 68 65 20 73  tions with the s
2c670 61 6d 65 20 6e 61 6d 65 20 62 75 74 20 77 69 74  ame name but wit
2c680 68 20 65 69 74 68 65 72 20 64 69 66 66 65 72 69  h either differi
2c690 6e 67 20 6e 75 6d 62 65 72 73 20 6f 66 0a 2a 2a  ng numbers of.**
2c6a0 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 64 69   arguments or di
2c6b0 66 66 65 72 69 6e 67 20 70 72 65 66 65 72 72 65  ffering preferre
2c6c0 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73  d text encodings
2c6d0 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75  .  SQLite will u
2c6e0 73 65 0a 2a 2a 20 74 68 65 20 69 6d 70 6c 65 6d  se.** the implem
2c6f0 65 6e 74 61 74 69 6f 6e 20 6d 6f 73 74 20 63 6c  entation most cl
2c700 6f 73 65 6c 79 20 6d 61 74 63 68 65 73 20 74 68  osely matches th
2c710 65 20 77 61 79 20 69 6e 20 77 68 69 63 68 20 74  e way in which t
2c720 68 65 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69  he.** SQL functi
2c730 6f 6e 20 69 73 20 75 73 65 64 2e 20 20 41 20 66  on is used.  A f
2c740 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e  unction implemen
2c750 74 61 74 69 6f 6e 20 77 69 74 68 20 61 20 6e 6f  tation with a no
2c760 6e 2d 6e 65 67 61 74 69 76 65 0a 2a 2a 20 6e 41  n-negative.** nA
2c770 72 67 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  rg parameter is 
2c780 61 20 62 65 74 74 65 72 20 6d 61 74 63 68 20 74  a better match t
2c790 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 69  han a function i
2c7a0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69  mplementation wi
2c7b0 74 68 0a 2a 2a 20 61 20 6e 65 67 61 74 69 76 65  th.** a negative
2c7c0 20 6e 41 72 67 2e 20 20 41 20 66 75 6e 63 74 69   nArg.  A functi
2c7d0 6f 6e 20 77 68 65 72 65 20 74 68 65 20 70 72 65  on where the pre
2c7e0 66 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f  ferred text enco
2c7f0 64 69 6e 67 0a 2a 2a 20 6d 61 74 63 68 65 73 20  ding.** matches 
2c800 74 68 65 20 64 61 74 61 62 61 73 65 20 65 6e 63  the database enc
2c810 6f 64 69 6e 67 20 69 73 20 61 20 62 65 74 74 65  oding is a bette
2c820 72 0a 2a 2a 20 6d 61 74 63 68 20 74 68 61 6e 20  r.** match than 
2c830 61 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65  a function where
2c840 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 69 73   the encoding is
2c850 20 64 69 66 66 65 72 65 6e 74 2e 20 20 0a 2a 2a   different.  .**
2c860 20 41 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72   A function wher
2c870 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 64  e the encoding d
2c880 69 66 66 65 72 65 6e 63 65 20 69 73 20 62 65 74  ifference is bet
2c890 77 65 65 6e 20 55 54 46 31 36 6c 65 20 61 6e 64  ween UTF16le and
2c8a0 20 55 54 46 31 36 62 65 0a 2a 2a 20 69 73 20 61   UTF16be.** is a
2c8b0 20 63 6c 6f 73 65 72 20 6d 61 74 63 68 20 74 68   closer match th
2c8c0 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 68  an a function wh
2c8d0 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67  ere the encoding
2c8e0 20 64 69 66 66 65 72 65 6e 63 65 20 69 73 0a 2a   difference is.*
2c8f0 2a 20 62 65 74 77 65 65 6e 20 55 54 46 38 20 61  * between UTF8 a
2c900 6e 64 20 55 54 46 31 36 2e 0a 2a 2a 0a 2a 2a 20  nd UTF16..**.** 
2c910 42 75 69 6c 74 2d 69 6e 20 66 75 6e 63 74 69 6f  Built-in functio
2c920 6e 73 20 6d 61 79 20 62 65 20 6f 76 65 72 6c 6f  ns may be overlo
2c930 61 64 65 64 20 62 79 20 6e 65 77 20 61 70 70 6c  aded by new appl
2c940 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
2c950 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 20 54 68  functions..** Th
2c960 65 20 66 69 72 73 74 20 61 70 70 6c 69 63 61 74  e first applicat
2c970 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
2c980 74 69 6f 6e 20 77 69 74 68 20 61 20 67 69 76 65  tion with a give
2c990 6e 20 6e 61 6d 65 20 6f 76 65 72 72 69 64 65 73  n name overrides
2c9a0 20 61 6c 6c 0a 2a 2a 20 62 75 69 6c 74 2d 69 6e   all.** built-in
2c9b0 20 66 75 6e 63 74 69 6f 6e 73 20 69 6e 20 74 68   functions in th
2c9c0 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65  e same [database
2c9d0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 69 74   connection] wit
2c9e0 68 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 2e  h the same name.
2c9f0 0a 2a 2a 20 53 75 62 73 65 71 75 65 6e 74 20 61  .** Subsequent a
2ca00 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
2ca10 65 64 20 66 75 6e 63 74 69 6f 6e 73 20 6f 66 20  ed functions of 
2ca20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 6f 6e  the same name on
2ca30 6c 79 20 6f 76 65 72 72 69 64 65 20 0a 2a 2a 20  ly override .** 
2ca40 70 72 69 6f 72 20 61 70 70 6c 69 63 61 74 69 6f  prior applicatio
2ca50 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
2ca60 6f 6e 73 20 74 68 61 74 20 61 72 65 20 61 6e 20  ons that are an 
2ca70 65 78 61 63 74 20 6d 61 74 63 68 20 66 6f 72 20  exact match for 
2ca80 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66  the.** number of
2ca90 20 70 61 72 61 6d 65 74 65 72 73 20 61 6e 64 20   parameters and 
2caa0 70 72 65 66 65 72 72 65 64 20 65 6e 63 6f 64 69  preferred encodi
2cab0 6e 67 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 70 70  ng..**.** An app
2cac0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
2cad0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 70 65 72   function is per
2cae0 6d 69 74 74 65 64 20 74 6f 20 63 61 6c 6c 20 6f  mitted to call o
2caf0 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69  ther.** SQLite i
2cb00 6e 74 65 72 66 61 63 65 73 2e 20 20 48 6f 77 65  nterfaces.  Howe
2cb10 76 65 72 2c 20 73 75 63 68 20 63 61 6c 6c 73 20  ver, such calls 
2cb20 6d 75 73 74 20 6e 6f 74 0a 2a 2a 20 63 6c 6f 73  must not.** clos
2cb30 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  e the database c
2cb40 6f 6e 6e 65 63 74 69 6f 6e 20 6e 6f 72 20 66 69  onnection nor fi
2cb50 6e 61 6c 69 7a 65 20 6f 72 20 72 65 73 65 74 20  nalize or reset 
2cb60 74 68 65 20 70 72 65 70 61 72 65 64 0a 2a 2a 20  the prepared.** 
2cb70 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 77 68 69  statement in whi
2cb80 63 68 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  ch the function 
2cb90 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 0a 2a  is running..**.*
2cba0 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
2cbb0 0a 2a 2a 20 7b 48 31 36 31 30 33 7d 20 54 68 65  .** {H16103} The
2cbc0 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
2cbd0 5f 66 75 6e 63 74 69 6f 6e 31 36 28 44 2c 58 2c  _function16(D,X,
2cbe0 2e 2e 2e 29 5d 20 69 6e 74 65 72 66 61 63 65 20  ...)] interface 
2cbf0 73 68 61 6c 6c 20 62 65 68 61 76 65 0a 2a 2a 20  shall behave.** 
2cc00 20 20 20 20 20 20 20 20 20 61 73 20 5b 73 71 6c           as [sql
2cc10 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
2cc20 74 69 6f 6e 28 44 2c 58 2c 2e 2e 2e 29 5d 20 69  tion(D,X,...)] i
2cc30 6e 20 65 76 65 72 79 20 77 61 79 20 65 78 63 65  n every way exce
2cc40 70 74 20 74 68 61 74 20 69 74 0a 2a 2a 20 20 20  pt that it.**   
2cc50 20 20 20 20 20 20 20 69 6e 74 65 72 70 72 65 74         interpret
2cc60 73 20 74 68 65 20 58 20 61 72 67 75 6d 65 6e 74  s the X argument
2cc70 20 61 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61   as zero-termina
2cc80 74 65 64 20 55 54 46 2d 31 36 0a 2a 2a 20 20 20  ted UTF-16.**   
2cc90 20 20 20 20 20 20 20 6e 61 74 69 76 65 20 62 79         native by
2cca0 74 65 20 6f 72 64 65 72 20 69 6e 73 74 65 61 64  te order instead
2ccb0 20 6f 66 20 61 73 20 7a 65 72 6f 2d 74 65 72 6d   of as zero-term
2ccc0 69 6e 61 74 65 64 20 55 54 46 2d 38 2e 0a 2a 2a  inated UTF-8..**
2ccd0 0a 2a 2a 20 7b 48 31 36 31 30 36 7d 20 41 20 73  .** {H16106} A s
2cce0 75 63 63 65 73 73 66 75 6c 20 69 6e 76 6f 63 61  uccessful invoca
2ccf0 74 69 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 20  tion of the.**  
2cd00 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
2cd10 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
2cd20 28 44 2c 58 2c 4e 2c 45 2c 2e 2e 2e 29 5d 20 69  (D,X,N,E,...)] i
2cd30 6e 74 65 72 66 61 63 65 20 73 68 61 6c 6c 20 72  nterface shall r
2cd40 65 67 69 73 74 65 72 0a 2a 2a 20 20 20 20 20 20  egister.**      
2cd50 20 20 20 20 6f 72 20 72 65 70 6c 61 63 65 73 20      or replaces 
2cd60 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
2cd70 6e 73 20 69 6e 20 74 68 65 20 5b 64 61 74 61 62  ns in the [datab
2cd80 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
2cd90 44 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 75 73  D.**          us
2cda0 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20  ed to implement 
2cdb0 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
2cdc0 20 6e 61 6d 65 64 20 58 20 77 69 74 68 20 4e 20   named X with N 
2cdd0 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 20 20  parameters.**   
2cde0 20 20 20 20 20 20 20 61 6e 64 20 68 61 76 69 6e         and havin
2cdf0 67 20 61 20 70 72 65 66 65 72 72 65 64 20 74 65  g a preferred te
2ce00 78 74 20 65 6e 63 6f 64 69 6e 67 20 6f 66 20 45  xt encoding of E
2ce10 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 31 30 39 7d  ..**.** {H16109}
2ce20 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 63 61   A successful ca
2ce30 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ll to [sqlite3_c
2ce40 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44  reate_function(D
2ce50 2c 58 2c 4e 2c 45 2c 50 2c 46 2c 53 2c 4c 29 5d  ,X,N,E,P,F,S,L)]
2ce60 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 68 61  .**          sha
2ce70 6c 6c 20 72 65 70 6c 61 63 65 20 74 68 65 20 50  ll replace the P
2ce80 2c 20 46 2c 20 53 2c 20 61 6e 64 20 4c 20 76 61  , F, S, and L va
2ce90 6c 75 65 73 20 66 72 6f 6d 20 61 6e 79 20 70 72  lues from any pr
2cea0 69 6f 72 20 63 61 6c 6c 73 20 77 69 74 68 0a 2a  ior calls with.*
2ceb0 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 73  *          the s
2cec0 61 6d 65 20 44 2c 20 58 2c 20 4e 2c 20 61 6e 64  ame D, X, N, and
2ced0 20 45 20 76 61 6c 75 65 73 2e 0a 2a 2a 0a 2a 2a   E values..**.**
2cee0 20 7b 48 31 36 31 31 32 7d 20 54 68 65 20 5b 73   {H16112} The [s
2cef0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
2cf00 6e 63 74 69 6f 6e 28 44 2c 58 2c 2e 2e 2e 29 5d  nction(D,X,...)]
2cf10 20 69 6e 74 65 72 66 61 63 65 20 73 68 61 6c 6c   interface shall
2cf20 20 66 61 69 6c 0a 2a 2a 20 20 20 20 20 20 20 20   fail.**        
2cf30 20 20 69 66 20 74 68 65 20 53 51 4c 20 66 75 6e    if the SQL fun
2cf40 63 74 69 6f 6e 20 6e 61 6d 65 20 58 20 69 73 0a  ction name X is.
2cf50 2a 2a 20 20 20 20 20 20 20 20 20 20 6c 6f 6e 67  **          long
2cf60 65 72 20 74 68 61 6e 20 32 35 35 20 62 79 74 65  er than 255 byte
2cf70 73 20 65 78 63 6c 75 73 69 76 65 20 6f 66 20 74  s exclusive of t
2cf80 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74  he zero terminat
2cf90 6f 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 31 31  or..**.** {H1611
2cfa0 38 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  8} The [sqlite3_
2cfb0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
2cfc0 44 2c 58 2c 4e 2c 45 2c 50 2c 46 2c 53 2c 4c 29  D,X,N,E,P,F,S,L)
2cfd0 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 20  ] interface.**  
2cfe0 20 20 20 20 20 20 20 20 73 68 61 6c 6c 20 66 61          shall fa
2cff0 69 6c 20 75 6e 6c 65 73 73 20 65 69 74 68 65 72  il unless either
2d000 20 46 20 69 73 20 4e 55 4c 4c 20 61 6e 64 20 53   F is NULL and S
2d010 20 61 6e 64 20 4c 20 61 72 65 20 6e 6f 6e 2d 4e   and L are non-N
2d020 55 4c 4c 20 6f 72 0a 2a 2a 2a 20 20 20 20 20 20  ULL or.***      
2d030 20 20 20 46 20 69 73 20 6e 6f 6e 2d 4e 55 4c 4c     F is non-NULL
2d040 20 61 6e 64 20 53 20 61 6e 64 20 4c 20 61 72 65   and S and L are
2d050 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31   NULL..**.** {H1
2d060 36 31 32 31 7d 20 54 68 65 20 5b 73 71 6c 69 74  6121} The [sqlit
2d070 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
2d080 6f 6e 28 44 2c 2e 2e 2e 29 5d 20 69 6e 74 65 72  on(D,...)] inter
2d090 66 61 63 65 20 73 68 61 6c 6c 20 66 61 69 6c 73  face shall fails
2d0a0 20 77 69 74 68 20 61 6e 0a 2a 2a 20 20 20 20 20   with an.**     
2d0b0 20 20 20 20 20 65 72 72 6f 72 20 63 6f 64 65 20       error code 
2d0c0 6f 66 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  of [SQLITE_BUSY]
2d0d0 20 69 66 20 74 68 65 72 65 20 65 78 69 73 74 20   if there exist 
2d0e0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2d0f0 65 6e 74 73 5d 0a 2a 2a 20 20 20 20 20 20 20 20  ents].**        
2d100 20 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74    associated wit
2d110 68 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  h the [database 
2d120 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2e 0a 2a  connection] D..*
2d130 2a 0a 2a 2a 20 7b 48 31 36 31 32 34 7d 20 54 68  *.** {H16124} Th
2d140 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  e [sqlite3_creat
2d150 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e  e_function(D,X,N
2d160 2c 2e 2e 2e 29 5d 20 69 6e 74 65 72 66 61 63 65  ,...)] interface
2d170 20 73 68 61 6c 6c 20 66 61 69 6c 20 77 69 74 68   shall fail with
2d180 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6e 20  .**          an 
2d190 65 72 72 6f 72 20 63 6f 64 65 20 6f 66 20 5b 53  error code of [S
2d1a0 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20  QLITE_ERROR] if 
2d1b0 70 61 72 61 6d 65 74 65 72 20 4e 20 69 73 20 6c  parameter N is l
2d1c0 65 73 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ess.**          
2d1d0 74 68 61 6e 20 2d 31 20 6f 72 20 67 72 65 61 74  than -1 or great
2d1e0 65 72 20 74 68 61 6e 20 31 32 37 2e 0a 2a 2a 0a  er than 127..**.
2d1f0 2a 2a 20 7b 48 31 36 31 32 37 7d 20 57 68 65 6e  ** {H16127} When
2d200 20 4e 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69   N is non-negati
2d210 76 65 2c 20 74 68 65 20 5b 73 71 6c 69 74 65 33  ve, the [sqlite3
2d220 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
2d230 28 44 2c 58 2c 4e 2c 2e 2e 2e 29 5d 0a 2a 2a 20  (D,X,N,...)].** 
2d240 20 20 20 20 20 20 20 20 20 69 6e 74 65 72 66 61           interfa
2d250 63 65 20 73 68 61 6c 6c 20 72 65 67 69 73 74 65  ce shall registe
2d260 72 20 63 61 6c 6c 62 61 63 6b 73 20 74 6f 20 62  r callbacks to b
2d270 65 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20 74 68  e invoked for th
2d280 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 53 51  e.**          SQ
2d290 4c 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 20 20  L function.**   
2d2a0 20 20 20 20 20 20 20 6e 61 6d 65 64 20 58 20 77         named X w
2d2b0 68 65 6e 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  hen the number o
2d2c0 66 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74  f arguments to t
2d2d0 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
2d2e0 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 65  is.**          e
2d2f0 78 61 63 74 6c 79 20 4e 2e 0a 2a 2a 0a 2a 2a 20  xactly N..**.** 
2d300 7b 48 31 36 31 33 30 7d 20 57 68 65 6e 20 4e 20  {H16130} When N 
2d310 69 73 20 2d 31 2c 20 74 68 65 20 5b 73 71 6c 69  is -1, the [sqli
2d320 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
2d330 69 6f 6e 28 44 2c 58 2c 4e 2c 2e 2e 2e 29 5d 0a  ion(D,X,N,...)].
2d340 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74 65  **          inte
2d350 72 66 61 63 65 20 73 68 61 6c 6c 20 72 65 67 69  rface shall regi
2d360 73 74 65 72 20 63 61 6c 6c 62 61 63 6b 73 20 74  ster callbacks t
2d370 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 66 6f 72  o be invoked for
2d380 20 74 68 65 20 53 51 4c 0a 2a 2a 20 20 20 20 20   the SQL.**     
2d390 20 20 20 20 20 66 75 6e 63 74 69 6f 6e 20 6e 61       function na
2d3a0 6d 65 64 20 58 20 77 69 74 68 20 61 6e 79 20 6e  med X with any n
2d3b0 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e  umber of argumen
2d3c0 74 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 31 33  ts..**.** {H1613
2d3d0 33 7d 20 57 68 65 6e 20 63 61 6c 6c 73 20 74 6f  3} When calls to
2d3e0 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
2d3f0 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c  _function(D,X,N,
2d400 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20  ...)].**        
2d410 20 20 73 70 65 63 69 66 79 20 6d 75 6c 74 69 70    specify multip
2d420 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  le implementatio
2d430 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66  ns of the same f
2d440 75 6e 63 74 69 6f 6e 20 58 0a 2a 2a 20 20 20 20  unction X.**    
2d450 20 20 20 20 20 20 61 6e 64 20 77 68 65 6e 20 6f        and when o
2d460 6e 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ne implementatio
2d470 6e 20 68 61 73 20 4e 3e 3d 30 20 61 6e 64 20 74  n has N>=0 and t
2d480 68 65 20 6f 74 68 65 72 20 68 61 73 20 4e 3d 28  he other has N=(
2d490 2d 31 29 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  -1).**          
2d4a0 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  the implementati
2d4b0 6f 6e 20 77 69 74 68 20 61 20 6e 6f 6e 2d 7a 65  on with a non-ze
2d4c0 72 6f 20 4e 20 73 68 61 6c 6c 20 62 65 20 70 72  ro N shall be pr
2d4d0 65 66 65 72 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b  eferred..**.** {
2d4e0 48 31 36 31 33 36 7d 20 57 68 65 6e 20 63 61 6c  H16136} When cal
2d4f0 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ls to [sqlite3_c
2d500 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44  reate_function(D
2d510 2c 58 2c 4e 2c 45 2c 2e 2e 2e 29 5d 0a 2a 2a 20  ,X,N,E,...)].** 
2d520 20 20 20 20 20 20 20 20 20 73 70 65 63 69 66 79           specify
2d530 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d   multiple implem
2d540 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65  entations of the
2d550 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 58   same function X
2d560 20 77 69 74 68 0a 2a 2a 20 20 20 20 20 20 20 20   with.**        
2d570 20 20 74 68 65 20 73 61 6d 65 20 6e 75 6d 62 65    the same numbe
2d580 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 4e  r of arguments N
2d590 20 62 75 74 20 77 69 74 68 20 64 69 66 66 65 72   but with differ
2d5a0 65 6e 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ent.**          
2d5b0 65 6e 63 6f 64 69 6e 67 73 20 45 2c 20 74 68 65  encodings E, the
2d5c0 6e 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  n the implementa
2d5d0 74 69 6f 6e 20 77 68 65 72 65 20 45 20 6d 61 74  tion where E mat
2d5e0 63 68 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 20  ches the.**     
2d5f0 20 20 20 20 20 64 61 74 61 62 61 73 65 20 65 6e       database en
2d600 63 6f 64 69 6e 67 20 73 68 61 6c 6c 20 70 72 65  coding shall pre
2d610 66 65 72 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48  ferred..**.** {H
2d620 31 36 31 33 39 7d 20 46 6f 72 20 61 6e 20 61 67  16139} For an ag
2d630 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63  gregate SQL func
2d640 74 69 6f 6e 20 63 72 65 61 74 65 64 20 75 73 69  tion created usi
2d650 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  ng.**          [
2d660 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
2d670 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 45 2c  unction(D,X,N,E,
2d680 50 2c 30 2c 53 2c 4c 29 5d 20 74 68 65 20 66 69  P,0,S,L)] the fi
2d690 6e 61 6c 69 7a 65 72 0a 2a 2a 20 20 20 20 20 20  nalizer.**      
2d6a0 20 20 20 20 66 75 6e 63 74 69 6f 6e 20 4c 20 73      function L s
2d6b0 68 61 6c 6c 20 61 6c 77 61 79 73 20 62 65 20 69  hall always be i
2d6c0 6e 76 6f 6b 65 64 20 65 78 61 63 74 6c 79 20 6f  nvoked exactly o
2d6d0 6e 63 65 20 69 66 20 74 68 65 0a 2a 2a 20 20 20  nce if the.**   
2d6e0 20 20 20 20 20 20 20 73 74 65 70 20 66 75 6e 63         step func
2d6f0 74 69 6f 6e 20 53 20 69 73 20 63 61 6c 6c 65 64  tion S is called
2d700 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d   one or more tim
2d710 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 31 34  es..**.** {H1614
2d720 32 7d 20 57 68 65 6e 20 53 51 4c 69 74 65 20 69  2} When SQLite i
2d730 6e 76 6f 6b 65 73 20 65 69 74 68 65 72 20 74 68  nvokes either th
2d740 65 20 78 46 75 6e 63 20 6f 72 20 78 53 74 65 70  e xFunc or xStep
2d750 20 66 75 6e 63 74 69 6f 6e 20 6f 66 0a 2a 2a 20   function of.** 
2d760 20 20 20 20 20 20 20 20 20 61 6e 20 61 70 70 6c           an appl
2d770 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
2d780 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20  SQL function or 
2d790 61 67 67 72 65 67 61 74 65 20 63 72 65 61 74 65  aggregate create
2d7a0 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 79  d.**          by
2d7b0 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
2d7c0 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 6f 72 20  _function()] or 
2d7d0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
2d7e0 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 2c 0a 2a  function16()],.*
2d7f0 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 6e 20  *          then 
2d800 74 68 65 20 61 72 72 61 79 20 6f 66 20 5b 73 71  the array of [sq
2d810 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
2d820 65 63 74 73 20 70 61 73 73 65 64 20 61 73 20 74  ects passed as t
2d830 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  he.**          t
2d840 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 73  hird parameter s
2d850 68 61 6c 6c 20 62 65 20 5b 70 72 6f 74 65 63 74  hall be [protect
2d860 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
2d870 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2f 0a 69 6e  ] objects..*/.in
2d880 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  t sqlite3_create
2d890 5f 66 75 6e 63 74 69 6f 6e 28 0a 20 20 73 71 6c  _function(.  sql
2d8a0 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73  ite3 *db,.  cons
2d8b0 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f  t char *zFunctio
2d8c0 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72  nName,.  int nAr
2d8d0 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65  g,.  int eTextRe
2d8e0 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c  p,.  void *pApp,
2d8f0 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29  .  void (*xFunc)
2d900 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
2d910 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61  *,int,sqlite3_va
2d920 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28  lue**),.  void (
2d930 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f  *xStep)(sqlite3_
2d940 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c  context*,int,sql
2d950 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20  ite3_value**),. 
2d960 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28   void (*xFinal)(
2d970 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
2d980 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ).);.int sqlite3
2d990 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
2d9a0 31 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  16(.  sqlite3 *d
2d9b0 62 2c 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  b,.  const void 
2d9c0 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a  *zFunctionName,.
2d9d0 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e    int nArg,.  in
2d9e0 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f  t eTextRep,.  vo
2d9f0 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64  id *pApp,.  void
2da00 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65   (*xFunc)(sqlite
2da10 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73  3_context*,int,s
2da20 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c  qlite3_value**),
2da30 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29  .  void (*xStep)
2da40 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
2da50 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61  *,int,sqlite3_va
2da60 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28  lue**),.  void (
2da70 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33  *xFinal)(sqlite3
2da80 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 0a 2f  _context*).);../
2da90 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54  *.** CAPI3REF: T
2daa0 65 78 74 20 45 6e 63 6f 64 69 6e 67 73 20 7b 48  ext Encodings {H
2dab0 31 30 32 36 37 7d 20 3c 53 35 30 32 30 30 3e 20  10267} <S50200> 
2dac0 3c 48 31 36 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 54  <H16100>.**.** T
2dad0 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 20 64 65  hese constant de
2dae0 66 69 6e 65 20 69 6e 74 65 67 65 72 20 63 6f 64  fine integer cod
2daf0 65 73 20 74 68 61 74 20 72 65 70 72 65 73 65 6e  es that represen
2db00 74 20 74 68 65 20 76 61 72 69 6f 75 73 0a 2a 2a  t the various.**
2db10 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 20   text encodings 
2db20 73 75 70 70 6f 72 74 65 64 20 62 79 20 53 51 4c  supported by SQL
2db30 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ite..*/.#define 
2db40 53 51 4c 49 54 45 5f 55 54 46 38 20 20 20 20 20  SQLITE_UTF8     
2db50 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20        1.#define 
2db60 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 20 20  SQLITE_UTF16LE  
2db70 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20        2.#define 
2db80 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 20 20  SQLITE_UTF16BE  
2db90 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20        3.#define 
2dba0 53 51 4c 49 54 45 5f 55 54 46 31 36 20 20 20 20  SQLITE_UTF16    
2dbb0 20 20 20 20 20 20 34 20 20 20 20 2f 2a 20 55 73        4    /* Us
2dbc0 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  e native byte or
2dbd0 64 65 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  der */.#define S
2dbe0 51 4c 49 54 45 5f 41 4e 59 20 20 20 20 20 20 20  QLITE_ANY       
2dbf0 20 20 20 20 20 35 20 20 20 20 2f 2a 20 73 71 6c       5    /* sql
2dc00 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
2dc10 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65  tion only */.#de
2dc20 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31  fine SQLITE_UTF1
2dc30 36 5f 41 4c 49 47 4e 45 44 20 20 38 20 20 20 20  6_ALIGNED  8    
2dc40 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  /* sqlite3_creat
2dc50 65 5f 63 6f 6c 6c 61 74 69 6f 6e 20 6f 6e 6c 79  e_collation only
2dc60 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   */../*.** CAPI3
2dc70 52 45 46 3a 20 44 65 70 72 65 63 61 74 65 64 20  REF: Deprecated 
2dc80 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 44 45 50  Functions.** DEP
2dc90 52 45 43 41 54 45 44 0a 2a 2a 0a 2a 2a 20 54 68  RECATED.**.** Th
2dca0 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 72  ese functions ar
2dcb0 65 20 5b 64 65 70 72 65 63 61 74 65 64 5d 2e 20  e [deprecated]. 
2dcc0 20 49 6e 20 6f 72 64 65 72 20 74 6f 20 6d 61 69   In order to mai
2dcd0 6e 74 61 69 6e 0a 2a 2a 20 62 61 63 6b 77 61 72  ntain.** backwar
2dce0 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ds compatibility
2dcf0 20 77 69 74 68 20 6f 6c 64 65 72 20 63 6f 64 65   with older code
2dd00 2c 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  , these function
2dd10 73 20 63 6f 6e 74 69 6e 75 65 20 0a 2a 2a 20 74  s continue .** t
2dd20 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 2e 20  o be supported. 
2dd30 20 48 6f 77 65 76 65 72 2c 20 6e 65 77 20 61 70   However, new ap
2dd40 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c  plications shoul
2dd50 64 20 61 76 6f 69 64 0a 2a 2a 20 74 68 65 20 75  d avoid.** the u
2dd60 73 65 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63  se of these func
2dd70 74 69 6f 6e 73 2e 20 20 54 6f 20 68 65 6c 70 20  tions.  To help 
2dd80 65 6e 63 6f 75 72 61 67 65 20 70 65 6f 70 6c 65  encourage people
2dd90 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 75 73 69   to avoid.** usi
2dda0 6e 67 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f  ng these functio
2ddb0 6e 73 2c 20 77 65 20 61 72 65 20 6e 6f 74 20 67  ns, we are not g
2ddc0 6f 69 6e 67 20 74 6f 20 74 65 6c 6c 20 79 6f 75  oing to tell you
2ddd0 20 77 61 6e 74 20 74 68 65 79 20 64 6f 2e 0a 2a   want they do..*
2dde0 2f 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41  /.SQLITE_DEPRECA
2ddf0 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  TED int sqlite3_
2de00 61 67 67 72 65 67 61 74 65 5f 63 6f 75 6e 74 28  aggregate_count(
2de10 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
2de20 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43  );.SQLITE_DEPREC
2de30 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33  ATED int sqlite3
2de40 5f 65 78 70 69 72 65 64 28 73 71 6c 69 74 65 33  _expired(sqlite3
2de50 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f  _stmt*);.SQLITE_
2de60 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73  DEPRECATED int s
2de70 71 6c 69 74 65 33 5f 74 72 61 6e 73 66 65 72 5f  qlite3_transfer_
2de80 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33  bindings(sqlite3
2de90 5f 73 74 6d 74 2a 2c 20 73 71 6c 69 74 65 33 5f  _stmt*, sqlite3_
2dea0 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44  stmt*);.SQLITE_D
2deb0 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71  EPRECATED int sq
2dec0 6c 69 74 65 33 5f 67 6c 6f 62 61 6c 5f 72 65 63  lite3_global_rec
2ded0 6f 76 65 72 28 76 6f 69 64 29 3b 0a 53 51 4c 49  over(void);.SQLI
2dee0 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 76 6f  TE_DEPRECATED vo
2def0 69 64 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61  id sqlite3_threa
2df00 64 5f 63 6c 65 61 6e 75 70 28 76 6f 69 64 29 3b  d_cleanup(void);
2df10 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54  .SQLITE_DEPRECAT
2df20 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d  ED int sqlite3_m
2df30 65 6d 6f 72 79 5f 61 6c 61 72 6d 28 76 6f 69 64  emory_alarm(void
2df40 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65  (*)(void*,sqlite
2df50 33 5f 69 6e 74 36 34 2c 69 6e 74 29 2c 76 6f 69  3_int64,int),voi
2df60 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  d*,sqlite3_int64
2df70 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2df80 45 46 3a 20 4f 62 74 61 69 6e 69 6e 67 20 53 51  EF: Obtaining SQ
2df90 4c 20 46 75 6e 63 74 69 6f 6e 20 50 61 72 61 6d  L Function Param
2dfa0 65 74 65 72 20 56 61 6c 75 65 73 20 7b 48 31 35  eter Values {H15
2dfb0 31 30 30 7d 20 3c 53 32 30 32 30 30 3e 0a 2a 2a  100} <S20200>.**
2dfc0 0a 2a 2a 20 54 68 65 20 43 2d 6c 61 6e 67 75 61  .** The C-langua
2dfd0 67 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ge implementatio
2dfe0 6e 20 6f 66 20 53 51 4c 20 66 75 6e 63 74 69 6f  n of SQL functio
2dff0 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 74 65  ns and aggregate
2e000 73 20 75 73 65 73 0a 2a 2a 20 74 68 69 73 20 73  s uses.** this s
2e010 65 74 20 6f 66 20 69 6e 74 65 72 66 61 63 65 20  et of interface 
2e020 72 6f 75 74 69 6e 65 73 20 74 6f 20 61 63 63 65  routines to acce
2e030 73 73 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  ss the parameter
2e040 20 76 61 6c 75 65 73 20 6f 6e 0a 2a 2a 20 74 68   values on.** th
2e050 65 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67  e function or ag
2e060 67 72 65 67 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54  gregate..**.** T
2e070 68 65 20 78 46 75 6e 63 20 28 66 6f 72 20 73 63  he xFunc (for sc
2e080 61 6c 61 72 20 66 75 6e 63 74 69 6f 6e 73 29 20  alar functions) 
2e090 6f 72 20 78 53 74 65 70 20 28 66 6f 72 20 61 67  or xStep (for ag
2e0a0 67 72 65 67 61 74 65 73 29 20 70 61 72 61 6d 65  gregates) parame
2e0b0 74 65 72 73 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69  ters.** to [sqli
2e0c0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
2e0d0 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  ion()] and [sqli
2e0e0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
2e0f0 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 64 65 66 69  ion16()].** defi
2e100 6e 65 20 63 61 6c 6c 62 61 63 6b 73 20 74 68 61  ne callbacks tha
2e110 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20  t implement the 
2e120 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e  SQL functions an
2e130 64 20 61 67 67 72 65 67 61 74 65 73 2e 0a 2a 2a  d aggregates..**
2e140 20 54 68 65 20 34 74 68 20 70 61 72 61 6d 65 74   The 4th paramet
2e150 65 72 20 74 6f 20 74 68 65 73 65 20 63 61 6c 6c  er to these call
2e160 62 61 63 6b 73 20 69 73 20 61 6e 20 61 72 72 61  backs is an arra
2e170 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f  y of pointers to
2e180 0a 2a 2a 20 5b 70 72 6f 74 65 63 74 65 64 20 73  .** [protected s
2e190 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
2e1a0 6a 65 63 74 73 2e 20 20 54 68 65 72 65 20 69 73  jects.  There is
2e1b0 20 6f 6e 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   one [sqlite3_va
2e1c0 6c 75 65 5d 20 6f 62 6a 65 63 74 20 66 6f 72 0a  lue] object for.
2e1d0 2a 2a 20 65 61 63 68 20 70 61 72 61 6d 65 74 65  ** each paramete
2e1e0 72 20 74 6f 20 74 68 65 20 53 51 4c 20 66 75 6e  r to the SQL fun
2e1f0 63 74 69 6f 6e 2e 20 20 54 68 65 73 65 20 72 6f  ction.  These ro
2e200 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 64 20  utines are used 
2e210 74 6f 0a 2a 2a 20 65 78 74 72 61 63 74 20 76 61  to.** extract va
2e220 6c 75 65 73 20 66 72 6f 6d 20 74 68 65 20 5b 73  lues from the [s
2e230 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
2e240 6a 65 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  jects..**.** The
2e250 73 65 20 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b  se routines work
2e260 20 6f 6e 6c 79 20 77 69 74 68 20 5b 70 72 6f 74   only with [prot
2e270 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
2e280 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a  lue] objects..**
2e290 20 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20   Any attempt to 
2e2a0 75 73 65 20 74 68 65 73 65 20 72 6f 75 74 69 6e  use these routin
2e2b0 65 73 20 6f 6e 20 61 6e 20 5b 75 6e 70 72 6f 74  es on an [unprot
2e2c0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
2e2d0 6c 75 65 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72  lue].** object r
2e2e0 65 73 75 6c 74 73 20 69 6e 20 75 6e 64 65 66 69  esults in undefi
2e2f0 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a  ned behavior..**
2e300 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
2e310 65 73 20 77 6f 72 6b 20 6a 75 73 74 20 6c 69 6b  es work just lik
2e320 65 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  e the correspond
2e330 69 6e 67 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65  ing [column acce
2e340 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 0a 2a 2a  ss functions].**
2e350 20 65 78 63 65 70 74 20 74 68 61 74 20 20 74 68   except that  th
2e360 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74 61 6b  ese routines tak
2e370 65 20 61 20 73 69 6e 67 6c 65 20 5b 70 72 6f 74  e a single [prot
2e380 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
2e390 6c 75 65 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 70  lue] object.** p
2e3a0 6f 69 6e 74 65 72 20 69 6e 73 74 65 61 64 20 6f  ointer instead o
2e3b0 66 20 61 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d  f a [sqlite3_stm
2e3c0 74 2a 5d 20 70 6f 69 6e 74 65 72 20 61 6e 64 20  t*] pointer and 
2e3d0 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 6c 75 6d  an integer colum
2e3e0 6e 20 6e 75 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a 20  n number..**.** 
2e3f0 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  The sqlite3_valu
2e400 65 5f 74 65 78 74 31 36 28 29 20 69 6e 74 65 72  e_text16() inter
2e410 66 61 63 65 20 65 78 74 72 61 63 74 73 20 61 20  face extracts a 
2e420 55 54 46 2d 31 36 20 73 74 72 69 6e 67 0a 2a 2a  UTF-16 string.**
2e430 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62   in the native b
2e440 79 74 65 2d 6f 72 64 65 72 20 6f 66 20 74 68 65  yte-order of the
2e450 20 68 6f 73 74 20 6d 61 63 68 69 6e 65 2e 20 20   host machine.  
2e460 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76  The.** sqlite3_v
2e470 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28 29 20  alue_text16be() 
2e480 61 6e 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  and sqlite3_valu
2e490 65 5f 74 65 78 74 31 36 6c 65 28 29 20 69 6e 74  e_text16le() int
2e4a0 65 72 66 61 63 65 73 0a 2a 2a 20 65 78 74 72 61  erfaces.** extra
2e4b0 63 74 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67  ct UTF-16 string
2e4c0 73 20 61 73 20 62 69 67 2d 65 6e 64 69 61 6e 20  s as big-endian 
2e4d0 61 6e 64 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61  and little-endia
2e4e0 6e 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a  n respectively..
2e4f0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
2e500 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f  3_value_numeric_
2e510 74 79 70 65 28 29 20 69 6e 74 65 72 66 61 63 65  type() interface
2e520 20 61 74 74 65 6d 70 74 73 20 74 6f 20 61 70 70   attempts to app
2e530 6c 79 0a 2a 2a 20 6e 75 6d 65 72 69 63 20 61 66  ly.** numeric af
2e540 66 69 6e 69 74 79 20 74 6f 20 74 68 65 20 76 61  finity to the va
2e550 6c 75 65 2e 20 20 54 68 69 73 20 6d 65 61 6e 73  lue.  This means
2e560 20 74 68 61 74 20 61 6e 20 61 74 74 65 6d 70 74   that an attempt
2e570 20 69 73 0a 2a 2a 20 6d 61 64 65 20 74 6f 20 63   is.** made to c
2e580 6f 6e 76 65 72 74 20 74 68 65 20 76 61 6c 75 65  onvert the value
2e590 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 6f   to an integer o
2e5a0 72 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74  r floating point
2e5b0 2e 20 20 49 66 0a 2a 2a 20 73 75 63 68 20 61 20  .  If.** such a 
2e5c0 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 6f  conversion is po
2e5d0 73 73 69 62 6c 65 20 77 69 74 68 6f 75 74 20 6c  ssible without l
2e5e0 6f 73 73 20 6f 66 20 69 6e 66 6f 72 6d 61 74 69  oss of informati
2e5f0 6f 6e 20 28 69 6e 20 6f 74 68 65 72 0a 2a 2a 20  on (in other.** 
2e600 77 6f 72 64 73 2c 20 69 66 20 74 68 65 20 76 61  words, if the va
2e610 6c 75 65 20 69 73 20 61 20 73 74 72 69 6e 67 20  lue is a string 
2e620 74 68 61 74 20 6c 6f 6f 6b 73 20 6c 69 6b 65 20  that looks like 
2e630 61 20 6e 75 6d 62 65 72 29 0a 2a 2a 20 74 68 65  a number).** the
2e640 6e 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e  n the conversion
2e650 20 69 73 20 70 65 72 66 6f 72 6d 65 64 2e 20 20   is performed.  
2e660 4f 74 68 65 72 77 69 73 65 20 6e 6f 20 63 6f 6e  Otherwise no con
2e670 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 2e 0a  version occurs..
2e680 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 49  ** The [SQLITE_I
2e690 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74 79 70  NTEGER | datatyp
2e6a0 65 5d 20 61 66 74 65 72 20 63 6f 6e 76 65 72 73  e] after convers
2e6b0 69 6f 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ion is returned.
2e6c0 0a 2a 2a 0a 2a 2a 20 50 6c 65 61 73 65 20 70 61  .**.** Please pa
2e6d0 79 20 70 61 72 74 69 63 75 6c 61 72 20 61 74 74  y particular att
2e6e0 65 6e 74 69 6f 6e 20 74 6f 20 74 68 65 20 66 61  ention to the fa
2e6f0 63 74 20 74 68 61 74 20 74 68 65 20 70 6f 69 6e  ct that the poin
2e700 74 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  ter returned.** 
2e710 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 76 61  from [sqlite3_va
2e720 6c 75 65 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71  lue_blob()], [sq
2e730 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
2e740 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  ()], or.** [sqli
2e750 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
2e760 28 29 5d 20 63 61 6e 20 62 65 20 69 6e 76 61 6c  ()] can be inval
2e770 69 64 61 74 65 64 20 62 79 20 61 20 73 75 62 73  idated by a subs
2e780 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a  equent call to.*
2e790 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  * [sqlite3_value
2e7a0 5f 62 79 74 65 73 28 29 5d 2c 20 5b 73 71 6c 69  _bytes()], [sqli
2e7b0 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31  te3_value_bytes1
2e7c0 36 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76  6()], [sqlite3_v
2e7d0 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a  alue_text()],.**
2e7e0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c   or [sqlite3_val
2e7f0 75 65 5f 74 65 78 74 31 36 28 29 5d 2e 0a 2a 2a  ue_text16()]..**
2e800 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
2e810 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65  es must be calle
2e820 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20  d from the same 
2e830 74 68 72 65 61 64 20 61 73 0a 2a 2a 20 74 68 65  thread as.** the
2e840 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 68   SQL function th
2e850 61 74 20 73 75 70 70 6c 69 65 64 20 74 68 65 20  at supplied the 
2e860 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 5d  [sqlite3_value*]
2e870 20 70 61 72 61 6d 65 74 65 72 73 2e 0a 2a 2a 0a   parameters..**.
2e880 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
2e890 2a 0a 2a 2a 20 7b 48 31 35 31 30 33 7d 20 54 68  *.** {H15103} Th
2e8a0 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
2e8b0 5f 62 6c 6f 62 28 56 29 5d 20 69 6e 74 65 72 66  _blob(V)] interf
2e8c0 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65  ace converts the
2e8d0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72  .**          [pr
2e8e0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
2e8f0 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56 20  value] object V 
2e900 69 6e 74 6f 20 61 20 42 4c 4f 42 20 61 6e 64 20  into a BLOB and 
2e910 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  then.**         
2e920 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
2e930 65 72 20 74 6f 20 74 68 65 20 63 6f 6e 76 65 72  er to the conver
2e940 74 65 64 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a  ted value..**.**
2e950 20 7b 48 31 35 31 30 36 7d 20 54 68 65 20 5b 73   {H15106} The [s
2e960 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74  qlite3_value_byt
2e970 65 73 28 56 29 5d 20 69 6e 74 65 72 66 61 63 65  es(V)] interface
2e980 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20   returns the.** 
2e990 20 20 20 20 20 20 20 20 20 6e 75 6d 62 65 72 20           number 
2e9a0 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20  of bytes in the 
2e9b0 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 20 28  BLOB or string (
2e9c0 65 78 63 6c 75 73 69 76 65 20 6f 66 20 74 68 65  exclusive of the
2e9d0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 7a 65 72  .**          zer
2e9e0 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 6f 6e 20  o terminator on 
2e9f0 74 68 65 20 73 74 72 69 6e 67 29 20 74 68 61 74  the string) that
2ea00 20 77 61 73 20 72 65 74 75 72 6e 65 64 20 62 79   was returned by
2ea10 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
2ea20 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c   most recent cal
2ea30 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 76 61  l to [sqlite3_va
2ea40 6c 75 65 5f 62 6c 6f 62 28 56 29 5d 20 6f 72 0a  lue_blob(V)] or.
2ea50 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
2ea60 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28  ite3_value_text(
2ea70 56 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 31  V)]..**.** {H151
2ea80 30 39 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  09} The [sqlite3
2ea90 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28 56  _value_bytes16(V
2eaa0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  )] interface ret
2eab0 75 72 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20 20  urns the.**     
2eac0 20 20 20 20 20 6e 75 6d 62 65 72 20 6f 66 20 62       number of b
2ead0 79 74 65 73 20 69 6e 20 74 68 65 20 73 74 72 69  ytes in the stri
2eae0 6e 67 20 28 65 78 63 6c 75 73 69 76 65 20 6f 66  ng (exclusive of
2eaf0 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
2eb00 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72   zero terminator
2eb10 20 6f 6e 20 74 68 65 20 73 74 72 69 6e 67 29 20   on the string) 
2eb20 74 68 61 74 20 77 61 73 20 72 65 74 75 72 6e 65  that was returne
2eb30 64 20 62 79 20 74 68 65 0a 2a 2a 20 20 20 20 20  d by the.**     
2eb40 20 20 20 20 20 6d 6f 73 74 20 72 65 63 65 6e 74       most recent
2eb50 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
2eb60 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 56  3_value_text16(V
2eb70 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  )],.**          
2eb80 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
2eb90 65 78 74 31 36 62 65 28 56 29 5d 2c 20 6f 72 20  ext16be(V)], or 
2eba0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
2ebb0 65 78 74 31 36 6c 65 28 56 29 5d 2e 0a 2a 2a 0a  ext16le(V)]..**.
2ebc0 2a 2a 20 7b 48 31 35 31 31 32 7d 20 54 68 65 20  ** {H15112} The 
2ebd0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64  [sqlite3_value_d
2ebe0 6f 75 62 6c 65 28 56 29 5d 20 69 6e 74 65 72 66  ouble(V)] interf
2ebf0 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65  ace converts the
2ec00 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72  .**          [pr
2ec10 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
2ec20 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56 20  value] object V 
2ec30 69 6e 74 6f 20 61 20 66 6c 6f 61 74 69 6e 67 20  into a floating 
2ec40 70 6f 69 6e 74 20 76 61 6c 75 65 20 61 6e 64 0a  point value and.
2ec50 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75  **          retu
2ec60 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68  rns a copy of th
2ec70 61 74 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20  at value..**.** 
2ec80 7b 48 31 35 31 31 35 7d 20 54 68 65 20 5b 73 71  {H15115} The [sq
2ec90 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28  lite3_value_int(
2eca0 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f  V)] interface co
2ecb0 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20  nverts the.**   
2ecc0 20 20 20 20 20 20 20 5b 70 72 6f 74 65 63 74 65         [protecte
2ecd0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
2ece0 20 6f 62 6a 65 63 74 20 56 20 69 6e 74 6f 20 61   object V into a
2ecf0 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69   64-bit signed i
2ed00 6e 74 65 67 65 72 20 61 6e 64 0a 2a 2a 20 20 20  nteger and.**   
2ed10 20 20 20 20 20 20 20 72 65 74 75 72 6e 73 20 74         returns t
2ed20 68 65 20 6c 6f 77 65 72 20 33 32 20 62 69 74 73  he lower 32 bits
2ed30 20 6f 66 20 74 68 61 74 20 69 6e 74 65 67 65 72   of that integer
2ed40 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 31 31 38 7d  ..**.** {H15118}
2ed50 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   The [sqlite3_va
2ed60 6c 75 65 5f 69 6e 74 36 34 28 56 29 5d 20 69 6e  lue_int64(V)] in
2ed70 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73  terface converts
2ed80 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
2ed90 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69   [protected sqli
2eda0 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
2edb0 74 20 56 20 69 6e 74 6f 20 61 20 36 34 2d 62 69  t V into a 64-bi
2edc0 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  t signed integer
2edd0 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20   and.**         
2ede0 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20   returns a copy 
2edf0 6f 66 20 74 68 61 74 20 69 6e 74 65 67 65 72 2e  of that integer.
2ee00 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 31 32 31 7d 20  .**.** {H15121} 
2ee10 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  The [sqlite3_val
2ee20 75 65 5f 74 65 78 74 28 56 29 5d 20 69 6e 74 65  ue_text(V)] inte
2ee30 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74  rface converts t
2ee40 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  he.**          [
2ee50 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
2ee60 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
2ee70 56 20 69 6e 74 6f 20 61 20 7a 65 72 6f 2d 74 65  V into a zero-te
2ee80 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 0a 2a  rminated UTF-8.*
2ee90 2a 20 20 20 20 20 20 20 20 20 20 73 74 72 69 6e  *          strin
2eea0 67 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20  g and returns a 
2eeb0 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 61 74 20  pointer to that 
2eec0 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48  string..**.** {H
2eed0 31 35 31 32 34 7d 20 54 68 65 20 5b 73 71 6c 69  15124} The [sqli
2eee0 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
2eef0 28 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63  (V)] interface c
2ef00 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20  onverts the.**  
2ef10 20 20 20 20 20 20 20 20 5b 70 72 6f 74 65 63 74          [protect
2ef20 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
2ef30 5d 20 6f 62 6a 65 63 74 20 56 20 69 6e 74 6f 20  ] object V into 
2ef40 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  a zero-terminate
2ef50 64 20 32 2d 62 79 74 65 0a 2a 2a 20 20 20 20 20  d 2-byte.**     
2ef60 20 20 20 20 20 61 6c 69 67 6e 65 64 20 55 54 46       aligned UTF
2ef70 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74 65 20  -16 native byte 
2ef80 6f 72 64 65 72 0a 2a 2a 20 20 20 20 20 20 20 20  order.**        
2ef90 20 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74    string and ret
2efa0 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
2efb0 6f 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a  o that string..*
2efc0 2a 0a 2a 2a 20 7b 48 31 35 31 32 37 7d 20 54 68  *.** {H15127} Th
2efd0 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
2efe0 5f 74 65 78 74 31 36 62 65 28 56 29 5d 20 69 6e  _text16be(V)] in
2eff0 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73  terface converts
2f000 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
2f010 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69   [protected sqli
2f020 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
2f030 74 20 56 20 69 6e 74 6f 20 61 20 7a 65 72 6f 2d  t V into a zero-
2f040 74 65 72 6d 69 6e 61 74 65 64 20 32 2d 62 79 74  terminated 2-byt
2f050 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6c  e.**          al
2f060 69 67 6e 65 64 20 55 54 46 2d 31 36 20 62 69 67  igned UTF-16 big
2f070 2d 65 6e 64 69 61 6e 0a 2a 2a 20 20 20 20 20 20  -endian.**      
2f080 20 20 20 20 73 74 72 69 6e 67 20 61 6e 64 20 72      string and r
2f090 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
2f0a0 20 74 6f 20 74 68 61 74 20 73 74 72 69 6e 67 2e   to that string.
2f0b0 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 31 33 30 7d 20  .**.** {H15130} 
2f0c0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  The [sqlite3_val
2f0d0 75 65 5f 74 65 78 74 31 36 6c 65 28 56 29 5d 20  ue_text16le(V)] 
2f0e0 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72  interface conver
2f0f0 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  ts the.**       
2f100 20 20 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71     [protected sq
2f110 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
2f120 65 63 74 20 56 20 69 6e 74 6f 20 61 20 7a 65 72  ect V into a zer
2f130 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 32 2d 62  o-terminated 2-b
2f140 79 74 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  yte.**          
2f150 61 6c 69 67 6e 65 64 20 55 54 46 2d 31 36 20 6c  aligned UTF-16 l
2f160 69 74 74 6c 65 2d 65 6e 64 69 61 6e 0a 2a 2a 20  ittle-endian.** 
2f170 20 20 20 20 20 20 20 20 20 73 74 72 69 6e 67 20           string 
2f180 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f  and returns a po
2f190 69 6e 74 65 72 20 74 6f 20 74 68 61 74 20 73 74  inter to that st
2f1a0 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35  ring..**.** {H15
2f1b0 31 33 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  133} The [sqlite
2f1c0 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 56 29 5d  3_value_type(V)]
2f1d0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
2f1e0 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  ns.**          o
2f1f0 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 4e 55  ne of [SQLITE_NU
2f200 4c 4c 5d 2c 20 5b 53 51 4c 49 54 45 5f 49 4e 54  LL], [SQLITE_INT
2f210 45 47 45 52 5d 2c 20 5b 53 51 4c 49 54 45 5f 46  EGER], [SQLITE_F
2f220 4c 4f 41 54 5d 2c 0a 2a 2a 20 20 20 20 20 20 20  LOAT],.**       
2f230 20 20 20 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d     [SQLITE_TEXT]
2f240 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 42 4c 4f  , or [SQLITE_BLO
2f250 42 5d 20 61 73 20 61 70 70 72 6f 70 72 69 61 74  B] as appropriat
2f260 65 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20  e for.**        
2f270 20 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76    the [sqlite3_v
2f280 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56 2e 0a  alue] object V..
2f290 2a 2a 0a 2a 2a 20 7b 48 31 35 31 33 36 7d 20 54  **.** {H15136} T
2f2a0 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  he [sqlite3_valu
2f2b0 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 56  e_numeric_type(V
2f2c0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e  )] interface con
2f2d0 76 65 72 74 73 0a 2a 2a 20 20 20 20 20 20 20 20  verts.**        
2f2e0 20 20 74 68 65 20 5b 70 72 6f 74 65 63 74 65 64    the [protected
2f2f0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
2f300 6f 62 6a 65 63 74 20 56 20 69 6e 74 6f 20 65 69  object V into ei
2f310 74 68 65 72 20 61 6e 20 69 6e 74 65 67 65 72 20  ther an integer 
2f320 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  or.**          a
2f330 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20   floating point 
2f340 76 61 6c 75 65 20 69 66 20 69 74 20 63 61 6e 20  value if it can 
2f350 64 6f 20 73 6f 20 77 69 74 68 6f 75 74 20 6c 6f  do so without lo
2f360 73 73 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20  ss of.**        
2f370 20 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2c 20 61    information, a
2f380 6e 64 20 72 65 74 75 72 6e 73 20 6f 6e 65 20 6f  nd returns one o
2f390 66 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2c  f [SQLITE_NULL],
2f3a0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51  .**          [SQ
2f3b0 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c 20 5b  LITE_INTEGER], [
2f3c0 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b  SQLITE_FLOAT], [
2f3d0 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20 6f 72  SQLITE_TEXT], or
2f3e0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51  .**          [SQ
2f3f0 4c 49 54 45 5f 42 4c 4f 42 5d 20 61 73 20 61 70  LITE_BLOB] as ap
2f400 70 72 6f 70 72 69 61 74 65 20 66 6f 72 20 74 68  propriate for th
2f410 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70  e.**          [p
2f420 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
2f430 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56  _value] object V
2f440 20 61 66 74 65 72 20 74 68 65 20 63 6f 6e 76 65   after the conve
2f450 72 73 69 6f 6e 20 61 74 74 65 6d 70 74 2e 0a 2a  rsion attempt..*
2f460 2f 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  /.const void *sq
2f470 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62  lite3_value_blob
2f480 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
2f490 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61  ;.int sqlite3_va
2f4a0 6c 75 65 5f 62 79 74 65 73 28 73 71 6c 69 74 65  lue_bytes(sqlite
2f4b0 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73  3_value*);.int s
2f4c0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74  qlite3_value_byt
2f4d0 65 73 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c  es16(sqlite3_val
2f4e0 75 65 2a 29 3b 0a 64 6f 75 62 6c 65 20 73 71 6c  ue*);.double sql
2f4f0 69 74 65 33 5f 76 61 6c 75 65 5f 64 6f 75 62 6c  ite3_value_doubl
2f500 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  e(sqlite3_value*
2f510 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76  );.int sqlite3_v
2f520 61 6c 75 65 5f 69 6e 74 28 73 71 6c 69 74 65 33  alue_int(sqlite3
2f530 5f 76 61 6c 75 65 2a 29 3b 0a 73 71 6c 69 74 65  _value*);.sqlite
2f540 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f  3_int64 sqlite3_
2f550 76 61 6c 75 65 5f 69 6e 74 36 34 28 73 71 6c 69  value_int64(sqli
2f560 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e  te3_value*);.con
2f570 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72  st unsigned char
2f580 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   *sqlite3_value_
2f590 74 65 78 74 28 73 71 6c 69 74 65 33 5f 76 61 6c  text(sqlite3_val
2f5a0 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  ue*);.const void
2f5b0 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   *sqlite3_value_
2f5c0 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 76  text16(sqlite3_v
2f5d0 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f  alue*);.const vo
2f5e0 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75  id *sqlite3_valu
2f5f0 65 5f 74 65 78 74 31 36 6c 65 28 73 71 6c 69 74  e_text16le(sqlit
2f600 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73  e3_value*);.cons
2f610 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
2f620 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28 73  value_text16be(s
2f630 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
2f640 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  int sqlite3_valu
2f650 65 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76  e_type(sqlite3_v
2f660 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69  alue*);.int sqli
2f670 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69  te3_value_numeri
2f680 63 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76  c_type(sqlite3_v
2f690 61 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  alue*);../*.** C
2f6a0 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 20  API3REF: Obtain 
2f6b0 41 67 67 72 65 67 61 74 65 20 46 75 6e 63 74 69  Aggregate Functi
2f6c0 6f 6e 20 43 6f 6e 74 65 78 74 20 7b 48 31 36 32  on Context {H162
2f6d0 31 30 7d 20 3c 53 32 30 32 30 30 3e 0a 2a 2a 0a  10} <S20200>.**.
2f6e0 2a 2a 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74  ** The implement
2f6f0 61 74 69 6f 6e 20 6f 66 20 61 67 67 72 65 67 61  ation of aggrega
2f700 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  te SQL functions
2f710 20 75 73 65 20 74 68 69 73 20 72 6f 75 74 69 6e   use this routin
2f720 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 0a 2a 2a  e to allocate.**
2f730 20 61 20 73 74 72 75 63 74 75 72 65 20 66 6f 72   a structure for
2f740 20 73 74 6f 72 69 6e 67 20 74 68 65 69 72 20 73   storing their s
2f750 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  tate..**.** The 
2f760 66 69 72 73 74 20 74 69 6d 65 20 74 68 65 20 73  first time the s
2f770 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
2f780 5f 63 6f 6e 74 65 78 74 28 29 20 72 6f 75 74 69  _context() routi
2f790 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 66 6f 72  ne is called for
2f7a0 20 61 0a 2a 2a 20 70 61 72 74 69 63 75 6c 61 72   a.** particular
2f7b0 20 61 67 67 72 65 67 61 74 65 2c 20 53 51 4c 69   aggregate, SQLi
2f7c0 74 65 20 61 6c 6c 6f 63 61 74 65 73 20 6e 42 79  te allocates nBy
2f7d0 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2c 20 7a  tes of memory, z
2f7e0 65 72 6f 65 73 20 6f 75 74 20 74 68 61 74 0a 2a  eroes out that.*
2f7f0 2a 20 6d 65 6d 6f 72 79 2c 20 61 6e 64 20 72 65  * memory, and re
2f800 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
2f810 74 6f 20 69 74 2e 20 4f 6e 20 73 65 63 6f 6e 64  to it. On second
2f820 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74 20   and subsequent 
2f830 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69  calls to.** sqli
2f840 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
2f850 6e 74 65 78 74 28 29 20 66 6f 72 20 74 68 65 20  ntext() for the 
2f860 73 61 6d 65 20 61 67 67 72 65 67 61 74 65 20 66  same aggregate f
2f870 75 6e 63 74 69 6f 6e 20 69 6e 64 65 78 2c 0a 2a  unction index,.*
2f880 2a 20 74 68 65 20 73 61 6d 65 20 62 75 66 66 65  * the same buffe
2f890 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 54  r is returned. T
2f8a0 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
2f8b0 6e 20 6f 66 20 74 68 65 20 61 67 67 72 65 67 61  n of the aggrega
2f8c0 74 65 20 63 61 6e 20 75 73 65 0a 2a 2a 20 74 68  te can use.** th
2f8d0 65 20 72 65 74 75 72 6e 65 64 20 62 75 66 66 65  e returned buffe
2f8e0 72 20 74 6f 20 61 63 63 75 6d 75 6c 61 74 65 20  r to accumulate 
2f8f0 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  data..**.** SQLi
2f900 74 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  te automatically
2f910 20 66 72 65 65 73 20 74 68 65 20 61 6c 6c 6f 63   frees the alloc
2f920 61 74 65 64 20 62 75 66 66 65 72 20 77 68 65 6e  ated buffer when
2f930 20 74 68 65 20 61 67 67 72 65 67 61 74 65 0a 2a   the aggregate.*
2f940 2a 20 71 75 65 72 79 20 63 6f 6e 63 6c 75 64 65  * query conclude
2f950 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72  s..**.** The fir
2f960 73 74 20 70 61 72 61 6d 65 74 65 72 20 73 68 6f  st parameter sho
2f970 75 6c 64 20 62 65 20 61 20 63 6f 70 79 20 6f 66  uld be a copy of
2f980 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
2f990 5f 63 6f 6e 74 65 78 74 20 7c 20 53 51 4c 20 66  _context | SQL f
2f9a0 75 6e 63 74 69 6f 6e 20 63 6f 6e 74 65 78 74 5d  unction context]
2f9b0 20 74 68 61 74 20 69 73 20 74 68 65 20 66 69 72   that is the fir
2f9c0 73 74 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20  st parameter.** 
2f9d0 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  to the callback 
2f9e0 72 6f 75 74 69 6e 65 20 74 68 61 74 20 69 6d 70  routine that imp
2f9f0 6c 65 6d 65 6e 74 73 20 74 68 65 20 61 67 67 72  lements the aggr
2fa00 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 2e 0a  egate function..
2fa10 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69  **.** This routi
2fa20 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65  ne must be calle
2fa30 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20  d from the same 
2fa40 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a  thread in which.
2fa50 2a 2a 20 74 68 65 20 61 67 67 72 65 67 61 74 65  ** the aggregate
2fa60 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73   SQL function is
2fa70 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20   running..**.** 
2fa80 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
2fa90 2a 20 7b 48 31 36 32 31 31 7d 20 54 68 65 20 66  * {H16211} The f
2faa0 69 72 73 74 20 69 6e 76 6f 63 61 74 69 6f 6e 20  irst invocation 
2fab0 6f 66 20 5b 73 71 6c 69 74 65 33 5f 61 67 67 72  of [sqlite3_aggr
2fac0 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c  egate_context(C,
2fad0 4e 29 5d 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20  N)] for.**      
2fae0 20 20 20 20 61 20 70 61 72 74 69 63 75 6c 61 72      a particular
2faf0 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 61 6e 20   instance of an 
2fb00 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69  aggregate functi
2fb10 6f 6e 20 28 66 6f 72 20 61 20 70 61 72 74 69 63  on (for a partic
2fb20 75 6c 61 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  ular.**         
2fb30 20 63 6f 6e 74 65 78 74 20 43 29 20 63 61 75 73   context C) caus
2fb40 65 73 20 53 51 4c 69 74 65 20 74 6f 20 61 6c 6c  es SQLite to all
2fb50 6f 63 61 74 65 20 4e 20 62 79 74 65 73 20 6f 66  ocate N bytes of
2fb60 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 20 20 20 20   memory,.**     
2fb70 20 20 20 20 20 7a 65 72 6f 20 74 68 61 74 20 6d       zero that m
2fb80 65 6d 6f 72 79 2c 20 61 6e 64 20 72 65 74 75 72  emory, and retur
2fb90 6e 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  n a pointer to t
2fba0 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 6d 65 6d  he allocated mem
2fbb0 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 32  ory..**.** {H162
2fbc0 31 33 7d 20 49 66 20 61 20 6d 65 6d 6f 72 79 20  13} If a memory 
2fbd0 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72  allocation error
2fbe0 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67 0a 2a   occurs during.*
2fbf0 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
2fc00 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
2fc10 6e 74 65 78 74 28 43 2c 4e 29 5d 20 74 68 65 6e  ntext(C,N)] then
2fc20 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 72 65   the function re
2fc30 74 75 72 6e 73 20 30 2e 0a 2a 2a 0a 2a 2a 20 7b  turns 0..**.** {
2fc40 48 31 36 32 31 35 7d 20 53 65 63 6f 6e 64 20 61  H16215} Second a
2fc50 6e 64 20 73 75 62 73 65 71 75 65 6e 74 20 69 6e  nd subsequent in
2fc60 76 6f 63 61 74 69 6f 6e 73 20 6f 66 0a 2a 2a 20  vocations of.** 
2fc70 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
2fc80 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
2fc90 65 78 74 28 43 2c 4e 29 5d 20 66 6f 72 20 74 68  ext(C,N)] for th
2fca0 65 20 73 61 6d 65 20 63 6f 6e 74 65 78 74 20 70  e same context p
2fcb0 6f 69 6e 74 65 72 20 43 0a 2a 2a 20 20 20 20 20  ointer C.**     
2fcc0 20 20 20 20 20 69 67 6e 6f 72 65 20 74 68 65 20       ignore the 
2fcd0 4e 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20  N parameter and 
2fce0 72 65 74 75 72 6e 20 61 20 70 6f 69 6e 74 65 72  return a pointer
2fcf0 20 74 6f 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20   to the same.** 
2fd00 20 20 20 20 20 20 20 20 20 62 6c 6f 63 6b 20 6f           block o
2fd10 66 20 6d 65 6d 6f 72 79 20 72 65 74 75 72 6e 65  f memory returne
2fd20 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20 69  d by the first i
2fd30 6e 76 6f 63 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  nvocation..**.**
2fd40 20 7b 48 31 36 32 31 37 7d 20 54 68 65 20 6d 65   {H16217} The me
2fd50 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 65 64 20 62  mory allocated b
2fd60 79 20 5b 73 71 6c 69 74 65 33 5f 61 67 67 72 65  y [sqlite3_aggre
2fd70 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e  gate_context(C,N
2fd80 29 5d 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20  )] is.**        
2fd90 20 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20    automatically 
2fda0 66 72 65 65 64 20 6f 6e 20 74 68 65 20 6e 65 78  freed on the nex
2fdb0 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  t call to [sqlit
2fdc0 65 33 5f 72 65 73 65 74 28 29 5d 0a 2a 2a 20 20  e3_reset()].**  
2fdd0 20 20 20 20 20 20 20 20 6f 72 20 5b 73 71 6c 69          or [sqli
2fde0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
2fdf0 66 6f 72 20 74 68 65 20 5b 70 72 65 70 61 72 65  for the [prepare
2fe00 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 63 6f 6e  d statement] con
2fe10 74 61 69 6e 69 6e 67 0a 2a 2a 20 20 20 20 20 20  taining.**      
2fe20 20 20 20 20 74 68 65 20 61 67 67 72 65 67 61 74      the aggregat
2fe30 65 20 66 75 6e 63 74 69 6f 6e 20 61 73 73 6f 63  e function assoc
2fe40 69 61 74 65 64 20 77 69 74 68 20 63 6f 6e 74 65  iated with conte
2fe50 78 74 20 43 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73  xt C..*/.void *s
2fe60 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
2fe70 5f 63 6f 6e 74 65 78 74 28 73 71 6c 69 74 65 33  _context(sqlite3
2fe80 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e  _context*, int n
2fe90 42 79 74 65 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  Bytes);../*.** C
2fea0 41 50 49 33 52 45 46 3a 20 55 73 65 72 20 44 61  API3REF: User Da
2feb0 74 61 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73  ta For Functions
2fec0 20 7b 48 31 36 32 34 30 7d 20 3c 53 32 30 32 30   {H16240} <S2020
2fed0 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  0>.**.** The sql
2fee0 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29  ite3_user_data()
2fef0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
2ff00 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20  ns a copy of.** 
2ff10 74 68 65 20 70 6f 69 6e 74 65 72 20 74 68 61 74  the pointer that
2ff20 20 77 61 73 20 74 68 65 20 70 55 73 65 72 44 61   was the pUserDa
2ff30 74 61 20 70 61 72 61 6d 65 74 65 72 20 28 74 68  ta parameter (th
2ff40 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 29  e 5th parameter)
2ff50 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  .** of the [sqli
2ff60 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
2ff70 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73  ion()].** and [s
2ff80 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
2ff90 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74  nction16()] rout
2ffa0 69 6e 65 73 20 74 68 61 74 20 6f 72 69 67 69 6e  ines that origin
2ffb0 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65 72  ally.** register
2ffc0 65 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ed the applicati
2ffd0 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on defined funct
2ffe0 69 6f 6e 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a  ion. {END}.**.**
2fff0 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75   This routine mu
30000 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f  st be called fro
30010 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61  m the same threa
30020 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68  d in which.** th
30030 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
30040 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 69  fined function i
30050 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a  s running..**.**
30060 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
30070 2a 2a 20 7b 48 31 36 32 34 33 7d 20 54 68 65 20  ** {H16243} The 
30080 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61  [sqlite3_user_da
30090 74 61 28 43 29 5d 20 69 6e 74 65 72 66 61 63 65  ta(C)] interface
300a0 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20   returns a copy 
300b0 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  of the.**       
300c0 20 20 20 50 20 70 6f 69 6e 74 65 72 20 66 72 6f     P pointer fro
300d0 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  m the [sqlite3_c
300e0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44  reate_function(D
300f0 2c 58 2c 4e 2c 45 2c 50 2c 46 2c 53 2c 4c 29 5d  ,X,N,E,P,F,S,L)]
30100 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20  .**          or 
30110 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
30120 66 75 6e 63 74 69 6f 6e 31 36 28 44 2c 58 2c 4e  function16(D,X,N
30130 2c 45 2c 50 2c 46 2c 53 2c 4c 29 5d 20 63 61 6c  ,E,P,F,S,L)] cal
30140 6c 20 74 68 61 74 0a 2a 2a 20 20 20 20 20 20 20  l that.**       
30150 20 20 20 72 65 67 69 73 74 65 72 65 64 20 74 68     registered th
30160 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 61  e SQL function a
30170 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 5b  ssociated with [
30180 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5d  sqlite3_context]
30190 20 43 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c   C..*/.void *sql
301a0 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 73  ite3_user_data(s
301b0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
301c0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
301d0 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e  F: Database Conn
301e0 65 63 74 69 6f 6e 20 46 6f 72 20 46 75 6e 63 74  ection For Funct
301f0 69 6f 6e 73 20 7b 48 31 36 32 35 30 7d 20 3c 53  ions {H16250} <S
30200 36 30 36 30 30 3e 3c 53 32 30 32 30 30 3e 0a 2a  60600><S20200>.*
30210 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
30220 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64  _context_db_hand
30230 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  le() interface r
30240 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66  eturns a copy of
30250 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65 72 20  .** the pointer 
30260 74 6f 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  to the [database
30270 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 74 68   connection] (th
30280 65 20 31 73 74 20 70 61 72 61 6d 65 74 65 72 29  e 1st parameter)
30290 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  .** of the [sqli
302a0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
302b0 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73  ion()].** and [s
302c0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
302d0 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74  nction16()] rout
302e0 69 6e 65 73 20 74 68 61 74 20 6f 72 69 67 69 6e  ines that origin
302f0 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65 72  ally.** register
30300 65 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ed the applicati
30310 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on defined funct
30320 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  ion..**.** INVAR
30330 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31  IANTS:.**.** {H1
30340 36 32 35 33 7d 20 54 68 65 20 5b 73 71 6c 69 74  6253} The [sqlit
30350 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61  e3_context_db_ha
30360 6e 64 6c 65 28 43 29 5d 20 69 6e 74 65 72 66 61  ndle(C)] interfa
30370 63 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70  ce returns a cop
30380 79 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 20  y of the.**     
30390 20 20 20 20 20 44 20 70 6f 69 6e 74 65 72 20 66       D pointer f
303a0 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33  rom the [sqlite3
303b0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
303c0 28 44 2c 58 2c 4e 2c 45 2c 50 2c 46 2c 53 2c 4c  (D,X,N,E,P,F,S,L
303d0 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  )].**          o
303e0 72 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  r [sqlite3_creat
303f0 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 44 2c 58  e_function16(D,X
30400 2c 4e 2c 45 2c 50 2c 46 2c 53 2c 4c 29 5d 20 63  ,N,E,P,F,S,L)] c
30410 61 6c 6c 20 74 68 61 74 0a 2a 2a 20 20 20 20 20  all that.**     
30420 20 20 20 20 20 72 65 67 69 73 74 65 72 65 64 20       registered 
30430 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
30440 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
30450 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78   [sqlite3_contex
30460 74 5d 20 43 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33  t] C..*/.sqlite3
30470 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78   *sqlite3_contex
30480 74 5f 64 62 5f 68 61 6e 64 6c 65 28 73 71 6c 69  t_db_handle(sqli
30490 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a  te3_context*);..
304a0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
304b0 46 75 6e 63 74 69 6f 6e 20 41 75 78 69 6c 69 61  Function Auxilia
304c0 72 79 20 44 61 74 61 20 7b 48 31 36 32 37 30 7d  ry Data {H16270}
304d0 20 3c 53 32 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20   <S20200>.**.** 
304e0 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 77  The following tw
304f0 6f 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20  o functions may 
30500 62 65 20 75 73 65 64 20 62 79 20 73 63 61 6c 61  be used by scala
30510 72 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  r SQL functions 
30520 74 6f 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 20  to.** associate 
30530 6d 65 74 61 64 61 74 61 20 77 69 74 68 20 61 72  metadata with ar
30540 67 75 6d 65 6e 74 20 76 61 6c 75 65 73 2e 20 49  gument values. I
30550 66 20 74 68 65 20 73 61 6d 65 20 76 61 6c 75 65  f the same value
30560 20 69 73 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a   is passed to.**
30570 20 6d 75 6c 74 69 70 6c 65 20 69 6e 76 6f 63 61   multiple invoca
30580 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d  tions of the sam
30590 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 64  e SQL function d
305a0 75 72 69 6e 67 20 71 75 65 72 79 20 65 78 65 63  uring query exec
305b0 75 74 69 6f 6e 2c 20 75 6e 64 65 72 0a 2a 2a 20  ution, under.** 
305c0 73 6f 6d 65 20 63 69 72 63 75 6d 73 74 61 6e 63  some circumstanc
305d0 65 73 20 74 68 65 20 61 73 73 6f 63 69 61 74 65  es the associate
305e0 64 20 6d 65 74 61 64 61 74 61 20 6d 61 79 20 62  d metadata may b
305f0 65 20 70 72 65 73 65 72 76 65 64 2e 20 54 68 69  e preserved. Thi
30600 73 20 6d 61 79 0a 2a 2a 20 62 65 20 75 73 65 64  s may.** be used
30610 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 74  , for example, t
30620 6f 20 61 64 64 20 61 20 72 65 67 75 6c 61 72 2d  o add a regular-
30630 65 78 70 72 65 73 73 69 6f 6e 20 6d 61 74 63 68  expression match
30640 69 6e 67 20 73 63 61 6c 61 72 0a 2a 2a 20 66 75  ing scalar.** fu
30650 6e 63 74 69 6f 6e 2e 20 54 68 65 20 63 6f 6d 70  nction. The comp
30660 69 6c 65 64 20 76 65 72 73 69 6f 6e 20 6f 66 20  iled version of 
30670 74 68 65 20 72 65 67 75 6c 61 72 20 65 78 70 72  the regular expr
30680 65 73 73 69 6f 6e 20 69 73 20 73 74 6f 72 65 64  ession is stored
30690 20 61 73 0a 2a 2a 20 6d 65 74 61 64 61 74 61 20   as.** metadata 
306a0 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
306b0 74 68 65 20 53 51 4c 20 76 61 6c 75 65 20 70 61  the SQL value pa
306c0 73 73 65 64 20 61 73 20 74 68 65 20 72 65 67 75  ssed as the regu
306d0 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e 0a 2a  lar expression.*
306e0 2a 20 70 61 74 74 65 72 6e 2e 20 20 54 68 65 20  * pattern.  The 
306f0 63 6f 6d 70 69 6c 65 64 20 72 65 67 75 6c 61 72  compiled regular
30700 20 65 78 70 72 65 73 73 69 6f 6e 20 63 61 6e 20   expression can 
30710 62 65 20 72 65 75 73 65 64 20 6f 6e 20 6d 75 6c  be reused on mul
30720 74 69 70 6c 65 0a 2a 2a 20 69 6e 76 6f 63 61 74  tiple.** invocat
30730 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65  ions of the same
30740 20 66 75 6e 63 74 69 6f 6e 20 73 6f 20 74 68 61   function so tha
30750 74 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 70  t the original p
30760 61 74 74 65 72 6e 20 73 74 72 69 6e 67 0a 2a 2a  attern string.**
30770 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74   does not need t
30780 6f 20 62 65 20 72 65 63 6f 6d 70 69 6c 65 64 20  o be recompiled 
30790 6f 6e 20 65 61 63 68 20 69 6e 76 6f 63 61 74 69  on each invocati
307a0 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  on..**.** The sq
307b0 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74  lite3_get_auxdat
307c0 61 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  a() interface re
307d0 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
307e0 74 6f 20 74 68 65 20 6d 65 74 61 64 61 74 61 0a  to the metadata.
307f0 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 62 79  ** associated by
30800 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74   the sqlite3_set
30810 5f 61 75 78 64 61 74 61 28 29 20 66 75 6e 63 74  _auxdata() funct
30820 69 6f 6e 20 77 69 74 68 20 74 68 65 20 4e 74 68  ion with the Nth
30830 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 76 61 6c   argument.** val
30840 75 65 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63  ue to the applic
30850 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
30860 6e 63 74 69 6f 6e 2e 20 49 66 20 6e 6f 20 6d 65  nction. If no me
30870 74 61 64 61 74 61 20 68 61 73 20 62 65 65 6e 20  tadata has been 
30880 65 76 65 72 0a 2a 2a 20 62 65 65 6e 20 73 65 74  ever.** been set
30890 20 66 6f 72 20 74 68 65 20 4e 74 68 20 61 72 67   for the Nth arg
308a0 75 6d 65 6e 74 20 6f 66 20 74 68 65 20 66 75 6e  ument of the fun
308b0 63 74 69 6f 6e 2c 20 6f 72 20 69 66 20 74 68 65  ction, or if the
308c0 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a   corresponding.*
308d0 2a 20 66 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d  * function param
308e0 65 74 65 72 20 68 61 73 20 63 68 61 6e 67 65 64  eter has changed
308f0 20 73 69 6e 63 65 20 74 68 65 20 6d 65 74 61 2d   since the meta-
30900 64 61 74 61 20 77 61 73 20 73 65 74 2c 0a 2a 2a  data was set,.**
30910 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 67 65   then sqlite3_ge
30920 74 5f 61 75 78 64 61 74 61 28 29 20 72 65 74 75  t_auxdata() retu
30930 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  rns a NULL point
30940 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  er..**.** The sq
30950 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74  lite3_set_auxdat
30960 61 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 61  a() interface sa
30970 76 65 73 20 74 68 65 20 6d 65 74 61 64 61 74 61  ves the metadata
30980 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20 62  .** pointed to b
30990 79 20 69 74 73 20 33 72 64 20 70 61 72 61 6d 65  y its 3rd parame
309a0 74 65 72 20 61 73 20 74 68 65 20 6d 65 74 61 64  ter as the metad
309b0 61 74 61 20 66 6f 72 20 74 68 65 20 4e 2d 74 68  ata for the N-th
309c0 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6f 66 20  .** argument of 
309d0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
309e0 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
309f0 2e 20 20 53 75 62 73 65 71 75 65 6e 74 0a 2a 2a  .  Subsequent.**
30a00 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65   calls to sqlite
30a10 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 20  3_get_auxdata() 
30a20 6d 69 67 68 74 20 72 65 74 75 72 6e 20 74 68 69  might return thi
30a30 73 20 64 61 74 61 2c 20 69 66 20 69 74 20 68 61  s data, if it ha
30a40 73 0a 2a 2a 20 6e 6f 74 20 62 65 65 6e 20 64 65  s.** not been de
30a50 73 74 72 6f 79 65 64 2e 0a 2a 2a 20 49 66 20 69  stroyed..** If i
30a60 74 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 53  t is not NULL, S
30a70 51 4c 69 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b  QLite will invok
30a80 65 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72  e the destructor
30a90 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 67 69 76  .** function giv
30aa0 65 6e 20 62 79 20 74 68 65 20 34 74 68 20 70 61  en by the 4th pa
30ab0 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
30ac0 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29  e3_set_auxdata()
30ad0 20 6f 6e 0a 2a 2a 20 74 68 65 20 6d 65 74 61 64   on.** the metad
30ae0 61 74 61 20 77 68 65 6e 20 74 68 65 20 63 6f 72  ata when the cor
30af0 72 65 73 70 6f 6e 64 69 6e 67 20 66 75 6e 63 74  responding funct
30b00 69 6f 6e 20 70 61 72 61 6d 65 74 65 72 20 63 68  ion parameter ch
30b10 61 6e 67 65 73 0a 2a 2a 20 6f 72 20 77 68 65 6e  anges.** or when
30b20 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
30b30 6e 74 20 63 6f 6d 70 6c 65 74 65 73 2c 20 77 68  nt completes, wh
30b40 69 63 68 65 76 65 72 20 63 6f 6d 65 73 20 66 69  ichever comes fi
30b50 72 73 74 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  rst..**.** SQLit
30b60 65 20 69 73 20 66 72 65 65 20 74 6f 20 63 61 6c  e is free to cal
30b70 6c 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72  l the destructor
30b80 20 61 6e 64 20 64 72 6f 70 20 6d 65 74 61 64 61   and drop metada
30b90 74 61 20 6f 6e 20 61 6e 79 0a 2a 2a 20 70 61 72  ta on any.** par
30ba0 61 6d 65 74 65 72 20 6f 66 20 61 6e 79 20 66 75  ameter of any fu
30bb0 6e 63 74 69 6f 6e 20 61 74 20 61 6e 79 20 74 69  nction at any ti
30bc0 6d 65 2e 20 20 54 68 65 20 6f 6e 6c 79 20 67 75  me.  The only gu
30bd0 61 72 61 6e 74 65 65 20 69 73 20 74 68 61 74 0a  arantee is that.
30be0 2a 2a 20 74 68 65 20 64 65 73 74 72 75 63 74 6f  ** the destructo
30bf0 72 20 77 69 6c 6c 20 62 65 20 63 61 6c 6c 65 64  r will be called
30c00 20 62 65 66 6f 72 65 20 74 68 65 20 6d 65 74 61   before the meta
30c10 64 61 74 61 20 69 73 20 64 72 6f 70 70 65 64 2e  data is dropped.
30c20 0a 2a 2a 0a 2a 2a 20 49 6e 20 70 72 61 63 74 69  .**.** In practi
30c30 63 65 2c 20 6d 65 74 61 64 61 74 61 20 69 73 20  ce, metadata is 
30c40 70 72 65 73 65 72 76 65 64 20 62 65 74 77 65 65  preserved betwee
30c50 6e 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 73  n function calls
30c60 20 66 6f 72 0a 2a 2a 20 65 78 70 72 65 73 73 69   for.** expressi
30c70 6f 6e 73 20 74 68 61 74 20 61 72 65 20 63 6f 6e  ons that are con
30c80 73 74 61 6e 74 20 61 74 20 63 6f 6d 70 69 6c 65  stant at compile
30c90 20 74 69 6d 65 2e 20 54 68 69 73 20 69 6e 63 6c   time. This incl
30ca0 75 64 65 73 20 6c 69 74 65 72 61 6c 0a 2a 2a 20  udes literal.** 
30cb0 76 61 6c 75 65 73 20 61 6e 64 20 53 51 4c 20 76  values and SQL v
30cc0 61 72 69 61 62 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20  ariables..**.** 
30cd0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d  These routines m
30ce0 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72  ust be called fr
30cf0 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65  om the same thre
30d00 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74  ad in which.** t
30d10 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
30d20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 0a 2a  is running..**.*
30d30 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
30d40 0a 2a 2a 20 7b 48 31 36 32 37 32 7d 20 54 68 65  .** {H16272} The
30d50 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75   [sqlite3_get_au
30d60 78 64 61 74 61 28 43 2c 4e 29 5d 20 69 6e 74 65  xdata(C,N)] inte
30d70 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20  rface returns a 
30d80 70 6f 69 6e 74 65 72 0a 2a 2a 20 20 20 20 20 20  pointer.**      
30d90 20 20 20 20 74 6f 20 6d 65 74 61 64 61 74 61 20      to metadata 
30da0 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
30db0 74 68 65 20 4e 74 68 20 70 61 72 61 6d 65 74 65  the Nth paramete
30dc0 72 20 6f 66 20 74 68 65 20 53 51 4c 20 66 75 6e  r of the SQL fun
30dd0 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20  ction.**        
30de0 20 20 77 68 6f 73 65 20 63 6f 6e 74 65 78 74 20    whose context 
30df0 69 73 20 43 2c 20 6f 72 20 4e 55 4c 4c 20 69 66  is C, or NULL if
30e00 20 74 68 65 72 65 20 69 73 20 6e 6f 20 6d 65 74   there is no met
30e10 61 64 61 74 61 20 61 73 73 6f 63 69 61 74 65 64  adata associated
30e20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 69 74  .**          wit
30e30 68 20 74 68 61 74 20 70 61 72 61 6d 65 74 65 72  h that parameter
30e40 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 32 37 34 7d  ..**.** {H16274}
30e50 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65   The [sqlite3_se
30e60 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c 50 2c  t_auxdata(C,N,P,
30e70 44 29 5d 20 69 6e 74 65 72 66 61 63 65 20 61 73  D)] interface as
30e80 73 69 67 6e 73 20 61 20 6d 65 74 61 64 61 74 61  signs a metadata
30e90 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70 6f 69  .**          poi
30ea0 6e 74 65 72 20 50 20 74 6f 20 74 68 65 20 4e 74  nter P to the Nt
30eb0 68 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 74  h parameter of t
30ec0 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
30ed0 77 69 74 68 20 63 6f 6e 74 65 78 74 20 43 2e 0a  with context C..
30ee0 2a 2a 0a 2a 2a 20 7b 48 31 36 32 37 36 7d 20 53  **.** {H16276} S
30ef0 51 4c 69 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b  QLite will invok
30f00 65 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72  e the destructor
30f10 20 44 20 77 69 74 68 20 61 20 73 69 6e 67 6c 65   D with a single
30f20 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 20 20 20   argument.**    
30f30 20 20 20 20 20 20 77 68 69 63 68 20 69 73 20 74        which is t
30f40 68 65 20 6d 65 74 61 64 61 74 61 20 70 6f 69 6e  he metadata poin
30f50 74 65 72 20 50 20 66 6f 6c 6c 6f 77 69 6e 67 20  ter P following 
30f60 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 20 20 20  a call to.**    
30f70 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 73        [sqlite3_s
30f80 65 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c 50  et_auxdata(C,N,P
30f90 2c 44 29 5d 20 77 68 65 6e 20 53 51 4c 69 74 65  ,D)] when SQLite
30fa0 20 63 65 61 73 65 73 20 74 6f 20 68 6f 6c 64 0a   ceases to hold.
30fb0 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
30fc0 6d 65 74 61 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20  metadata..**.** 
30fd0 7b 48 31 36 32 37 37 7d 20 53 51 4c 69 74 65 20  {H16277} SQLite 
30fe0 63 65 61 73 65 73 20 74 6f 20 68 6f 6c 64 20 6d  ceases to hold m
30ff0 65 74 61 64 61 74 61 20 66 6f 72 20 61 6e 20 53  etadata for an S
31000 51 4c 20 66 75 6e 63 74 69 6f 6e 20 70 61 72 61  QL function para
31010 6d 65 74 65 72 0a 2a 2a 20 20 20 20 20 20 20 20  meter.**        
31020 20 20 77 68 65 6e 20 74 68 65 20 76 61 6c 75 65    when the value
31030 20 6f 66 20 74 68 61 74 20 70 61 72 61 6d 65 74   of that paramet
31040 65 72 20 63 68 61 6e 67 65 73 2e 0a 2a 2a 0a 2a  er changes..**.*
31050 2a 20 7b 48 31 36 32 37 38 7d 20 57 68 65 6e 20  * {H16278} When 
31060 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78  [sqlite3_set_aux
31070 64 61 74 61 28 43 2c 4e 2c 50 2c 44 29 5d 20 69  data(C,N,P,D)] i
31080 73 20 69 6e 76 6f 6b 65 64 2c 20 74 68 65 20 64  s invoked, the d
31090 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20 20 20 20  estructor.**    
310a0 20 20 20 20 20 20 69 73 20 63 61 6c 6c 65 64 20        is called 
310b0 66 6f 72 20 61 6e 79 20 70 72 69 6f 72 20 6d 65  for any prior me
310c0 74 61 64 61 74 61 20 61 73 73 6f 63 69 61 74 65  tadata associate
310d0 64 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20  d with the same 
310e0 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20  function.**     
310f0 20 20 20 20 20 63 6f 6e 74 65 78 74 20 43 20 61       context C a
31100 6e 64 20 70 61 72 61 6d 65 74 65 72 20 4e 2e 0a  nd parameter N..
31110 2a 2a 0a 2a 2a 20 7b 48 31 36 32 37 39 7d 20 53  **.** {H16279} S
31120 51 4c 69 74 65 20 77 69 6c 6c 20 63 61 6c 6c 20  QLite will call 
31130 64 65 73 74 72 75 63 74 6f 72 73 20 66 6f 72 20  destructors for 
31140 61 6e 79 20 6d 65 74 61 64 61 74 61 20 69 74 20  any metadata it 
31150 69 73 20 68 6f 6c 64 69 6e 67 0a 2a 2a 20 20 20  is holding.**   
31160 20 20 20 20 20 20 20 69 6e 20 61 20 70 61 72 74         in a part
31170 69 63 75 6c 61 72 20 5b 70 72 65 70 61 72 65 64  icular [prepared
31180 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 77 68   statement] S wh
31190 65 6e 20 65 69 74 68 65 72 0a 2a 2a 20 20 20 20  en either.**    
311a0 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 72        [sqlite3_r
311b0 65 73 65 74 28 53 29 5d 20 6f 72 20 5b 73 71 6c  eset(S)] or [sql
311c0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29  ite3_finalize(S)
311d0 5d 20 69 73 20 63 61 6c 6c 65 64 2e 0a 2a 2f 0a  ] is called..*/.
311e0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 67 65  void *sqlite3_ge
311f0 74 5f 61 75 78 64 61 74 61 28 73 71 6c 69 74 65  t_auxdata(sqlite
31200 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20  3_context*, int 
31210 4e 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  N);.void sqlite3
31220 5f 73 65 74 5f 61 75 78 64 61 74 61 28 73 71 6c  _set_auxdata(sql
31230 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69  ite3_context*, i
31240 6e 74 20 4e 2c 20 76 6f 69 64 2a 2c 20 76 6f 69  nt N, void*, voi
31250 64 20 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 0a  d (*)(void*));..
31260 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
31270 20 43 6f 6e 73 74 61 6e 74 73 20 44 65 66 69 6e   Constants Defin
31280 69 6e 67 20 53 70 65 63 69 61 6c 20 44 65 73 74  ing Special Dest
31290 72 75 63 74 6f 72 20 42 65 68 61 76 69 6f 72 20  ructor Behavior 
312a0 7b 48 31 30 32 38 30 7d 20 3c 53 33 30 31 30 30  {H10280} <S30100
312b0 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72  >.**.** These ar
312c0 65 20 73 70 65 63 69 61 6c 20 76 61 6c 75 65 73  e special values
312d0 20 66 6f 72 20 74 68 65 20 64 65 73 74 72 75 63   for the destruc
312e0 74 6f 72 20 74 68 61 74 20 69 73 20 70 61 73 73  tor that is pass
312f0 65 64 20 69 6e 20 61 73 20 74 68 65 0a 2a 2a 20  ed in as the.** 
31300 66 69 6e 61 6c 20 61 72 67 75 6d 65 6e 74 20 74  final argument t
31310 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20  o routines like 
31320 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
31330 62 6c 6f 62 28 29 5d 2e 20 20 49 66 20 74 68 65  blob()].  If the
31340 20 64 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20 61   destructor.** a
31350 72 67 75 6d 65 6e 74 20 69 73 20 53 51 4c 49 54  rgument is SQLIT
31360 45 5f 53 54 41 54 49 43 2c 20 69 74 20 6d 65 61  E_STATIC, it mea
31370 6e 73 20 74 68 61 74 20 74 68 65 20 63 6f 6e 74  ns that the cont
31380 65 6e 74 20 70 6f 69 6e 74 65 72 20 69 73 20 63  ent pointer is c
31390 6f 6e 73 74 61 6e 74 0a 2a 2a 20 61 6e 64 20 77  onstant.** and w
313a0 69 6c 6c 20 6e 65 76 65 72 20 63 68 61 6e 67 65  ill never change
313b0 2e 20 20 49 74 20 64 6f 65 73 20 6e 6f 74 20 6e  .  It does not n
313c0 65 65 64 20 74 6f 20 62 65 20 64 65 73 74 72 6f  eed to be destro
313d0 79 65 64 2e 20 20 54 68 65 0a 2a 2a 20 53 51 4c  yed.  The.** SQL
313e0 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 20 76 61  ITE_TRANSIENT va
313f0 6c 75 65 20 6d 65 61 6e 73 20 74 68 61 74 20 74  lue means that t
31400 68 65 20 63 6f 6e 74 65 6e 74 20 77 69 6c 6c 20  he content will 
31410 6c 69 6b 65 6c 79 20 63 68 61 6e 67 65 20 69 6e  likely change in
31420 0a 2a 2a 20 74 68 65 20 6e 65 61 72 20 66 75 74  .** the near fut
31430 75 72 65 20 61 6e 64 20 74 68 61 74 20 53 51 4c  ure and that SQL
31440 69 74 65 20 73 68 6f 75 6c 64 20 6d 61 6b 65 20  ite should make 
31450 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20  its own private 
31460 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 63  copy of.** the c
31470 6f 6e 74 65 6e 74 20 62 65 66 6f 72 65 20 72 65  ontent before re
31480 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54  turning..**.** T
31490 68 65 20 74 79 70 65 64 65 66 20 69 73 20 6e 65  he typedef is ne
314a0 63 65 73 73 61 72 79 20 74 6f 20 77 6f 72 6b 20  cessary to work 
314b0 61 72 6f 75 6e 64 20 70 72 6f 62 6c 65 6d 73 20  around problems 
314c0 69 6e 20 63 65 72 74 61 69 6e 0a 2a 2a 20 43 2b  in certain.** C+
314d0 2b 20 63 6f 6d 70 69 6c 65 72 73 2e 20 20 53 65  + compilers.  Se
314e0 65 20 74 69 63 6b 65 74 20 23 32 31 39 31 2e 0a  e ticket #2191..
314f0 2a 2f 0a 74 79 70 65 64 65 66 20 76 6f 69 64 20  */.typedef void 
31500 28 2a 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75  (*sqlite3_destru
31510 63 74 6f 72 5f 74 79 70 65 29 28 76 6f 69 64 2a  ctor_type)(void*
31520 29 3b 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  );.#define SQLIT
31530 45 5f 53 54 41 54 49 43 20 20 20 20 20 20 28 28  E_STATIC      ((
31540 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74  sqlite3_destruct
31550 6f 72 5f 74 79 70 65 29 30 29 0a 23 64 65 66 69  or_type)0).#defi
31560 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49  ne SQLITE_TRANSI
31570 45 4e 54 20 20 20 28 28 73 71 6c 69 74 65 33 5f  ENT   ((sqlite3_
31580 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29  destructor_type)
31590 2d 31 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  -1)../*.** CAPI3
315a0 52 45 46 3a 20 53 65 74 74 69 6e 67 20 54 68 65  REF: Setting The
315b0 20 52 65 73 75 6c 74 20 4f 66 20 41 6e 20 53 51   Result Of An SQ
315c0 4c 20 46 75 6e 63 74 69 6f 6e 20 7b 48 31 36 34  L Function {H164
315d0 30 30 7d 20 3c 53 32 30 32 30 30 3e 0a 2a 2a 0a  00} <S20200>.**.
315e0 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
315f0 73 20 61 72 65 20 75 73 65 64 20 62 79 20 74 68  s are used by th
31600 65 20 78 46 75 6e 63 20 6f 72 20 78 46 69 6e 61  e xFunc or xFina
31610 6c 20 63 61 6c 6c 62 61 63 6b 73 20 74 68 61 74  l callbacks that
31620 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 20 53 51  .** implement SQ
31630 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20  L functions and 
31640 61 67 67 72 65 67 61 74 65 73 2e 20 20 53 65 65  aggregates.  See
31650 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  .** [sqlite3_cre
31660 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20  ate_function()] 
31670 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  and [sqlite3_cre
31680 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29  ate_function16()
31690 5d 0a 2a 2a 20 66 6f 72 20 61 64 64 69 74 69 6f  ].** for additio
316a0 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e  nal information.
316b0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e  .**.** These fun
316c0 63 74 69 6f 6e 73 20 77 6f 72 6b 20 76 65 72 79  ctions work very
316d0 20 6d 75 63 68 20 6c 69 6b 65 20 74 68 65 20 5b   much like the [
316e0 70 61 72 61 6d 65 74 65 72 20 62 69 6e 64 69 6e  parameter bindin
316f0 67 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20  g] family of.** 
31700 66 75 6e 63 74 69 6f 6e 73 20 75 73 65 64 20 74  functions used t
31710 6f 20 62 69 6e 64 20 76 61 6c 75 65 73 20 74 6f  o bind values to
31720 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73   host parameters
31730 20 69 6e 20 70 72 65 70 61 72 65 64 20 73 74 61   in prepared sta
31740 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 52 65 66 65  tements..** Refe
31750 72 20 74 6f 20 74 68 65 20 5b 53 51 4c 20 70 61  r to the [SQL pa
31760 72 61 6d 65 74 65 72 5d 20 64 6f 63 75 6d 65 6e  rameter] documen
31770 74 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74  tation for addit
31780 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f  ional informatio
31790 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  n..**.** The sql
317a0 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62  ite3_result_blob
317b0 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74  () interface set
317c0 73 20 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f  s the result fro
317d0 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61 74  m.** an applicat
317e0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
317f0 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 42  tion to be the B
31800 4c 4f 42 20 77 68 6f 73 65 20 63 6f 6e 74 65 6e  LOB whose conten
31810 74 20 69 73 20 70 6f 69 6e 74 65 64 0a 2a 2a 20  t is pointed.** 
31820 74 6f 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64  to by the second
31830 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20 77   parameter and w
31840 68 69 63 68 20 69 73 20 4e 20 62 79 74 65 73 20  hich is N bytes 
31850 6c 6f 6e 67 20 77 68 65 72 65 20 4e 20 69 73 20  long where N is 
31860 74 68 65 0a 2a 2a 20 74 68 69 72 64 20 70 61 72  the.** third par
31870 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68  ameter..**.** Th
31880 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
31890 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 69 6e 74 65  _zeroblob() inte
318a0 72 66 61 63 65 73 20 73 65 74 20 74 68 65 20 72  rfaces set the r
318b0 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20  esult of.** the 
318c0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
318d0 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  ned function to 
318e0 62 65 20 61 20 42 4c 4f 42 20 63 6f 6e 74 61 69  be a BLOB contai
318f0 6e 69 6e 67 20 61 6c 6c 20 7a 65 72 6f 0a 2a 2a  ning all zero.**
31900 20 62 79 74 65 73 20 61 6e 64 20 4e 20 62 79 74   bytes and N byt
31910 65 73 20 69 6e 20 73 69 7a 65 2c 20 77 68 65 72  es in size, wher
31920 65 20 4e 20 69 73 20 74 68 65 20 76 61 6c 75 65  e N is the value
31930 20 6f 66 20 74 68 65 20 32 6e 64 20 70 61 72 61   of the 2nd para
31940 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  meter..**.** The
31950 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
31960 64 6f 75 62 6c 65 28 29 20 69 6e 74 65 72 66 61  double() interfa
31970 63 65 20 73 65 74 73 20 74 68 65 20 72 65 73 75  ce sets the resu
31980 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70  lt from.** an ap
31990 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
319a0 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  d function to be
319b0 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e   a floating poin
319c0 74 20 76 61 6c 75 65 20 73 70 65 63 69 66 69 65  t value specifie
319d0 64 0a 2a 2a 20 62 79 20 69 74 73 20 32 6e 64 20  d.** by its 2nd 
319e0 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  argument..**.** 
319f0 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
31a00 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 73  lt_error() and s
31a10 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
31a20 72 6f 72 31 36 28 29 20 66 75 6e 63 74 69 6f 6e  ror16() function
31a30 73 0a 2a 2a 20 63 61 75 73 65 20 74 68 65 20 69  s.** cause the i
31a40 6d 70 6c 65 6d 65 6e 74 65 64 20 53 51 4c 20 66  mplemented SQL f
31a50 75 6e 63 74 69 6f 6e 20 74 6f 20 74 68 72 6f 77  unction to throw
31a60 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 2e 0a 2a   an exception..*
31a70 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 74 68  * SQLite uses th
31a80 65 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 64  e string pointed
31a90 20 74 6f 20 62 79 20 74 68 65 0a 2a 2a 20 32 6e   to by the.** 2n
31aa0 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 73  d parameter of s
31ab0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
31ac0 72 6f 72 28 29 20 6f 72 20 73 71 6c 69 74 65 33  ror() or sqlite3
31ad0 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
31ae0 29 0a 2a 2a 20 61 73 20 74 68 65 20 74 65 78 74  ).** as the text
31af0 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 6d 65 73   of an error mes
31b00 73 61 67 65 2e 20 20 53 51 4c 69 74 65 20 69 6e  sage.  SQLite in
31b10 74 65 72 70 72 65 74 73 20 74 68 65 20 65 72 72  terprets the err
31b20 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 73 74  or.** message st
31b30 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74 65  ring from sqlite
31b40 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29  3_result_error()
31b50 20 61 73 20 55 54 46 2d 38 2e 20 53 51 4c 69 74   as UTF-8. SQLit
31b60 65 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74 73 20  e.** interprets 
31b70 74 68 65 20 73 74 72 69 6e 67 20 66 72 6f 6d 20  the string from 
31b80 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
31b90 72 72 6f 72 31 36 28 29 20 61 73 20 55 54 46 2d  rror16() as UTF-
31ba0 31 36 20 69 6e 20 6e 61 74 69 76 65 0a 2a 2a 20  16 in native.** 
31bb0 62 79 74 65 20 6f 72 64 65 72 2e 20 20 49 66 20  byte order.  If 
31bc0 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
31bd0 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72  ter to sqlite3_r
31be0 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a  esult_error().**
31bf0 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75   or sqlite3_resu
31c00 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 69 73 20  lt_error16() is 
31c10 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 53 51  negative then SQ
31c20 4c 69 74 65 20 74 61 6b 65 73 20 61 73 20 74 68  Lite takes as th
31c30 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61  e error.** messa
31c40 67 65 20 61 6c 6c 20 74 65 78 74 20 75 70 20 74  ge all text up t
31c50 68 72 6f 75 67 68 20 74 68 65 20 66 69 72 73 74  hrough the first
31c60 20 7a 65 72 6f 20 63 68 61 72 61 63 74 65 72 2e   zero character.
31c70 0a 2a 2a 20 49 66 20 74 68 65 20 74 68 69 72 64  .** If the third
31c80 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
31c90 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
31ca0 6f 72 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74  or() or.** sqlit
31cb0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31  e3_result_error1
31cc0 36 28 29 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74  6() is non-negat
31cd0 69 76 65 20 74 68 65 6e 20 53 51 4c 69 74 65 20  ive then SQLite 
31ce0 74 61 6b 65 73 20 74 68 61 74 20 6d 61 6e 79 0a  takes that many.
31cf0 2a 2a 20 62 79 74 65 73 20 28 6e 6f 74 20 63 68  ** bytes (not ch
31d00 61 72 61 63 74 65 72 73 29 20 66 72 6f 6d 20 74  aracters) from t
31d10 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
31d20 20 61 73 20 74 68 65 20 65 72 72 6f 72 20 6d 65   as the error me
31d30 73 73 61 67 65 2e 0a 2a 2a 20 54 68 65 20 73 71  ssage..** The sq
31d40 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
31d50 6f 72 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  or() and sqlite3
31d60 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
31d70 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 6d 61  ).** routines ma
31d80 6b 65 20 61 20 70 72 69 76 61 74 65 20 63 6f 70  ke a private cop
31d90 79 20 6f 66 20 74 68 65 20 65 72 72 6f 72 20 6d  y of the error m
31da0 65 73 73 61 67 65 20 74 65 78 74 20 62 65 66 6f  essage text befo
31db0 72 65 0a 2a 2a 20 74 68 65 79 20 72 65 74 75 72  re.** they retur
31dc0 6e 2e 20 20 48 65 6e 63 65 2c 20 74 68 65 20 63  n.  Hence, the c
31dd0 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20  alling function 
31de0 63 61 6e 20 64 65 61 6c 6c 6f 63 61 74 65 20 6f  can deallocate o
31df0 72 0a 2a 2a 20 6d 6f 64 69 66 79 20 74 68 65 20  r.** modify the 
31e00 74 65 78 74 20 61 66 74 65 72 20 74 68 65 79 20  text after they 
31e10 72 65 74 75 72 6e 20 77 69 74 68 6f 75 74 20 68  return without h
31e20 61 72 6d 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69  arm..** The sqli
31e30 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
31e40 5f 63 6f 64 65 28 29 20 66 75 6e 63 74 69 6f 6e  _code() function
31e50 20 63 68 61 6e 67 65 73 20 74 68 65 20 65 72 72   changes the err
31e60 6f 72 20 63 6f 64 65 0a 2a 2a 20 72 65 74 75 72  or code.** retur
31e70 6e 65 64 20 62 79 20 53 51 4c 69 74 65 20 61 73  ned by SQLite as
31e80 20 61 20 72 65 73 75 6c 74 20 6f 66 20 61 6e 20   a result of an 
31e90 65 72 72 6f 72 20 69 6e 20 61 20 66 75 6e 63 74  error in a funct
31ea0 69 6f 6e 2e 20 20 42 79 20 64 65 66 61 75 6c 74  ion.  By default
31eb0 2c 0a 2a 2a 20 74 68 65 20 65 72 72 6f 72 20 63  ,.** the error c
31ec0 6f 64 65 20 69 73 20 53 51 4c 49 54 45 5f 45 52  ode is SQLITE_ER
31ed0 52 4f 52 2e 20 20 41 20 73 75 62 73 65 71 75 65  ROR.  A subseque
31ee0 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74  nt call to sqlit
31ef0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28  e3_result_error(
31f00 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f  ).** or sqlite3_
31f10 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29  result_error16()
31f20 20 72 65 73 65 74 73 20 74 68 65 20 65 72 72 6f   resets the erro
31f30 72 20 63 6f 64 65 20 74 6f 20 53 51 4c 49 54 45  r code to SQLITE
31f40 5f 45 52 52 4f 52 2e 0a 2a 2a 0a 2a 2a 20 54 68  _ERROR..**.** Th
31f50 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
31f60 5f 74 6f 6f 62 69 67 28 29 20 69 6e 74 65 72 66  _toobig() interf
31f70 61 63 65 20 63 61 75 73 65 73 20 53 51 4c 69 74  ace causes SQLit
31f80 65 20 74 6f 20 74 68 72 6f 77 20 61 6e 20 65 72  e to throw an er
31f90 72 6f 72 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e  ror.** indicatin
31fa0 67 20 74 68 61 74 20 61 20 73 74 72 69 6e 67 20  g that a string 
31fb0 6f 72 20 42 4c 4f 42 20 69 73 20 74 6f 20 6c 6f  or BLOB is to lo
31fc0 6e 67 20 74 6f 20 72 65 70 72 65 73 65 6e 74 2e  ng to represent.
31fd0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
31fe0 65 33 5f 72 65 73 75 6c 74 5f 6e 6f 6d 65 6d 28  e3_result_nomem(
31ff0 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 75 73  ) interface caus
32000 65 73 20 53 51 4c 69 74 65 20 74 6f 20 74 68 72  es SQLite to thr
32010 6f 77 20 61 6e 20 65 72 72 6f 72 0a 2a 2a 20 69  ow an error.** i
32020 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74 20 61  ndicating that a
32030 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
32040 6f 6e 20 66 61 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a  on failed..**.**
32050 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   The sqlite3_res
32060 75 6c 74 5f 69 6e 74 28 29 20 69 6e 74 65 72 66  ult_int() interf
32070 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65 74  ace sets the ret
32080 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20  urn value.** of 
32090 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
320a0 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
320b0 20 74 6f 20 62 65 20 74 68 65 20 33 32 2d 62 69   to be the 32-bi
320c0 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  t signed integer
320d0 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76 65 6e 20  .** value given 
320e0 69 6e 20 74 68 65 20 32 6e 64 20 61 72 67 75 6d  in the 2nd argum
320f0 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ent..** The sqli
32100 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34  te3_result_int64
32110 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74  () interface set
32120 73 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  s the return val
32130 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70  ue.** of the app
32140 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
32150 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
32160 74 68 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65  the 64-bit signe
32170 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c  d integer.** val
32180 75 65 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20  ue given in the 
32190 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  2nd argument..**
321a0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
321b0 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 29 20 69 6e  result_null() in
321c0 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65  terface sets the
321d0 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a   return value.**
321e0 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74   of the applicat
321f0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
32200 74 69 6f 6e 20 74 6f 20 62 65 20 4e 55 4c 4c 2e  tion to be NULL.
32210 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
32220 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 29  e3_result_text()
32230 2c 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  , sqlite3_result
32240 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 73 71  _text16(),.** sq
32250 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
32260 74 31 36 6c 65 28 29 2c 20 61 6e 64 20 73 71 6c  t16le(), and sql
32270 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
32280 31 36 62 65 28 29 20 69 6e 74 65 72 66 61 63 65  16be() interface
32290 73 0a 2a 2a 20 73 65 74 20 74 68 65 20 72 65 74  s.** set the ret
322a0 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 65  urn value of the
322b0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
322c0 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f  ined function to
322d0 20 62 65 0a 2a 2a 20 61 20 74 65 78 74 20 73 74   be.** a text st
322e0 72 69 6e 67 20 77 68 69 63 68 20 69 73 20 72 65  ring which is re
322f0 70 72 65 73 65 6e 74 65 64 20 61 73 20 55 54 46  presented as UTF
32300 2d 38 2c 20 55 54 46 2d 31 36 20 6e 61 74 69 76  -8, UTF-16 nativ
32310 65 20 62 79 74 65 20 6f 72 64 65 72 2c 0a 2a 2a  e byte order,.**
32320 20 55 54 46 2d 31 36 20 6c 69 74 74 6c 65 20 65   UTF-16 little e
32330 6e 64 69 61 6e 2c 20 6f 72 20 55 54 46 2d 31 36  ndian, or UTF-16
32340 20 62 69 67 20 65 6e 64 69 61 6e 2c 20 72 65 73   big endian, res
32350 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 53 51  pectively..** SQ
32360 4c 69 74 65 20 74 61 6b 65 73 20 74 68 65 20 74  Lite takes the t
32370 65 78 74 20 72 65 73 75 6c 74 20 66 72 6f 6d 20  ext result from 
32380 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
32390 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 32 6e 64 20  from.** the 2nd 
323a0 70 61 72 61 6d 65 74 65 72 20 6f 66 20 74 68 65  parameter of the
323b0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
323c0 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73  text* interfaces
323d0 2e 0a 2a 2a 20 49 66 20 74 68 65 20 33 72 64 20  ..** If the 3rd 
323e0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
323f0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
32400 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73  text* interfaces
32410 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69 76 65 2c  .** is negative,
32420 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b   then SQLite tak
32430 65 73 20 72 65 73 75 6c 74 20 74 65 78 74 20 66  es result text f
32440 72 6f 6d 20 74 68 65 20 32 6e 64 20 70 61 72 61  rom the 2nd para
32450 6d 65 74 65 72 0a 2a 2a 20 74 68 72 6f 75 67 68  meter.** through
32460 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20   the first zero 
32470 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 49 66  character..** If
32480 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74   the 3rd paramet
32490 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  er to the sqlite
324a0 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69  3_result_text* i
324b0 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69 73 20  nterfaces.** is 
324c0 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68  non-negative, th
324d0 65 6e 20 61 73 20 6d 61 6e 79 20 62 79 74 65 73  en as many bytes
324e0 20 28 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73   (not characters
324f0 29 20 6f 66 20 74 68 65 20 74 65 78 74 0a 2a 2a  ) of the text.**
32500 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74   pointed to by t
32510 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
32520 20 61 72 65 20 74 61 6b 65 6e 20 61 73 20 74 68   are taken as th
32530 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
32540 66 69 6e 65 64 0a 2a 2a 20 66 75 6e 63 74 69 6f  fined.** functio
32550 6e 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 49 66 20  n result..** If 
32560 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65  the 4th paramete
32570 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  r to the sqlite3
32580 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e  _result_text* in
32590 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73  terfaces.** or s
325a0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c  qlite3_result_bl
325b0 6f 62 20 69 73 20 61 20 6e 6f 6e 2d 4e 55 4c 4c  ob is a non-NULL
325c0 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 53   pointer, then S
325d0 51 4c 69 74 65 20 63 61 6c 6c 73 20 74 68 61 74  QLite calls that
325e0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 61 73 20  .** function as 
325f0 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 6f  the destructor o
32600 6e 20 74 68 65 20 74 65 78 74 20 6f 72 20 42 4c  n the text or BL
32610 4f 42 20 72 65 73 75 6c 74 20 77 68 65 6e 20 69  OB result when i
32620 74 20 68 61 73 0a 2a 2a 20 66 69 6e 69 73 68 65  t has.** finishe
32630 64 20 75 73 69 6e 67 20 74 68 61 74 20 72 65 73  d using that res
32640 75 6c 74 2e 0a 2a 2a 20 49 66 20 74 68 65 20 34  ult..** If the 4
32650 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
32660 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  the sqlite3_resu
32670 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61  lt_text* interfa
32680 63 65 73 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  ces or.** sqlite
32690 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73  3_result_blob is
326a0 20 74 68 65 20 73 70 65 63 69 61 6c 20 63 6f 6e   the special con
326b0 73 74 61 6e 74 20 53 51 4c 49 54 45 5f 53 54 41  stant SQLITE_STA
326c0 54 49 43 2c 20 74 68 65 6e 20 53 51 4c 69 74 65  TIC, then SQLite
326d0 0a 2a 2a 20 61 73 73 75 6d 65 73 20 74 68 61 74  .** assumes that
326e0 20 74 68 65 20 74 65 78 74 20 6f 72 20 42 4c 4f   the text or BLO
326f0 42 20 72 65 73 75 6c 74 20 69 73 20 69 6e 20 63  B result is in c
32700 6f 6e 73 74 61 6e 74 20 73 70 61 63 65 20 61 6e  onstant space an
32710 64 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 63 6f  d does not.** co
32720 70 79 20 74 68 65 20 69 74 20 6f 72 20 63 61 6c  py the it or cal
32730 6c 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 77  l a destructor w
32740 68 65 6e 20 69 74 20 68 61 73 20 66 69 6e 69 73  hen it has finis
32750 68 65 64 20 75 73 69 6e 67 20 74 68 61 74 20 72  hed using that r
32760 65 73 75 6c 74 2e 0a 2a 2a 20 49 66 20 74 68 65  esult..** If the
32770 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   4th parameter t
32780 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65  o the sqlite3_re
32790 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72  sult_text* inter
327a0 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69  faces.** or sqli
327b0 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20  te3_result_blob 
327c0 69 73 20 74 68 65 20 73 70 65 63 69 61 6c 20 63  is the special c
327d0 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54 45 5f 54  onstant SQLITE_T
327e0 52 41 4e 53 49 45 4e 54 0a 2a 2a 20 74 68 65 6e  RANSIENT.** then
327f0 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20   SQLite makes a 
32800 63 6f 70 79 20 6f 66 20 74 68 65 20 72 65 73 75  copy of the resu
32810 6c 74 20 69 6e 74 6f 20 73 70 61 63 65 20 6f 62  lt into space ob
32820 74 61 69 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 66  tained from.** f
32830 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  rom [sqlite3_mal
32840 6c 6f 63 28 29 5d 20 62 65 66 6f 72 65 20 69 74  loc()] before it
32850 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20   returns..**.** 
32860 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
32870 6c 74 5f 76 61 6c 75 65 28 29 20 69 6e 74 65 72  lt_value() inter
32880 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65  face sets the re
32890 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61  sult of.** the a
328a0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
328b0 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
328c0 65 20 61 20 63 6f 70 79 20 74 68 65 0a 2a 2a 20  e a copy the.** 
328d0 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c  [unprotected sql
328e0 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
328f0 63 74 20 73 70 65 63 69 66 69 65 64 20 62 79 20  ct specified by 
32900 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65  the 2nd paramete
32910 72 2e 20 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74  r.  The.** sqlit
32920 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28  e3_result_value(
32930 29 20 69 6e 74 65 72 66 61 63 65 20 6d 61 6b 65  ) interface make
32940 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
32950 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a  [sqlite3_value].
32960 2a 2a 20 73 6f 20 74 68 61 74 20 74 68 65 20 5b  ** so that the [
32970 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 73  sqlite3_value] s
32980 70 65 63 69 66 69 65 64 20 69 6e 20 74 68 65 20  pecified in the 
32990 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 63 68  parameter may ch
329a0 61 6e 67 65 20 6f 72 0a 2a 2a 20 62 65 20 64 65  ange or.** be de
329b0 61 6c 6c 6f 63 61 74 65 64 20 61 66 74 65 72 20  allocated after 
329c0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76  sqlite3_result_v
329d0 61 6c 75 65 28 29 20 72 65 74 75 72 6e 73 20 77  alue() returns w
329e0 69 74 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20  ithout harm..** 
329f0 41 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c  A [protected sql
32a00 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
32a10 63 74 20 6d 61 79 20 61 6c 77 61 79 73 20 62 65  ct may always be
32a20 20 75 73 65 64 20 77 68 65 72 65 20 61 6e 0a 2a   used where an.*
32a30 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73  * [unprotected s
32a40 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
32a50 6a 65 63 74 20 69 73 20 72 65 71 75 69 72 65 64  ject is required
32a60 2c 20 73 6f 20 65 69 74 68 65 72 0a 2a 2a 20 6b  , so either.** k
32a70 69 6e 64 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f  ind of [sqlite3_
32a80 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 63 61  value] object ca
32a90 6e 20 62 65 20 75 73 65 64 20 77 69 74 68 20 74  n be used with t
32aa0 68 69 73 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  his interface..*
32ab0 2a 0a 2a 2a 20 49 66 20 74 68 65 73 65 20 72 6f  *.** If these ro
32ac0 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65  utines are calle
32ad0 64 20 66 72 6f 6d 20 77 69 74 68 69 6e 20 74 68  d from within th
32ae0 65 20 64 69 66 66 65 72 65 6e 74 20 74 68 72 65  e different thre
32af0 61 64 0a 2a 2a 20 74 68 61 6e 20 74 68 65 20 6f  ad.** than the o
32b00 6e 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68  ne containing th
32b10 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
32b20 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74  fined function t
32b30 68 61 74 20 72 65 63 65 69 76 65 64 0a 2a 2a 20  hat received.** 
32b40 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  the [sqlite3_con
32b50 74 65 78 74 5d 20 70 6f 69 6e 74 65 72 2c 20 74  text] pointer, t
32b60 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75  he results are u
32b70 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  ndefined..**.** 
32b80 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
32b90 2a 20 7b 48 31 36 34 30 33 7d 20 54 68 65 20 64  * {H16403} The d
32ba0 65 66 61 75 6c 74 20 72 65 74 75 72 6e 20 76 61  efault return va
32bb0 6c 75 65 20 66 72 6f 6d 20 61 6e 79 20 53 51 4c  lue from any SQL
32bc0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 4e 55 4c   function is NUL
32bd0 4c 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 30 36  L..**.** {H16406
32be0 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72  } The [sqlite3_r
32bf0 65 73 75 6c 74 5f 62 6c 6f 62 28 43 2c 56 2c 4e  esult_blob(C,V,N
32c00 2c 44 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63  ,D)] interface c
32c10 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20 20  hanges the.**   
32c20 20 20 20 20 20 20 20 72 65 74 75 72 6e 20 76 61         return va
32c30 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20  lue of function 
32c40 43 20 74 6f 20 62 65 20 61 20 42 4c 4f 42 20 74  C to be a BLOB t
32c50 68 61 74 20 69 73 20 4e 20 62 79 74 65 73 0a 2a  hat is N bytes.*
32c60 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20 6c 65  *          in le
32c70 6e 67 74 68 20 61 6e 64 20 77 69 74 68 20 63 6f  ngth and with co
32c80 6e 74 65 6e 74 20 70 6f 69 6e 74 65 64 20 74 6f  ntent pointed to
32c90 20 62 79 20 56 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31   by V..**.** {H1
32ca0 36 34 30 39 7d 20 54 68 65 20 5b 73 71 6c 69 74  6409} The [sqlit
32cb0 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65  e3_result_double
32cc0 28 43 2c 56 29 5d 20 69 6e 74 65 72 66 61 63 65  (C,V)] interface
32cd0 20 63 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20   changes the.** 
32ce0 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 20           return 
32cf0 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 6f  value of functio
32d00 6e 20 43 20 74 6f 20 62 65 20 74 68 65 20 66 6c  n C to be the fl
32d10 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c  oating point val
32d20 75 65 20 56 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36  ue V..**.** {H16
32d30 34 31 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  412} The [sqlite
32d40 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 43  3_result_error(C
32d50 2c 56 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65  ,V,N)] interface
32d60 20 63 68 61 6e 67 65 73 20 74 68 65 20 72 65 74   changes the ret
32d70 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  urn.**          
32d80 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 6f  value of functio
32d90 6e 20 43 20 74 6f 20 62 65 20 61 6e 20 65 78 63  n C to be an exc
32da0 65 70 74 69 6f 6e 20 77 69 74 68 20 65 72 72 6f  eption with erro
32db0 72 20 63 6f 64 65 0a 2a 2a 20 20 20 20 20 20 20  r code.**       
32dc0 20 20 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52     [SQLITE_ERROR
32dd0 5d 20 61 6e 64 20 61 20 55 54 46 2d 38 20 65 72  ] and a UTF-8 er
32de0 72 6f 72 20 6d 65 73 73 61 67 65 20 63 6f 70 69  ror message copi
32df0 65 64 20 66 72 6f 6d 20 56 20 75 70 20 74 6f 20  ed from V up to 
32e00 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
32e10 66 69 72 73 74 20 7a 65 72 6f 20 62 79 74 65 20  first zero byte 
32e20 6f 72 20 75 6e 74 69 6c 20 4e 20 62 79 74 65 73  or until N bytes
32e30 20 61 72 65 20 72 65 61 64 20 69 66 20 4e 20 69   are read if N i
32e40 73 20 70 6f 73 69 74 69 76 65 2e 0a 2a 2a 0a 2a  s positive..**.*
32e50 2a 20 7b 48 31 36 34 31 35 7d 20 54 68 65 20 5b  * {H16415} The [
32e60 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
32e70 72 72 6f 72 31 36 28 43 2c 56 2c 4e 29 5d 20 69  rror16(C,V,N)] i
32e80 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67 65 73  nterface changes
32e90 20 74 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20 20   the return.**  
32ea0 20 20 20 20 20 20 20 20 76 61 6c 75 65 20 6f 66          value of
32eb0 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62   function C to b
32ec0 65 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 20 77  e an exception w
32ed0 69 74 68 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a  ith error code.*
32ee0 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49  *          [SQLI
32ef0 54 45 5f 45 52 52 4f 52 5d 20 61 6e 64 20 61 20  TE_ERROR] and a 
32f00 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79  UTF-16 native by
32f10 74 65 20 6f 72 64 65 72 20 65 72 72 6f 72 20 6d  te order error m
32f20 65 73 73 61 67 65 0a 2a 2a 20 20 20 20 20 20 20  essage.**       
32f30 20 20 20 63 6f 70 69 65 64 20 66 72 6f 6d 20 56     copied from V
32f40 20 75 70 20 74 6f 20 74 68 65 20 66 69 72 73 74   up to the first
32f50 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72   zero terminator
32f60 20 6f 72 20 75 6e 74 69 6c 20 4e 20 62 79 74 65   or until N byte
32f70 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 72  s.**          ar
32f80 65 20 72 65 61 64 20 69 66 20 4e 20 69 73 20 70  e read if N is p
32f90 6f 73 69 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b  ositive..**.** {
32fa0 48 31 36 34 31 38 7d 20 54 68 65 20 5b 73 71 6c  H16418} The [sql
32fb0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
32fc0 72 5f 74 6f 6f 62 69 67 28 43 29 5d 20 69 6e 74  r_toobig(C)] int
32fd0 65 72 66 61 63 65 20 63 68 61 6e 67 65 73 20 74  erface changes t
32fe0 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20 20 20 20  he return.**    
32ff0 20 20 20 20 20 20 76 61 6c 75 65 20 6f 66 20 74        value of t
33000 68 65 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f  he function C to
33010 20 62 65 20 61 6e 20 65 78 63 65 70 74 69 6f 6e   be an exception
33020 20 77 69 74 68 20 65 72 72 6f 72 20 63 6f 64 65   with error code
33030 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51  .**          [SQ
33040 4c 49 54 45 5f 54 4f 4f 42 49 47 5d 20 61 6e 64  LITE_TOOBIG] and
33050 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20   an appropriate 
33060 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a  error message..*
33070 2a 0a 2a 2a 20 7b 48 31 36 34 32 31 7d 20 54 68  *.** {H16421} Th
33080 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  e [sqlite3_resul
33090 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28 43 29  t_error_nomem(C)
330a0 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e  ] interface chan
330b0 67 65 73 20 74 68 65 20 72 65 74 75 72 6e 0a 2a  ges the return.*
330c0 2a 20 20 20 20 20 20 20 20 20 20 76 61 6c 75 65  *          value
330d0 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e   of the function
330e0 20 43 20 74 6f 20 62 65 20 61 6e 20 65 78 63 65   C to be an exce
330f0 70 74 69 6f 6e 20 77 69 74 68 20 65 72 72 6f 72  ption with error
33100 20 63 6f 64 65 0a 2a 2a 20 20 20 20 20 20 20 20   code.**        
33110 20 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d    [SQLITE_NOMEM]
33120 20 61 6e 64 20 61 6e 20 61 70 70 72 6f 70 72 69   and an appropri
33130 61 74 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67  ate error messag
33140 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 32 34  e..**.** {H16424
33150 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72  } The [sqlite3_r
33160 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65  esult_error_code
33170 28 43 2c 45 29 5d 20 69 6e 74 65 72 66 61 63 65  (C,E)] interface
33180 20 63 68 61 6e 67 65 73 20 74 68 65 20 72 65 74   changes the ret
33190 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  urn.**          
331a0 76 61 6c 75 65 20 6f 66 20 74 68 65 20 66 75 6e  value of the fun
331b0 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 61 6e  ction C to be an
331c0 20 65 78 63 65 70 74 69 6f 6e 20 77 69 74 68 20   exception with 
331d0 65 72 72 6f 72 20 63 6f 64 65 20 45 2e 0a 2a 2a  error code E..**
331e0 20 20 20 20 20 20 20 20 20 20 54 68 65 20 65 72            The er
331f0 72 6f 72 20 6d 65 73 73 61 67 65 20 74 65 78 74  ror message text
33200 20 69 73 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a   is unchanged..*
33210 2a 0a 2a 2a 20 7b 48 31 36 34 32 37 7d 20 54 68  *.** {H16427} Th
33220 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  e [sqlite3_resul
33230 74 5f 69 6e 74 28 43 2c 56 29 5d 20 69 6e 74 65  t_int(C,V)] inte
33240 72 66 61 63 65 20 63 68 61 6e 67 65 73 20 74 68  rface changes th
33250 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65  e.**          re
33260 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 66 75  turn value of fu
33270 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 74  nction C to be t
33280 68 65 20 33 32 2d 62 69 74 20 69 6e 74 65 67 65  he 32-bit intege
33290 72 20 76 61 6c 75 65 20 56 2e 0a 2a 2a 0a 2a 2a  r value V..**.**
332a0 20 7b 48 31 36 34 33 30 7d 20 54 68 65 20 5b 73   {H16430} The [s
332b0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e  qlite3_result_in
332c0 74 36 34 28 43 2c 56 29 5d 20 69 6e 74 65 72 66  t64(C,V)] interf
332d0 61 63 65 20 63 68 61 6e 67 65 73 20 74 68 65 0a  ace changes the.
332e0 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75  **          retu
332f0 72 6e 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63  rn value of func
33300 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 74 68 65  tion C to be the
33310 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72 20   64-bit integer 
33320 76 61 6c 75 65 20 56 2e 0a 2a 2a 0a 2a 2a 20 7b  value V..**.** {
33330 48 31 36 34 33 33 7d 20 54 68 65 20 5b 73 71 6c  H16433} The [sql
33340 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c  ite3_result_null
33350 28 43 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63  (C)] interface c
33360 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20 20  hanges the.**   
33370 20 20 20 20 20 20 20 72 65 74 75 72 6e 20 76 61         return va
33380 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20  lue of function 
33390 43 20 74 6f 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a  C to be NULL..**
333a0 0a 2a 2a 20 7b 48 31 36 34 33 36 7d 20 54 68 65  .** {H16436} The
333b0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
333c0 5f 74 65 78 74 28 43 2c 56 2c 4e 2c 44 29 5d 20  _text(C,V,N,D)] 
333d0 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67 65  interface change
333e0 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  s the.**        
333f0 20 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f    return value o
33400 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20  f function C to 
33410 62 65 20 74 68 65 20 55 54 46 2d 38 20 73 74 72  be the UTF-8 str
33420 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ing.**          
33430 56 20 75 70 20 74 6f 20 74 68 65 20 66 69 72 73  V up to the firs
33440 74 20 7a 65 72 6f 20 69 66 20 4e 20 69 73 20 6e  t zero if N is n
33450 65 67 61 74 69 76 65 0a 2a 2a 20 20 20 20 20 20  egative.**      
33460 20 20 20 20 6f 72 20 74 68 65 20 66 69 72 73 74      or the first
33470 20 4e 20 62 79 74 65 73 20 6f 66 20 56 20 69 66   N bytes of V if
33480 20 4e 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69   N is non-negati
33490 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 33  ve..**.** {H1643
334a0 39 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  9} The [sqlite3_
334b0 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28 43 2c  result_text16(C,
334c0 56 2c 4e 2c 44 29 5d 20 69 6e 74 65 72 66 61 63  V,N,D)] interfac
334d0 65 20 63 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a  e changes the.**
334e0 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e            return
334f0 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 69   value of functi
33500 6f 6e 20 43 20 74 6f 20 62 65 20 74 68 65 20 55  on C to be the U
33510 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74  TF-16 native byt
33520 65 20 6f 72 64 65 72 0a 2a 2a 20 20 20 20 20 20  e order.**      
33530 20 20 20 20 73 74 72 69 6e 67 20 56 20 75 70 20      string V up 
33540 74 6f 20 74 68 65 20 66 69 72 73 74 20 7a 65 72  to the first zer
33550 6f 20 69 66 20 4e 20 69 73 20 6e 65 67 61 74 69  o if N is negati
33560 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  ve.**          o
33570 72 20 74 68 65 20 66 69 72 73 74 20 4e 20 62 79  r the first N by
33580 74 65 73 20 6f 66 20 56 20 69 66 20 4e 20 69 73  tes of V if N is
33590 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2e 0a 2a   non-negative..*
335a0 2a 0a 2a 2a 20 7b 48 31 36 34 34 32 7d 20 54 68  *.** {H16442} Th
335b0 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  e [sqlite3_resul
335c0 74 5f 74 65 78 74 31 36 62 65 28 43 2c 56 2c 4e  t_text16be(C,V,N
335d0 2c 44 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63  ,D)] interface c
335e0 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20 20  hanges the.**   
335f0 20 20 20 20 20 20 20 72 65 74 75 72 6e 20 76 61         return va
33600 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20  lue of function 
33610 43 20 74 6f 20 62 65 20 74 68 65 20 55 54 46 2d  C to be the UTF-
33620 31 36 20 62 69 67 2d 65 6e 64 69 61 6e 0a 2a 2a  16 big-endian.**
33630 20 20 20 20 20 20 20 20 20 20 73 74 72 69 6e 67            string
33640 20 56 20 75 70 20 74 6f 20 74 68 65 20 66 69 72   V up to the fir
33650 73 74 20 7a 65 72 6f 20 69 66 20 4e 20 69 73 20  st zero if N is 
33660 6e 65 67 61 74 69 76 65 0a 2a 2a 20 20 20 20 20  negative.**     
33670 20 20 20 20 20 6f 72 20 74 68 65 20 66 69 72 73       or the firs
33680 74 20 4e 20 62 79 74 65 73 20 6f 72 20 56 20 69  t N bytes or V i
33690 66 20 4e 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74  f N is non-negat
336a0 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34  ive..**.** {H164
336b0 34 35 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  45} The [sqlite3
336c0 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65  _result_text16le
336d0 28 43 2c 56 2c 4e 2c 44 29 5d 20 69 6e 74 65 72  (C,V,N,D)] inter
336e0 66 61 63 65 20 63 68 61 6e 67 65 73 20 74 68 65  face changes the
336f0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74  .**          ret
33700 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 66 75 6e  urn value of fun
33710 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 74 68  ction C to be th
33720 65 20 55 54 46 2d 31 36 20 6c 69 74 74 6c 65 2d  e UTF-16 little-
33730 65 6e 64 69 61 6e 0a 2a 2a 20 20 20 20 20 20 20  endian.**       
33740 20 20 20 73 74 72 69 6e 67 20 56 20 75 70 20 74     string V up t
33750 6f 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f  o the first zero
33760 20 69 66 20 4e 20 69 73 20 6e 65 67 61 74 69 76   if N is negativ
33770 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72  e.**          or
33780 20 74 68 65 20 66 69 72 73 74 20 4e 20 62 79 74   the first N byt
33790 65 73 20 6f 66 20 56 20 69 66 20 4e 20 69 73 20  es of V if N is 
337a0 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2e 0a 2a 2a  non-negative..**
337b0 0a 2a 2a 20 7b 48 31 36 34 34 38 7d 20 54 68 65  .** {H16448} The
337c0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
337d0 5f 76 61 6c 75 65 28 43 2c 56 29 5d 20 69 6e 74  _value(C,V)] int
337e0 65 72 66 61 63 65 20 63 68 61 6e 67 65 73 20 74  erface changes t
337f0 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72  he.**          r
33800 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 66  eturn value of f
33810 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20  unction C to be 
33820 74 68 65 20 5b 75 6e 70 72 6f 74 65 63 74 65 64  the [unprotected
33830 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a   sqlite3_value].
33840 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 62 6a 65  **          obje
33850 63 74 20 56 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36  ct V..**.** {H16
33860 34 35 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  451} The [sqlite
33870 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f  3_result_zeroblo
33880 62 28 43 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63  b(C,N)] interfac
33890 65 20 63 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a  e changes the.**
338a0 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e            return
338b0 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 69   value of functi
338c0 6f 6e 20 43 20 74 6f 20 62 65 20 61 6e 20 4e 2d  on C to be an N-
338d0 62 79 74 65 20 42 4c 4f 42 20 6f 66 20 61 6c 6c  byte BLOB of all
338e0 20 7a 65 72 6f 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48   zeros..**.** {H
338f0 31 36 34 35 34 7d 20 54 68 65 20 5b 73 71 6c 69  16454} The [sqli
33900 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
33910 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
33920 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
33930 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  )].**          i
33940 6e 74 65 72 66 61 63 65 73 20 6d 61 6b 65 20 61  nterfaces make a
33950 20 63 6f 70 79 20 6f 66 20 74 68 65 69 72 20 65   copy of their e
33960 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72  rror message str
33970 69 6e 67 73 20 62 65 66 6f 72 65 0a 2a 2a 20 20  ings before.**  
33980 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 69 6e          returnin
33990 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 35 37  g..**.** {H16457
339a0 7d 20 49 66 20 74 68 65 20 44 20 64 65 73 74 72  } If the D destr
339b0 75 63 74 6f 72 20 70 61 72 61 6d 65 74 65 72 20  uctor parameter 
339c0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  to [sqlite3_resu
339d0 6c 74 5f 62 6c 6f 62 28 43 2c 56 2c 4e 2c 44 29  lt_blob(C,V,N,D)
339e0 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  ],.**          [
339f0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
33a00 65 78 74 28 43 2c 56 2c 4e 2c 44 29 5d 2c 20 5b  ext(C,V,N,D)], [
33a10 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
33a20 65 78 74 31 36 28 43 2c 56 2c 4e 2c 44 29 5d 2c  ext16(C,V,N,D)],
33a30 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
33a40 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
33a50 74 31 36 62 65 28 43 2c 56 2c 4e 2c 44 29 5d 2c  t16be(C,V,N,D)],
33a60 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   or.**          
33a70 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
33a80 74 65 78 74 31 36 6c 65 28 43 2c 56 2c 4e 2c 44  text16le(C,V,N,D
33a90 29 5d 20 69 73 20 74 68 65 20 63 6f 6e 73 74 61  )] is the consta
33aa0 6e 74 20 5b 53 51 4c 49 54 45 5f 53 54 41 54 49  nt [SQLITE_STATI
33ab0 43 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  C].**          t
33ac0 68 65 6e 20 6e 6f 20 64 65 73 74 72 75 63 74 6f  hen no destructo
33ad0 72 20 69 73 20 65 76 65 72 20 63 61 6c 6c 65 64  r is ever called
33ae0 20 6f 6e 20 74 68 65 20 70 6f 69 6e 74 65 72 20   on the pointer 
33af0 56 20 61 6e 64 20 53 51 4c 69 74 65 0a 2a 2a 20  V and SQLite.** 
33b00 20 20 20 20 20 20 20 20 20 61 73 73 75 6d 65 73           assumes
33b10 20 74 68 61 74 20 56 20 69 73 20 69 6d 6d 75 74   that V is immut
33b20 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36  able..**.** {H16
33b30 34 36 30 7d 20 49 66 20 74 68 65 20 44 20 64 65  460} If the D de
33b40 73 74 72 75 63 74 6f 72 20 70 61 72 61 6d 65 74  structor paramet
33b50 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72  er to [sqlite3_r
33b60 65 73 75 6c 74 5f 62 6c 6f 62 28 43 2c 56 2c 4e  esult_blob(C,V,N
33b70 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20  ,D)],.**        
33b80 20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c    [sqlite3_resul
33b90 74 5f 74 65 78 74 28 43 2c 56 2c 4e 2c 44 29 5d  t_text(C,V,N,D)]
33ba0 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  , [sqlite3_resul
33bb0 74 5f 74 65 78 74 31 36 28 43 2c 56 2c 4e 2c 44  t_text16(C,V,N,D
33bc0 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  )],.**          
33bd0 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
33be0 74 65 78 74 31 36 62 65 28 43 2c 56 2c 4e 2c 44  text16be(C,V,N,D
33bf0 29 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20  )], or.**       
33c00 20 20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75     [sqlite3_resu
33c10 6c 74 5f 74 65 78 74 31 36 6c 65 28 43 2c 56 2c  lt_text16le(C,V,
33c20 4e 2c 44 29 5d 20 69 73 20 74 68 65 20 63 6f 6e  N,D)] is the con
33c30 73 74 61 6e 74 0a 2a 2a 20 20 20 20 20 20 20 20  stant.**        
33c40 20 20 5b 53 51 4c 49 54 45 5f 54 52 41 4e 53 49    [SQLITE_TRANSI
33c50 45 4e 54 5d 20 74 68 65 6e 20 74 68 65 20 69 6e  ENT] then the in
33c60 74 65 72 66 61 63 65 73 20 6d 61 6b 65 73 20 61  terfaces makes a
33c70 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20   copy of the.** 
33c80 20 20 20 20 20 20 20 20 20 63 6f 6e 74 65 6e 74           content
33c90 20 6f 66 20 56 20 61 6e 64 20 72 65 74 61 69 6e   of V and retain
33ca0 73 20 74 68 65 20 63 6f 70 79 2e 0a 2a 2a 0a 2a  s the copy..**.*
33cb0 2a 20 7b 48 31 36 34 36 33 7d 20 49 66 20 74 68  * {H16463} If th
33cc0 65 20 44 20 64 65 73 74 72 75 63 74 6f 72 20 70  e D destructor p
33cd0 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c  arameter to [sql
33ce0 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62  ite3_result_blob
33cf0 28 43 2c 56 2c 4e 2c 44 29 5d 2c 0a 2a 2a 20 20  (C,V,N,D)],.**  
33d00 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
33d10 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 43 2c 56  _result_text(C,V
33d20 2c 4e 2c 44 29 5d 2c 20 5b 73 71 6c 69 74 65 33  ,N,D)], [sqlite3
33d30 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28 43  _result_text16(C
33d40 2c 56 2c 4e 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20  ,V,N,D)],.**    
33d50 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 72        [sqlite3_r
33d60 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28 43  esult_text16be(C
33d70 2c 56 2c 4e 2c 44 29 5d 2c 20 6f 72 0a 2a 2a 20  ,V,N,D)], or.** 
33d80 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
33d90 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c  3_result_text16l
33da0 65 28 43 2c 56 2c 4e 2c 44 29 5d 20 69 73 20 73  e(C,V,N,D)] is s
33db0 6f 6d 65 20 76 61 6c 75 65 20 6f 74 68 65 72 20  ome value other 
33dc0 74 68 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  than.**         
33dd0 20 74 68 65 20 63 6f 6e 73 74 61 6e 74 73 20 5b   the constants [
33de0 53 51 4c 49 54 45 5f 53 54 41 54 49 43 5d 20 61  SQLITE_STATIC] a
33df0 6e 64 20 5b 53 51 4c 49 54 45 5f 54 52 41 4e 53  nd [SQLITE_TRANS
33e00 49 45 4e 54 5d 20 74 68 65 6e 0a 2a 2a 20 20 20  IENT] then.**   
33e10 20 20 20 20 20 20 20 53 51 4c 69 74 65 20 77 69         SQLite wi
33e20 6c 6c 20 69 6e 76 6f 6b 65 20 74 68 65 20 64 65  ll invoke the de
33e30 73 74 72 75 63 74 6f 72 20 44 20 77 69 74 68 20  structor D with 
33e40 56 20 61 73 20 69 74 73 20 6f 6e 6c 79 20 61 72  V as its only ar
33e50 67 75 6d 65 6e 74 0a 2a 2a 20 20 20 20 20 20 20  gument.**       
33e60 20 20 20 77 68 65 6e 20 69 74 20 68 61 73 20 66     when it has f
33e70 69 6e 69 73 68 65 64 20 77 69 74 68 20 74 68 65  inished with the
33e80 20 56 20 76 61 6c 75 65 2e 0a 2a 2f 0a 76 6f 69   V value..*/.voi
33e90 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
33ea0 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f  _blob(sqlite3_co
33eb0 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f  ntext*, const vo
33ec0 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a  id*, int, void(*
33ed0 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20  )(void*));.void 
33ee0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 64  sqlite3_result_d
33ef0 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f  ouble(sqlite3_co
33f00 6e 74 65 78 74 2a 2c 20 64 6f 75 62 6c 65 29 3b  ntext*, double);
33f10 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
33f20 73 75 6c 74 5f 65 72 72 6f 72 28 73 71 6c 69 74  sult_error(sqlit
33f30 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e  e3_context*, con
33f40 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 29 3b 0a  st char*, int);.
33f50 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
33f60 75 6c 74 5f 65 72 72 6f 72 31 36 28 73 71 6c 69  ult_error16(sqli
33f70 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f  te3_context*, co
33f80 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 29 3b  nst void*, int);
33f90 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
33fa0 73 75 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f 62 69  sult_error_toobi
33fb0 67 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  g(sqlite3_contex
33fc0 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  t*);.void sqlite
33fd0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 6e  3_result_error_n
33fe0 6f 6d 65 6d 28 73 71 6c 69 74 65 33 5f 63 6f 6e  omem(sqlite3_con
33ff0 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c  text*);.void sql
34000 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
34010 72 5f 63 6f 64 65 28 73 71 6c 69 74 65 33 5f 63  r_code(sqlite3_c
34020 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 76  ontext*, int);.v
34030 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
34040 6c 74 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 63  lt_int(sqlite3_c
34050 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 76  ontext*, int);.v
34060 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
34070 6c 74 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33  lt_int64(sqlite3
34080 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74  _context*, sqlit
34090 65 33 5f 69 6e 74 36 34 29 3b 0a 76 6f 69 64 20  e3_int64);.void 
340a0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e  sqlite3_result_n
340b0 75 6c 6c 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ull(sqlite3_cont
340c0 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69  ext*);.void sqli
340d0 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28  te3_result_text(
340e0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
340f0 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69  , const char*, i
34100 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64  nt, void(*)(void
34110 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  *));.void sqlite
34120 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28  3_result_text16(
34130 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
34140 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
34150 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64  nt, void(*)(void
34160 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  *));.void sqlite
34170 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c  3_result_text16l
34180 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  e(sqlite3_contex
34190 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  t*, const void*,
341a0 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69   int,void(*)(voi
341b0 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  d*));.void sqlit
341c0 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
341d0 62 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  be(sqlite3_conte
341e0 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  xt*, const void*
341f0 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f  , int,void(*)(vo
34200 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69  id*));.void sqli
34210 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65  te3_result_value
34220 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
34230 2a 2c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  *, sqlite3_value
34240 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  *);.void sqlite3
34250 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62  _result_zeroblob
34260 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
34270 2a 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a  *, int n);../*.*
34280 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 66 69  * CAPI3REF: Defi
34290 6e 65 20 4e 65 77 20 43 6f 6c 6c 61 74 69 6e 67  ne New Collating
342a0 20 53 65 71 75 65 6e 63 65 73 20 7b 48 31 36 36   Sequences {H166
342b0 30 30 7d 20 3c 53 32 30 33 30 30 3e 0a 2a 2a 0a  00} <S20300>.**.
342c0 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f  ** These functio
342d0 6e 73 20 61 72 65 20 75 73 65 64 20 74 6f 20 61  ns are used to a
342e0 64 64 20 6e 65 77 20 63 6f 6c 6c 61 74 69 6f 6e  dd new collation
342f0 20 73 65 71 75 65 6e 63 65 73 20 74 6f 20 74 68   sequences to th
34300 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  e.** [database c
34310 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63 69  onnection] speci
34320 66 69 65 64 20 61 73 20 74 68 65 20 66 69 72 73  fied as the firs
34330 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a  t argument..**.*
34340 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  * The name of th
34350 65 20 6e 65 77 20 63 6f 6c 6c 61 74 69 6f 6e 20  e new collation 
34360 73 65 71 75 65 6e 63 65 20 69 73 20 73 70 65 63  sequence is spec
34370 69 66 69 65 64 20 61 73 20 61 20 55 54 46 2d 38  ified as a UTF-8
34380 20 73 74 72 69 6e 67 0a 2a 2a 20 66 6f 72 20 73   string.** for s
34390 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
343a0 6c 6c 61 74 69 6f 6e 28 29 20 61 6e 64 20 73 71  llation() and sq
343b0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
343c0 6c 61 74 69 6f 6e 5f 76 32 28 29 0a 2a 2a 20 61  lation_v2().** a
343d0 6e 64 20 61 20 55 54 46 2d 31 36 20 73 74 72 69  nd a UTF-16 stri
343e0 6e 67 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63  ng for sqlite3_c
343f0 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31  reate_collation1
34400 36 28 29 2e 20 49 6e 20 61 6c 6c 20 63 61 73 65  6(). In all case
34410 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 69 73  s.** the name is
34420 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 73   passed as the s
34430 65 63 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61  econd function a
34440 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54  rgument..**.** T
34450 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  he third argumen
34460 74 20 6d 61 79 20 62 65 20 6f 6e 65 20 6f 66 20  t may be one of 
34470 74 68 65 20 63 6f 6e 73 74 61 6e 74 73 20 5b 53  the constants [S
34480 51 4c 49 54 45 5f 55 54 46 38 5d 2c 0a 2a 2a 20  QLITE_UTF8],.** 
34490 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d  [SQLITE_UTF16LE]
344a0 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 31   or [SQLITE_UTF1
344b0 36 42 45 5d 2c 20 69 6e 64 69 63 61 74 69 6e 67  6BE], indicating
344c0 20 74 68 61 74 20 74 68 65 20 75 73 65 72 2d 73   that the user-s
344d0 75 70 70 6c 69 65 64 0a 2a 2a 20 72 6f 75 74 69  upplied.** routi
344e0 6e 65 20 65 78 70 65 63 74 73 20 74 6f 20 62 65  ne expects to be
344f0 20 70 61 73 73 65 64 20 70 6f 69 6e 74 65 72 73   passed pointers
34500 20 74 6f 20 73 74 72 69 6e 67 73 20 65 6e 63 6f   to strings enco
34510 64 65 64 20 75 73 69 6e 67 20 55 54 46 2d 38 2c  ded using UTF-8,
34520 0a 2a 2a 20 55 54 46 2d 31 36 20 6c 69 74 74 6c  .** UTF-16 littl
34530 65 2d 65 6e 64 69 61 6e 2c 20 6f 72 20 55 54 46  e-endian, or UTF
34540 2d 31 36 20 62 69 67 2d 65 6e 64 69 61 6e 2c 20  -16 big-endian, 
34550 72 65 73 70 65 63 74 69 76 65 6c 79 2e 20 54 68  respectively. Th
34560 65 0a 2a 2a 20 74 68 69 72 64 20 61 72 67 75 6d  e.** third argum
34570 65 6e 74 20 6d 69 67 68 74 20 61 6c 73 6f 20 62  ent might also b
34580 65 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5f  e [SQLITE_UTF16_
34590 41 4c 49 47 4e 45 44 5d 20 74 6f 20 69 6e 64 69  ALIGNED] to indi
345a0 63 61 74 65 20 74 68 61 74 0a 2a 2a 20 74 68 65  cate that.** the
345b0 20 72 6f 75 74 69 6e 65 20 65 78 70 65 63 74 73   routine expects
345c0 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 31 36 2d   pointers to 16-
345d0 62 69 74 20 77 6f 72 64 20 61 6c 69 67 6e 65 64  bit word aligned
345e0 20 73 74 72 69 6e 67 73 0a 2a 2a 20 6f 66 20 55   strings.** of U
345f0 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74  TF-16 in the nat
34600 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 6f  ive byte order o
34610 66 20 74 68 65 20 68 6f 73 74 20 63 6f 6d 70 75  f the host compu
34620 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 20 70 6f 69  ter..**.** A poi
34630 6e 74 65 72 20 74 6f 20 74 68 65 20 75 73 65 72  nter to the user
34640 20 73 75 70 70 6c 69 65 64 20 72 6f 75 74 69 6e   supplied routin
34650 65 20 6d 75 73 74 20 62 65 20 70 61 73 73 65 64  e must be passed
34660 20 61 73 20 74 68 65 20 66 69 66 74 68 0a 2a 2a   as the fifth.**
34670 20 61 72 67 75 6d 65 6e 74 2e 20 20 49 66 20 69   argument.  If i
34680 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 69 73 20  t is NULL, this 
34690 69 73 20 74 68 65 20 73 61 6d 65 20 61 73 20 64  is the same as d
346a0 65 6c 65 74 69 6e 67 20 74 68 65 20 63 6f 6c 6c  eleting the coll
346b0 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63  ation.** sequenc
346c0 65 20 28 73 6f 20 74 68 61 74 20 53 51 4c 69 74  e (so that SQLit
346d0 65 20 63 61 6e 6e 6f 74 20 63 61 6c 6c 20 69 74  e cannot call it
346e0 20 61 6e 79 6d 6f 72 65 29 2e 0a 2a 2a 20 45 61   anymore)..** Ea
346f0 63 68 20 74 69 6d 65 20 74 68 65 20 61 70 70 6c  ch time the appl
34700 69 63 61 74 69 6f 6e 20 73 75 70 70 6c 69 65 64  ication supplied
34710 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 69 6e 76   function is inv
34720 6f 6b 65 64 2c 20 69 74 20 69 73 20 70 61 73 73  oked, it is pass
34730 65 64 0a 2a 2a 20 61 73 20 69 74 73 20 66 69 72  ed.** as its fir
34740 73 74 20 70 61 72 61 6d 65 74 65 72 20 61 20 63  st parameter a c
34750 6f 70 79 20 6f 66 20 74 68 65 20 76 6f 69 64 2a  opy of the void*
34760 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66   passed as the f
34770 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 0a 2a  ourth argument.*
34780 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 72 65  * to sqlite3_cre
34790 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 20  ate_collation() 
347a0 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  or sqlite3_creat
347b0 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 2e  e_collation16().
347c0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 72 65 6d 61 69  .**.** The remai
347d0 6e 69 6e 67 20 61 72 67 75 6d 65 6e 74 73 20 74  ning arguments t
347e0 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  o the applicatio
347f0 6e 2d 73 75 70 70 6c 69 65 64 20 72 6f 75 74 69  n-supplied routi
34800 6e 65 20 61 72 65 20 74 77 6f 20 73 74 72 69 6e  ne are two strin
34810 67 73 2c 0a 2a 2a 20 65 61 63 68 20 72 65 70 72  gs,.** each repr
34820 65 73 65 6e 74 65 64 20 62 79 20 61 20 28 6c 65  esented by a (le
34830 6e 67 74 68 2c 20 64 61 74 61 29 20 70 61 69 72  ngth, data) pair
34840 20 61 6e 64 20 65 6e 63 6f 64 65 64 20 69 6e 20   and encoded in 
34850 74 68 65 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20  the encoding.** 
34860 74 68 61 74 20 77 61 73 20 70 61 73 73 65 64 20  that was passed 
34870 61 73 20 74 68 65 20 74 68 69 72 64 20 61 72 67  as the third arg
34880 75 6d 65 6e 74 20 77 68 65 6e 20 74 68 65 20 63  ument when the c
34890 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63  ollation sequenc
348a0 65 20 77 61 73 0a 2a 2a 20 72 65 67 69 73 74 65  e was.** registe
348b0 72 65 64 2e 20 7b 45 4e 44 7d 20 20 54 68 65 20  red. {END}  The 
348c0 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69  application defi
348d0 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 72 6f  ned collation ro
348e0 75 74 69 6e 65 20 73 68 6f 75 6c 64 0a 2a 2a 20  utine should.** 
348f0 72 65 74 75 72 6e 20 6e 65 67 61 74 69 76 65 2c  return negative,
34900 20 7a 65 72 6f 20 6f 72 20 70 6f 73 69 74 69 76   zero or positiv
34910 65 20 69 66 20 74 68 65 20 66 69 72 73 74 20 73  e if the first s
34920 74 72 69 6e 67 20 69 73 20 6c 65 73 73 20 74 68  tring is less th
34930 61 6e 2c 0a 2a 2a 20 65 71 75 61 6c 20 74 6f 2c  an,.** equal to,
34940 20 6f 72 20 67 72 65 61 74 65 72 20 74 68 61 6e   or greater than
34950 20 74 68 65 20 73 65 63 6f 6e 64 20 73 74 72 69   the second stri
34960 6e 67 2e 20 69 2e 65 2e 20 28 53 54 52 49 4e 47  ng. i.e. (STRING
34970 31 20 2d 20 53 54 52 49 4e 47 32 29 2e 0a 2a 2a  1 - STRING2)..**
34980 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
34990 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
349a0 5f 76 32 28 29 20 77 6f 72 6b 73 20 6c 69 6b 65  _v2() works like
349b0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
349c0 63 6f 6c 6c 61 74 69 6f 6e 28 29 0a 2a 2a 20 65  collation().** e
349d0 78 63 65 70 74 20 74 68 61 74 20 69 74 20 74 61  xcept that it ta
349e0 6b 65 73 20 61 6e 20 65 78 74 72 61 20 61 72 67  kes an extra arg
349f0 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61  ument which is a
34a00 20 64 65 73 74 72 75 63 74 6f 72 20 66 6f 72 0a   destructor for.
34a10 2a 2a 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e  ** the collation
34a20 2e 20 20 54 68 65 20 64 65 73 74 72 75 63 74 6f  .  The destructo
34a30 72 20 69 73 20 63 61 6c 6c 65 64 20 77 68 65 6e  r is called when
34a40 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 69   the collation i
34a50 73 0a 2a 2a 20 64 65 73 74 72 6f 79 65 64 20 61  s.** destroyed a
34a60 6e 64 20 69 73 20 70 61 73 73 65 64 20 61 20 63  nd is passed a c
34a70 6f 70 79 20 6f 66 20 74 68 65 20 66 6f 75 72 74  opy of the fourt
34a80 68 20 70 61 72 61 6d 65 74 65 72 20 76 6f 69 64  h parameter void
34a90 2a 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 6f 66 20  * pointer.** of 
34aa0 74 68 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61  the sqlite3_crea
34ab0 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28  te_collation_v2(
34ac0 29 2e 0a 2a 2a 20 43 6f 6c 6c 61 74 69 6f 6e 73  )..** Collations
34ad0 20 61 72 65 20 64 65 73 74 72 6f 79 65 64 20 77   are destroyed w
34ae0 68 65 6e 20 74 68 65 79 20 61 72 65 20 6f 76 65  hen they are ove
34af0 72 72 69 64 64 65 6e 20 62 79 20 6c 61 74 65 72  rridden by later
34b00 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 0a 2a 2a   calls to the.**
34b10 20 63 6f 6c 6c 61 74 69 6f 6e 20 63 72 65 61 74   collation creat
34b20 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72  ion functions or
34b30 20 77 68 65 6e 20 74 68 65 20 5b 64 61 74 61 62   when the [datab
34b40 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
34b50 69 73 20 63 6c 6f 73 65 64 0a 2a 2a 20 75 73 69  is closed.** usi
34b60 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73  ng [sqlite3_clos
34b70 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  e()]..**.** INVA
34b80 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48  RIANTS:.**.** {H
34b90 31 36 36 30 33 7d 20 41 20 73 75 63 63 65 73 73  16603} A success
34ba0 66 75 6c 20 63 61 6c 6c 20 74 6f 20 74 68 65 0a  ful call to the.
34bb0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
34bc0 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
34bd0 61 74 69 6f 6e 5f 76 32 28 42 2c 58 2c 45 2c 50  ation_v2(B,X,E,P
34be0 2c 46 2c 44 29 5d 20 69 6e 74 65 72 66 61 63 65  ,F,D)] interface
34bf0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 67  .**          reg
34c00 69 73 74 65 72 73 20 66 75 6e 63 74 69 6f 6e 20  isters function 
34c10 46 20 61 73 20 74 68 65 20 63 6f 6d 70 61 72 69  F as the compari
34c20 73 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 75 73 65  son function use
34c30 64 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20  d to.**         
34c40 20 69 6d 70 6c 65 6d 65 6e 74 20 63 6f 6c 6c 61   implement colla
34c50 74 69 6f 6e 20 58 20 6f 6e 20 74 68 65 20 5b 64  tion X on the [d
34c60 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
34c70 6f 6e 5d 20 42 20 66 6f 72 0a 2a 2a 20 20 20 20  on] B for.**    
34c80 20 20 20 20 20 20 64 61 74 61 62 61 73 65 73 20        databases 
34c90 68 61 76 69 6e 67 20 65 6e 63 6f 64 69 6e 67 20  having encoding 
34ca0 45 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 36 30 34  E..**.** {H16604
34cb0 7d 20 53 51 4c 69 74 65 20 75 6e 64 65 72 73 74  } SQLite underst
34cc0 61 6e 64 73 20 74 68 65 20 58 20 70 61 72 61 6d  ands the X param
34cd0 65 74 65 72 20 74 6f 0a 2a 2a 20 20 20 20 20 20  eter to.**      
34ce0 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 72 65      [sqlite3_cre
34cf0 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32  ate_collation_v2
34d00 28 42 2c 58 2c 45 2c 50 2c 46 2c 44 29 5d 20 61  (B,X,E,P,F,D)] a
34d10 73 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  s a zero-termina
34d20 74 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ted.**          
34d30 55 54 46 2d 38 20 73 74 72 69 6e 67 20 69 6e 20  UTF-8 string in 
34d40 77 68 69 63 68 20 63 61 73 65 20 69 73 20 69 67  which case is ig
34d50 6e 6f 72 65 64 20 66 6f 72 20 41 53 43 49 49 20  nored for ASCII 
34d60 63 68 61 72 61 63 74 65 72 73 20 61 6e 64 0a 2a  characters and.*
34d70 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 73 69  *          is si
34d80 67 6e 69 66 69 63 61 6e 74 20 66 6f 72 20 6e 6f  gnificant for no
34d90 6e 2d 41 53 43 49 49 20 63 68 61 72 61 63 74 65  n-ASCII characte
34da0 72 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 36 30  rs..**.** {H1660
34db0 36 7d 20 53 75 63 63 65 73 73 69 76 65 20 63 61  6} Successive ca
34dc0 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
34dd0 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
34de0 5f 76 32 28 42 2c 58 2c 45 2c 50 2c 46 2c 44 29  _v2(B,X,E,P,F,D)
34df0 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 69  ].**          wi
34e00 74 68 20 74 68 65 20 73 61 6d 65 20 76 61 6c 75  th the same valu
34e10 65 73 20 66 6f 72 20 42 2c 20 58 2c 20 61 6e 64  es for B, X, and
34e20 20 45 2c 20 6f 76 65 72 72 69 64 65 20 70 72 69   E, override pri
34e30 6f 72 20 76 61 6c 75 65 73 0a 2a 2a 20 20 20 20  or values.**    
34e40 20 20 20 20 20 20 6f 66 20 50 2c 20 46 2c 20 61        of P, F, a
34e50 6e 64 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36  nd D..**.** {H16
34e60 36 30 39 7d 20 49 66 20 74 68 65 20 64 65 73 74  609} If the dest
34e70 72 75 63 74 6f 72 20 44 20 69 6e 20 5b 73 71 6c  ructor D in [sql
34e80 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
34e90 61 74 69 6f 6e 5f 76 32 28 42 2c 58 2c 45 2c 50  ation_v2(B,X,E,P
34ea0 2c 46 2c 44 29 5d 0a 2a 2a 20 20 20 20 20 20 20  ,F,D)].**       
34eb0 20 20 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74     is not NULL t
34ec0 68 65 6e 20 69 74 20 69 73 20 63 61 6c 6c 65 64  hen it is called
34ed0 20 77 69 74 68 20 61 72 67 75 6d 65 6e 74 20 50   with argument P
34ee0 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20 20 20 20   when the.**    
34ef0 20 20 20 20 20 20 63 6f 6c 6c 61 74 69 6e 67 20        collating 
34f00 66 75 6e 63 74 69 6f 6e 20 69 73 20 64 72 6f 70  function is drop
34f10 70 65 64 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a  ped by SQLite..*
34f20 2a 0a 2a 2a 20 7b 48 31 36 36 31 32 7d 20 41 20  *.** {H16612} A 
34f30 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69  collating functi
34f40 6f 6e 20 69 73 20 64 72 6f 70 70 65 64 20 77 68  on is dropped wh
34f50 65 6e 20 69 74 20 69 73 20 6f 76 65 72 6c 6f 61  en it is overloa
34f60 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 36  ded..**.** {H166
34f70 31 35 7d 20 41 20 63 6f 6c 6c 61 74 69 6e 67 20  15} A collating 
34f80 66 75 6e 63 74 69 6f 6e 20 69 73 20 64 72 6f 70  function is drop
34f90 70 65 64 20 77 68 65 6e 20 74 68 65 20 64 61 74  ped when the dat
34fa0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
34fb0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20  .**          is 
34fc0 63 6c 6f 73 65 64 20 75 73 69 6e 67 20 5b 73 71  closed using [sq
34fd0 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 2e 0a  lite3_close()]..
34fe0 2a 2a 0a 2a 2a 20 7b 48 31 36 36 31 38 7d 20 54  **.** {H16618} T
34ff0 68 65 20 70 6f 69 6e 74 65 72 20 50 20 69 6e 20  he pointer P in 
35000 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
35010 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 42 2c 58  collation_v2(B,X
35020 2c 45 2c 50 2c 46 2c 44 29 5d 0a 2a 2a 20 20 20  ,E,P,F,D)].**   
35030 20 20 20 20 20 20 20 69 73 20 70 61 73 73 65 64         is passed
35040 20 74 68 72 6f 75 67 68 20 61 73 20 74 68 65 20   through as the 
35050 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
35060 74 6f 20 74 68 65 20 63 6f 6d 70 61 72 69 73 6f  to the compariso
35070 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 75  n.**          fu
35080 6e 63 74 69 6f 6e 20 46 20 66 6f 72 20 61 6c 6c  nction F for all
35090 20 73 75 62 73 65 71 75 65 6e 74 20 69 6e 76 6f   subsequent invo
350a0 63 61 74 69 6f 6e 73 20 6f 66 20 46 2e 0a 2a 2a  cations of F..**
350b0 0a 2a 2a 20 7b 48 31 36 36 32 31 7d 20 41 20 63  .** {H16621} A c
350c0 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
350d0 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
350e0 28 42 2c 58 2c 45 2c 50 2c 46 29 5d 20 69 73 20  (B,X,E,P,F)] is 
350f0 65 78 61 63 74 6c 79 0a 2a 2a 20 20 20 20 20 20  exactly.**      
35100 20 20 20 20 74 68 65 20 73 61 6d 65 20 61 73 20      the same as 
35110 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  a call to [sqlit
35120 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
35130 69 6f 6e 5f 76 32 28 29 5d 20 77 69 74 68 0a 2a  ion_v2()] with.*
35140 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 73  *          the s
35150 61 6d 65 20 70 61 72 61 6d 65 74 65 72 73 20 61  ame parameters a
35160 6e 64 20 61 20 4e 55 4c 4c 20 64 65 73 74 72 75  nd a NULL destru
35170 63 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36  ctor..**.** {H16
35180 36 32 34 7d 20 46 6f 6c 6c 6f 77 69 6e 67 20 61  624} Following a
35190 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
351a0 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 42 2c  _collation_v2(B,
351b0 58 2c 45 2c 50 2c 46 2c 44 29 5d 2c 0a 2a 2a 20  X,E,P,F,D)],.** 
351c0 20 20 20 20 20 20 20 20 20 53 51 4c 69 74 65 20           SQLite 
351d0 75 73 65 73 20 74 68 65 20 63 6f 6d 70 61 72 69  uses the compari
351e0 73 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 46 20 66  son function F f
351f0 6f 72 20 61 6c 6c 20 74 65 78 74 20 63 6f 6d 70  or all text comp
35200 61 72 69 73 6f 6e 0a 2a 2a 20 20 20 20 20 20 20  arison.**       
35210 20 20 20 6f 70 65 72 61 74 69 6f 6e 73 20 6f 6e     operations on
35220 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
35230 6f 6e 6e 65 63 74 69 6f 6e 5d 20 42 20 6f 6e 20  onnection] B on 
35240 74 65 78 74 20 76 61 6c 75 65 73 20 74 68 61 74  text values that
35250 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 75 73 65  .**          use
35260 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 73   the collating s
35270 65 71 75 65 6e 63 65 20 6e 61 6d 65 64 20 58 2e  equence named X.
35280 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 36 32 37 7d 20  .**.** {H16627} 
35290 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  The [sqlite3_cre
352a0 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28  ate_collation16(
352b0 42 2c 58 2c 45 2c 50 2c 46 29 5d 20 77 6f 72 6b  B,X,E,P,F)] work
352c0 73 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 20 20  s the same.**   
352d0 20 20 20 20 20 20 20 61 73 20 5b 73 71 6c 69 74         as [sqlit
352e0 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
352f0 69 6f 6e 28 42 2c 58 2c 45 2c 50 2c 46 29 5d 20  ion(B,X,E,P,F)] 
35300 65 78 63 65 70 74 20 74 68 61 74 20 74 68 65 0a  except that the.
35310 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6c 6c  **          coll
35320 61 74 69 6f 6e 20 6e 61 6d 65 20 58 20 69 73 20  ation name X is 
35330 75 6e 64 65 72 73 74 6f 6f 64 20 61 73 20 55 54  understood as UT
35340 46 2d 31 36 20 69 6e 20 6e 61 74 69 76 65 20 62  F-16 in native b
35350 79 74 65 20 6f 72 64 65 72 0a 2a 2a 20 20 20 20  yte order.**    
35360 20 20 20 20 20 20 69 6e 73 74 65 61 64 20 6f 66        instead of
35370 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 7b 48   UTF-8..**.** {H
35380 31 36 36 33 30 7d 20 57 68 65 6e 20 6d 75 6c 74  16630} When mult
35390 69 70 6c 65 20 63 6f 6d 70 61 72 69 73 6f 6e 20  iple comparison 
353a0 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 61 76  functions are av
353b0 61 69 6c 61 62 6c 65 20 66 6f 72 20 74 68 65 20  ailable for the 
353c0 73 61 6d 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  same.**         
353d0 20 63 6f 6c 6c 61 74 69 6e 67 20 73 65 71 75 65   collating seque
353e0 6e 63 65 2c 20 53 51 4c 69 74 65 20 63 68 6f 6f  nce, SQLite choo
353f0 73 65 73 20 74 68 65 20 6f 6e 65 20 77 68 6f 73  ses the one whos
35400 65 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 0a  e text encoding.
35410 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 71 75  **          requ
35420 69 72 65 73 20 74 68 65 20 6c 65 61 73 74 20 61  ires the least a
35430 6d 6f 75 6e 74 20 6f 66 20 63 6f 6e 76 65 72 73  mount of convers
35440 69 6f 6e 20 66 72 6f 6d 20 74 68 65 20 64 65 66  ion from the def
35450 61 75 6c 74 0a 2a 2a 20 20 20 20 20 20 20 20 20  ault.**         
35460 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 6f   text encoding o
35470 66 20 74 68 65 20 64 61 74 61 62 61 73 65 2e 0a  f the database..
35480 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  */.int sqlite3_c
35490 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28  reate_collation(
354a0 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20  .  sqlite3*, .  
354b0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
354c0 65 2c 20 0a 20 20 69 6e 74 20 65 54 65 78 74 52  e, .  int eTextR
354d0 65 70 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20  ep, .  void*,.  
354e0 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76  int(*xCompare)(v
354f0 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76  oid*,int,const v
35500 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76  oid*,int,const v
35510 6f 69 64 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c  oid*).);.int sql
35520 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
35530 61 74 69 6f 6e 5f 76 32 28 0a 20 20 73 71 6c 69  ation_v2(.  sqli
35540 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 63  te3*, .  const c
35550 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69  har *zName, .  i
35560 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20  nt eTextRep, .  
35570 76 6f 69 64 2a 2c 0a 20 20 69 6e 74 28 2a 78 43  void*,.  int(*xC
35580 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e  ompare)(void*,in
35590 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e  t,const void*,in
355a0 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 2c 0a  t,const void*),.
355b0 20 20 76 6f 69 64 28 2a 78 44 65 73 74 72 6f 79    void(*xDestroy
355c0 29 28 76 6f 69 64 2a 29 0a 29 3b 0a 69 6e 74 20  )(void*).);.int 
355d0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
355e0 6f 6c 6c 61 74 69 6f 6e 31 36 28 0a 20 20 73 71  ollation16(.  sq
355f0 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74  lite3*, .  const
35600 20 76 6f 69 64 20 2a 7a 4e 61 6d 65 2c 0a 20 20   void *zName,.  
35610 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20  int eTextRep, . 
35620 20 76 6f 69 64 2a 2c 0a 20 20 69 6e 74 28 2a 78   void*,.  int(*x
35630 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69  Compare)(void*,i
35640 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69  nt,const void*,i
35650 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a  nt,const void*).
35660 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
35670 45 46 3a 20 43 6f 6c 6c 61 74 69 6f 6e 20 4e 65  EF: Collation Ne
35680 65 64 65 64 20 43 61 6c 6c 62 61 63 6b 73 20 7b  eded Callbacks {
35690 48 31 36 37 30 30 7d 20 3c 53 32 30 33 30 30 3e  H16700} <S20300>
356a0 0a 2a 2a 0a 2a 2a 20 54 6f 20 61 76 6f 69 64 20  .**.** To avoid 
356b0 68 61 76 69 6e 67 20 74 6f 20 72 65 67 69 73 74  having to regist
356c0 65 72 20 61 6c 6c 20 63 6f 6c 6c 61 74 69 6f 6e  er all collation
356d0 20 73 65 71 75 65 6e 63 65 73 20 62 65 66 6f 72   sequences befor
356e0 65 20 61 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  e a database.** 
356f0 63 61 6e 20 62 65 20 75 73 65 64 2c 20 61 20 73  can be used, a s
35700 69 6e 67 6c 65 20 63 61 6c 6c 62 61 63 6b 20 66  ingle callback f
35710 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65 20 72  unction may be r
35720 65 67 69 73 74 65 72 65 64 20 77 69 74 68 20 74  egistered with t
35730 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  he.** [database 
35740 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 62  connection] to b
35750 65 20 63 61 6c 6c 65 64 20 77 68 65 6e 65 76 65  e called wheneve
35760 72 20 61 6e 20 75 6e 64 65 66 69 6e 65 64 20 63  r an undefined c
35770 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75  ollation.** sequ
35780 65 6e 63 65 20 69 73 20 72 65 71 75 69 72 65 64  ence is required
35790 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 66  ..**.** If the f
357a0 75 6e 63 74 69 6f 6e 20 69 73 20 72 65 67 69 73  unction is regis
357b0 74 65 72 65 64 20 75 73 69 6e 67 20 74 68 65 20  tered using the 
357c0 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f  sqlite3_collatio
357d0 6e 5f 6e 65 65 64 65 64 28 29 20 41 50 49 2c 0a  n_needed() API,.
357e0 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20 70 61  ** then it is pa
357f0 73 73 65 64 20 74 68 65 20 6e 61 6d 65 73 20 6f  ssed the names o
35800 66 20 75 6e 64 65 66 69 6e 65 64 20 63 6f 6c 6c  f undefined coll
35810 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 73 20  ation sequences 
35820 61 73 20 73 74 72 69 6e 67 73 0a 2a 2a 20 65 6e  as strings.** en
35830 63 6f 64 65 64 20 69 6e 20 55 54 46 2d 38 2e 20  coded in UTF-8. 
35840 7b 48 31 36 37 30 33 7d 20 49 66 20 73 71 6c 69  {H16703} If sqli
35850 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65  te3_collation_ne
35860 65 64 65 64 31 36 28 29 20 69 73 20 75 73 65 64  eded16() is used
35870 2c 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 73 20 61  ,.** the names a
35880 72 65 20 70 61 73 73 65 64 20 61 73 20 55 54 46  re passed as UTF
35890 2d 31 36 20 69 6e 20 6d 61 63 68 69 6e 65 20 6e  -16 in machine n
358a0 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
358b0 2e 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 65  ..** A call to e
358c0 69 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 20 72  ither function r
358d0 65 70 6c 61 63 65 73 20 61 6e 79 20 65 78 69 73  eplaces any exis
358e0 74 69 6e 67 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a  ting callback..*
358f0 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 63 61  *.** When the ca
35900 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
35910 64 2c 20 74 68 65 20 66 69 72 73 74 20 61 72 67  d, the first arg
35920 75 6d 65 6e 74 20 70 61 73 73 65 64 20 69 73 20  ument passed is 
35930 61 20 63 6f 70 79 0a 2a 2a 20 6f 66 20 74 68 65  a copy.** of the
35940 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
35950 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c   to sqlite3_coll
35960 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 20 6f  ation_needed() o
35970 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c  r.** sqlite3_col
35980 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28  lation_needed16(
35990 29 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 61  ).  The second a
359a0 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 64  rgument is the d
359b0 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65  atabase.** conne
359c0 63 74 69 6f 6e 2e 20 20 54 68 65 20 74 68 69 72  ction.  The thir
359d0 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e  d argument is on
359e0 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 55 54 46  e of [SQLITE_UTF
359f0 38 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46 31  8], [SQLITE_UTF1
35a00 36 42 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c  6BE],.** or [SQL
35a10 49 54 45 5f 55 54 46 31 36 4c 45 5d 2c 20 69 6e  ITE_UTF16LE], in
35a20 64 69 63 61 74 69 6e 67 20 74 68 65 20 6d 6f 73  dicating the mos
35a30 74 20 64 65 73 69 72 61 62 6c 65 20 66 6f 72 6d  t desirable form
35a40 20 6f 66 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f   of the collatio
35a50 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20 66 75  n.** sequence fu
35a60 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 64 2e  nction required.
35a70 20 20 54 68 65 20 66 6f 75 72 74 68 20 70 61 72    The fourth par
35a80 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e 61  ameter is the na
35a90 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65 71  me of the.** req
35aa0 75 69 72 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20  uired collation 
35ab0 73 65 71 75 65 6e 63 65 2e 0a 2a 2a 0a 2a 2a 20  sequence..**.** 
35ac0 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  The callback fun
35ad0 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 72 65 67  ction should reg
35ae0 69 73 74 65 72 20 74 68 65 20 64 65 73 69 72 65  ister the desire
35af0 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 75 73 69 6e  d collation usin
35b00 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72  g.** [sqlite3_cr
35b10 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29  eate_collation()
35b20 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  ], [sqlite3_crea
35b30 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29  te_collation16()
35b40 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  ], or.** [sqlite
35b50 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
35b60 6f 6e 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  on_v2()]..**.** 
35b70 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
35b80 2a 20 7b 48 31 36 37 30 32 7d 20 41 20 73 75 63  * {H16702} A suc
35b90 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20  cessful call to 
35ba0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69  [sqlite3_collati
35bb0 6f 6e 5f 6e 65 65 64 65 64 28 44 2c 50 2c 46 29  on_needed(D,P,F)
35bc0 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72  ].**          or
35bd0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74   [sqlite3_collat
35be0 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 44 2c 50  ion_needed16(D,P
35bf0 2c 46 29 5d 20 63 61 75 73 65 73 0a 2a 2a 20 20  ,F)] causes.**  
35c00 20 20 20 20 20 20 20 20 74 68 65 20 5b 64 61 74          the [dat
35c10 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
35c20 5d 20 44 20 74 6f 20 69 6e 76 6f 6b 65 20 63 61  ] D to invoke ca
35c30 6c 6c 62 61 63 6b 20 46 20 77 69 74 68 20 66 69  llback F with fi
35c40 72 73 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  rst.**          
35c50 70 61 72 61 6d 65 74 65 72 20 50 20 77 68 65 6e  parameter P when
35c60 65 76 65 72 20 69 74 20 6e 65 65 64 73 20 61 20  ever it needs a 
35c70 63 6f 6d 70 61 72 69 73 6f 6e 20 66 75 6e 63 74  comparison funct
35c80 69 6f 6e 20 66 6f 72 20 61 0a 2a 2a 20 20 20 20  ion for a.**    
35c90 20 20 20 20 20 20 63 6f 6c 6c 61 74 69 6e 67 20        collating 
35ca0 73 65 71 75 65 6e 63 65 20 74 68 61 74 20 69 74  sequence that it
35cb0 20 64 6f 65 73 20 6e 6f 74 20 6b 6e 6f 77 20 61   does not know a
35cc0 62 6f 75 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36  bout..**.** {H16
35cd0 37 30 34 7d 20 45 61 63 68 20 73 75 63 63 65 73  704} Each succes
35ce0 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71  sful call to [sq
35cf0 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  lite3_collation_
35d00 6e 65 65 64 65 64 28 29 5d 20 6f 72 0a 2a 2a 20  needed()] or.** 
35d10 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
35d20 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64  3_collation_need
35d30 65 64 31 36 28 29 5d 20 6f 76 65 72 72 69 64 65  ed16()] override
35d40 73 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72  s the callback r
35d50 65 67 69 73 74 65 72 65 64 0a 2a 2a 20 20 20 20  egistered.**    
35d60 20 20 20 20 20 20 6f 6e 20 74 68 65 20 73 61 6d        on the sam
35d70 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
35d80 65 63 74 69 6f 6e 5d 20 62 79 20 70 72 69 6f 72  ection] by prior
35d90 20 63 61 6c 6c 73 20 74 6f 20 65 69 74 68 65 72   calls to either
35da0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74  .**          int
35db0 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48  erface..**.** {H
35dc0 31 36 37 30 36 7d 20 54 68 65 20 6e 61 6d 65 20  16706} The name 
35dd0 6f 66 20 74 68 65 20 72 65 71 75 65 73 74 65 64  of the requested
35de0 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74   collating funct
35df0 69 6f 6e 20 70 61 73 73 65 64 20 69 6e 20 74 68  ion passed in th
35e00 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 34 74  e.**          4t
35e10 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
35e20 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  he callback is i
35e30 6e 20 55 54 46 2d 38 20 69 66 20 74 68 65 20 63  n UTF-8 if the c
35e40 61 6c 6c 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20  allback.**      
35e50 20 20 20 20 77 61 73 20 72 65 67 69 73 74 65 72      was register
35e60 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ed using [sqlite
35e70 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64  3_collation_need
35e80 65 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 20 20 20  ed()] and.**    
35e90 20 20 20 20 20 20 69 73 20 69 6e 20 55 54 46 2d        is in UTF-
35ea0 31 36 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  16 native byte o
35eb0 72 64 65 72 20 69 66 20 74 68 65 20 63 61 6c 6c  rder if the call
35ec0 62 61 63 6b 20 77 61 73 0a 2a 2a 20 20 20 20 20  back was.**     
35ed0 20 20 20 20 20 72 65 67 69 73 74 65 72 65 64 20       registered 
35ee0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63  using [sqlite3_c
35ef0 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31  ollation_needed1
35f00 36 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  6()]..*/.int sql
35f10 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e  ite3_collation_n
35f20 65 65 64 65 64 28 0a 20 20 73 71 6c 69 74 65 33  eeded(.  sqlite3
35f30 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 20 0a 20 20  *, .  void*, .  
35f40 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71  void(*)(void*,sq
35f50 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54 65 78 74  lite3*,int eText
35f60 52 65 70 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29  Rep,const char*)
35f70 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
35f80 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64  collation_needed
35f90 31 36 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20  16(.  sqlite3*, 
35fa0 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 76 6f 69 64  .  void*,.  void
35fb0 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65  (*)(void*,sqlite
35fc0 33 2a 2c 69 6e 74 20 65 54 65 78 74 52 65 70 2c  3*,int eTextRep,
35fd0 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a  const void*).);.
35fe0 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66 79 20 74  ./*.** Specify t
35ff0 68 65 20 6b 65 79 20 66 6f 72 20 61 6e 20 65 6e  he key for an en
36000 63 72 79 70 74 65 64 20 64 61 74 61 62 61 73 65  crypted database
36010 2e 20 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  .  This routine 
36020 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 63 61 6c  should be.** cal
36030 6c 65 64 20 72 69 67 68 74 20 61 66 74 65 72 20  led right after 
36040 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 2e 0a  sqlite3_open()..
36050 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 74  **.** The code t
36060 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 69 73  o implement this
36070 20 41 50 49 20 69 73 20 6e 6f 74 20 61 76 61 69   API is not avai
36080 6c 61 62 6c 65 20 69 6e 20 74 68 65 20 70 75 62  lable in the pub
36090 6c 69 63 20 72 65 6c 65 61 73 65 0a 2a 2a 20 6f  lic release.** o
360a0 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74  f SQLite..*/.int
360b0 20 73 71 6c 69 74 65 33 5f 6b 65 79 28 0a 20 20   sqlite3_key(.  
360c0 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
360d0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
360e0 2a 20 44 61 74 61 62 61 73 65 20 74 6f 20 62 65  * Database to be
360f0 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f   rekeyed */.  co
36100 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20  nst void *pKey, 
36110 69 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20  int nKey     /* 
36120 54 68 65 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f  The key */.);../
36130 2a 0a 2a 2a 20 43 68 61 6e 67 65 20 74 68 65 20  *.** Change the 
36140 6b 65 79 20 6f 6e 20 61 6e 20 6f 70 65 6e 20 64  key on an open d
36150 61 74 61 62 61 73 65 2e 20 20 49 66 20 74 68 65  atabase.  If the
36160 20 63 75 72 72 65 6e 74 20 64 61 74 61 62 61 73   current databas
36170 65 20 69 73 20 6e 6f 74 0a 2a 2a 20 65 6e 63 72  e is not.** encr
36180 79 70 74 65 64 2c 20 74 68 69 73 20 72 6f 75 74  ypted, this rout
36190 69 6e 65 20 77 69 6c 6c 20 65 6e 63 72 79 70 74  ine will encrypt
361a0 20 69 74 2e 20 20 49 66 20 70 4e 65 77 3d 3d 30   it.  If pNew==0
361b0 20 6f 72 20 6e 4e 65 77 3d 3d 30 2c 20 74 68 65   or nNew==0, the
361c0 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 69 73 20  .** database is 
361d0 64 65 63 72 79 70 74 65 64 2e 0a 2a 2a 0a 2a 2a  decrypted..**.**
361e0 20 54 68 65 20 63 6f 64 65 20 74 6f 20 69 6d 70   The code to imp
361f0 6c 65 6d 65 6e 74 20 74 68 69 73 20 41 50 49 20  lement this API 
36200 69 73 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c 65  is not available
36210 20 69 6e 20 74 68 65 20 70 75 62 6c 69 63 20 72   in the public r
36220 65 6c 65 61 73 65 0a 2a 2a 20 6f 66 20 53 51 4c  elease.** of SQL
36230 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ite..*/.int sqli
36240 74 65 33 5f 72 65 6b 65 79 28 0a 20 20 73 71 6c  te3_rekey(.  sql
36250 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
36260 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44              /* D
36270 61 74 61 62 61 73 65 20 74 6f 20 62 65 20 72 65  atabase to be re
36280 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74  keyed */.  const
36290 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74   void *pKey, int
362a0 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54 68 65   nKey     /* The
362b0 20 6e 65 77 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a   new key */.);..
362c0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
362d0 53 75 73 70 65 6e 64 20 45 78 65 63 75 74 69 6f  Suspend Executio
362e0 6e 20 46 6f 72 20 41 20 53 68 6f 72 74 20 54 69  n For A Short Ti
362f0 6d 65 20 7b 48 31 30 35 33 30 7d 20 3c 53 34 30  me {H10530} <S40
36300 34 31 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  410>.**.** The s
36310 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 29 20 66  qlite3_sleep() f
36320 75 6e 63 74 69 6f 6e 20 63 61 75 73 65 73 20 74  unction causes t
36330 68 65 20 63 75 72 72 65 6e 74 20 74 68 72 65 61  he current threa
36340 64 20 74 6f 20 73 75 73 70 65 6e 64 20 65 78 65  d to suspend exe
36350 63 75 74 69 6f 6e 0a 2a 2a 20 66 6f 72 20 61 74  cution.** for at
36360 20 6c 65 61 73 74 20 61 20 6e 75 6d 62 65 72 20   least a number 
36370 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20  of milliseconds 
36380 73 70 65 63 69 66 69 65 64 20 69 6e 20 69 74 73  specified in its
36390 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a   parameter..**.*
363a0 2a 20 49 66 20 74 68 65 20 6f 70 65 72 61 74 69  * If the operati
363b0 6e 67 20 73 79 73 74 65 6d 20 64 6f 65 73 20 6e  ng system does n
363c0 6f 74 20 73 75 70 70 6f 72 74 20 73 6c 65 65 70  ot support sleep
363d0 20 72 65 71 75 65 73 74 73 20 77 69 74 68 0a 2a   requests with.*
363e0 2a 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 20 74 69  * millisecond ti
363f0 6d 65 20 72 65 73 6f 6c 75 74 69 6f 6e 2c 20 74  me resolution, t
36400 68 65 6e 20 74 68 65 20 74 69 6d 65 20 77 69 6c  hen the time wil
36410 6c 20 62 65 20 72 6f 75 6e 64 65 64 20 75 70 20  l be rounded up 
36420 74 6f 0a 2a 2a 20 74 68 65 20 6e 65 61 72 65 73  to.** the neares
36430 74 20 73 65 63 6f 6e 64 2e 20 54 68 65 20 6e 75  t second. The nu
36440 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63  mber of millisec
36450 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 20 61 63  onds of sleep ac
36460 74 75 61 6c 6c 79 0a 2a 2a 20 72 65 71 75 65 73  tually.** reques
36470 74 65 64 20 66 72 6f 6d 20 74 68 65 20 6f 70 65  ted from the ope
36480 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69 73  rating system is
36490 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
364a0 20 53 51 4c 69 74 65 20 69 6d 70 6c 65 6d 65 6e   SQLite implemen
364b0 74 73 20 74 68 69 73 20 69 6e 74 65 72 66 61 63  ts this interfac
364c0 65 20 62 79 20 63 61 6c 6c 69 6e 67 20 74 68 65  e by calling the
364d0 20 78 53 6c 65 65 70 28 29 0a 2a 2a 20 6d 65 74   xSleep().** met
364e0 68 6f 64 20 6f 66 20 74 68 65 20 64 65 66 61 75  hod of the defau
364f0 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  lt [sqlite3_vfs]
36500 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 49   object..**.** I
36510 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
36520 20 7b 48 31 30 35 33 33 7d 20 54 68 65 20 5b 73   {H10533} The [s
36530 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 4d 29 5d  qlite3_sleep(M)]
36540 20 69 6e 74 65 72 66 61 63 65 20 69 6e 76 6f 6b   interface invok
36550 65 73 20 74 68 65 20 78 53 6c 65 65 70 0a 2a 2a  es the xSleep.**
36560 20 20 20 20 20 20 20 20 20 20 6d 65 74 68 6f 64            method
36570 20 6f 66 20 74 68 65 20 64 65 66 61 75 6c 74 20   of the default 
36580 5b 73 71 6c 69 74 65 33 5f 76 66 73 7c 56 46 53  [sqlite3_vfs|VFS
36590 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 0a 2a 2a  ] in order to.**
365a0 20 20 20 20 20 20 20 20 20 20 73 75 73 70 65 6e            suspen
365b0 64 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 74  d execution of t
365c0 68 65 20 63 75 72 72 65 6e 74 20 74 68 72 65 61  he current threa
365d0 64 20 66 6f 72 20 61 74 20 6c 65 61 73 74 0a 2a  d for at least.*
365e0 2a 20 20 20 20 20 20 20 20 20 20 4d 20 6d 69 6c  *          M mil
365f0 6c 69 73 65 63 6f 6e 64 73 2e 0a 2a 2a 0a 2a 2a  liseconds..**.**
36600 20 7b 48 31 30 35 33 36 7d 20 54 68 65 20 5b 73   {H10536} The [s
36610 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 4d 29 5d  qlite3_sleep(M)]
36620 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
36630 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
36640 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 69 6c  .**          mil
36650 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65  liseconds of sle
36660 65 70 20 61 63 74 75 61 6c 6c 79 20 72 65 71 75  ep actually requ
36670 65 73 74 65 64 20 6f 66 20 74 68 65 20 6f 70 65  ested of the ope
36680 72 61 74 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20  rating.**       
36690 20 20 20 73 79 73 74 65 6d 2c 20 77 68 69 63 68     system, which
366a0 20 6d 69 67 68 74 20 62 65 20 6c 61 72 67 65 72   might be larger
366b0 20 74 68 61 6e 20 74 68 65 20 70 61 72 61 6d 65   than the parame
366c0 74 65 72 20 4d 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ter M..*/.int sq
366d0 6c 69 74 65 33 5f 73 6c 65 65 70 28 69 6e 74 29  lite3_sleep(int)
366e0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
366f0 46 3a 20 4e 61 6d 65 20 4f 66 20 54 68 65 20 46  F: Name Of The F
36700 6f 6c 64 65 72 20 48 6f 6c 64 69 6e 67 20 54 65  older Holding Te
36710 6d 70 6f 72 61 72 79 20 46 69 6c 65 73 20 7b 48  mporary Files {H
36720 31 30 33 31 30 7d 20 3c 53 32 30 30 30 30 3e 0a  10310} <S20000>.
36730 2a 2a 0a 2a 2a 20 49 66 20 74 68 69 73 20 67 6c  **.** If this gl
36740 6f 62 61 6c 20 76 61 72 69 61 62 6c 65 20 69 73  obal variable is
36750 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74   made to point t
36760 6f 20 61 20 73 74 72 69 6e 67 20 77 68 69 63 68  o a string which
36770 20 69 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20   is.** the name 
36780 6f 66 20 61 20 66 6f 6c 64 65 72 20 28 61 2e 6b  of a folder (a.k
36790 2e 61 2e 20 64 69 72 65 63 74 6f 72 79 29 2c 20  .a. directory), 
367a0 74 68 65 6e 20 61 6c 6c 20 74 65 6d 70 6f 72 61  then all tempora
367b0 72 79 20 66 69 6c 65 73 0a 2a 2a 20 63 72 65 61  ry files.** crea
367c0 74 65 64 20 62 79 20 53 51 4c 69 74 65 20 77 69  ted by SQLite wi
367d0 6c 6c 20 62 65 20 70 6c 61 63 65 64 20 69 6e 20  ll be placed in 
367e0 74 68 61 74 20 64 69 72 65 63 74 6f 72 79 2e 20  that directory. 
367f0 20 49 66 20 74 68 69 73 20 76 61 72 69 61 62 6c   If this variabl
36800 65 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70  e.** is a NULL p
36810 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 53 51 4c  ointer, then SQL
36820 69 74 65 20 70 65 72 66 6f 72 6d 73 20 61 20 73  ite performs a s
36830 65 61 72 63 68 20 66 6f 72 20 61 6e 20 61 70 70  earch for an app
36840 72 6f 70 72 69 61 74 65 0a 2a 2a 20 74 65 6d 70  ropriate.** temp
36850 6f 72 61 72 79 20 66 69 6c 65 20 64 69 72 65 63  orary file direc
36860 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69  tory..**.** It i
36870 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 6d 6f  s not safe to mo
36880 64 69 66 79 20 74 68 69 73 20 76 61 72 69 61 62  dify this variab
36890 6c 65 20 6f 6e 63 65 20 61 20 5b 64 61 74 61 62  le once a [datab
368a0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a  ase connection].
368b0 2a 2a 20 68 61 73 20 62 65 65 6e 20 6f 70 65 6e  ** has been open
368c0 65 64 2e 20 20 49 74 20 69 73 20 69 6e 74 65 6e  ed.  It is inten
368d0 64 65 64 20 74 68 61 74 20 74 68 69 73 20 76 61  ded that this va
368e0 72 69 61 62 6c 65 20 62 65 20 73 65 74 20 6f 6e  riable be set on
368f0 63 65 0a 2a 2a 20 61 73 20 70 61 72 74 20 6f 66  ce.** as part of
36900 20 70 72 6f 63 65 73 73 20 69 6e 69 74 69 61 6c   process initial
36910 69 7a 61 74 69 6f 6e 20 61 6e 64 20 62 65 66 6f  ization and befo
36920 72 65 20 61 6e 79 20 53 51 4c 69 74 65 20 69 6e  re any SQLite in
36930 74 65 72 66 61 63 65 0a 2a 2a 20 72 6f 75 74 69  terface.** routi
36940 6e 65 73 20 68 61 76 65 20 62 65 65 6e 20 63 61  nes have been ca
36950 6c 6c 20 61 6e 64 20 72 65 6d 61 69 6e 20 75 6e  ll and remain un
36960 63 68 61 6e 67 65 64 20 74 68 65 72 65 61 66 74  changed thereaft
36970 65 72 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58  er..*/.SQLITE_EX
36980 54 45 52 4e 20 63 68 61 72 20 2a 73 71 6c 69 74  TERN char *sqlit
36990 65 33 5f 74 65 6d 70 5f 64 69 72 65 63 74 6f 72  e3_temp_director
369a0 79 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  y;../*.** CAPI3R
369b0 45 46 3a 20 54 65 73 74 20 46 6f 72 20 41 75 74  EF: Test For Aut
369c0 6f 2d 43 6f 6d 6d 69 74 20 4d 6f 64 65 20 7b 48  o-Commit Mode {H
369d0 31 32 39 33 30 7d 20 3c 53 36 30 32 30 30 3e 0a  12930} <S60200>.
369e0 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 75  ** KEYWORDS: {au
369f0 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 7d 0a 2a  tocommit mode}.*
36a00 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
36a10 5f 67 65 74 5f 61 75 74 6f 63 6f 6d 6d 69 74 28  _get_autocommit(
36a20 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
36a30 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 20 6f 72 0a  rns non-zero or.
36a40 2a 2a 20 7a 65 72 6f 20 69 66 20 74 68 65 20 67  ** zero if the g
36a50 69 76 65 6e 20 64 61 74 61 62 61 73 65 20 63 6f  iven database co
36a60 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 72 20 69  nnection is or i
36a70 73 20 6e 6f 74 20 69 6e 20 61 75 74 6f 63 6f 6d  s not in autocom
36a80 6d 69 74 20 6d 6f 64 65 2c 0a 2a 2a 20 72 65 73  mit mode,.** res
36a90 70 65 63 74 69 76 65 6c 79 2e 20 20 41 75 74 6f  pectively.  Auto
36aa0 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 6f  commit mode is o
36ab0 6e 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a  n by default..**
36ac0 20 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65   Autocommit mode
36ad0 20 69 73 20 64 69 73 61 62 6c 65 64 20 62 79 20   is disabled by 
36ae0 61 20 5b 42 45 47 49 4e 5d 20 73 74 61 74 65 6d  a [BEGIN] statem
36af0 65 6e 74 2e 0a 2a 2a 20 41 75 74 6f 63 6f 6d 6d  ent..** Autocomm
36b00 69 74 20 6d 6f 64 65 20 69 73 20 72 65 2d 65 6e  it mode is re-en
36b10 61 62 6c 65 64 20 62 79 20 61 20 5b 43 4f 4d 4d  abled by a [COMM
36b20 49 54 5d 20 6f 72 20 5b 52 4f 4c 4c 42 41 43 4b  IT] or [ROLLBACK
36b30 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 63 65 72 74  ]..**.** If cert
36b40 61 69 6e 20 6b 69 6e 64 73 20 6f 66 20 65 72 72  ain kinds of err
36b50 6f 72 73 20 6f 63 63 75 72 20 6f 6e 20 61 20 73  ors occur on a s
36b60 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20  tatement within 
36b70 61 20 6d 75 6c 74 69 2d 73 74 61 74 65 6d 65 6e  a multi-statemen
36b80 74 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e  t.** transaction
36b90 20 28 65 72 72 6f 72 73 20 69 6e 63 6c 75 64 69   (errors includi
36ba0 6e 67 20 5b 53 51 4c 49 54 45 5f 46 55 4c 4c 5d  ng [SQLITE_FULL]
36bb0 2c 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d  , [SQLITE_IOERR]
36bc0 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d  ,.** [SQLITE_NOM
36bd0 45 4d 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 55 53  EM], [SQLITE_BUS
36be0 59 5d 2c 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f  Y], and [SQLITE_
36bf0 49 4e 54 45 52 52 55 50 54 5d 29 20 74 68 65 6e  INTERRUPT]) then
36c00 20 74 68 65 0a 2a 2a 20 74 72 61 6e 73 61 63 74   the.** transact
36c10 69 6f 6e 20 6d 69 67 68 74 20 62 65 20 72 6f 6c  ion might be rol
36c20 6c 65 64 20 62 61 63 6b 20 61 75 74 6f 6d 61 74  led back automat
36c30 69 63 61 6c 6c 79 2e 20 20 54 68 65 20 6f 6e 6c  ically.  The onl
36c40 79 20 77 61 79 20 74 6f 0a 2a 2a 20 66 69 6e 64  y way to.** find
36c50 20 6f 75 74 20 77 68 65 74 68 65 72 20 53 51 4c   out whether SQL
36c60 69 74 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  ite automaticall
36c70 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 74 68  y rolled back th
36c80 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 61 66  e transaction af
36c90 74 65 72 0a 2a 2a 20 61 6e 20 65 72 72 6f 72 20  ter.** an error 
36ca0 69 73 20 74 6f 20 75 73 65 20 74 68 69 73 20 66  is to use this f
36cb0 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49  unction..**.** I
36cc0 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
36cd0 20 7b 48 31 32 39 33 31 7d 20 54 68 65 20 5b 73   {H12931} The [s
36ce0 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 74 6f 63  qlite3_get_autoc
36cf0 6f 6d 6d 69 74 28 44 29 5d 20 69 6e 74 65 72 66  ommit(D)] interf
36d00 61 63 65 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d  ace returns non-
36d10 7a 65 72 6f 20 6f 72 0a 2a 2a 20 20 20 20 20 20  zero or.**      
36d20 20 20 20 20 7a 65 72 6f 20 69 66 20 74 68 65 20      zero if the 
36d30 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
36d40 74 69 6f 6e 5d 20 44 20 69 73 20 6f 72 20 69 73  tion] D is or is
36d50 20 6e 6f 74 20 69 6e 20 61 75 74 6f 63 6f 6d 6d   not in autocomm
36d60 69 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d  it.**          m
36d70 6f 64 65 2c 20 72 65 73 70 65 63 74 69 76 65 6c  ode, respectivel
36d80 79 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 33 32  y..**.** {H12932
36d90 7d 20 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64  } Autocommit mod
36da0 65 20 69 73 20 6f 6e 20 62 79 20 64 65 66 61 75  e is on by defau
36db0 6c 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 33  lt..**.** {H1293
36dc0 33 7d 20 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f  3} Autocommit mo
36dd0 64 65 20 69 73 20 64 69 73 61 62 6c 65 64 20 62  de is disabled b
36de0 79 20 61 20 73 75 63 63 65 73 73 66 75 6c 20 5b  y a successful [
36df0 42 45 47 49 4e 5d 20 73 74 61 74 65 6d 65 6e 74  BEGIN] statement
36e00 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 33 34 7d  ..**.** {H12934}
36e10 20 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65   Autocommit mode
36e20 20 69 73 20 65 6e 61 62 6c 65 64 20 62 79 20 61   is enabled by a
36e30 20 73 75 63 63 65 73 73 66 75 6c 20 5b 43 4f 4d   successful [COM
36e40 4d 49 54 5d 20 6f 72 20 5b 52 4f 4c 4c 42 41 43  MIT] or [ROLLBAC
36e50 4b 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73  K].**          s
36e60 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  tatement..**.** 
36e70 41 53 53 55 4d 50 54 49 4f 4e 53 3a 0a 2a 2a 0a  ASSUMPTIONS:.**.
36e80 2a 2a 20 7b 41 31 32 39 33 36 7d 20 49 66 20 61  ** {A12936} If a
36e90 6e 6f 74 68 65 72 20 74 68 72 65 61 64 20 63 68  nother thread ch
36ea0 61 6e 67 65 73 20 74 68 65 20 61 75 74 6f 63 6f  anges the autoco
36eb0 6d 6d 69 74 20 73 74 61 74 75 73 20 6f 66 20 74  mmit status of t
36ec0 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 20  he database.**  
36ed0 20 20 20 20 20 20 20 20 63 6f 6e 6e 65 63 74 69          connecti
36ee0 6f 6e 20 77 68 69 6c 65 20 74 68 69 73 20 72 6f  on while this ro
36ef0 75 74 69 6e 65 20 69 73 20 72 75 6e 6e 69 6e 67  utine is running
36f00 2c 20 74 68 65 6e 20 74 68 65 20 72 65 74 75 72  , then the retur
36f10 6e 20 76 61 6c 75 65 0a 2a 2a 20 20 20 20 20 20  n value.**      
36f20 20 20 20 20 69 73 20 75 6e 64 65 66 69 6e 65 64      is undefined
36f30 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
36f40 5f 67 65 74 5f 61 75 74 6f 63 6f 6d 6d 69 74 28  _get_autocommit(
36f50 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a  sqlite3*);../*.*
36f60 2a 20 43 41 50 49 33 52 45 46 3a 20 46 69 6e 64  * CAPI3REF: Find
36f70 20 54 68 65 20 44 61 74 61 62 61 73 65 20 48 61   The Database Ha
36f80 6e 64 6c 65 20 4f 66 20 41 20 50 72 65 70 61 72  ndle Of A Prepar
36f90 65 64 20 53 74 61 74 65 6d 65 6e 74 20 7b 48 31  ed Statement {H1
36fa0 33 31 32 30 7d 20 3c 53 36 30 36 30 30 3e 0a 2a  3120} <S60600>.*
36fb0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
36fc0 5f 64 62 5f 68 61 6e 64 6c 65 20 69 6e 74 65 72  _db_handle inter
36fd0 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65  face returns the
36fe0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
36ff0 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 0a 2a 2a  ction] handle.**
37000 20 74 6f 20 77 68 69 63 68 20 61 20 5b 70 72 65   to which a [pre
37010 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
37020 20 62 65 6c 6f 6e 67 73 2e 20 20 54 68 65 20 64   belongs.  The d
37030 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 72  atabase handle r
37040 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 73 71  eturned by.** sq
37050 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65 20  lite3_db_handle 
37060 69 73 20 74 68 65 20 73 61 6d 65 20 64 61 74 61  is the same data
37070 62 61 73 65 20 68 61 6e 64 6c 65 20 74 68 61 74  base handle that
37080 20 77 61 73 20 74 68 65 20 66 69 72 73 74 20 61   was the first a
37090 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 74 68  rgument.** to th
370a0 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  e [sqlite3_prepa
370b0 72 65 5f 76 32 28 29 5d 20 63 61 6c 6c 20 28 6f  re_v2()] call (o
370c0 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 29 20  r its variants) 
370d0 74 68 61 74 20 77 61 73 20 75 73 65 64 20 74 6f  that was used to
370e0 0a 2a 2a 20 63 72 65 61 74 65 20 74 68 65 20 73  .** create the s
370f0 74 61 74 65 6d 65 6e 74 20 69 6e 20 74 68 65 20  tatement in the 
37100 66 69 72 73 74 20 70 6c 61 63 65 2e 0a 2a 2a 0a  first place..**.
37110 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
37120 2a 0a 2a 2a 20 7b 48 31 33 31 32 33 7d 20 54 68  *.** {H13123} Th
37130 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 68 61  e [sqlite3_db_ha
37140 6e 64 6c 65 28 53 29 5d 20 69 6e 74 65 72 66 61  ndle(S)] interfa
37150 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  ce returns a poi
37160 6e 74 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  nter.**         
37170 20 74 6f 20 74 68 65 20 5b 64 61 74 61 62 61 73   to the [databas
37180 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 73  e connection] as
37190 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68  sociated with th
371a0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70  e.**          [p
371b0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
371c0 74 5d 20 53 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33  t] S..*/.sqlite3
371d0 20 2a 73 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e   *sqlite3_db_han
371e0 64 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  dle(sqlite3_stmt
371f0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
37200 52 45 46 3a 20 46 69 6e 64 20 74 68 65 20 6e 65  REF: Find the ne
37210 78 74 20 70 72 65 70 61 72 65 64 20 73 74 61 74  xt prepared stat
37220 65 6d 65 6e 74 20 7b 48 31 33 31 34 30 7d 20 3c  ement {H13140} <
37230 53 36 30 36 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68  S60600>.**.** Th
37240 69 73 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  is interface ret
37250 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
37260 6f 20 74 68 65 20 6e 65 78 74 20 5b 70 72 65 70  o the next [prep
37270 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
37280 61 66 74 65 72 0a 2a 2a 20 70 53 74 6d 74 20 61  after.** pStmt a
37290 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74  ssociated with t
372a0 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
372b0 6e 65 63 74 69 6f 6e 5d 20 70 44 62 2e 20 20 49  nection] pDb.  I
372c0 66 20 70 53 74 6d 74 20 69 73 20 4e 55 4c 4c 0a  f pStmt is NULL.
372d0 2a 2a 20 74 68 65 6e 20 74 68 69 73 20 69 6e 74  ** then this int
372e0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61  erface returns a
372f0 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
37300 66 69 72 73 74 20 70 72 65 70 61 72 65 64 20 73  first prepared s
37310 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 61 73 73 6f  tatement.** asso
37320 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20  ciated with the 
37330 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
37340 69 6f 6e 20 70 44 62 2e 20 20 49 66 20 6e 6f 20  ion pDb.  If no 
37350 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
37360 6e 74 0a 2a 2a 20 73 61 74 69 73 66 69 65 73 20  nt.** satisfies 
37370 74 68 65 20 63 6f 6e 64 69 74 69 6f 6e 73 20 6f  the conditions o
37380 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20  f this routine, 
37390 69 74 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 2e  it returns NULL.
373a0 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
373b0 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 31 34 33  S:.**.** {H13143
373c0 7d 20 49 66 20 44 20 69 73 20 61 20 5b 64 61 74  } If D is a [dat
373d0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
373e0 5d 20 74 68 61 74 20 68 6f 6c 64 73 20 6f 6e 65  ] that holds one
373f0 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 20 20 20 20   or more.**     
37400 20 20 20 20 20 75 6e 66 69 6e 61 6c 69 7a 65 64       unfinalized
37410 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
37420 6d 65 6e 74 73 5d 20 61 6e 64 20 53 20 69 73 20  ments] and S is 
37430 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 0a  a NULL pointer,.
37440 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 6e  **          then
37450 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73   [sqlite3_next_s
37460 74 6d 74 28 44 2c 20 53 29 5d 20 72 6f 75 74 69  tmt(D, S)] routi
37470 6e 65 20 73 68 61 6c 6c 20 72 65 74 75 72 6e 20  ne shall return 
37480 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 20 20 20  a pointer.**    
37490 20 20 20 20 20 20 74 6f 20 6f 6e 65 20 6f 66 20        to one of 
374a0 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61  the prepared sta
374b0 74 65 6d 65 6e 74 73 20 61 73 73 6f 63 69 61 74  tements associat
374c0 65 64 20 77 69 74 68 20 44 2e 0a 2a 2a 0a 2a 2a  ed with D..**.**
374d0 20 7b 48 31 33 31 34 36 7d 20 49 66 20 44 20 69   {H13146} If D i
374e0 73 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f  s a [database co
374f0 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74 20 68  nnection] that h
37500 6f 6c 64 73 20 6e 6f 20 75 6e 66 69 6e 61 6c 69  olds no unfinali
37510 7a 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  zed.**          
37520 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
37530 65 6e 74 73 5d 20 61 6e 64 20 53 20 69 73 20 61  ents] and S is a
37540 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74   NULL pointer, t
37550 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  hen.**          
37560 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74  [sqlite3_next_st
37570 6d 74 28 44 2c 20 53 29 5d 20 72 6f 75 74 69 6e  mt(D, S)] routin
37580 65 20 73 68 61 6c 6c 20 72 65 74 75 72 6e 20 61  e shall return a
37590 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a   NULL pointer..*
375a0 2a 0a 2a 2a 20 7b 48 31 33 31 34 39 7d 20 49 66  *.** {H13149} If
375b0 20 53 20 69 73 20 61 20 5b 70 72 65 70 61 72 65   S is a [prepare
375c0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20  d statement] in 
375d0 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
375e0 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a 2a 20 20  nnection] D.**  
375f0 20 20 20 20 20 20 20 20 61 6e 64 20 53 20 69 73          and S is
37600 20 6e 6f 74 20 74 68 65 20 6c 61 73 74 20 70 72   not the last pr
37610 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
37620 20 69 6e 20 44 2c 20 74 68 65 6e 0a 2a 2a 20 20   in D, then.**  
37630 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
37640 5f 6e 65 78 74 5f 73 74 6d 74 28 44 2c 20 53 29  _next_stmt(D, S)
37650 5d 20 72 6f 75 74 69 6e 65 20 73 68 61 6c 6c 20  ] routine shall 
37660 72 65 74 75 72 6e 20 61 20 70 6f 69 6e 74 65 72  return a pointer
37670 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20  .**          to 
37680 74 68 65 20 6e 65 78 74 20 70 72 65 70 61 72 65  the next prepare
37690 64 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 44  d statement in D
376a0 20 61 66 74 65 72 20 53 2e 0a 2a 2a 0a 2a 2a 20   after S..**.** 
376b0 7b 48 31 33 31 35 32 7d 20 49 66 20 53 20 69 73  {H13152} If S is
376c0 20 74 68 65 20 6c 61 73 74 20 5b 70 72 65 70 61   the last [prepa
376d0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69  red statement] i
376e0 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  n the.**        
376f0 20 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e    [database conn
37700 65 63 74 69 6f 6e 5d 20 44 20 74 68 65 6e 20 74  ection] D then t
37710 68 65 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74  he [sqlite3_next
37720 5f 73 74 6d 74 28 44 2c 20 53 29 5d 0a 2a 2a 20  _stmt(D, S)].** 
37730 20 20 20 20 20 20 20 20 20 72 6f 75 74 69 6e 65           routine
37740 20 73 68 61 6c 6c 20 72 65 74 75 72 6e 20 61 20   shall return a 
37750 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  NULL pointer..**
37760 0a 2a 2a 20 41 53 53 55 4d 50 54 49 4f 4e 53 3a  .** ASSUMPTIONS:
37770 0a 2a 2a 0a 2a 2a 20 7b 41 31 33 31 35 34 7d 20  .**.** {A13154} 
37780 54 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  The [database co
37790 6e 6e 65 63 74 69 6f 6e 5d 20 70 6f 69 6e 74 65  nnection] pointe
377a0 72 20 44 20 69 6e 20 61 20 63 61 6c 6c 20 74 6f  r D in a call to
377b0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
377c0 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28  lite3_next_stmt(
377d0 44 2c 53 29 5d 20 6d 75 73 74 20 72 65 66 65 72  D,S)] must refer
377e0 20 74 6f 20 61 6e 20 6f 70 65 6e 20 64 61 74 61   to an open data
377f0 62 61 73 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  base.**         
37800 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 61 6e 64 20   connection and 
37810 69 6e 20 70 61 72 74 69 63 75 6c 61 72 20 6d 75  in particular mu
37820 73 74 20 6e 6f 74 20 62 65 20 61 20 4e 55 4c 4c  st not be a NULL
37830 20 70 6f 69 6e 74 65 72 2e 0a 2a 2f 0a 73 71 6c   pointer..*/.sql
37840 69 74 65 33 5f 73 74 6d 74 20 2a 73 71 6c 69 74  ite3_stmt *sqlit
37850 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 73 71 6c  e3_next_stmt(sql
37860 69 74 65 33 20 2a 70 44 62 2c 20 73 71 6c 69 74  ite3 *pDb, sqlit
37870 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
37880 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
37890 3a 20 43 6f 6d 6d 69 74 20 41 6e 64 20 52 6f 6c  : Commit And Rol
378a0 6c 62 61 63 6b 20 4e 6f 74 69 66 69 63 61 74 69  lback Notificati
378b0 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 20 7b 48 31  on Callbacks {H1
378c0 32 39 35 30 7d 20 3c 53 36 30 34 30 30 3e 0a 2a  2950} <S60400>.*
378d0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
378e0 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 20 69  _commit_hook() i
378f0 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65  nterface registe
37900 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a  rs a callback.**
37910 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
37920 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72  invoked whenever
37930 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69   a transaction i
37940 73 20 63 6f 6d 6d 69 74 74 65 64 2e 0a 2a 2a 20  s committed..** 
37950 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73 65 74  Any callback set
37960 20 62 79 20 61 20 70 72 65 76 69 6f 75 73 20 63   by a previous c
37970 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  all to sqlite3_c
37980 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 0a 2a 2a 20  ommit_hook().** 
37990 66 6f 72 20 74 68 65 20 73 61 6d 65 20 64 61 74  for the same dat
379a0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
379b0 20 69 73 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a   is overridden..
379c0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72  ** The sqlite3_r
379d0 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29 20 69  ollback_hook() i
379e0 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65  nterface registe
379f0 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a  rs a callback.**
37a00 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
37a10 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72  invoked whenever
37a20 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69   a transaction i
37a30 73 20 63 6f 6d 6d 69 74 74 65 64 2e 0a 2a 2a 20  s committed..** 
37a40 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73 65 74  Any callback set
37a50 20 62 79 20 61 20 70 72 65 76 69 6f 75 73 20 63   by a previous c
37a60 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  all to sqlite3_c
37a70 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 0a 2a 2a 20  ommit_hook().** 
37a80 66 6f 72 20 74 68 65 20 73 61 6d 65 20 64 61 74  for the same dat
37a90 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
37aa0 20 69 73 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a   is overridden..
37ab0 2a 2a 20 54 68 65 20 70 41 72 67 20 61 72 67 75  ** The pArg argu
37ac0 6d 65 6e 74 20 69 73 20 70 61 73 73 65 64 20 74  ment is passed t
37ad0 68 72 6f 75 67 68 20 74 6f 20 74 68 65 20 63 61  hrough to the ca
37ae0 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 49 66 20 74 68  llback..** If th
37af0 65 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 20 61 20  e callback on a 
37b00 63 6f 6d 6d 69 74 20 68 6f 6f 6b 20 66 75 6e 63  commit hook func
37b10 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 6e 6f 6e  tion returns non
37b20 2d 7a 65 72 6f 2c 0a 2a 2a 20 74 68 65 6e 20 74  -zero,.** then t
37b30 68 65 20 63 6f 6d 6d 69 74 20 69 73 20 63 6f 6e  he commit is con
37b40 76 65 72 74 65 64 20 69 6e 74 6f 20 61 20 72 6f  verted into a ro
37b50 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 49 66  llback..**.** If
37b60 20 61 6e 6f 74 68 65 72 20 66 75 6e 63 74 69 6f   another functio
37b70 6e 20 77 61 73 20 70 72 65 76 69 6f 75 73 6c 79  n was previously
37b80 20 72 65 67 69 73 74 65 72 65 64 2c 20 69 74 73   registered, its
37b90 0a 2a 2a 20 70 41 72 67 20 76 61 6c 75 65 20 69  .** pArg value i
37ba0 73 20 72 65 74 75 72 6e 65 64 2e 20 20 4f 74 68  s returned.  Oth
37bb0 65 72 77 69 73 65 20 4e 55 4c 4c 20 69 73 20 72  erwise NULL is r
37bc0 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  eturned..**.** T
37bd0 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 6d 70 6c  he callback impl
37be0 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 75 73 74 20  ementation must 
37bf0 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20  not do anything 
37c00 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79  that will modify
37c10 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65  .** the database
37c20 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74   connection that
37c30 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 63 61 6c   invoked the cal
37c40 6c 62 61 63 6b 2e 20 20 41 6e 79 20 61 63 74 69  lback.  Any acti
37c50 6f 6e 73 0a 2a 2a 20 74 6f 20 6d 6f 64 69 66 79  ons.** to modify
37c60 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
37c70 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20 62 65  nnection must be
37c80 20 64 65 66 65 72 72 65 64 20 75 6e 74 69 6c 20   deferred until 
37c90 61 66 74 65 72 20 74 68 65 0a 2a 2a 20 63 6f 6d  after the.** com
37ca0 70 6c 65 74 69 6f 6e 20 6f 66 20 74 68 65 20 5b  pletion of the [
37cb0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
37cc0 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65  call that trigge
37cd0 72 65 64 20 74 68 65 20 63 6f 6d 6d 69 74 0a 2a  red the commit.*
37ce0 2a 20 6f 72 20 72 6f 6c 6c 62 61 63 6b 20 68 6f  * or rollback ho
37cf0 6f 6b 20 69 6e 20 74 68 65 20 66 69 72 73 74 20  ok in the first 
37d00 70 6c 61 63 65 2e 0a 2a 2a 20 4e 6f 74 65 20 74  place..** Note t
37d10 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  hat [sqlite3_pre
37d20 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b  pare_v2()] and [
37d30 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
37d40 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69  both modify thei
37d50 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f  r.** database co
37d60 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68  nnections for th
37d70 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f  e meaning of "mo
37d80 64 69 66 79 22 20 69 6e 20 74 68 69 73 20 70 61  dify" in this pa
37d90 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 52  ragraph..**.** R
37da0 65 67 69 73 74 65 72 69 6e 67 20 61 20 4e 55 4c  egistering a NUL
37db0 4c 20 66 75 6e 63 74 69 6f 6e 20 64 69 73 61 62  L function disab
37dc0 6c 65 73 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  les the callback
37dd0 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 74 68 65 20  ..**.** For the 
37de0 70 75 72 70 6f 73 65 73 20 6f 66 20 74 68 69 73  purposes of this
37df0 20 41 50 49 2c 20 61 20 74 72 61 6e 73 61 63 74   API, a transact
37e00 69 6f 6e 20 69 73 20 73 61 69 64 20 74 6f 20 68  ion is said to h
37e10 61 76 65 20 62 65 65 6e 0a 2a 2a 20 72 6f 6c 6c  ave been.** roll
37e20 65 64 20 62 61 63 6b 20 69 66 20 61 6e 20 65 78  ed back if an ex
37e30 70 6c 69 63 69 74 20 22 52 4f 4c 4c 42 41 43 4b  plicit "ROLLBACK
37e40 22 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 65  " statement is e
37e50 78 65 63 75 74 65 64 2c 20 6f 72 0a 2a 2a 20 61  xecuted, or.** a
37e60 6e 20 65 72 72 6f 72 20 6f 72 20 63 6f 6e 73 74  n error or const
37e70 72 61 69 6e 74 20 63 61 75 73 65 73 20 61 6e 20  raint causes an 
37e80 69 6d 70 6c 69 63 69 74 20 72 6f 6c 6c 62 61 63  implicit rollbac
37e90 6b 20 74 6f 20 6f 63 63 75 72 2e 0a 2a 2a 20 54  k to occur..** T
37ea0 68 65 20 72 6f 6c 6c 62 61 63 6b 20 63 61 6c 6c  he rollback call
37eb0 62 61 63 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f  back is not invo
37ec0 6b 65 64 20 69 66 20 61 20 74 72 61 6e 73 61 63  ked if a transac
37ed0 74 69 6f 6e 20 69 73 0a 2a 2a 20 61 75 74 6f 6d  tion is.** autom
37ee0 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20  atically rolled 
37ef0 62 61 63 6b 20 62 65 63 61 75 73 65 20 74 68 65  back because the
37f00 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
37f10 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a  tion is closed..
37f20 2a 2a 20 54 68 65 20 72 6f 6c 6c 62 61 63 6b 20  ** The rollback 
37f30 63 61 6c 6c 62 61 63 6b 20 69 73 20 6e 6f 74 20  callback is not 
37f40 69 6e 76 6f 6b 65 64 20 69 66 20 61 20 74 72 61  invoked if a tra
37f50 6e 73 61 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 72  nsaction is.** r
37f60 6f 6c 6c 65 64 20 62 61 63 6b 20 62 65 63 61 75  olled back becau
37f70 73 65 20 61 20 63 6f 6d 6d 69 74 20 63 61 6c 6c  se a commit call
37f80 62 61 63 6b 20 72 65 74 75 72 6e 65 64 20 6e 6f  back returned no
37f90 6e 2d 7a 65 72 6f 2e 0a 2a 2a 20 3c 74 6f 64 6f  n-zero..** <todo
37fa0 3e 20 43 68 65 63 6b 20 6f 6e 20 74 68 69 73 20  > Check on this 
37fb0 3c 2f 74 6f 64 6f 3e 0a 2a 2a 0a 2a 2a 20 49 4e  </todo>.**.** IN
37fc0 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
37fd0 7b 48 31 32 39 35 31 7d 20 54 68 65 20 5b 73 71  {H12951} The [sq
37fe0 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f  lite3_commit_hoo
37ff0 6b 28 44 2c 46 2c 50 29 5d 20 69 6e 74 65 72 66  k(D,F,P)] interf
38000 61 63 65 20 72 65 67 69 73 74 65 72 73 20 74 68  ace registers th
38010 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 61  e.**          ca
38020 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
38030 46 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20  F to be invoked 
38040 77 69 74 68 20 61 72 67 75 6d 65 6e 74 20 50 20  with argument P 
38050 77 68 65 6e 65 76 65 72 0a 2a 2a 20 20 20 20 20  whenever.**     
38060 20 20 20 20 20 61 20 74 72 61 6e 73 61 63 74 69       a transacti
38070 6f 6e 20 63 6f 6d 6d 69 74 73 20 6f 6e 20 74 68  on commits on th
38080 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
38090 65 63 74 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a  ection] D..**.**
380a0 20 7b 48 31 32 39 35 32 7d 20 54 68 65 20 5b 73   {H12952} The [s
380b0 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f  qlite3_commit_ho
380c0 6f 6b 28 44 2c 46 2c 50 29 5d 20 69 6e 74 65 72  ok(D,F,P)] inter
380d0 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65  face returns the
380e0 20 50 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 20   P argument.**  
380f0 20 20 20 20 20 20 20 20 66 72 6f 6d 20 74 68 65          from the
38100 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 77   previous call w
38110 69 74 68 20 74 68 65 20 73 61 6d 65 20 5b 64 61  ith the same [da
38120 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
38130 6e 5d 20 44 2c 0a 2a 2a 20 20 20 20 20 20 20 20  n] D,.**        
38140 20 20 6f 72 20 4e 55 4c 4c 20 6f 6e 20 74 68 65    or NULL on the
38150 20 66 69 72 73 74 20 63 61 6c 6c 20 66 6f 72 20   first call for 
38160 61 20 70 61 72 74 69 63 75 6c 61 72 20 64 61 74  a particular dat
38170 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
38180 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 35   D..**.** {H1295
38190 33 7d 20 45 61 63 68 20 63 61 6c 6c 20 74 6f 20  3} Each call to 
381a0 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f  [sqlite3_commit_
381b0 68 6f 6f 6b 28 29 5d 20 6f 76 65 72 77 72 69 74  hook()] overwrit
381c0 65 73 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a  es the callback.
381d0 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 67 69  **          regi
381e0 73 74 65 72 65 64 20 62 79 20 70 72 69 6f 72 20  stered by prior 
381f0 63 61 6c 6c 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  calls..**.** {H1
38200 32 39 35 34 7d 20 49 66 20 74 68 65 20 46 20 61  2954} If the F a
38210 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69  rgument to [sqli
38220 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28  te3_commit_hook(
38230 44 2c 46 2c 50 29 5d 20 69 73 20 4e 55 4c 4c 0a  D,F,P)] is NULL.
38240 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 6e  **          then
38250 20 74 68 65 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b   the commit hook
38260 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 63 61 6e   callback is can
38270 63 65 6c 65 64 20 61 6e 64 20 6e 6f 20 63 61 6c  celed and no cal
38280 6c 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 20 20  lback.**        
38290 20 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65    is invoked whe
382a0 6e 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  n a transaction 
382b0 63 6f 6d 6d 69 74 73 2e 0a 2a 2a 0a 2a 2a 20 7b  commits..**.** {
382c0 48 31 32 39 35 35 7d 20 49 66 20 74 68 65 20 63  H12955} If the c
382d0 6f 6d 6d 69 74 20 63 61 6c 6c 62 61 63 6b 20 72  ommit callback r
382e0 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 20  eturns non-zero 
382f0 74 68 65 6e 20 74 68 65 20 63 6f 6d 6d 69 74 20  then the commit 
38300 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63  is.**          c
38310 6f 6e 76 65 72 74 65 64 20 69 6e 74 6f 20 61 20  onverted into a 
38320 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20  rollback..**.** 
38330 7b 48 31 32 39 36 31 7d 20 54 68 65 20 5b 73 71  {H12961} The [sq
38340 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68  lite3_rollback_h
38350 6f 6f 6b 28 44 2c 46 2c 50 29 5d 20 69 6e 74 65  ook(D,F,P)] inte
38360 72 66 61 63 65 20 72 65 67 69 73 74 65 72 73 20  rface registers 
38370 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
38380 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
38390 6e 20 46 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65  n F to be invoke
383a0 64 20 77 69 74 68 20 61 72 67 75 6d 65 6e 74 20  d with argument 
383b0 50 20 77 68 65 6e 65 76 65 72 0a 2a 2a 20 20 20  P whenever.**   
383c0 20 20 20 20 20 20 20 61 20 74 72 61 6e 73 61 63         a transac
383d0 74 69 6f 6e 20 72 6f 6c 6c 73 20 62 61 63 6b 20  tion rolls back 
383e0 6f 6e 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  on the [database
383f0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2e 0a   connection] D..
38400 2a 2a 0a 2a 2a 20 7b 48 31 32 39 36 32 7d 20 54  **.** {H12962} T
38410 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 6f 6c 6c  he [sqlite3_roll
38420 62 61 63 6b 5f 68 6f 6f 6b 28 44 2c 46 2c 50 29  back_hook(D,F,P)
38430 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ] interface retu
38440 72 6e 73 20 74 68 65 20 50 0a 2a 2a 20 20 20 20  rns the P.**    
38450 20 20 20 20 20 20 61 72 67 75 6d 65 6e 74 20 66        argument f
38460 72 6f 6d 20 74 68 65 20 70 72 65 76 69 6f 75 73  rom the previous
38470 20 63 61 6c 6c 20 77 69 74 68 20 74 68 65 20 73   call with the s
38480 61 6d 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ame.**          
38490 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
384a0 74 69 6f 6e 5d 20 44 2c 20 6f 72 20 4e 55 4c 4c  tion] D, or NULL
384b0 20 6f 6e 20 74 68 65 20 66 69 72 73 74 20 63 61   on the first ca
384c0 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66  ll.**          f
384d0 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  or a particular 
384e0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
384f0 69 6f 6e 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  ion D..**.** {H1
38500 32 39 36 33 7d 20 45 61 63 68 20 63 61 6c 6c 20  2963} Each call 
38510 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 6f 6c 6c  to [sqlite3_roll
38520 62 61 63 6b 5f 68 6f 6f 6b 28 29 5d 20 6f 76 65  back_hook()] ove
38530 72 77 72 69 74 65 73 20 74 68 65 20 63 61 6c 6c  rwrites the call
38540 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 20 20 20  back.**         
38550 20 72 65 67 69 73 74 65 72 65 64 20 62 79 20 70   registered by p
38560 72 69 6f 72 20 63 61 6c 6c 73 2e 0a 2a 2a 0a 2a  rior calls..**.*
38570 2a 20 7b 48 31 32 39 36 34 7d 20 49 66 20 74 68  * {H12964} If th
38580 65 20 46 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  e F argument to 
38590 5b 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63  [sqlite3_rollbac
385a0 6b 5f 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d 20 69  k_hook(D,F,P)] i
385b0 73 20 4e 55 4c 4c 0a 2a 2a 20 20 20 20 20 20 20  s NULL.**       
385c0 20 20 20 74 68 65 6e 20 74 68 65 20 72 6f 6c 6c     then the roll
385d0 62 61 63 6b 20 68 6f 6f 6b 20 63 61 6c 6c 62 61  back hook callba
385e0 63 6b 20 69 73 20 63 61 6e 63 65 6c 65 64 20 61  ck is canceled a
385f0 6e 64 20 6e 6f 20 63 61 6c 6c 62 61 63 6b 0a 2a  nd no callback.*
38600 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 69 6e  *          is in
38610 76 6f 6b 65 64 20 77 68 65 6e 20 61 20 74 72 61  voked when a tra
38620 6e 73 61 63 74 69 6f 6e 20 72 6f 6c 6c 73 20 62  nsaction rolls b
38630 61 63 6b 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71  ack..*/.void *sq
38640 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f  lite3_commit_hoo
38650 6b 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28  k(sqlite3*, int(
38660 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a  *)(void*), void*
38670 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  );.void *sqlite3
38680 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 73  _rollback_hook(s
38690 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 28 2a 29  qlite3*, void(*)
386a0 28 76 6f 69 64 20 2a 29 2c 20 76 6f 69 64 2a 29  (void *), void*)
386b0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
386c0 46 3a 20 44 61 74 61 20 43 68 61 6e 67 65 20 4e  F: Data Change N
386d0 6f 74 69 66 69 63 61 74 69 6f 6e 20 43 61 6c 6c  otification Call
386e0 62 61 63 6b 73 20 7b 48 31 32 39 37 30 7d 20 3c  backs {H12970} <
386f0 53 36 30 34 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68  S60400>.**.** Th
38700 65 20 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65  e sqlite3_update
38710 5f 68 6f 6f 6b 28 29 20 69 6e 74 65 72 66 61 63  _hook() interfac
38720 65 20 72 65 67 69 73 74 65 72 73 20 61 20 63 61  e registers a ca
38730 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a  llback function.
38740 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 64 61 74  ** with the [dat
38750 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
38760 5d 20 69 64 65 6e 74 69 66 69 65 64 20 62 79 20  ] identified by 
38770 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
38780 6e 74 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 76 6f  nt.** to be invo
38790 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61 20 72  ked whenever a r
387a0 6f 77 20 69 73 20 75 70 64 61 74 65 64 2c 20 69  ow is updated, i
387b0 6e 73 65 72 74 65 64 20 6f 72 20 64 65 6c 65 74  nserted or delet
387c0 65 64 2e 0a 2a 2a 20 41 6e 79 20 63 61 6c 6c 62  ed..** Any callb
387d0 61 63 6b 20 73 65 74 20 62 79 20 61 20 70 72 65  ack set by a pre
387e0 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 74 68  vious call to th
387f0 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 66  is function.** f
38800 6f 72 20 74 68 65 20 73 61 6d 65 20 64 61 74 61  or the same data
38810 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
38820 69 73 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a  is overridden..*
38830 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  *.** The